heyspex 0.2.6 → 0.2.7

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

@@ -1,464 +1,464 @@
----
-id: HS-PROTO-canonical-frontmatter-templates
-name: Canonical frontmatter templates per entity kind
-type: protocol
-status: open
-priority: 1
-scope: vault
-owner: TODO — your name/handle
-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:
-  - '[[entity-model]]'
-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`. |
+---
+id: HS-PROTO-canonical-frontmatter-templates
+name: Canonical frontmatter templates per entity kind
+type: protocol
+status: open
+priority: 1
+scope: vault
+owner: TODO — your name/handle
+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:
+  - '[[entity-model]]'
+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`. |