heyspex 0.1.0

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

@@ -0,0 +1,531 @@
+---
+id: HS-PROTO-canonical-frontmatter-templates
+name: Canonical frontmatter templates per entity kind
+type: protocol
+status: open
+priority: 1
+scope: vault
+owner: pwher
+assisted_by:
+  - Claude Code
+created: "2026-06-13"
+updated: "2026-06-13"
+tags:
+  - protocol
+  - spec-filing
+  - canonical-templates
+  - agent-experience
+  - frontmatter
+triggers:
+  - file_milestone
+  - 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"
+templates:
+  milestone:
+    folder: milestones/
+    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)"
+    frontmatter:
+      id: "{{ID}}"
+      name: "{{NAME}}"
+      summary: ""
+      type: milestone
+      status: open
+      owner: "{{OWNER}}"
+      created: "{{TODAY}}"
+      updated: "{{TODAY}}"
+      epics: []
+      target_date: ""
+      tags:
+        - milestone
+    body_skeleton: |
+      # {{NAME}}
+
+      ## Intended outcome
+
+      <!-- Re-derive from the source research's intended outcome — do NOT copy it (HS-K4D4-2I29-RES-outcome-cascade-through-a-requirements-h). -->
+      **Outcome at the milestone altitude (required):** What outcome does this milestone deliver?
+
+      **Moves (↑ link, required):** Which research/parent outcome does it move — and by what **mechanism of contribution**? (Name the mechanism; don't echo the parent's words.)
+
+      ## Why this is a milestone, not loose epics
+
+      ## Acceptance gate
+
+      ## Suggested landing order
+
+      ## Out of scope
+
+      ## Expected Breakage & Consequences
+
+      <!-- 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>"
+    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)"
+    frontmatter:
+      id: "{{ID}}"
+      name: "{{NAME}}"
+      summary: ""
+      type: epic
+      status: open
+      kind: feature
+      effort: 3
+      owner: "{{OWNER}}"
+      created: "{{TODAY}}"
+      updated: "{{TODAY}}"
+      milestone: "{{PARENT_ID}}"
+      children: []
+      tags: []
+    body_skeleton: |
+      # {{NAME}}
+
+      ## Intended outcome
+
+      <!-- Re-derive from the parent milestone's intended outcome — do NOT copy it (HS-K4D4-2I29-RES-outcome-cascade-through-a-requirements-h). -->
+      **User-visible outcome of this epic (required):** What changes for the user when this epic ships?
+
+      **Moves (↑ link, required):** Which milestone outcome does it move — and by what **mechanism of contribution**?
+
+      ## Expected Breakage & Consequences
+
+      ## Why this epic exists
+
+      <!-- Substantive priority rationale (HS-XMSD). Plain language, no scores. -->
+      **Problem right now (required):** One sentence — what specific problem does this solve, and why is now (not next cycle) the right time?
+
+      **What this unlocks (required if `kind: infra` or `foundation`):** What future work becomes possible after this ships that isn't possible today?
+
+      **Skip cost (write before pinning this as on-deck):** If we skip this cycle, we lose: …
+
+      **Confidence note (optional):** Flag any part of the rationale above where your confidence is low.
+
+      ## Tasks
+
+      ## Acceptance gate — epic close
+
+      ## Change log
+  task:
+    folder: tasks/
+    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)"
+    frontmatter:
+      id: "{{ID}}"
+      name: "{{NAME}}"
+      summary: ""
+      type: task
+      status: open
+      kind: feature
+      effort: 3
+      owner: "{{OWNER}}"
+      created: "{{TODAY}}"
+      updated: "{{TODAY}}"
+      parent: "{{PARENT_ID}}"
+      tags:
+        - near-term
+    body_skeleton: |
+      # {{NAME}}
+
+      ## Intended outcome
+
+      <!-- Re-derive from the parent epic's intended outcome — do NOT copy it (HS-K4D4-2I29-RES-outcome-cascade-through-a-requirements-h). -->
+      **Observable condition this task produces (required):** What can you monitor and control once this task is done? Express it as a checkable condition — this directly seeds the Acceptance criteria below.
+
+      **Moves (↑ link, required):** Which epic outcome does it move?
+
+      ## Expected Breakage & Consequences
+
+      ## Scope
+
+      ## Acceptance criteria
+
+      <!-- Each criterion is a monitorable + controllable condition derived from the Intended outcome above, traceable ↑ to the epic outcome. -->
+
+      ## Builder brief
+
+      <!-- Fleet dispatch hints for dev-factory (optional until breakdown files the task). Consult builder-fleet-capability-reference. -->
+      - **Target:** `{{TARGET_OR_TBD}}`
+      - **Context files:** `path/to/dep.ts`
+      - **Estimated context:** ~0 tokens
+      - **recommended_num_ctx:** 65536
+      - **suggested_model:** `qwen3-coder:30b`
+      - **suggested_machine:** `specops-gpu0`
+      - **fit_assessment:** safe
+
+      ## References
+  research:
+    folder: research/
+    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)"
+    frontmatter:
+      id: "{{ID}}"
+      name: "{{NAME}}"
+      type: research
+      status: open
+      owner: "{{OWNER}}"
+      created: "{{TODAY}}"
+      updated: "{{TODAY}}"
+      tags:
+        - research
+    body_skeleton: |
+      # {{NAME}}
+
+      ## Executive Summary
+
+      ## Conclusion & intended outcome
+
+      <!-- The root outcome that milestones/epics/tasks spawned from this research refine (translate, don't copy) (HS-K4D4-2I29-RES-outcome-cascade-through-a-requirements-h). -->
+      **Conclusion (one line):** Acting on this research, what is the conclusion?
+
+      **What acting on this achieves:** What changes for the user or system if we act on it?
+
+      ## Findings
+
+      ## Sources
+  memory-lesson:
+    folder: memory/lessons/
+    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)"
+    frontmatter:
+      id: "{{ID}}"
+      name: "{{NAME}}"
+      type: memory-lesson
+      status: open
+      owner: "{{OWNER}}"
+      created: "{{TODAY}}"
+      updated: "{{TODAY}}"
+      topic: "{{SLUG}}"
+      observed: "{{TODAY}}"
+    body_skeleton: |
+      # {{NAME}}
+
+      ## Problem
+
+      ## Fix
+  memory-decision:
+    folder: memory/decisions/
+    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)"
+    frontmatter:
+      id: "{{ID}}"
+      name: "{{NAME}}"
+      type: memory-decision
+      status: open
+      owner: "{{OWNER}}"
+      created: "{{TODAY}}"
+      updated: "{{TODAY}}"
+      topic: "{{SLUG}}"
+      decided: "{{TODAY}}"
+      deciders:
+        - "{{OWNER}}"
+    body_skeleton: |
+      # {{NAME}}
+
+      ## Decision
+
+      ## Rationale
+  memory-reference:
+    folder: memory/references/
+    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)"
+    frontmatter:
+      id: "{{ID}}"
+      name: "{{NAME}}"
+      type: memory-reference
+      status: open
+      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>"
+    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)"
+    frontmatter:
+      id: "{{ID}}"
+      name: "{{NAME}}"
+      type: memory-ui-pattern
+      status: open
+      owner: "{{OWNER}}"
+      created: "{{TODAY}}"
+      updated: "{{TODAY}}"
+      topic: "{{SLUG}}"
+      documented: "{{TODAY}}"
+    body_skeleton: |
+      # {{NAME}}
+
+      ## Pattern
+
+      ## When to apply
+
+      ## Rules
+
+      ## Implementation
+  review:
+    folder: reviews/
+    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)"
+    frontmatter:
+      id: "{{ID}}"
+      name: "{{NAME}}"
+      type: review
+      status: open
+      owner: "{{OWNER}}"
+      created: "{{TODAY}}"
+      updated: "{{TODAY}}"
+      parent: "{{PARENT_ID}}"
+      reviews: "{{PARENT_ID}}"
+    body_skeleton: |
+      # Review — {{NAME}}
+
+      ## Acceptance verification
+
+      ## Reviewer notes
+
+      ## Memory candidates
+
+      | Candidate | Type | Conflict check | Score | Accept? |
+      |---|---|---|---|---|
+
+      ## Decision: close or reopen
+  agent:
+    folder: agents/
+    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"
+    frontmatter:
+      id: "{{ID}}"
+      name: "{{NAME}}"
+      type: agent
+      status: open
+      owner: "{{OWNER}}"
+      role: "{{NAME}}"
+      created: "{{TODAY}}"
+      updated: "{{TODAY}}"
+      owned_paths: []
+      tags:
+        - agent
+    body_skeleton: |
+      # {{NAME}}
+
+      > Persona / instructions for this agent identity. This body compiles to the system-prompt of `.claude/agents/<name>.md` and `.cursor/agents/<name>.md` ([[entity-model]] §agent). The vault spec is the SSOT; the generated host files are derived.
+
+      You are {{NAME}}. <describe the role, what it optimizes for, and how it works.>
+
+      ## Responsibilities
+
+      ## Workflow conventions
+
+      ## Guardrails
+  pillar:
+    folder: pillars/
+    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"
+    frontmatter:
+      id: "{{ID}}"
+      name: "{{NAME}}"
+      type: pillar
+      status: perpetual
+      owner: "{{OWNER}}"
+      created: "{{TODAY}}"
+      updated: "{{TODAY}}"
+      canonical: true
+      secondary_pillars: []
+      tags:
+        - pillar
+    body_skeleton: |
+      # {{NAME}}
+
+      > Perpetual structural theme — never closes. Epics name this pillar as their home for accumulated learning ([[entity-model]] §pillar).
+
+      ## What this pillar is
+
+      ## Why it's perpetual
+
+      ## 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
+
+This protocol is the single source of truth for the frontmatter shape of every new spec. The executable data lives in the **frontmatter** `templates:` map above — one entry per kind, each carrying `folder`, `id_format`, `parent_kinds`, `required_fields`, `optional_fields`, a `schema_source` citation, a ready-to-stamp `frontmatter` template, and a `body_skeleton`. The procedure-catalog builder (`scripts/build-procedure-catalog.mjs`) parses protocol frontmatter, so the catalog picks the templates up with no builder change, and `heyspex_get_procedure({ name: 'canonical-frontmatter-templates' })` returns the whole file (frontmatter + this body) to a calling agent.
+
+**Never compose frontmatter from a sibling example.** That is the exact anti-pattern this protocol exists to retire (user-memory `feedback_consult_procedures_dont_pattern_match`). Call `heyspex_file_spec` (or `POST /api/specs`); the server allocates the id and stamps the template. These templates are also the SSOT HS-OFUB-CVOB-EPIC-saas-customer-vault-onboarding scaffolds customer workspaces from.
+
+## Placeholders
+
+The `frontmatter`/`body_skeleton` templates use these tokens, all server-substituted at filing time:
+
+- `{{ID}}` — server-allocated id (`allocateRandomVaultId()` for task/epic/milestone, numeric increment for research, slug-derived for memory kinds, parent-suffix for review). **Never client-supplied.**
+- `{{NAME}}` — the human-readable title.
+- `{{OWNER}}` — canonical owner (`pwher`).
+- `{{TODAY}}` — filing date / timestamp (`YYYY-MM-DD`).
+- `{{PARENT_ID}}` — the parent's id, for the `milestone:`/`parent:` wikilink.
+- `{{SLUG}}` — the title slug (memory `topic:` default).
+
+## Per-kind reference
+
+The authoritative schema for every field below is **[[entity-model]] §Frontmatter schemas** — each entry's `schema_source` names the exact section + line range. The notes here cover the recovery path and parent-kind constraints; they do not restate the schema.
+
+### `milestone` — `specs/entity-model.md` §milestone (lines 497–519)
+
+The top of the hierarchy: `parent_kinds: []` — a milestone has no parent (sub-milestones are out of scope; split horizontally). No scalar `kind`/`effort`/`priority` — milestone ordering is the deterministic scheduler's output, never a stored scalar. `epics:` is the mirror of each child epic's `milestone:` pointer (write both sides). Required body sections: rationale, acceptance gate, landing order, out-of-scope.
+
+### `epic` — `specs/entity-model.md` §epic (lines 455–494)
+
+`parent_kinds: [milestone]` — an epic belongs to exactly one milestone via `milestone:` (the reverse of the milestone's `epics:` array). The `milestone:` requirement is in a **validator grace window until 2026-06-26**, after which a missing parent escalates from warning to error (HS-V5UA-T5PX-TASK-required-milestone-parent-on-epic-validator-and-grace-window). **`pillar:` is required and HARD-BLOCKED at filing** (owner decision 2026-06-18): every epic must name the perpetual Pillar that is its home for accumulated learning, and `POST /api/specs` / `heyspex_file_spec` refuse a `type: epic` with no resolvable `HS-PILR` theme (400 `pillar_required`, which lists existing pillars and how to author a net-new one). When no existing pillar fits, author one first via `heyspex_file_spec({ type: "pillar", name })`. Full rules: pillar-assignment-protocol. The ~226 legacy pillar-less epics are surfaced as a non-blocking Resolution backfill queue (`EPIC_MISSING_PILLAR`, grace until 2026-07-31). `research:` and `planning_flow:` are required for new epics by [[entity-model]] §epic but are filed during the milestone grace window per FRZE precedent — listed `optional_fields` here until the grace closes (HS-YXBD-1EM0-EPIC-canonical-spec-filing-surface-templates §Scope cuts). Shares the §task base schema; `type: epic` is the discriminator.
+
+### `task` — `specs/entity-model.md` §task (lines 392–453)
+
+`parent_kinds: [epic, task]`. A **child task** is NOT a separate type — it is `type: task` whose `parent:` points at another task instead of an epic (same shape, different parent kind). `parent:` is optional at the schema level (the generic new-spec form and Epic Studio file parentless specs), but when present the server validates the parent kind and back-links the child into the parent's `children:` array at filing time (bidirectional linkage — see HS-3J4S-U13O-TASK-extend-post-api-specs-to-all-kinds-with).
+
+### `research` — `specs/entity-model.md` §research (lines 761–793)
+
+**Evergreen** (research-is-evergreen): `status: open` is the resting state for the doc's whole life — there are no `in_review`/`closed` transitions; lineage is recorded through relational fields, never a status flip. Not hierarchical (`parent_kinds: []`): a research doc `enhances:` a single milestone (bidirectional with that milestone's `informed_by:`), it is not a child in a `children:` array. Numeric id (`HS-RES-<NNN>`), server-incremented. Required body sections: Executive Summary + Sources (research-capture-protocol).
+
+### `memory-lesson` — `specs/entity-model.md` §memory-lesson (lines 604–615)
+
+`parent_kinds: []` — memory specs link via `related:` wikilinks, not hierarchy. Slug-derived id (`HS-LES-<slug>`). Required: `topic` + `observed`. Body sections: `## Problem`, `## Fix`. Full capture rules: [[memory-protocol]].
+
+### `memory-decision` — `specs/entity-model.md` §memory-decision (lines 617–629)
+
+Slug id (`HS-DEC-<slug>`). Required: `topic` + `decided` + `deciders`. Body: `## Decision`, `## Rationale`. A `memory-decision` is the day-to-day choice that doesn't warrant a full ADR but should still persist.
+
+### `memory-reference` — `specs/entity-model.md` §memory-reference (lines 631–641)
+
+Slug id (`HS-REF-<slug>`). Required: `topic`. Body is the brief context for why the reference matters; `url:` is optional.
+
+### `memory-ui-pattern` — `specs/entity-model.md` §memory-ui-pattern (lines 643–653)
+
+Slug id (`HS-UIP-<slug>`). Required: `topic` + `documented`. Reusable console interaction/visual patterns. Body sections: `## Pattern`, `## When to apply`, `## Rules`, `## Implementation`. Distinct from `memory-ux-principle` (cross-brand rules).
+
+### `review` — `specs/entity-model.md` §review (lines 679–705)
+
+`parent_kinds: [task, epic, milestone]`; `parent:` is **required** (a review with no subject is meaningless). The id is the bare `HS-REV-<parent-suffix>` — the suffix is segment `[2]` of the parent id (`HS-U13O-TASK` → `HS-U13O-REV`, `HS-0028-EPIC` → `HS-0028-REV`); the slug rides only in the filename. `reviews:` mirrors `parent:` (legacy alias for back-compat reads). A review has **no** `children:`/parent-array back-link — it cross-links to its subject via `parent:`/`reviews:` plus a `## Review` section the parent spec must carry. Four required body sections: `## Acceptance verification`, `## Reviewer notes`, `## Memory candidates` (scored table with a Conflict-check column), `## Decision: close or reopen`.
+
+### `pillar` — `specs/entity-model.md` §pillar
+
+`parent_kinds: []` — a Pillar is a perpetual structural theme, not a child in any hierarchy; epics point UP at it via their required `pillar:` field. **`status: perpetual`** always (it never closes) and **`canonical:` is required** (`true` for owner-curated library pillars). Slug-only id (`HS-PILR-<slug>`, so id == basename and `[[HS-PILR-<slug>]]` resolves without a suffix). `secondary_pillars:` is always present (usually `[]`). Authoring a net-new pillar as a subject naturally arises during development is a **first-class, encouraged act** — file one with `heyspex_file_spec({ type: "pillar", name })` (or `POST /api/specs`), then point the epic's `pillar:` at it. The owner may also author a pillar standalone at any time. Full rules: pillar-assignment-protocol.
+
+## 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.)
+
+## Drift gate
+
+Adding or removing a kind here changes the file, so `npm run build:procedure-catalog` must be re-run and the regenerated `specs/protocols/.catalog.json` committed; `npm run validate:procedure-catalog` is the CI drift gate. The inline `BODY_SKELETONS` in `spex-console/src/lib/vault.ts` (the server's create-time skeleton injection for `review`, the four memory kinds, `diagnose`, and `pillar`) must stay in lockstep with the `body_skeleton` entries above.
+
+## 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| 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/memory-protocol.md

@@ -0,0 +1,48 @@
+---
+id: HS-PROTO-memory-protocol
+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"
+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.
+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/`  |
+| 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).                    |