heyspex 0.2.6 → 0.2.7

package/dist/cli-templates/customer-vault/specs/entity-model.md

@@ -1,1728 +1,1728 @@
----
-id: HS-L2-ENTITY
-name: HeySpex Entity Model
-type: l2
-status: draft
-priority: 0
-owner: TODO — your name/handle
-created: 2026-05-14
-updated: 2026-05-18
-tags: "[foundation, l2, entity-model, schema]"
----
-
-
-
-
-
-
-# HeySpex Entity Model
-
-> [!important] Constitutional dependency
-> Every constraint in this document derives from a numbered principle in heyspex-north-star. If a future change to this document contradicts the L1 spec, the change is wrong. When the L1 changes, this document updates downstream.
-
-This L2 spec defines the shape of every artifact that lives in a HeySpex vault: the entity types, their frontmatter schemas, their on-disk layout, the dependency relations between them, and the wikilink resolution rules. It is the contract that the console, the CLI (`hs`), and any AI agent must satisfy when reading or writing the vault.
-
-## Vocabulary
-
-- **Vault.** A folder of plain-text files under git. The on-disk layout is canonical. A single Builder owns one or more vaults; this document specifies the structure of one vault.
-- **Spec.** A single markdown file in the vault. Every spec has YAML frontmatter and a markdown body. The frontmatter declares the spec's type and identity.
-- **Entity type.** The value of the `type:` field in frontmatter. Determines which folder the spec lives in, which other fields are required, and how the spec is rendered in the console.
-- **Hierarchy level.** L1 / L2 / L3. Vision → architecture → use-case. A different axis from entity type. Some entity types are level-tagged (`type: l1`, `type: l2`, `type: l3`); most are not.
-- **Wikilink.** A reference of the form `[[link-target]]`, resolved by filename match across the vault.
-- **Memory (conceptual layer).** Durable project knowledge surfaced together in the console: `memory-lesson`, `memory-decision`, `memory-reference`, `memory-ux-principle`, `memory-ui-pattern`, and `protocol`. Protocols are filed under `specs/protocols/` on disk but are a **subsection of Memory** in navigation and in `hs prime` — not a peer of Memory beside Epics/Tasks. See memory-protocols-subsection-of-memory. Work to *create* or change a protocol remains `type: epic` / `task`.
-
-## Vault root layout
-
-```
-specs/
-├── heyspex-north-star.md          # the L1; one file
-├── entity-model.md                # this document; L2
-├── architecture-foundations.md    # L2 sibling (renamed 2026-05-31 from architecture-pillars.md to disambiguate from the `type: pillar` entity)
-├── principles.md                  # L2 (expansion of L1's principle list)
-├── glossary.md                    # L2 (authoritative term dictionary) — North Star tier
-├── adr/                           # one ADR per file
-│   ├── adr-0001-vault-format.md
-│   ├── adr-0002-derived-index.md
-│   └── ...
-├── use-cases/                     # one L3 use-case spec per file
-│   ├── uc-capture-intent.md
-│   ├── uc-decompose-intent.md
-│   └── ...
-├── tasks/                         # task / feature / bug specs
-│   ├── HS-ZF0T-TASK-<slug>.md          # legacy sequential, or HS-K7M2-<slug>.md (random)
-│   └── ...
-├── milestones/                    # milestone specs (the grouping above epic)
-│   └── HS-MIL-<suffix>-<slug>.md  # e.g. HS-IART-MIL-console-ia-restructure.md
-├── pillars/                       # type: pillar — perpetual categorical containers (Scaling, Reliability, DX, etc.)
-│   └── HS-PILR-<slug>.md          # canonical Pillars; customers may also create HS-PILR-<suffix>-<slug>.md
-├── epics/                         # epic specs
-│   └── HS-0001-EPIC-<slug>.md     # legacy, or HS-EPIC-X9P4-<slug>.md (random)
-├── branches/                      # branch-brief specs (one per git branch)
-│   └── <branch-slug>.md
-├── memory/
-│   ├── lessons/                   # memory-lesson specs
-│   │   └── <slug>.md
-│   ├── decisions/                 # memory-decision specs
-│   │   └── <slug>.md
-│   ├── references/                # memory-reference specs
-│   │   └── <slug>.md
-│   ├── ux-principles/             # memory-ux-principle specs (cross-brand interaction rules)
-│   │   └── <slug>.md
-│   └── ui-patterns/               # memory-ui-pattern specs (reusable interaction/visual rules)
-│       └── <slug>.md
-├── protocols/                     # type: protocol — Memory subsection on disk (how-we-work rules)
-│   └── <slug>.md                  # (not epic/task work; those stay in epics/ and tasks/)
-├── reviews/                       # type: review — HS-REV-<suffix>-<slug>.md companions for in_review parent specs
-│   └── HS-REV-<suffix>-<slug>.md
-├── business/                      # business model / marketing / positioning / pricing
-│   ├── positioning/               # business-positioning specs
-│   │   └── <slug>.md
-│   ├── pricing/                   # business-pricing specs
-│   │   └── <slug>.md
-│   ├── marketing/                 # business-marketing specs
-│   │   └── <slug>.md
-│   └── model/                     # business-model specs
-│       └── <slug>.md
-├── canvases/                      # JSON Canvas design files + .heyspex.yaml sidecars ([[adr-0013-canvas-vault-format-and-obsidian-interop]])
-│   ├── system-design.canvas
-│   ├── system-design.heyspex.yaml
-│   ├── diagrams/                  # per-spec editable design diagrams ([[spec-diagram-design-vs-as-built-canvas]])
-│   │   └── <spec-basename>-design.canvas
-│   ├── as-built/                  # sealed shipped spec diagrams (read-only in HeySpex)
-│   │   └── <spec-basename>.canvas
-│   └── ...
-├── roadmaps/                      # phased roadmap specs (orchestration over tasks/epics)
-│   └── HS-ROADMAP-<slug>.md
-├── roadmap-design-v2/               # Console Roadmap surface v2 design pack (protocol docs; not manifest entities)
-│   ├── roadmap-design-v2-index.md   # hub
-│   ├── roadmap-v2-implementation-checklist.md  # printable when coding
-│   ├── roadmap-v2-implementation-handoff.md  # read order + context
-│   ├── roadmap-v2-tabextend-reference.md
-│   ├── roadmap-v2-narrative-board-ux.md
-│   ├── roadmap-v2-display-titles-and-summaries.md
-│   └── roadmap-v2-*.md              # see index for full map
-├── companion-research-board/        # Chrome + Companion mirrored research board (protocol docs)
-│   ├── companion-research-board-index.md
-│   ├── companion-research-board-dual-surface-mirror.md
-│   ├── companion-research-board-implementation-checklist.md
-│   └── companion-research-board-*.md
-├── future-considerations/         # pre-task research (promote to tasks when scheduled)
-│   └── <slug>.md
-├── research/                      # audit/research/draft notes
-│   ├── HS-XBPJ-RES-bd-feature-inventory.md
-│   └── ...
-├── captures/                      # concise core capture entries — kind: idea | bug-fix | clip | reference | question | spec-import ([[capture-guardrails]])
-│   └── HS-CAP-<suffix>-<slug>.md
-├── flows/                         # planning-flow lifecycle diagrams ([[planning-flow-research-epic-lifecycle]])
-│   └── HS-FLOW-<NNN>-<slug>.md
-├── drafts/                        # ingested-but-untriaged
-│   └── <slug>.md
-├── events/                        # audit-export JSONL — one file per UTC month ([[HS-FD93-AEHR-EPIC-audit-export-heyspex-yaml-and-heyspex-retirement]])
-│   └── YYYY-MM.jsonl              #   committed snapshot of claim/focus/spec events (git-clone-is-backup)
-└── daily/                         # optional daily notes
-    └── 2026-05-14.md
-```
-
-Two committed siblings live **outside** `specs/` at the repo root, written/owned by the control plane:
-
-- **`heyspex.yaml`** — the top-level vault marker (`schema_version`, `console_url`, `vault_root`) written by `hs init` (HS-FD93-AEHR-EPIC-audit-export-heyspex-yaml-and-heyspex-retirement §2). `schema_version: 2` = the post-SCAH Neon-control-plane layout; `1` was the implicit pre-SCAH `.heyspex/`-files layout. The web companion reads it to bootstrap a vault.
-- **`.heyspex/`** — per-vault config home (adr-0009-heyspex-directory-contract): tracked `config.yaml`, `.gitignore`, `*.example` scaffolding templates, and `focus.yaml` (cross-machine pin SSOT, focus-yaml-is-tracked-pin-ssot). On the **free tier** (no Neon) this directory ALSO holds the live runtime state (`active-claims.json`, `claim-history.jsonl`, `focus-history.jsonl`); on the **paid tier** that state lives in Neon and these files are the export's free-tier source only (HS-7FA9-FREE-EPIC-zero-neon-local-only-tier). The audit export (`specs/events/`) reads whichever store is live for the tier.
-
-The L1 lives at the vault root as `heyspex-north-star.md`. The other L2 specs (`entity-model.md`, `architecture-foundations.md`, `principles.md`, `glossary.md`) also live at the root because they are foundational — in the console they surface under the **North Star** rail group, not Business (which is scoped to `business-*` types) or Memory (scoped to `memory-*` types). The glossary carries a `marketing` *tag* because marketing copy consumes its definitions, but its `type: l2` keeps it in the foundational tier. Everything else is filed under a folder matching its entity type.
-
-> [!note] Why folders, not flat?
-> Obsidian works with either, and HeySpex's link resolution treats folders as opaque (see [Wikilink resolution rules](#wikilink-resolution-rules)). Folders exist purely for human navigation and for the indexer's "list all <type>" view. Files can be moved between folders without breaking links.
-
-## Entity types
-
-The table below names every entity type in v1 and points at the frontmatter contract. Each type has its own subsection below with the full schema.
-
-| `type:` value | Folder | Hierarchy level | One-line description |
-| --- | --- | --- | --- |
-| `l1` | root | L1 | The North Star vision; one per vault. |
-| `l2` | root | L2 | Foundational architecture or model documents. |
-| `l3` | `use-cases/` | L3 | Use-case specs that elaborate L1 system use cases. |
-| `adr` | `adr/` | — | Architectural Decision Record. |
-| `task` | `tasks/` | — | The atomic unit of work. Subsumes bd's `task`, `feature`, and `bug` types. |
-| `epic` | `epics/` | — | A grouping of related tasks under a common goal. |
-| `milestone` | `milestones/` | — | The grouping **above** epic: a coherent multi-epic ship that closes when every child epic closes and the milestone's own acceptance gate is met. Distinct from the legacy `kind: milestone` task discriminator (see [`#### task`](#task)). |
-| `diagnose` | `diagnoses/` | — | A user-reported **bug fix** as first-class executable work (claimable, decomposable). Standalone by default — no epic/milestone parent required — with an optional `parent:` (epic or milestone) for organization. Carries `severity:`; surfaces on the Resolution surface as a derived `kind: "bug"` row that links back to the diagnose. Elevates the bug concept that `task` historically subsumed (see [`#### task`](#task)) into its own lane. Ratified by introduction lineage HS-OXBS-BFIX-MIL-bug-fix-diagnose-lane (milestone-precedent, like `milestone`/`pillar`). See HS-AO2F-1KZK-RES-bug-fix-resolution-task-entity-model-and. Proposed (not-yet-ratified) field extensions — a `problem_layer: symptom \| core \| unknown` classifier and an optional bidirectional `caused_by`/`symptoms` link pair — are designed in HS-4QOK-UBJM-RES-diagnose-problem-layer-classification-sy. End-to-end workflow procedure: resolution-diagnose-workflow. |
-| `pillar` | `pillars/` | — | Perpetual categorical container that never closes; cross-cutting axis for epics. Every epic carries `pillar:` (required, single primary) + optional `secondary_pillars:`. Canonical Pillars ship pre-loaded with HeySpex; customers may add scoped Pillars. Orthogonal to `milestone` (a milestone is a shippable increment; a Pillar is a perpetual concern). See HS-PILR-pillars (meta-Pillar) and HS-AWDI-PILR-RES-pm-perpetual-container-terminology (research + 2026-05-31 resolution). |
-| `agent` | `agents/` | — | A durable, user-authored **agent identity** (the "home where agents live"): name, role, preferred tools, model tier, procedures, and persona body. Compiles to the host-native agent formats (`.claude/agents/*.md`, `.cursor/agents/*.md`) — the vault spec is the SSOT, the generated files are derived. Carries HeySpex-only extras (`lane`, `color`, `owned_paths`, `golden_cases`, and `source_attribution` when imported) stripped on compile. `owned_paths` is the machine-checkable file-ownership set for parallel-agent stomp-detection; `lane` remains a human label. An **imported** agent (community-collection per HS-SURM-TMXZ-EPIC-default-agent-roster-and-import-path AC#2, or own-agent per HS-11ME-1NL4-EPIC-import-and-adopt-your-own-existing-agent) records its provenance in `source_attribution` (collection, url, path, commit, license, imported_at); authored agents omit it. Evergreen (does not close). See HS-XNX5-UQHA-MIL-agent-home. |
-| `golden-case` | `agents/golden-cases/` | — | A saved **eval fixture** for one agent identity: the prompt (and optional setup + deterministic graders) the test-before-publish harness runs against a draft agent (HS-R1JM-OAG3-EPIC-agent-testing-harness-try-a-draft-agent). Stored under the `agents/` tree so fixtures version beside the identities they exercise in the same git history. Evergreen (updated in place). Introduced by HS-8AQT-J6FU-TASK-golden-case-vault-artifact-format-and-st. |
-| `branch-brief` | `branches/` | — | "What this git branch is trying to do, and how it actually went." Plan-vs-actual + evidence for one branch. |
-| `memory-lesson` | `memory/lessons/` | — | "Here's what went wrong and how to avoid it." |
-| `memory-decision` | `memory/decisions/` | — | "Here's what we chose and why." |
-| `memory-reference` | `memory/references/` | — | "Here's where to look for X." |
-| `memory-ui-pattern` | `memory/ui-patterns/` | — | "Here's a reusable console interaction/visual pattern to copy." |
-| `memory-ux-principle` | `memory/ux-principles/` | — | "Here's a cross-brand UX rule (what/why) before implementation." |
-| `protocol` | `protocols/` | Memory subsection | Repeatable how-we-work rules for agents/humans (session-close, memory capture, MCP usage). Browsed under Memory → Protocols in console; not a peer nav item beside Memory. |
-| `review` | `reviews/` | — | Companion fill-in workspace for an `in_review` parent spec — acceptance verification, reviewer notes, memory candidates, decision. One per parent, suffix-matched 1:1. |
-| `business-positioning` | `business/positioning/` | — | Brand H1, taglines, audience qualifier, message hierarchy. |
-| `business-pricing` | `business/pricing/` | — | Tier tables, AI add-on terms, discount/refund policy. |
-| `business-marketing` | `business/marketing/` | — | Channels, launches, campaigns, copy decks. |
-| `business-model` | `business/model/` | — | Unit economics, cost structure, monetization decisions. |
-| `roadmap` | `roadmaps/` | — | Phased plan orchestrating tasks/epics; compact `roadmap_manifest` for indexer/CLI (adr-0012-roadmap-storage). |
-| `capture` | `captures/` | — | Concise capture entry; `kind:` field discriminates idea / bug-fix / clip / reference / question / spec-import. Replaces the legacy `type: idea` entity (renamed 2026-05-22 per HS-B2B8-DLQI-EPIC-capture-rename-migration-idea-to-capture). `spec-import` is the **import-origin** kind — one capture per imported foreign doc, created by the bulk spec-import feature (HS-8V8T-8SBG-EPIC-first-connect-rough-import / HS-ROIU-9P4B-EPIC-import-preview-and-confirm); grounding HS-J7T5-VEW8-RES-import-specs-one-click-feature-pipeline. |
-| `research` | `research/` | — | Audit reports, feature inventories, exploratory notes. |
-| `planning-flow` | `flows/` | — | Epic lifecycle orchestration diagram (mermaid source + canvas projection). |
-| `draft` | `drafts/` | — | Ingested content awaiting triage. |
-| `daily` | `daily/` | — | Optional daily-note scratchpad. |
-| `run-retrospective` | `dev-factory/reports/retrospectives/` (outside `specs/`, sibling to `heyspex.yaml`/`.heyspex/`) | — | A **generated** run-close record — never hand-authored, not scheduled/claimable, not a wikilink-addressable spec. One file per COO-dispatcher run, `<runId>.md` (`runId` = the run's milestone id), produced deterministically by `dev-factory/lib/retrospective.mjs` from `run-events.jsonl` + the gate ledger + `coo-dispatcher-state.json`. Frontmatter: `runId`, `generatedAt`, `shippedUnits[]` (gate-verified units), `autoAppliedDecisions[]` (dispatcher auto-applies), `stoppedReason`, `restartCondition`, `ownerGates[]` (pending owner-only gates). Body: the three Retrospective sections (what went well / what could be improved / actionable next steps). Read by What's Next's Retrospective hero (Assisted/Autonomous fronts) — see HS-4HI5-JEPA-EPIC-what-s-next-multi-run-mode-run-dashboard and the-retrospective-is-a-generated-run-rec.
-
-Adding a new entity type requires an ADR. `branch-brief` was added by adr-0008-branch-brief-and-evidence-schema; `roadmap` by adr-0012-roadmap-storage; all other core types ratified at adr-0001-vault-format. `milestone` is the exception that proves the rule: the type was used informally first — 33 `HS-MIL-*` files (e.g. HS-RM22-IART-MIL-console-ia-restructure) were hand-authored before formalization — so rather than a standalone ADR, the convention is ratified by its introduction lineage, HS-VK7C-MILE-EPIC-milestone-entity-type-and-surfacing (this schema row, the validator, MCP support) followed by HS-OFR5-M2J3-EPIC-introduce-milestones-as-highest-entity (required-parent-on-epics + the roadmap drilldown). The canonical hierarchy these two epics serve is documented in [[spec-hierarchy]].
-
-`pillar` follows the same milestone-precedent (no standalone "introduce the entity type" ADR): ratified by its introduction lineage HS-EBIL-0011-EPIC-goal-hierarchy-l2-strategic-pillars-l3 (the L2 perpetual-Pillars epic, sibling of HS-OR8V-0010-EPIC-north-star-vision-first-class-entity in HS-J6K8-NSPL-MIL-north-star-and-strategic-pillars-hierarchy) plus the design captured in HS-AWDI-PILR-RES-pm-perpetual-container-terminology; the privacy-boundary side of the work (aggregate-learning telemetry on the Pillar Library) is in adr-0016-pillar-library-privacy-boundary. The 2026-05-31 resolution that produced the Pillar tier also retired the previously planned L3 Themes tier (per-epic teleological anchoring collapsed into perpetual Pillars). First canonical Pillar filed: HS-PILR-pillars (the meta-Pillar; dogfooding instance).
-
-`agent` follows the same milestone/pillar-precedent (no standalone "introduce the entity type" ADR): ratified by its introduction lineage HS-XNX5-UQHA-MIL-agent-home (this schema row, the frontmatter-schema branch, the `KIND_RULES`/`TYPE_TO_FOLDER` registration, and the compiler that exports identities to host-native `.claude/agents`/`.cursor/agents` formats). The agent identity is the durable, user-authored counterpart to the ephemeral control-plane presence (`active_claims`) — the vault holds *who an agent is*, the control plane holds *what it is doing now*. Positioning context: HS-O46R-R30X-RES-agent-layer-as-the-demand-side-twin-of-t.
-
-`golden-case` follows the same introduction-lineage precedent under HS-R1JM-OAG3-EPIC-agent-testing-harness-try-a-draft-agent / HS-8AQT-J6FU-TASK-golden-case-vault-artifact-format-and-st: a first-class vault artifact for agent eval fixtures (not JSON sidecars or console-only blobs). Bodies follow a fixed section contract; optional deterministic graders validate against `specs/schemas/golden-case-body.schema.json`.
-
-## Lifecycle classes
-
-Entity types fall into four lifecycle classes. The class determines which subset of the [universal status enum](#frontmatter-schemas) a type uses, when its `canonical:` flag flips, and what the close-out ritual is. **A reader asking *"can I flip this file's status to `in_review`?"* should consult this section first — the answer depends entirely on which class the file's type belongs to.**
-
-### Evergreen (living reference substrate)
-
-`l1` · `l2` · `l3` · `adr` · `pillar` · `agent` · `golden-case` · `protocol` · `memory-lesson` · `memory-decision` · `memory-reference` · `memory-ui-pattern` · `memory-ux-principle` · `research` · `business-positioning` · `business-pricing` · `business-marketing` · `business-model`
-
-These are **standalone reference artifacts**. `status: open` is the resting state and stays the resting state for the doc's entire life. There are no `in_review` or `closed` transitions — the close-as-historical-record ritual does not apply.
-
-- **Updates** happen in-place: amend the body, bump `updated:`, append a change-log row.
-- **Supersession** is the only "lifecycle event" — record it via relational fields (`supersedes:` / `superseded_by:` on ADRs, `superseded_by:` on memories and research, `canonical: false` as the universal drift tombstone per canonicalization-arbiter-is-link-graph-not-policy). The original stays as the historical record at `status: open`.
-- **Research lineage** to downstream artifacts is recorded via `enhances:`, `spawned_epics:`, `bound_epic:`, `incorporated_into:` — these are relational edges, **not** status transitions. See research-is-evergreen for the full rule and the deferred MCP-tool / UI-epic / validator surfaces still being remediated.
-
-Session-close protocol carve-out: an agent who touched an evergreen doc this session **must not** flip its status. See [[session-close-protocol]] step 1.
-
-### Trackable plan-side (open → in_progress → in_review → closed)
-
-`task` · `epic` · `milestone` · `diagnose` · `review` · `branch-brief` · `planning-flow`
-
-These are **work containers** with a definite scope and a moment at which they're done. They follow the full status flow and are **frozen at close** per closed-trackable-specs-are-historical-record-not-living-docs — the body becomes historical record of the plan as it was at the moment of close.
-
-- **Session close** flips completed-this-session specs to `status: in_review` and creates an `HS-REV-<suffix>` companion ([[session-close-protocol]]).
-- **Reviewer close** flips `in_review → closed`, flips `canonical: true → false`, optionally sets the `outcome:`/`outcome_note:` verdict (`met` | `partially-met` | `not-met` — reviewer judgment, never inferred; see §Iteration lineage), and freezes the frontmatter forever after.
-- **`branch-brief`** closes when the branch ships; **`planning-flow`** closes with its bound epic.
-
-### Single-shot ingest (triage-driven; promotion replaces closure)
-
-`capture` · `draft` · `daily`
-
-These are **inbound surfaces** scoped to one input session. They don't close in the lifecycle sense — they get **promoted** (capture → research / task / epic; draft → some other type) or remain as a dated scratchpad (daily).
-
-- **`capture`** carries `promoted_to:` as a binary pointer to the first downstream artifact and `informs_research:` as the M:N lineage list (see the `capture` schema below).
-- **`draft`** is triaged by editing the `type:` field in place and moving the file to the destination folder.
-- **`daily`** is a single-date scratchpad — no status semantics; the date IS the lifecycle.
-
-### Per-instance (class declared at filing time)
-
-`roadmap`
-
-`roadmap` is the one type whose lifecycle class depends on the specific roadmap. A perpetual product roadmap is evergreen; a per-quarter ship plan is trackable. Each `HS-ROADMAP-*` declares its class via its own `status:` value at filing: roadmaps that never close stay `open`; roadmaps with a defined ship horizon use the trackable flow. See adr-0012-roadmap-storage for the compact-manifest design that supports both shapes.
-
-### Cross-reference summary
-
-| Class | Status values used | Close-as-historical-record? | `canonical: false` trigger |
-|---|---|---|---|
-| Evergreen | `open` (resting state) | No | Supersession (relational edge) |
-| Trackable plan-side | `open` → `in_progress` → `in_review` → `closed` (plus `deferred`) | Yes — frozen at close | Close-out write |
-| Single-shot ingest | `open` (capture/draft pre-promotion) / N/A (daily) | No — promoted or archived by date | Not used |
-| Per-instance | Declared at filing | Per-instance | Per-instance |
-
-## Identity, IDs, and filenames
-
-> [!important] Identifier format migration in progress (updated 2026-08-11)
-> The vault is migrating to **file-key-first** (era 3) ordering: `HS-<file key>-<family key>-<type label>-<title slug>` — the leading token after `HS-` is the **unique per-file ID**, not the family (HS-6B0S-Q9YG-RES-naming-system-v3-file-key-first, rulings naming-v3-7-rulings-hs-namespace-kept; owner re-confirmed the token order 2026-08-11). On disk today most files are still **family-first** (era 2, `HS-<family key>-<type label>-…`) or legacy type-first (era 1); the vault-wide rename is built and **pending owner review/execution** (HS-L6Y4-01D7-EPIC-deterministic-rename-with-link-rewrite). The type label's position (1st/2nd/3rd token) tells you a filename's era — never guess which token is the file ID by position alone; read frontmatter `file_id:`/`id:`. The ID-format and filename tables below still show older orderings pending the flip; the token **names** are canonical in every era. Plain-language explainer: how-spec-ids-and-naming-work.
-
-### Identifier tokens (file key · family key · type label · title slug)
-
-A managed spec's basename decomposes into named tokens. Canonical names per glossary §Identifier anatomy and HS-37O7-T9KP-RES-identifier-token-terminology-family-key (external-validated; supersedes the "pipeline ID / type token / file ID" names in HS-MF8M-CCVE-RES-family-first-spec-identifier-format-hs-i).
-
-| Token | Example | Role |
-| --- | --- | --- |
-| **File key** | `L6Y4` | The per-file 4+ char uppercase-alphanumeric key (at least one letter), **unique vault-wide** — the identity and one-token citation handle for exactly one file. Recorded in frontmatter `file_id:` (SSOT) and embedded in the filename; becomes the `id:` itself (`id: HS-L6Y4`) under era 3. Server-minted, never hand-picked. |
-| **Family key** | `P2TR` | The shared 4+ char alphanumeric code that groups one initiative's specs — an epic and all its child tasks, research, and reviews — into one greppable **family** (`grep HS-P2TR` returns the whole family). Shared across the family; uniqueness is enforced on the full **basename** per kind, never on the family key alone (see vault-id-assignment-protocol §Shared-suffix families). |
-| **Type label** | `TASK` | The entity-kind token (`TASK`, `EPIC`, `MILESTONE`, `RESEARCH`, `REVIEW`, …). A **human-readable hint only**. |
-| **Title slug** | `verification-state-schema` | The lowercased-hyphenated descriptive tail derived from `title:` — the part that makes each basename unique within a family. |
-
-**Filename shapes (era = type-label position):**
-- **File-key-first (era 3, ratified target):** `HS-<file key>-<family key>-<type label>-<title slug>.md` → `HS-L6Y4-01D7-EPIC-deterministic-rename-with-link-rewrite.md` — lands vault-wide with HS-L6Y4-01D7-EPIC-deterministic-rename-with-link-rewrite.
-- **Family-first (era 2, current on disk / current minting):** `HS-<family key>-<type label>-[<file key>-]<title slug>.md` → `HS-P2TR-TASK-verification-state-schema.md`, `HS-0G910-EPIC-G3D3-api-foundation-keys-scopes-error.md`
-- **Type-first (era 1, legacy):** `HS-<type label>-<family key>-<title slug>.md` → `HS-TASK-P2TR-verification-state-schema.md`
-
-**Routing rule (SSOT for entity type):** code MUST determine a spec's entity type from the frontmatter **`type:`** field (and its directory), **never** by parsing the type label out of the filename. The type label is a convenience hint that survives out of directory context (wikilinks, search results, clipboard, terminal output); it is **not** authoritative and must never drive a mutation, a route, or a reclassification on its own. This is the semantic-identifier guardrail from HS-MF8M-CCVE-RES-family-first-spec-identifier-format-hs-i (don't route on parsed-ID semantics).
-
-**Retired / avoid:** **"suffix"** (the legacy name for the family key — self-contradictory once the family key leads), **"pipeline ID"** (overloaded with CI/CD + the feature-pipeline graph), **"prefix" / "type prefix"** for the family key (industry convention encodes *type*, not a family). The legacy term `<suffix>` still appears in the tables below and in the `legacy_slug_only` naming atoms until the Phase 3 codegen flip.
-
-### ID format
-
-| Entity type | ID format | Example |
-| --- | --- | --- |
-| `l1` | `HS-L1` | `HS-L1` |
-| `l2` | `HS-L2-<UPPER>` | `HS-L2-ENTITY`, `HS-L2-FOUNDATIONS` |
-| `l3` | `HS-UC-<short>` | `HS-UC-CAPTURE` |
-| `adr` | `HS-ADR-NNNN` (zero-padded sequence) | `HS-ADR-0001` |
-| `task` | `HS-TASK-<suffix>` — `<suffix>` is 4+ random A-Z0-9 (vault-id-assignment-protocol). Pre-2026-05-22 entries (`HS-NNNN`, `HS-<4+ A-Z0-9>`) were migrated to this prefix. | `HS-TASK-K7M2` |
-| `epic` | `HS-EPIC-<suffix>` — same rules | `HS-DE8L`, `HS-V888` |
-| `milestone` | `HS-MIL-<suffix>` — `<suffix>` is 4+ uppercase `A–Z0–9` (vault-id-assignment-protocol); legacy 4-character mnemonic IDs (e.g. `HS-RM22`) remain valid | `HS-RM22`, `HS-1JC8` |
-| `diagnose` | `HS-DIAG-<suffix>` — `<suffix>` is 4+ random A-Z0-9 (vault-id-assignment-protocol) | `HS-DIAG-K7M2` |
-| `pillar` | `HS-PILR-<slug>` (canonical; slug uniquely identifies the concept; no random suffix) or `HS-PILR-<suffix>-<slug>` (customer-scoped; random 4+ A-Z0-9) | `HS-PILR-pillars`, `HS-PILR-scaling`, `HS-PILR-K7M2-team-onboarding` |
-| `branch-brief` | `HS-BB-<slug>` | `HS-BB-feature-checkout-redesign` |
-| `memory-lesson` | `HS-LES-<slug>` | `HS-LES-bd-process-leak` |
-| `memory-decision` | `HS-DEC-<slug>` | `HS-DEC-dep-relate-for-epic-children` |
-| `memory-reference` | `HS-REF-<slug>` | `HS-REF-dolt-time-travel-docs` |
-| `memory-ui-pattern` | `HS-UIP-<slug>` | `HS-UIP-rail-active-vs-keyboard-cursor` |
-| `memory-ux-principle` | `HS-UXP-<slug>` | `HS-UXP-toggle-current-state-semantics` |
-| `protocol` | `HS-PROTO-<slug>` | `HS-PROTO-session-close` |
-| `review` | `HS-REV-<suffix>` — `<suffix>` matches the parent task/epic id 1:1 (e.g. parent `HS-76RX` → review `HS-QMHO`). Detection: [`extractSpecSuffix` in `console/src/lib/vault.ts:155`](../console/src/lib/vault.ts). | `HS-QMHO`, `HS-R3HO`, `HS-CCEQ` |
-| `business-positioning` | `HS-BIZ-POS-<slug>` | `HS-BIZ-POS-2nd-brain-harness-for-specs` |
-| `business-pricing` | `HS-BIZ-PRI-<slug>` | `HS-BIZ-PRI-tiers-and-byok-2026-05` |
-| `business-marketing` | `HS-BIZ-MKT-<slug>` | `HS-BIZ-MKT-launch-playbook-companion` |
-| `business-model` | `HS-BIZ-MOD-<slug>` | `HS-BIZ-MOD-flat-per-vault-economics` |
-| `roadmap` | `HS-ROADMAP-<SLUG>` | `HS-ROADMAP-PRODUCT` |
-| `research` | `HS-RES-<suffix>` — legacy `HS-RES-NNN` or random `HS-RES-<4+ A-Z0-9>` (vault-id-assignment-protocol) | `HS-RES-001`, `HS-RES-K7M2` |
-| `capture` | `HS-CAP-<suffix>` — same rules; legacy `HS-IDEA-<suffix>` preserved in `legacy_idea_id:` for archaeology | `HS-CAP-JKLN`, `HS-CAP-OAP3` |
-| `agent` | `HS-AGENT-<suffix>` — `<suffix>` is 4+ random A-Z0-9 (vault-id-assignment-protocol) | `HS-634I` |
-| `golden-case` | `HS-GCASE-<suffix>` — same rules | `HS-HPIO` |
-| `planning-flow` | `HS-FLOW-NNN` | `HS-FLOW-001` |
-| `draft` | `HS-DRAFT-<slug>` | `HS-DRAFT-2026-05-14-1130-article-link` |
-| `daily` | `HS-DAILY-YYYY-MM-DD` | `HS-DAILY-2026-05-14` |
-
-**New task/epic/research/capture IDs** (console `POST /api/specs`, MCP `heyspex_save_research`, agents): allocate a random 4-character suffix from `A–Z` and `0–9`, checking the full vault for collisions (frontmatter `id` and filename prefix). When every combination at the current length is taken, the suffix grows to 5 characters, then 6, and so on. Legacy sequential IDs (`HS-NNNN`, `HS-RES-NNN`, `HS-IDEA-*`, slug-only research filenames) remain valid in the read-path until HS-23PN-9HVY-TASK-capture-rename-repo-wide-wikilink-rewrite retires them. Validate with `npm run validate:vault-ids` at the repo root.
-
-### Filename derivation
-
-The filename is **derived from the ID + an optional slug**, lowercased, with the same prefix the ID uses minus the `HS-` prefix (kept lowercase in filenames for readability):
-
-| Entity | Filename pattern | Example |
-| --- | --- | --- |
-| `l1` | `heyspex-north-star.md` (literal, only one) | `heyspex-north-star.md` |
-| `l2` | `<topic>.md` (literal slug) | `entity-model.md` |
-| `l3` | `uc-<short>.md` | `uc-capture-intent.md` |
-| `adr` | `adr-NNNN-<slug>.md` | `adr-0001-vault-format.md` |
-| `task` | `HS-TASK-<suffix>-<slug>.md` | `HS-TASK-K7M2-fix-foo.md` |
-| `epic` | `HS-EPIC-<suffix>-<slug>.md` | `HS-0007-EPIC-console-resilience.md`, `HS-W9ZE-EPIC-design-system-enforcement-auto-surface-u.md` |
-| `milestone` | `HS-MIL-<suffix>-<slug>.md` | `HS-IART-MIL-console-ia-restructure.md` |
-| `diagnose` | `HS-DIAG-<suffix>-<slug>.md` | `HS-DIAG-K7M2-console-startup-lag.md` |
-| `pillar` | `HS-PILR-<slug>.md` (canonical; slug IS the ID with no random suffix) or `HS-PILR-<suffix>-<slug>.md` (customer-scoped) | `HS-PILR-pillars.md`, `HS-PILR-K7M2-team-onboarding.md` |
-| `branch-brief` | `<branch-slug>.md` | `feature-checkout-redesign.md` |
-| `memory-lesson` | `<slug>.md` | `bd-process-leak.md` |
-| `memory-decision` | `<slug>.md` | `dep-relate-for-epic-children.md` |
-| `memory-reference` | `<slug>.md` | `dolt-time-travel-docs.md` |
-| `memory-ui-pattern` | `<slug>.md` | `rail-active-vs-keyboard-cursor.md` |
-| `memory-ux-principle` | `<slug>.md` | `toggle-current-state-semantics.md` |
-| `protocol` | `<slug>.md` | `session-close-protocol.md` |
-| `review` | `HS-REV-<suffix>-<slug>.md` (slug truncated from parent's slug, ≤40 chars) | `HS-SK1L-REV-hs-idea-skill-four-beats-layered-confirms.md` |
-| `research` | `HS-RES-<suffix>-<slug>.md` (legacy: `<slug>.md` only) | `HS-RES-K7M2-agent-governance.md` |
-| `capture` | `HS-CAP-<suffix>-<slug>.md` | `HS-CAP-JKLN-vault-triage.md` |
-| `agent` | `HS-AGENT-<suffix>-<slug>.md` | `HS-9TNK-AGENT-code-reviewer.md` |
-| `golden-case` | `HS-GCASE-<suffix>-<slug>.md` | `HS-R4VW-GCASE-review-missing-ac.md` |
-| `planning-flow` | `HS-FLOW-<NNN>-<slug>.md` | `HS-FLOW-001-epic-planning-flow-studio.md` |
-| `draft` | `<slug>.md` | `2026-05-14-1130-article-link.md` |
-| `daily` | `YYYY-MM-DD.md` | `2026-05-14.md` |
-
-Slug rules: lowercase, ASCII, dash-separated, no trailing punctuation, no leading number for non-task types.
-
-> [!note] Branch-brief slug
-> For `branch-brief` the slug is **derived from the git branch name**: lowercased, every run of non-`[a-z0-9]` characters collapsed to a single `-`, trailing `-` stripped. `feature/checkout-redesign` → `feature-checkout-redesign`. The raw, unsanitized branch name is preserved in the required `branch:` field — the slug is for the filesystem and wikilink resolution only; git lookups use `branch:`. Ratified in adr-0008-branch-brief-and-evidence-schema.
-
-> [!note] Why not put the ID in the filename for memories?
-> bd memory keys are content-derived (`lessons/bd-process-leak`), and the Builder already thinks in those terms. The filename `bd-process-leak.md` IS the key, the ID is the metadata. Wikilink resolution finds the file by name; the `HS-LES-` prefix in the `id:` field is for the index and for stable cross-references.
-
-### ID + filename for the migration
-
-The migration plan (migration-from-bd) maps each bd issue to a new HeySpex task ID by sorting bd issues by `created_at` and assigning `HS-U2K9`, `HS-FMWM`, etc., in that order. The original bd ID is preserved as `legacy_bd_id` in frontmatter so cross-references in old commits/logs remain resolvable.
-
-## Frontmatter schemas
-
-Every spec opens with a YAML frontmatter block. The schemas below define **required** fields (must be present and non-empty) and **optional** fields (may be omitted).
-
-Universal fields (every spec has these):
-
-```yaml
-id:        # required, string, matches the entity type's ID format
-name:      # required, string, human-readable title
-type:      # required, one of the entity type values above
-status:    # required, see status enum below
-priority:  # required, integer 0–4 (0 = highest)
-owner:     # required, string (email or handle) — the ORIGINATING + accountable human (doubles as author).
-           #   See §Authorship provenance below.
-created:   # required, ISO-8601 date (YYYY-MM-DD)
-updated:   # required, ISO-8601 date
-contributors: # optional, list of "Name <email>" — OTHER humans who later enhanced the doc (append-only;
-              #   OMIT when empty). Auto-stamped, never hand-maintained. See §Authorship provenance.
-assisted_by:  # optional, list of "AGENT" or "AGENT:MODEL" — agents/IDEs + model that assisted (append-only;
-              #   OMIT when empty). Auto-stamped, never hand-maintained. See §Authorship provenance.
-tags:      # optional, list of strings
-related:   # optional, list of wikilinks (alternative to inline body links)
-what_matters: # optional, enum: star | heart — per-spec user-priority signal
-```
-
-**`what_matters`** is the per-spec user-priority signal that replaced the retired What Matters column (scheduler-and-whats-next-what-matters-column-mechanics, HS-78E7-Y9OJ-EPIC-deterministic-priority-scheduler). It is optional and two-level:
-
-- `star` (★) — *priority*: "consider this please."
-- `heart` (♥) — *very important*: "appreciate this being next if at all possible." A stronger signal than `star`.
-- absent — unflagged (no default is injected).
-
-The value is held verbatim; an unrecognized value is tolerated by the parser and emits a warn-only `INVALID_WHAT_MATTERS` validator notice rather than an error. A Phase 7b scheduler stage consumes it for ordering.
-
-### Authorship provenance
-
-Three universal fields carry GitHub-faithful provenance, following the cross-foundation `Assisted-by:` convention (Linux Kernel, Fedora, LLVM, OpenTelemetry) that keeps the human as the sole accountable author and records AI as a tool that *assisted*, not a co-author. Origin: HS-N1WG-W48S-RES-git-github-authorship-attribution-best-p → HS-Y4JH-IKIM-EPIC-authorship-provenance-frontmatter-owner. The SSOT question (frontmatter vs git history) is resolved in provenance-frontmatter-is-ssot-not-git-echo.
-
-| Field | Who | Item format | Cardinality |
-| --- | --- | --- | --- |
-| `owner` | the **originating + accountable** human (doubles as author) | handle or email (e.g. `pwher`) | single scalar |
-| `contributors` | **other** humans who later enhanced the doc | `Name <email>` — GitHub form, round-trips with the `Co-authored-by:` trailer | append-only list |
-| `assisted_by` | agents/IDEs + model that assisted | `AGENT` or `AGENT:MODEL` — e.g. `Claude Opus 4.8`, `Cursor` | append-only list |
-
-Semantics (apply to every entity kind):
-
-- **`owner` is universally required** and unchanged in type — only its meaning is enriched here (originator + accountable, not merely a pointer). A later ownership *transfer* is not preserved in frontmatter; git history (first-commit author) retains the original creator. Acceptable trade per HS-N1WG-W48S-RES-git-github-authorship-attribution-best-p.
-- **`contributors` and `assisted_by` are universal-but-optional and omit-when-empty** — they are not emitted as empty lists, so a solo-vault doc stays clean and only grows a list once a second human or an agent touches the doc.
-- **Append-only + de-dup, never reorder/remove.** A new acting human ≠ `owner` is appended to `contributors`; an acting agent is appended to `assisted_by`; an entry already present is not duplicated.
-- **Auto-stamped, never hand-maintained.** Seeded at creation (`owner` from the resolved user, `assisted_by` from the acting agent) and appended on edit, sourced from the existing claim/session trail (Neon `active_claims`). Authoring/wiring lives in HS-Y4JH-IKIM-EPIC-authorship-provenance-frontmatter-owner.
-
-> [!note] Schema addition self-gating
-> Per entity-model-self-gates-schema-changes-via-adr, new reserved frontmatter keys are normally gated behind an ADR. `contributors`/`assisted_by` are admitted here **without a standalone ADR** under the same milestone-precedent the `milestone` and `pillar` entity types used: they are additive, optional, omit-when-empty enrichments of the existing universal `owner` field (not a new entity type or a new lifecycle), ratified by their introduction lineage HS-N1WG-W48S-RES-git-github-authorship-attribution-best-p → HS-Y4JH-IKIM-EPIC-authorship-provenance-frontmatter-owner. The decision rationale is recorded in provenance-frontmatter-is-ssot-not-git-echo.
-
-### Artifact linkage
-
-An optional `artifact:` mapping records a published Claude Artifact that this spec/doc is the vault source for, so the artifact is never the only copy of its content — HS-6YIS-5GSW-EPIC-artifacts-as-vault-documents. **Universal** — unlike the type-specific schemas below, it attaches to ANY entity kind (a task, an epic, a research doc, a memory doc, or a non-frontmatter file like a roadmap page — see the HTML variant below), because a published artifact can belong to a doc at any level, not one lifecycle stage.
-
-```yaml
-artifact: { title: "…", url: "https://claude.ai/code/artifact/…", version: "…", updated: "2026-08-23" }
-# title:    required when artifact: is present — the artifact's display title (matches its published <title>/heading).
-# url:      required — the published URL.
-# version:  optional, string — the last-published version stamp this vault file was confirmed against. This is
-#           a LOCAL claim, not a live read: it is the freshness anchor for the push-first stale-guard
-#           (HS-6YIS-5GSW-EPIC part 2) — before publishing this file over the artifact, the publishing session
-#           reads the LIVE page and confirms it is not ahead of this stamp, THEN writes the new version back
-#           here after a successful publish. Never hand-edited to "catch up" without actually reading the live
-#           page first (the incident this field exists to prevent: [[a-published-artifact-and-its-vault-copy]]).
-# updated:  optional, ISO-8601 date — when this vault file was last published/stamped against the artifact.
-```
-
-Either a single-line flow mapping (above) or an equivalent nested block mapping is valid YAML; the artifact-publish tooling (HS-6YIS-5GSW-EPIC-artifacts-as-vault-documents part 2, `scripts/hs-artifact.mjs`) reads and writes the flow-mapping form. Omit the whole `artifact:` key when the doc has no published artifact (omit-when-empty, same posture as `contributors`/`assisted_by`).
-
-**Non-frontmatter vault files** (a raw HTML page under `specs/roadmap/`, for example, has no YAML frontmatter at all): the same four fields are carried as a single machine-readable `ARTIFACT-STAMP: {...}` JSON line inside the file's existing leading `<!-- -->` source-of-truth comment, read/written by the same tooling. This is the shape `specs/roadmap/heyspex-sprint-roadmap0829.html` uses.
-
-> [!note] Schema addition self-gating
-> Per entity-model-self-gates-schema-changes-via-adr, `artifact:` is admitted here **without a standalone ADR** under the same milestone-precedent as `contributors`/`assisted_by` above: additive, optional, omit-when-empty, not a new entity type or lifecycle — ratified by its introduction lineage, the owner's immediate order following the incident recorded in a-published-artifact-and-its-vault-copy → HS-6YIS-5GSW-EPIC-artifacts-as-vault-documents.
-
-Status enum (universal):
-
-- `draft` — under active authorship, not yet ratified.
-- `open` — ratified and available to work against (for tasks, epics) or stable (for L1/L2/L3/ADR).
-- `in_progress` — claimed and being executed (tasks only).
-- `in_review` — implementation complete, awaiting human verification before closure (tasks only).
-- `closed` — done (tasks) or superseded (ADRs).
-- `deferred` — **deprecated** (2026-06-24 per parked-is-the-single-hold-status-deferre). Use `status: parked` for indefinite hold or `defer_until:` for dated snooze instead. Kept for read-back-compat only.
-
-### Type-specific schemas
-
-#### `l1`
-
-```yaml
-type: l1
-aliases:   # optional, list of alternative names
-brand:     # optional, mapping with canonical/variants/pronunciation/comma
-domains:   # optional, list of relevant domains
-version:        # optional, monotonic integer — bumped on every material edit to the record.
-               #   The alignment-drift detector ([[HS-E3D3-RDFT-EPIC-alignment-drift-detector-into-resolution]])
-               #   compares the version an epic was last aligned against (its `alignment_baseline`)
-               #   to this current version; a bump past the baseline surfaces a `drift` resolution item.
-last_edited_at: # optional, ISO-8601 timestamp of the last edit to the record. Timestamp FALLBACK for
-               #   drift detection when an epic carries no per-layer `alignment_baseline`: the layer's
-               #   `last_edited_at` newer than the epic's `alignment_reviewed_at` means drift.
-```
-
-Only one `l1` exists per vault. The `version` / `last_edited_at` fields are the versioning prerequisites carried from HS-OR8V-0010-EPIC-north-star-vision-first-class-entity; they make the L1 record a drift baseline anchor for the alignment-drift detector.
-
-#### `l2`
-
-Universal fields only. No required L2-specific fields.
-
-#### `l3` (use case)
-
-```yaml
-type: l3
-actors:           # required, list of actor names from L1
-trigger:          # required, string — what initiates this use case
-outcomes:         # required, list — observable end states
-depends_on:       # optional, list of wikilinks to other use cases
-```
-
-#### `adr`
-
-```yaml
-type: adr
-decision_date:    # required, ISO-8601 date
-deciders:         # required, list of strings
-supersedes:       # optional, wikilink to ADR this replaces
-superseded_by:    # optional, wikilink to ADR replacing this
-status:           # adr-status enum: proposed | accepted | deprecated
-                  #   `superseded` is DEPRECATED 2026-06-03 per [[superseded-enum-values-deprecated-use-canonical-false-and-superseded-by]]
-                  #   New writes: set `canonical: false` + `superseded_by: '[[<successor>]]'` instead. Existing
-                  #   ADRs that already carry `status: superseded` stay as historical record per the
-                  #   immutability principle ([[closed-trackable-specs-are-historical-record-not-living-docs]]) —
-                  #   readers infer `canonical: false` from the legacy value.
-canonical:        # universal flag — true (or absent) = current/authoritative; false = historical record
-                  #   (current canonical is at `superseded_by:`). Flipped at supersession-time via
-                  #   [[supersession-protocol]]; frozen thereafter.
-```
-
-The ADR-specific `status` enum overrides the universal status enum for ADRs. The `canonical:` field applies to ADRs the same way it does to every spec type.
-
-#### `task`
-
-```yaml
-type: task
-kind:             # one of: infra | foundation | feature | polish (scheduler tier — SSOT is
-                  #   SCHEDULER_KIND_VOCAB in console/src/lib/indexer/vault-rules.mjs). Legacy bd
-                  #   kinds (bug | spike | story | milestone) are retired; migrate via
-                  #   scripts/migrate-to-scheduler-metadata.mjs. Bugs now have their own lane
-                  #   (kind: bug-fix capture → HS-DIAG-* diagnose spec → Resolution surface).
-assignee:         # optional, string
-started_at:       # optional, ISO-8601 datetime — set on first transition to in_progress
-closed_at:        # optional, ISO-8601 datetime
-close_reason:     # optional, enum: shipped | deprecated | obsolete | wont_fix | duplicate
-                  #   shipped → "Done" archive view; deprecated* → "Deprecated" archive view
-                  #   `superseded` is DEPRECATED 2026-06-03 per [[superseded-enum-values-deprecated-use-canonical-false-and-superseded-by]]
-                  #   New writes that involve supersession: omit `close_reason` (or use another value
-                  #   like `deprecated`) and set `canonical: false` + `superseded_by:` instead.
-                  #   Existing closed specs with `close_reason: superseded` stay as historical record
-                  #   per immutability ([[closed-trackable-specs-are-historical-record-not-living-docs]]).
-defer_until:      # optional, ISO-8601 date — dated snooze evaluated by isDeferredNow(); scheduler-invisible
-                  #   until the date, then auto-returns with no status change ([[parked-is-the-single-hold-status-deferre]]).
-                  #   Distinct from `status: parked` (indefinite hold). Do NOT pair with deprecated `status: deferred`.
-target:           # optional, string — repo-relative path(s) of the file(s) an autonomous builder edits
-                  #   for this task (comma-separated for multi-file). DISPATCH METADATA for the dev-factory
-                  #   overnight loop: its backlog selector only dispatches an open, dependency-ready task
-                  #   that carries target:; without it the task is skipped with a warning. Hand-editing this
-                  #   field is allowed (it is not status). Owner-approved 2026-07-04 (HS-BMAW go-live);
-                  #   interim docs lived in dev-factory/README.md §Vault-task target: frontmatter.
-test:             # optional, string — the test file that gates the autonomous build of this task
-                  #   (scoped vitest run / self-test). When omitted the gate falls back to tsc --noEmit
-                  #   plus the module's own self-test conventions. Pairs with target: above.
-suggested_model:  # optional, string — breakdown-authored Ollama model id for local builder dispatch
-                  #   (e.g. qwen3-coder:30b). Honored as first candidate in scheduler/backlog-selector;
-                  #   falls back through routing-table build chain when unavailable.
-suggested_machine:# optional, string — machine key from routing-table (specops-gpu0, basement-geek, …).
-                  #   Scheduler tries this machine first when reachable + capable.
-recommended_num_ctx: # optional, integer — Ollama num_ctx bucket (16384 | 32768 | 65536 | 131072).
-                  #   pick-num-ctx.mjs honors when ≤ machine ceiling (spec-ops 65536, basement 131072).
-estimated_context_tokens: # optional, integer — breakdown estimate of prompt tokens (target + deps + spec).
-context_files:    # optional, list of repo-relative paths — passed to builder.mjs as --extra (types, deps).
-                  #   Omit the target file (builder always reads it). Body duplicate: ## Builder brief.
-fit_assessment:   # optional, enum: safe | tight | overflow — breakdown confidence in context fit.
-parallel_safe:    # optional, boolean — false when task must not run concurrently (shared config/schema).
-affects_paths:    # optional, list of repo-relative paths — read/write set for stomp detection at dispatch.
-parallel_group:   # optional, string — wave id; tasks in same group may run together when paths disjoint.
-builder_profile:  # optional on child tasks only when inherited from epic; see builder-fleet-capability-reference.
-canonical:        # universal flag — true (or absent) = current/authoritative; false = historical record.
-                  #   Flipped to false during the in_review → closed transition for plan-side specs per
-                  #   [[session-close-protocol]] §Reviewer responsibilities step 4, or at supersession per
-                  #   [[supersession-protocol]]. `status: parked` keeps `canonical: true` (paused, not historical).
-superseded_by:    # optional, wikilink — pointer to the current canonical when canonical: false.
-                  #   Required when canonical: false AND there is a successor (per [[supersession-protocol]]).
-                  #   When close_reason was historically deprecated|duplicate, this field can still point
-                  #   at the successor; the legacy enum value stays as historical record.
-
-# Dependency edges (see "Dependencies" section below)
-blocks:           # optional, list of wikilinks — this task blocks these
-blocked_by:       # optional, list of wikilinks — these tasks block this one
-related:          # optional, list of wikilinks — soft, navigational
-parent:           # optional, single wikilink — hierarchical parent
-children:         # optional, list of wikilinks — hierarchical children
-discovered_from:  # optional, single wikilink — provenance edge ("this task was born while
-                  #   working on X"). Also the code-audit **cleanup→task exit**: a task filed
-                  #   from a `research_type: code-audit` finding row (Action: task) sets this to
-                  #   the source `[[HS-RES-…]]` (see §research "Code-audit findings table" /
-                  #   [[HS-7D0I-WL88-TASK-code-audit-research-type-with-a-defined]]).
-
-# Delegation / task-split lineage ([[HS-HXE2-YQ5A-EPIC-delegation-defer-work-from-one-agent-to]],
-# [[HS-DTL1-CX5K-CAP-task-split-handoff-when-context-runs-low]], [[HS-PD6K-NCH5-TASK-handoff-envelope-schema-and-split-child]])
-split_of:         # optional, single wikilink — parent task or epic this spec continues (option B:
-                  #   random child id + frontmatter linkage). Must pair with split_index.
-split_index:      # optional, positive integer — 1-based sequence among siblings split from the
-                  #   same split_of parent. Required when split_of is set.
-handoff_id:       # optional, string — dedup key for idempotent defer re-posts
-                  #   ([[HS-PJN4-W146-TASK-defer-idempotency-handoff-id-and-cross-a]]).
-
-# Ingest + roadmap admission ([[plan-ingest-review-roadmap-workflow]], [[adr-0012-roadmap-storage]])
-ingest_draft:           # optional, wikilink to draft this spec was promoted from
-forked_from:            # optional, wikilink — source spec when forked from sealed as-built diagram ([[HS-G8JS-F6P1-TASK-fork-spec-from-as-built-canvas]])
-forked_from_canvas:     # optional, string — vault-relative as-built canvas path
-has_diagram:            # optional, boolean — spec contains architecture mermaid; indexes Shipped gallery
-source_intent_hash:     # optional, copied from draft at promote time
-roadmap_admission:      # optional, enum: pending | scheduled | horizon | declined
-roadmap_phase:          # optional, string — phase id from a HS-ROADMAP-* manifest (e.g. M3)
-                        # horizon backlog: set priority: 4 and/or tag horizon; roadmap_admission: horizon
-
-# Optional structured content; preferred form is markdown sections in body
-acceptance:       # optional, list of acceptance criteria. Each entry is EITHER a plain string
-                  #   (prose criterion — stays fully valid) OR an object carrying a runnable check:
-                  #     - text: "<the criterion>"
-                  #       verification:        # optional — how a machine proves this criterion
-                  #         kind: test | lint | types | command | guard | evidence
-                  #         run:  "<command or test path>"   # required for machine kinds
-                  #         expect: exit-0 | no-net-new      # default exit-0
-                  #   `kind: evidence` names an evidence type a human/receipt records instead of a
-                  #   command. Prose-only criteria are receipt-marked "human-verified" honestly.
-                  #   Backward compatible by construction ([[HS-MNW5-IU2S-EPIC-executable-acceptance-criteria-and]]);
-                  #   kinds/expects mirror the checks-manifest contract ([[checks-manifest-authoring]],
-                  #   parser: spex-console/src/lib/cli/checks-manifest.ts).
-skills:           # optional, list of strings
-context:          # optional, list of strings
-evidence:         # optional, evidence array — sources proving acceptance met
-                  #   (see "Evidence linking" below)
-
-# Council session output ([[adr-0015-council-as-cross-cutting-capability]])
-deliberation_record: # optional; multi-LLM debate output, append-only `runs[]`. Permitted on task/epic/review
-                     # in addition to draft. Schema lives under `draft` §`deliberation_record` above. Attaches
-                     # on promoted-spec recheck (invocation #3) via `/hs-next` claim path; never gates work.
-
-# Parallel-agent module hints ([[HS-ZMAQ-M15C-TASK-declare-owned-path-globs-on-agent-identi]])
-affects_paths:    # optional, list of repo-relative glob strings — coarse module hints for
-                  #   overlap detection when multiple agents work in parallel; advisory in v1
-                  #   (same posture as the advisory `lane:` label on agent identities).
-
-# Migration provenance
-legacy_bd_id:     # optional, string — original bd id for migrated entries
-```
-
-##### Handoff envelope (body)
-
-When an agent defers or splits remaining work into a child task, the **handoff envelope** carries the next agent's starting context. SSOT is the **body**, not frontmatter — a `## Handoff envelope` heading followed by a fenced ` ```yaml ` block matching `schemas/handoff-envelope.schema.json`:
-
-```yaml
-reason: "Why the defer/split happened (context budget, blocked, lane hand-off)"
-summary_done:
-  - "Work completed before the handoff"
-remaining:
-  - "Actionable items for the picking-up agent"
-success_criteria:
-  - "How the reviewer knows the deferred work is done"
-```
-
-Field semantics align with the WIP ledger (`remaining` / verified-style `summary_done`) plus delegation-specific `reason` and `success_criteria` per HS-SUMD-4T35-RES-parallel-agent-coordination-handoff-and. A task with `split_of:` **must** include this section; `scripts/validate-vault-ids.mjs` enforces shape. The defer command (HS-MS3T-1U0Z-TASK-hs-defer-mcp-tool-and-slash-command) authors both the lineage frontmatter and this block.
-
-#### `agent`
-
-Durable agent identity (HS-XNX5-UQHA-MIL-agent-home). Evergreen — does not close. Compiles to `.claude/agents/<name>.md` and `.cursor/agents/<name>.md`; the vault spec is the SSOT.
-
-```yaml
-type: agent
-role:             # required, string — human-readable role title (also used as description fallback on compile)
-model:            # optional, enum: opus | sonnet | haiku
-description:      # optional, string — host-native description on compile
-goal:             # optional, string — HeySpex-resident intent label (not compiled)
-allowed_tools:    # optional, list of strings — compiled to host `tools:` when present
-disallowed_tools: # optional, list of strings — compiled to host `disallowedTools:` when present
-procedures:       # optional, list of wikilinks — HeySpex-resident procedure refs
-handoffs:         # optional, list — HeySpex-resident handoff targets
-guardrails:       # optional, list of strings — HeySpex-resident; persona body carries compiled guardrails
-lane:             # optional, string — human label for parallel work (advisory in v1)
-isolation:        # optional, enum: default | worktree — operator guidance for checkout
-                  #   isolation when parallel agents each need a dev server; advisory in v1
-                  #   ([[parallel-agent-isolation-guidance]]). `worktree` = use a dedicated git
-                  #   worktree before implementation. HeySpex-only — stripped on compile (like `lane`).
-color:            # optional, string — console roster accent (HeySpex-only)
-owned_paths:      # optional, list of repo-relative glob strings — machine-checkable file/module
-                  #   ownership for stomp-detection ([[HS-8PNX-Q1KC-EPIC-lanes-and-stomp-detection-for-parallel-a]]).
-                  #   Example: spex-console/src/lib/scheduler/**, vendor/heyspex-mcp/**. HeySpex-only — stripped on compile.
-golden_cases:     # optional, list of wikilinks to HS-GCASE-* fixtures owned by this agent.
-                  #   Reverse of each case's `agent:` pointer. HeySpex-only — stripped on compile
-                  #   ([[HS-8AQT-J6FU-TASK-golden-case-vault-artifact-format-and-st]]).
-source_attribution: # optional object — import provenance for community/own-agent imports only
-tags:             # required for roster grouping — MUST include `agent` plus at least one
-                  #   `purpose/*` tag (see Purpose tags below). Plain frontmatter array;
-                  #   no agent-only grouping engine ([[HS-IAYA-5345-TASK-lock-agent-purpose-taxonomy-and-tag-conv]]).
-```
-
-**Purpose tags** (HS-E2VS-LBUS-EPIC-roster-organization-and-discovery-for-a, HS-WDHW-0009-EPIC-tag-taxonomy-tag-browser-obsidian-style): agent identities reuse the vault's nested-tag namespaces — a dedicated **`purpose/`** namespace (seventh namespace alongside 0009's `area/`, `type/`, `surface/`, `theme/`, `dep/`, `stage/`) for roster discovery. Values are multi-select tags in `tags:`; grouping UI and `GET /api/agents` read them later (HS-NRND-UF9J-TASK-expose-agent-tags-in-get-api-agents-rost).
-
-| Tag | When to use |
-|-----|-------------|
-| `purpose/reviewer` | Verify acceptance criteria, review diffs, read-only audit before close-out |
-| `purpose/researcher` | Synthesize cited research into durable `HS-RES-*` specs |
-| `purpose/planner` | Ground plans/epics, stress-test assumptions at the plan→execute boundary |
-| `purpose/triager` | Intake routing — captures, resolution items, smallest-fix triage |
-| `purpose/implementer` | Build, edit, deploy — agents that modify code or infra |
-| `purpose/writer` | Prose/docs authoring (reserved; no starter roster member yet) |
-
-Rules:
-
-1. **Required:** every shipped `type: agent` spec carries **at least one** `purpose/*` tag in `tags:` (in addition to the `agent` marker).
-2. **Primary purpose:** the **first** `purpose/*` tag in `tags:` array order is the roster section key. Downstream surfaces expose it as `primaryPurpose` (computed server-side — not a separate frontmatter field). When an agent legitimately spans multiple purposes, list the primary group first and secondary `purpose/*` tags after.
-3. **`lane:` is not a substitute:** `lane` is parallel-work coordination (advisory, HeySpex-only, stripped on compile). `purpose/*` is vault-resident discovery metadata that flows to the API. They often align but are independent fields.
-
-#### `golden-case`
-
-Saved eval fixture for the agent testing harness (HS-R1JM-OAG3-EPIC-agent-testing-harness-try-a-draft-agent). Evergreen — updated in place as the agent evolves; does not close. One golden case exercises exactly one `type: agent` identity. The eval spawn (HS-YNIE-ZDQ7-TASK-transient-eval-spawn-and-trajectory-capt) reads the body; the verdict engine (HS-ZOHQ-MOOE-TASK-verdict-engine-deterministic-graders-plu) consumes optional deterministic graders. Expected trajectories (regression baselines) are **run artifacts**, not stored in the fixture at v1 — they land in run history later (HS-ZR0Z-TS11-TASK-run-history-storage).
-
-```yaml
-type: golden-case
-agent:            # required, wikilink to HS-AGENT-* — the identity under test
-tags:             # should include golden-case, agents, testing
-related:          # optional wikilinks — e.g. the task spec used as setup context
-```
-
-**Bidirectional linkage:** each golden case carries `agent:`; the agent MAY carry `golden_cases:` (list of wikilinks). Filing via `createSpec` / `heyspex_file_spec` with `frontmatter.agent` auto-appends to the agent's `golden_cases:` array (same pattern as task→epic `children:`).
-
-**Required body sections:**
-
-| Section | Required | Purpose |
-| --- | --- | --- |
-| `## Prompt` | yes | The user message the eval spawn sends to the draft agent (≥12 characters). |
-| `## Setup` | no | Freeform context — wikilinks to task specs, files in scope, env hints. |
-| `## Deterministic graders` | no | Fenced `yaml` block matching `specs/schemas/golden-case-body.schema.json`. Keys the reproducible pass/fail signal; LLM-judge critique remains advisory per OAG3 AC#4. |
-
-**On-disk layout:** `specs/agents/golden-cases/HS-GCASE-<suffix>-<slug>.md` — nested under `agents/` so fixtures travel in the same git subtree as agent identities.
-
-#### `epic`
-
-Same as `task` schema (including optional `affects_paths:`). The `type: epic` is what differentiates. An epic typically has many `children:` and few `blocks:`/`blocked_by:`.
-
-**Planning flow requirements** (planning-flow-research-epic-lifecycle): every epic MUST include `research:` and `planning_flow:` wikilinks. Console Epic Studio and `POST /api/specs` enforce this for newly filed epics.
-
-```yaml
-research:         # required for new epics — wikilink to HS-RES-*
-planning_flow:    # required for new epics — wikilink to HS-FLOW-*
-milestone:        # REQUIRED — single wikilink to the parent HS-MIL-* this epic belongs to.
-                  #   The inverse of the milestone's `epics:` array (write both sides;
-                  #   `scripts/validate-vault-ids.mjs` rejects one-sided drift).
-                  #   Grace window: missing `milestone:` is a validator warning until
-                  #   2026-06-26, then escalates to an error
-                  #   ([[HS-V5UA-T5PX-TASK-required-milestone-parent-on-epic-validator-and-grace-window]],
-                  #   part of [[HS-OFR5-M2J3-EPIC-introduce-milestones-as-highest-entity]]).
-                  #   Pre-rule orphan epics live at
-                  #   [[HS-3DJS-ORPH-MIL-uncategorized-pre-2026-05-26-epics]]
-                  #   pending walk-the-floor reassignment.
-derived_from:     # optional, single wikilink to HS-RES-* — the research that spawned this epic.
-                  #   Reverse of `research.spawned_epics:` (1:N). See §Provenance edges.
-```
-
-**Alignment fields** (drift-detection prerequisites; HS-E3D3-RDFT-EPIC-alignment-drift-detector-into-resolution, owned by HS-KA1E-0012-EPIC-creation-guardrails-agent-pushback for the vault-wide backfill):
-
-```yaml
-alignment_rationale: # optional (backfill in progress), string — a wikilink to the Pillar / L1 principle
-                     #   this epic advances PLUS a one-line "why", e.g.
-                     #   "[[HS-PILR-architecture]] — advances the foundations concern by converging detection paths".
-                     #   Distinct from the membership `pillar:` field: `pillar:` categorizes; `alignment_rationale`
-                     #   carries the teleological "why" the drift detector reasons over. The wikilink target
-                     #   SHOULD match the epic's `pillar:`. An `alignment_rationale` that resolves to no layer
-                     #   record surfaces as an `orphan` resolution item.
-alignment_baseline:  # optional, mapping { <layer-id>: <int version>, anti_goals?: <fingerprint> } — the layer
-                     #   versions this epic was last aligned against. PRIMARY drift baseline: when a referenced
-                     #   layer's current `version` exceeds the baseline here, a `drift` item is emitted. The
-                     #   `anti_goals` key stamps the L1 anti-goal fingerprint so a changed anti-goal set re-checks
-                     #   every active + recently-closed epic. Absent → the detector falls back to
-                     #   `alignment_reviewed_at` vs the layer's `last_edited_at`; absent both → no drift (never a
-                     #   false positive). Stamped by the alignment checkpoint on re-alignment.
-```
-
-#### `milestone`
-
-The grouping **above** epic: a coherent multi-epic ship (a restructure or release) that closes when every child epic closes and the milestone's own acceptance gate is met. Formalized by HS-VK7C-MILE-EPIC-milestone-entity-type-and-surfacing; the canonical hierarchy and filing rules live in [[spec-hierarchy]]. The 33 `HS-MIL-*` files on disk (seed: HS-RM22-IART-MIL-console-ia-restructure) predate this schema row and are described by it retroactively.
-
-```yaml
-type: milestone
-status:           # one of: open | in_progress | closed (subset of the universal enum)
-epics:            # list of wikilinks to every child epic — the mirror of each child epic's
-                  #   `milestone:` pointer. Write both sides (bidirectional linkage; see [[spec-hierarchy]]).
-informed_by:      # optional, list of wikilinks to HS-RES-* — research docs that enhance this milestone.
-                  #   Reverse of `research.enhances:` (each research enhances exactly one milestone, M:1;
-                  #   one milestone may be informed by many research docs over time). Bidirectional
-                  #   consistency enforced by `scripts/validate-vault-ids.mjs`. See §Provenance edges.
-target_date:      # optional, ISO-8601 date or empty string "" — the intended ship date
-tags:             # optional, list of strings
-related:          # optional, list of wikilinks
-```
-
-**No scalar `priority:` field.** Milestone ordering is the **output** of the deterministic priority scheduler, never a stored scalar (deterministic-priority-scheduler-supersedes-scored-priority, HS-78E7-Y9OJ-EPIC-deterministic-priority-scheduler). This deliberately diverges from the universal "`priority:` required" rule above — the same way current epics and tasks omit the scalar. Do not add a `priority:` to a milestone.
-
-Sub-milestones are **out of scope**: large milestones are split horizontally (more milestones at the same level), not nested ([[spec-hierarchy]] §Open questions). There is no `milestone:` (parent-milestone) field on a milestone.
-
-Required body sections ([[spec-hierarchy]] §Frontmatter requirements per level): rationale ("why this is a milestone, not loose epics"), an acceptance gate (numbered closure conditions), suggested landing order, and out-of-scope.
-
-#### `diagnose`
-
-A user-reported **bug fix** as first-class executable work — claimable and decomposable like a task, but typed so it reads as "a reported bug to fix," not planned roadmap work. Introduced by HS-OXBS-BFIX-MIL-bug-fix-diagnose-lane (milestone-precedent, no standalone ADR). Standalone by default; an optional `parent:` (epic OR milestone) groups related fixes. Surfaces on the Resolution surface as a derived `kind: "bug"` row (the row is derived; this spec is the work — see blockers-are-gating-subset-of-resolution and HS-AO2F-1KZK-RES-bug-fix-resolution-task-entity-model-and).
-
-```yaml
-type: diagnose
-status:           # universal enum: open | in_progress | in_review | closed | …
-severity:         # REQUIRED — one of: error | warning | info. Maps onto the scheduler's
-                  #   existing priority signals (channel B): a higher-severity diagnose
-                  #   competes higher for on-deck. Drives the derived bug row's color.
-parent:           # OPTIONAL — single wikilink to an HS-EPIC-* or HS-MIL-* parent.
-                  #   Standalone (absent) is the DEFAULT and is exempt from the
-                  #   epic→milestone mandatory-parent rule. One-way pointer (no auto back-link).
-depends_on:       # optional, list of wikilinks — tasks/specs that must close first.
-blocks:           # optional, list of wikilinks to HS-EPIC-*/HS-TASK-* this fix gates.
-                  #   Surfaces as a gating item in that spec's On-Deck overlay (channel A).
-promoted_from:    # optional, single wikilink to HS-CAP-* — set when this diagnose was promoted
-                  #   from a bug-report capture via `heyspex_promote_capture_to_diagnose`.
-                  #   Reverse of `capture.promoted_to:` (first-promotion).
-derived_from:     # optional, single wikilink to HS-RES-* — the research that surfaced this bug,
-                  #   set when this diagnose was promoted from a research investigation via
-                  #   `heyspex_promote_research_to_diagnose` (mirrors `epic.derived_from`).
-                  #   Reverse of `research.produces_diagnose:` (1:N).
-tags:             # optional, list of strings
-related:          # optional, list of wikilinks
-```
-
-**No scalar `priority:`** — like task/epic/milestone, ordering is the scheduler's output; `severity:` is the diagnose's contribution to that ranking, not a stored priority.
-
-Required body sections: Symptom, Reproduction, Root cause, Fix, Acceptance criteria.
-
-#### `pillar`
-
-Perpetual categorical container that never closes — the cross-cutting axis to which every epic associates via a primary `pillar:` field. Pillars are the structural primitive that makes HeySpex's "preserve context across time" claim true rather than aspirational ("Linear and Jira are queues; HeySpex is context" — see heyspex-market-positioning). Introduced 2026-05-31 per HS-AWDI-PILR-RES-pm-perpetual-container-terminology; ratified by introduction lineage HS-EBIL-0011-EPIC-goal-hierarchy-l2-strategic-pillars-l3 (milestone precedent, no standalone ADR for the entity itself). The meta-Pillar — the Pillar about Pillars themselves, dogfooding instance — is HS-PILR-pillars.
-
-```yaml
-type: pillar
-status:           # `perpetual` — non-terminal. Pillars never transition to closed/in_review/etc.
-                  #   Universal status enum does NOT apply.
-canonical:        # required, boolean
-                  #   true  → curated by HeySpex team; ships pre-loaded in customer vaults; read-only (fork to customize)
-                  #   false → customer-scoped Pillar (filed by the customer with high friction)
-library_tier:     # optional enum: meta | foundational | discretionary (placeholder; library taxonomy TBD)
-secondary_pillars: # always present; usually empty []. Reserved for future cross-Pillar linking.
-version:          # optional, monotonic integer — same semantics as the `l1` `version` field above.
-                  #   A Pillar edit that materially changes scope bumps this; epics aligned against the
-                  #   prior version surface as `drift` items ([[HS-E3D3-RDFT-EPIC-alignment-drift-detector-into-resolution]]).
-last_edited_at:   # optional, ISO-8601 timestamp of the last edit — drift timestamp fallback (see `l1`).
-related:          # optional, list of wikilinks
-tags:             # optional, list of strings
-```
-
-The `version` / `last_edited_at` fields are the versioning prerequisites carried from HS-EBIL-0011-EPIC-goal-hierarchy-l2-strategic-pillars-l3; together with the L1 fields they let the alignment-drift detector tell a material Pillar revision apart from a no-op touch.
-
-**Per-epic membership** (new fields on every epic, added 2026-05-31 by HS-EBIL-0011-EPIC-goal-hierarchy-l2-strategic-pillars-l3):
-
-```yaml
-pillar:             # required on every epic, single wikilink to a Pillar.
-                    #   The home for library/learning. Forces "what perpetual concern does this advance?"
-                    #   at filing time. HARD-BLOCKED at the filing boundary (owner decision 2026-06-18):
-                    #   POST /api/specs / heyspex_file_spec refuse an epic with no resolvable HS-PILR pillar
-                    #   (400 pillar_required). Legacy pillar-less epics are caught by the EPIC_MISSING_PILLAR
-                    #   vault-rule — warning (Resolution backfill queue) until 2026-07-31, then error.
-                    #   Full rules: [[pillar-assignment-protocol]].
-secondary_pillars:  # optional, list of wikilinks to Pillars.
-                    #   For genuinely cross-cutting work ("Add caching layer" is primarily Scaling but also Reliability).
-                    #   Tasks inherit their epic's primary pillar; do not set secondary on tasks.
-```
-
-**Authored as the work surfaces themes.** Pillars are created over time, not enumerated up front — there are deliberately only a few today and many more are expected. When filing an epic surfaces a theme with no pillar yet, the agent is prompted to author one (`heyspex_file_spec({ type: "pillar", name })`); the owner may also author a pillar standalone whenever a theme is foreseen. The procedure is pillar-assignment-protocol.
-
-**Milestones surface a derived pillar roll-up.** A milestone has **no authored `pillar:` field** — it is a dated ship that groups epics, which may belong to different pillars. Instead a milestone *surfaces* the de-duped set of pillars its child epics carry (computed in `getSpec`, rendered on the milestone detail drawer). The roll-up is derived and may list multiple pillars, so it never drifts from the epics' `pillar:` fields.
-
-**Status semantics.** Pillars carry `status: perpetual` as a single non-terminal value, distinct from the universal enum. The close-out protocol skips Pillars; the scheduler skips Pillars as on-deck candidates (only their epics are scheduled); review-doc flow does not apply. A Pillar's body grows over time as epics close and lessons accumulate against the concern — accumulation IS the point.
-
-**Body sections.** Required: a one-line "why this Pillar exists" hook; `## In scope` / `## Out of scope`; `## Anticipated epics`; `## Library status` (canonical | customer-scoped). The body is a living document, not a frozen artifact.
-
-**Disambiguation — three distinct uses of "pillar" in this vault:**
-
-1. **`type: pillar` entities (`HS-PILR-*`)** — this section. Perpetual product concerns (Scaling, Reliability, DX, etc.). Queryable, schematized.
-2. **HS-DOC-architecture-foundations** (renamed 2026-05-31 from `architecture-pillars`) — L2 doc that names the five technical foundations of the system (vault, indexer, console, CLI, sync mesh) and refers to them as "Pillars 0–5" in internal section headers. Unrelated to (1); the section names are preserved for now and may be renamed in a future cosmetic pass.
-3. **HS-OR8V-0010-EPIC-north-star-vision-first-class-entity's FIVE COMPONENTS section** — five implementation parts of that epic. Previously named "FIVE PILLARS"; renamed 2026-05-31 to remove the overload.
-
-Only sense (1) is a queryable entity. (2) and (3) use the word as a non-schematized noun within their own documents.
-
-#### `branch-brief`
-
-A durable "plan receipt" for one git branch. Ratified by adr-0008-branch-brief-and-evidence-schema; closes the Continuity Layer schema gaps (HS-7KOO-0022-EPIC-continuity-layer-gaps). One brief per branch; re-generation overwrites the file in place (git history is the version trail). Generated by HS-838Y-ALDY-TASK-branch-brief-generation.
-
-```yaml
-type: branch-brief
-branch:           # required, string — the raw (unsanitized) git branch name
-repo:             # optional, string — repo name if multi-repo
-goal:             # required, string — what this branch is trying to accomplish
-implements:       # optional, list of wikilinks — tasks/epics this branch implements
-plan:             # optional, list of { step: int, description: string }
-                  #   the ORIGINAL intent. Sourced (priority order) from:
-                  #   1. the linked implementing spec's acceptance criteria
-                  #      (its `acceptance:` array, else its `## Acceptance` body)
-                  #   2. a manual plan authored here (exploratory branches)
-                  #   Commit messages / PR bodies are NOT v1 plan sources.
-actual:           # optional, list of { step: int, description: string,
-                  #   status: <drift enum>, evidence: [<evidence ref>] }
-                  #   what was implemented, captured at brief-generation time.
-risks:            # optional, list of strings — identified risks/concerns
-open_questions:   # optional, list of strings — unresolved questions
-next_steps:       # optional, list of strings — recommended next actions
-decisions:        # optional, list of wikilinks — memory-decisions made on this branch
-evidence:         # optional, evidence array (see "Evidence linking" below)
-```
-
-**Drift enum** (the `status:` of each `actual` step) — defined once here, reused by HS-838Y-ALDY-TASK-branch-brief-generation and any drift tooling (HS-CM22-0019-EPIC-post-edit-alignment-drift-detection):
-
-| Value | Meaning |
-| --- | --- |
-| `match` | Implementation achieves the planned step. |
-| `drift` | Implementation differs from the plan in a material way. |
-| `missing` | Planned step not implemented. |
-| `extra` | Implemented change that was not in the plan. |
-
-Required body sections: `## Goal`, `## Plan vs Actual` (a table rendering `plan`/`actual` with an `Evidence` column), and — when any step is `drift`/`missing`/`extra` — a `## Drift Analysis` section explaining each, with risk and a recommendation. Optional: `## Decisions`, `## Risks`, `## Open Questions`, `## Next Steps`, `## Evidence`. The frontmatter `plan`/`actual` arrays are canonical for queries; the body table is the human view (same canonical-frontmatter rule as dependencies and tags).
-
-#### `memory-lesson`
-
-```yaml
-type: memory-lesson
-topic:            # required, short string — the subject
-observed:         # required, ISO-8601 date — when the lesson was learned
-related:          # optional, list of wikilinks
-evidence:         # optional, evidence array — sources grounding the problem/fix
-                  #   (see "Evidence linking" below)
-```
-
-The body of a memory-lesson spec has two required sections: `## Problem` and `## Fix`.
-
-#### `memory-decision`
-
-```yaml
-type: memory-decision
-topic:            # required, short string
-decided:          # required, ISO-8601 date
-deciders:         # required, list of strings
-supersedes:       # optional, wikilink to a prior decision
-evidence:         # optional, evidence array — sources grounding the rationale
-                  #   (see "Evidence linking" below)
-```
-
-The body has two required sections: `## Decision` and `## Rationale`. (An ADR is a heavier-weight decision; a `memory-decision` is the day-to-day choice that doesn't warrant an ADR but should still be persisted.)
-
-#### `memory-reference`
-
-```yaml
-type: memory-reference
-topic:            # required, short string
-url:              # optional, URL the reference points at
-evidence:         # optional, evidence array — additional grounded sources
-                  #   (see "Evidence linking" below)
-```
-
-Body is the brief context for why this reference matters.
-
-#### `memory-ui-pattern`
-
-```yaml
-type: memory-ui-pattern
-topic:            # required, short string — the pattern name/slug
-documented:       # required, ISO-8601 date — when the pattern was captured
-related:          # optional, list of wikilinks
-evidence:         # optional, evidence array
-```
-
-Reusable **console interaction and visual patterns** (keyboard ownership, two-layer highlights, drill-in between panes). Distinct from `memory-ux-principle` (cross-brand rules) and `memory-decision` (a one-time choice). Body sections: `## Pattern`, `## When to apply`, `## Rules`, `## Implementation` (file map + copy-paste shape). See rail-active-vs-keyboard-cursor.
-
-#### `memory-ux-principle`
-
-```yaml
-type: memory-ux-principle
-topic:            # required, short string — the principle name/slug
-documented:       # required, ISO-8601 date — when the principle was captured
-related:          # optional, list of wikilinks
-evidence:         # optional, evidence array
-```
-
-Cross-brand **interaction rules** (Apple HIG, Material, Linear, Nielsen) — product-agnostic **what/why**. Distinct from `memory-ui-pattern` (HeySpex **how**). Body sections: `## Principle`, `## When to apply`, `## Rules`, `## Related UI patterns`, `## Sources`. See toggle-current-state-semantics and ux-principles-vs-ui-patterns.
-
-#### `protocol`
-
-Part of the **Memory** layer (memory-protocols-subsection-of-memory). Epics/tasks that *implement* or *revise* a protocol stay in `epics/` / `tasks/`; only the finished operational doc is `type: protocol`.
-
-```yaml
-type: protocol
-scope:            # required, one of: session | project | vault | tool
-version:          # optional, semver-ish version of the protocol
-```
-
-Body describes the protocol with numbered steps.
-
-#### `review`
-
-Companion fill-in workspace for a parent spec at `status: in_review`. One review doc per parent spec; created by the agent at the moment of flipping the parent to `in_review`. The reviewer (human) walks acceptance criteria, reads the agent's session observations, scores memory candidates, and records pass/reopen. Naming: `HS-REV-<suffix>-<slug>.md` where `<suffix>` matches the parent's id 1:1 (`HS-76RX` → `HS-SK1L-REV-…`, `HS-KQ5O` → `HS-IDFV-REV-…`).
-
-```yaml
-type: review
-parent:           # required, single wikilink — the spec under review
-reviews:          # optional, single wikilink — same as parent (legacy alias retained for back-compat reads)
-                  # parent: is the canonical edge; reviews: is kept for older docs
-deliberation_record: # optional; Council session output for invocation #4 (review close-out)
-                     # ([[adr-0015-council-as-cross-cutting-capability]]). Schema lives under `draft`
-                     # §`deliberation_record` above. Attached when the human triggers council during
-                     # `/hs-review` close-out; never gates the human's pass/reopen decision.
-```
-
-Body has four required sections — the unified workspace:
-
-- `## Acceptance verification` — checkboxes mirroring the parent spec's acceptance criteria; reviewer ticks them during verification and adds inline deviation notes. For epic-level reviews, expand into a manual testing walkthrough (fast-fail commands, click-by-click steps, expected behavior the reviewer can follow top-to-bottom).
-- `## Reviewer notes` — free-form workspace. **The agent writes implementation observations here during the work session** (architecture choices, judgment calls, surprises, gotchas). The reviewer adds deviation/surprise notes during the testing pass. This prose is the raw material the close-out memory-extraction pass reads.
-- `## Memory candidates` — table of proposed lessons / decisions / UI patterns / references derived from the Reviewer notes. Each row scored against the four-axis rubric (non-derivability / reusability / surprise-cost / concreteness, 0–3 each, threshold ≥ 7/12) and **MUST include a "Conflict check" column** noting `New`, `Refines [[existing-memory]]`, or `Conflict [[existing-memory]]`. A `Conflict` row is a red flag and must be resolved before accepting. Owned by HS-35JN-REVD-TASK-review-doc-fill-in-template-and-memory-extraction.
-- `## Decision: close or reopen` — explicit pass/fail outcome with reasoning, plus a checkbox indicating whether to materialize accepted memory candidates.
-
-Cross-link from the parent spec: every parent spec at `in_review` MUST add a `## Review` section pointing to its companion: `Reviewer workspace for this spec lives at [[HS-REV-<suffix>-<slug>]] — pre-review checklist, manual verification steps, reviewer notes, and memory candidates extracted at close-out.`
-
-The console shows a "Review" button on cards only when the parent spec is `status: in_review` and an `HS-REV-<suffix>-*` companion exists (detection: `console/src/lib/vault.ts:155 extractSpecSuffix`). Once the parent moves to `closed`, the button disappears but the wikilink in the parent body remains.
-
-The four-section unified-workspace template and the close-out flow are specified in HS-35JN-REVD-TASK-review-doc-fill-in-template-and-memory-extraction and CLAUDE.md §Session Completion. The MCP tool that loads a review doc into agent context (`heyspex_review_on_deck` + `/hs-review`) is specified in HS-XRO1-RVDC-TASK-heyspex-review-on-deck-mcp-and-hs-review. The legacy `{basename}.review.md` sibling naming was migrated by `scripts/migrate-review-doc-naming.mjs` — do not use it for new docs.
-
-#### `business-positioning` / `business-pricing` / `business-marketing` / `business-model`
-
-Parallel layer to Memory for **business-side** knowledge: how the product is positioned, priced, marketed, and the business model itself. Like Memory, browsed in the console on its own surface (**Business**) with category filters.
-
-```yaml
-type: business-positioning  # or business-pricing | business-marketing | business-model
-topic:            # required, short string — the subject (e.g. "homepage-h1", "tier-table")
-status:           # universal status enum — draft | open | in_progress | in_review | closed | deferred
-                  #   `active` is allowed as a synonym for `open` on migrated docs.
-related:          # optional, list of wikilinks
-evidence:         # optional, evidence array — sources grounding the claim/decision
-```
-
-Body is free-form prose; the recommended shape is a one-line H1 frame, then sections that match the doc's purpose (e.g. **Decision** / **Why each word is load-bearing** for positioning; **Tier table** / **AI add-on** / **What this also unlocks** for pricing).
-
-Distinct from `memory-decision` — memory captures *how-we-work* decisions for agents/humans inside the project; business docs capture *what-we-sell-and-how* decisions for the outside world. A pricing change is a `business-pricing` doc; a "don't mock the database in tests" rule is a `memory-decision`.
-
-#### `capture`
-
-Concise core-intent capture **before** research (capture-guardrails). Replaces the legacy `type: idea` entity (renamed 2026-05-22 per HS-B2B8-DLQI-EPIC-capture-rename-migration-idea-to-capture, source rationale HS-ZKFN-1FXG-CAP-capture-as-universal-companion-verb-and-parent-term). Not a draft inbox item and not a research doc.
-
-```yaml
-type: capture
-kind:             # required, one of: idea | bug-fix | clip | reference | question | spec-import | feedback
-                  #   idea       → speculative concept worth exploring (default — migrated entries land here)
-                  #   bug-fix    → defect observation paired with proposed fix
-                  #   clip       → web/document excerpt saved verbatim for later use
-                  #   reference  → a pointer to an external resource worth keeping
-                  #   question   → an open question to revisit when more context lands
-                  #   spec-import→ an imported foreign doc (README / top-level project doc) landed as a RAW
-                  #               capture by the bulk spec-import feature ([[HS-8V8T-8SBG-EPIC-first-connect-rough-import]]);
-                  #               source doc in ## Source Material; carries source_repo/source_path for
-                  #               (repo, vault) idempotency; stays RAW for manual triage. The
-                  #               "pin → run feature pipeline" exit ([[HS-J7T5-VEW8-RES-import-specs-one-click-feature-pipeline]])
-                  #               is a deferred follow-on — NOT wired in this wave.
-                  #   feedback   → app feedback / bug report / product idea / support question captured through
-                  #               a deterministic (no-AI) intake channel ([[HS-KQEW-I5DV-EPIC-feedback-capture-type-deterministic]]);
-                  #               classified by `routeFeedback()` ([[HS-FUII-EI9R-TASK-deterministic-feedback-router-module-no]]) toward diagnose/research/
-                  #               answered, or stays `feedback` when unmatched. Optional structured fields below
-                  #               (declared alongside `source:` further down this block — see `example`/
-                  #               `user_story`/`situation`).
-example:          # optional, string — a concrete example/repro illustrating the feedback (e.g. steps to reproduce a bug).
-                  #   Only ever populated on `kind: feedback` captures; never forced, never required by the schema.
-user_story:       # optional, string — "as a user, I want to… so that…" framing for a feedback-sourced product idea.
-                  #   Same optionality as `example`.
-situation:        # optional, string — the situational context the user was in when the feedback arose.
-                  #   Same optionality as `example`.
-capture_status:   # required, one of: raw | expanded — default raw
-                  #   raw      → no Core Idea content yet (single textarea / quick capture)
-                  #   expanded → Core Idea / Concept / Details has been written (modal v3 or agent rewrite)
-                  #   Flips raw → expanded automatically when an agent writes to core_idea,
-                  #   concept, or agent_expansion via executeUpdateCapture (vendor/heyspex-mcp).
-                  #   Console save-time linter force-corrects raw → expanded when `# Core Idea`
-                  #   body has content. See [[HS-BDDT-Q1B7-EPIC-idea-capture-modal-v3-single-textbox-cle]].
-promoted_to:      # binary: null (not promoted) or "[[HS-RES-<suffix>-<slug>]]" (promoted to research).
-                  #   Records the FIRST research doc this capture was promoted into; not the full set.
-                  #   For the M:N "every research doc this capture informs" view, see `informs_research:`.
-informs_research: # optional, list of wikilinks to HS-RES-* — every research doc this capture informs (M:N).
-                  #   Reverse of `research.sources_captures:`. Distinct from `promoted_to:` (binary
-                  #   first-promotion pointer); a capture may appear in multiple research docs over time.
-                  #   Bidirectional consistency enforced by `scripts/validate-vault-ids.mjs`. See §Provenance edges.
-source:           # optional capture channel (console, cli, companion, agent, …). On `kind: feedback` captures this
-                  #   also doubles as the free-text originating-channel/page-context signal `routeFeedback()`
-                  #   reads ([[HS-FUII-EI9R-TASK-deterministic-feedback-router-module-no]]) — still optional, never forced.
-related:          # optional wikilinks
-legacy_idea_id:   # optional, string — original HS-IDEA-* id for migrated entries (archaeology)
-```
-
-`promoted_to` is the **single binary promotion field** (HS-KQ5O-IDFV-EPIC-unified-idea-workflow-v2 / HS-QOAC-IDFL-RES-unified-idea-workflow-v2). `research_stage` was removed 2026-05-22; intermediate "promoted-but-research-not-written-yet" state lives in `.heyspex/research-focus.yaml`, not in the spec.
-
-`kind:` is the taxonomy field locked in by HS-B2B8-DLQI-EPIC-capture-rename-migration-idea-to-capture Milestone A. Migration of pre-2026-05-22 `type: idea` entries set `kind: idea` for every record; new captures pick the kind at creation time. The enum was extended from 5 to 6 values on 2026-07-10 — `spec-import` added as the **import-origin** kind for the bulk spec-import feature (HS-8V8T-8SBG-EPIC-first-connect-rough-import / HS-ROIU-9P4B-EPIC-import-preview-and-confirm, grounding HS-J7T5-VEW8-RES-import-specs-one-click-feature-pipeline). `spec-import` was added as a documentation/protocol convention only, not to the hard validator enum — `scripts/validate-vault-schema` (`schemas/heyspex-frontmatter.schema.json`) only required that a capture carry a `kind:` and a `capture_status:`, so `spec-import` slipped past AJV. `feedback` (7th value, HS-KQEW-I5DV-EPIC-feedback-capture-type-deterministic / HS-PUK1-48ZZ-TASK-add-feedback-capture-kind-optional) was added to BOTH the doc above and the hard AJV `kind` enum in `schemas/heyspex-frontmatter.schema.json` — a `kind: feedback` capture passes `scripts/validate-vault-schema.mjs` the same way the original five values do. Further consolidation (getting `spec-import` onto the hard enum too) is still deferred.
-
-Body **must** use four named sections — `# Core Idea` / `## Notes` (verbatim human words inside `"quotes"`) / `## Concept` (AI brief summary, ≤1200 chars hard / ≤800 soft) / `<details>Details</details>` (AI synthesis / deep dive, collapsed by default). Core Idea ≤280 chars soft / ≤500 hard. (The body section names retain the legacy "Idea" / "Notes" / "Concept" / "Details" wording even for captures whose `kind:` is not `idea`; the headings are a fixed scaffold, not a taxonomy field — agents and humans use the same four-section shape for every kind.) Legacy `# Core idea` / `## Notes` / `<details>Expanded idea (agent)</details>` is read back-compat during the deprecation window; writes always emit v2. AI may write to any section but: (a) never alters words inside a quote, (b) `## Notes` format-wrap is confirm-free, (c) `# Core Idea` / `## Concept` / `## Details` writes require user confirm. Agents must not add research sections (Executive Summary, Findings, Sources) to capture files — only the separate research doc after `/hs-res` (capture-guardrails).
-
-#### `research`
-
-Research is **evergreen** per the lifecycle-class taxonomy above and the canonical decision research-is-evergreen. `status: open` is the resting state for the doc's entire life — there are no `in_review` or `closed` transitions. Lineage to downstream artifacts is recorded through the relational fields below (`enhances:`, `spawned_epics:`, `bound_epic:`, `incorporated_into:`, `superseded_by:`), **never** through a status flip.
-
-```yaml
-type: research
-research_type:    # REQUIRED, enum — the declared purpose of this research doc, set at creation
-                  #   ([[HS-45YJ-120I-EPIC-research-type-field-the-declared-purpose]]). Coherent with the
-                  #   capture `kind:` vocabulary (`idea | bug-fix | clip | reference | question`) one
-                  #   level up the lifecycle, but not identical — research_type describes what the
-                  #   research is FOR, not what kind of capture seeded it. Five values:
-                  #     new-feature  — grounds a not-yet-built capability or product surface
-                  #     enhancement  — improves or extends something already shipped
-                  #     diagnose     — investigates a bug, defect, or quality problem
-                  #     code-audit   — reviews existing code/architecture with no specific bug in hand
-                  #     reference    — captures external/background knowledge for reuse (the default)
-                  #   Enforced by `schemas/heyspex-frontmatter.schema.json`. Missing on a pre-existing
-                  #   doc is a WARNING during the grace window (`RESEARCH_TYPE_GRACE_END` in
-                  #   `spex-console/src/lib/indexer/vault-rules.mjs`, mirroring `EPIC_PILLAR_GRACE_END`),
-                  #   then a hard error. Deterministic kind→research_type suggestion is out of scope
-                  #   here — owned by [[HS-6CFV-MVC1-EPIC-deterministic-type-assist-suggest-resear]].
-scope:            # optional, enum — how broad a search context this research was run at:
-                  #     internal — specs/, memories, ADRs only
-                  #     codebase — the repo (console/, vendor/, scripts/, etc.)
-                  #     external — web search
-                  #     all      — vault + codebase + web
-                  #   Default "internal" when omitted. This is a CONSISTENCY fix, not a new
-                  #   requirement — scope is NOT required and has no grace window
-                  #   ([[HS-NGD1-TASK-consolidate-and-fix-the-research-scope-field]]). Written the
-                  #   same way (same enum, same default) by `heyspex_save_research`,
-                  #   `heyspex_promote_capture`, and `heyspex_complete_research`. Validated as a
-                  #   string enum by `schemas/heyspex-frontmatter.schema.json` (distinct from the
-                  #   unrelated freetext `scope:` on `type: protocol`).
-enhances:         # REQUIRED when set — bidirectional consistency rule. If `enhances:` exists, the
-                  #   target milestone MUST list this research in `informed_by:` (see §Provenance edges).
-                  #   Single wikilink to the HS-MIL-* this research enhances. Not an array (M:1 rule).
-                  #   Open research may omit during exploration; the validator enforces bidirectional
-                  #   consistency whenever the field IS set. A research doc that spans multiple
-                  #   milestones must be split first ([[HS-TQQS-GTH9-TASK-hs-split-research-mcp-tool]]).
-                  #   NOTE: `scripts/validate-vault-ids.mjs` still gates on the legacy
-                  #   `status: closed` framing — validator catch-up to this "when set" framing is on
-                  #   the deferred list in [[research-is-evergreen]].
-sources_captures: # optional, list of wikilinks to HS-CAP-* — captures this research aggregates (M:N).
-                  #   Reverse of `capture.informs_research:`. Bidirectional consistency enforced.
-spawned_epics:    # optional, list of wikilinks to HS-EPIC-* — epics this research spawned (1:N).
-                  #   Reverse of `epic.derived_from:`.
-enhances_epics:   # optional, list of wikilinks to HS-EPIC-* — already-existing epics this research
-                  #   augmented (M:N, rare). One-sided in v1 — no reverse field on epic.
-produces_diagnose: # optional, list of wikilinks to HS-DIAG-* — bugs found during this research and
-                  #   promoted to a diagnose (1:N, mirrors `spawned_epics`). Reverse of
-                  #   `diagnose.derived_from:`. Written by `heyspex_promote_research_to_diagnose`
-                  #   ([[HS-W5VP-MSHY-TASK-research-diagnose-link-send-bugs-to-the]]); reuses the existing
-                  #   diagnose machinery — see [[resolution-diagnose-workflow]].
-split_into:       # optional, list of wikilinks — on the original (archive) research when split;
-                  #   names the child research docs that carry forward.
-split_from:       # optional, single wikilink — on a research created by splitting from an ancestor;
-                  #   mirror of `split_into:` on the ancestor.
-source_capture:   # optional wikilink to HS-CAP-* — legacy single-capture seed pointer; retained for
-                  #   read-side back-compat. New research uses `sources_captures:` (M:N) as canonical.
-planning_flow:    # optional until flow filed; then wikilink to HS-FLOW-*
-bound_epic:       # optional; set when epic filed — locks findings to append-only ([[planning-flow-research-epic-lifecycle]])
-forked_from:      # optional, wikilink — source HS-RES when forked for a new epic
-```
-
-Body is the research note. After `bound_epic:` is set, findings sections are append-only; new epic scope uses `## Scope for <epic name>` addendum sections.
-
-##### Code-audit findings table (`research_type: code-audit`)
-
-A `research_type: code-audit` doc's body **must** carry a findings table — the authored standard for "reviewed the code, found N things, here's what happens to each" (HS-7D0I-WL88-TASK-code-audit-research-type-with-a-defined). Four columns, in this order:
-
-| Finding | Severity | Action (diagnose\|task\|reference) | Exit (open\|closed) |
-| --- | --- | --- | --- |
-| One-line description of what was found | freetext (e.g. high/med/low) | `diagnose` \| `task` \| `reference` | `open` \| `closed` |
-
-Every row's `Action` maps to exactly one of three defined exits — no fourth "just leave it" option:
-
-- **`diagnose`** — a real bug. Promote it with the existing `heyspex_promote_research_to_diagnose` tool (HS-W5VP-MSHY-TASK-research-diagnose-link-send-bugs-to-the), which writes `research.produces_diagnose:` / `diagnose.derived_from:` (see §Provenance edges). Not new machinery — reuse it.
-- **`task`** — a cleanup/follow-up with no bug attached. File a task and set its `discovered_from: [[HS-RES-…]]` back to this research doc (see `task.discovered_from` above and §Dependencies "Discovered-from").
-- **`reference`** — non-actionable; the row itself IS the exit. Set `Exit: closed` directly, no further linkage required.
-
-**Enforcement** (`spex-console/src/lib/indexer/vault-rules.mjs`):
-
-- `CODE_AUDIT_FINDINGS_MALFORMED` — no findings table, or one that doesn't match the 4-column header shape, or a data row with an unrecognized `Action`/`Exit` value. Warning during the `CODE_AUDIT_GRACE_END` grace window (mirrors `RESEARCH_TYPE_GRACE_END`'s pattern — pre-existing code-audit docs like `HS-ZHAB-RES-doc-authoring-contract-audit-required-st` predate this format and are exempt while the window is open), then a hard error.
-- `CODE_AUDIT_FINDINGS_OPEN_ON_CLOSE` — the **closure gate**: a code-audit doc at `status: closed` or `review_pending` with any finding row whose `Exit` is `open`. Warning during the same grace window, then error — blocks closing a code-audit doc until every finding has exited.
-
-#### `planning-flow`
-
-Orchestration artifact for epic filing (planning-flow-research-epic-lifecycle). Body contains a `## Planning flow` section with fenced `mermaid` (semantic source for canvas projection per spec-diagram-design-vs-as-built-canvas).
-
-```yaml
-type: planning-flow
-research:         # required, wikilink to HS-RES-*
-decisions:        # optional, list of wikilinks — memory-decision or adr
-epic:             # optional until epic filed; then wikilink to HS-EPIC-*
-has_diagram:      # required, true — indexes canvas bridge + Shipped gallery when closed
-related:          # optional, wikilinks to tasks and supporting specs
-```
-
-#### `roadmap`
-
-```yaml
-type: roadmap
-roadmap_manifest:   # required, machine-readable phase index (see below)
-related_roadmaps:   # optional, wikilinks to other HS-ROADMAP-* specs
-```
-
-`roadmap_manifest` shape (indexer validates; agents request via `--compact`):
-
-```yaml
-roadmap_manifest:
-  version: 1
-  phases:
-    - id: M2                    # short stable id
-      name: Indexer MVP
-      tasks: [HS-V3YS, HS-1BML]   # HS-NNNN or HS-EPIC-NNNN ids
-  horizon:                      # may not ship — priority-4 / tag:horizon backlog
-    - HS-WYHZ
-  initiatives:                  # optional links to other roadmap docs
-    - HS-ROADMAP-VOICE-CHROME
-```
-
-Body is the human narrative (goals, exit criteria, risks). **Do not duplicate** the task list in prose without mirroring ids in `roadmap_manifest` — the manifest is the console/CLI source of truth for ordering.
-
-Horizon items use native `HS-NNNN` ids (or wikilinks to `future-considerations/` research until promoted). No separate FC id namespace (adr-0012-roadmap-storage).
-
-#### `draft`
-
-```yaml
-type: draft
-source:           # optional, where this draft came from (URL, "phone capture", "screenshot", etc.)
-captured_at:      # required, ISO-8601 datetime
-source_intent_hash: # optional but required on Agent ingest; SHA-256 of canonical capture blob ([[plan-ingest-review-roadmap-workflow]])
-source_intent:    # optional verbatim excerpt (≤2 KB) of human inputs at capture time
-agent_output_hash: # optional; SHA-256 of structured Agent preview at Save-to-drafts
-review_stage:     # optional, enum: inbox | deliberating | staging | review | promoted | rejected
-council_requested: # optional bool | null — per-submit override; null = apply deliberation.triggers policy ([[council-opt-in-pre-review-conditioning]])
-triage_record:    # optional; scout pre-pass ([[council-triage-scout-optional-llm]], [[review-inbox-workshop-scout-overview]])
-deliberation_record: # optional; Gate 0 output ([[ai-deliberation-gate]]) — append-only runs
-suggestions:      # optional; staged Gate A records ([[HS-EU98-GCGE-TASK-staged-draft-suggestion-schema]]) — omit when empty
-review_record:    # optional; Gate A commit audit — who/when/per-suggestion outcomes
-ingest_mode:      # optional, enum: manual | agent_llm — default manual when omitted
-capture_scope:    # optional, enum: selection | full — did a highlight scope the body? (HS-M54O); absent ⇒ full
-purpose:          # optional free string — the user's stated "why" for capturing (HS-7S40)
-context_blocks:   # optional list of { source: typed | voice, text, at: ISO-8601 } — enrichment
-                  # added on the intent card (HS-JQ7O/0077), each bound to this draft's trace_id.
-                  # Append-only within a trace_id; ordered by `at`. Absent ⇒ no extra context.
-llm_route:        # optional, required when ingest_mode is agent_llm — builder-selected route from console picker:
-                  # chatgpt | gemini | claude | auto | ... (enum grows with integrations; must stay in sync with UI labels)
-llm_resolved_at: # optional, ISO-8601 datetime when ingest_mode agent_llm — when the routed model finished
-resolved_model:  # optional free string or structured id — actual provider/model id after routing (meaningful when llm_route: auto or when aliases map to concrete models)
-submission_kind:  # optional, enum: external_media | refined_intent — Gate 0 epistemic mode ([[companion-external-media-vs-refined-intent-council]]); companion defaults external_media
-capture_channel:  # optional, enum: manual_ui | cli | voice | extension | companion | ...
-companion_dialogue: # optional append-only [{ role: user|assistant, text, at }] — pre-send chat about capture ([[HS-67TW-2966-TASK-companion-pre-council-context-dialogue]]); omit when empty
-capture_group_id:  # optional string — shared id linking multiple captures made in one multi-capture
-                   # companion session; drafts sharing this id render as a connected set on the
-                   # Captures surface, ordered by capture_group_seq. Distinct from capture_bundle_id
-                   # below (one composite draft with multiple sources) — this links multiple SEPARATE
-                   # draft files. Omit for standalone single captures.
-capture_group_seq: # optional positive integer — 1-based position within capture_group_id's group.
-                   # Only meaningful when capture_group_id is set.
-capture_bundle_id: # optional UUID — companion-local bundle id when submitted from Capture inbox ([[companion-capture-inbox-and-bundles]])
-source_set:       # optional — multi-source bundle; list of members, each with { url | file_path, title, member_trace_id, member_note, file_size?, file_type? }
-                  # For web captures: url (required), title, member_trace_id, member_note ([[HS-D1YU-OVFO-TASK-bundle-submit-composite-draft-source-set]])
-                  # For file captures: file_path (required), title (filename), file_size, file_type, member_trace_id, member_note ([[HS-5FI0-0036-EPIC-file-system-selection-voice-capture]])
-                  # Omit for single-source captures
-wake_used:        # optional bool — companion wake phrase invoked (vs shortcut-only capture)
-foreground_app:   # optional string — OS-visible focused app title/name at capture time
-spoken_command_tail: # optional sanitized transcript excerpt when capture_channel includes voice (see [[uc-voice-ingest-hey-spex]])
-shortcut_binding_id: # optional stable identifier for whichever hotkey initiated capture
-voice_companion_semver: # optional — installed companion semantic version emitting the draft
-pointer_screen_x: # optional — mouse pointer X in screen px, sampled once at ingest trigger
-pointer_screen_y: # mouse pointer Y (screen px)
-pointer_dpi_scale:
-pointer_sampled_at: # ISO-8601
-last_click_screen_x:
-last_click_screen_y:
-last_click_at:
-spatial_hint_ttl_ms:
-chrome_viewport_ratio_x:
-chrome_viewport_ratio_y:
-pointer_dom_hint: # optional heuristic from Chrome elementFromPoint; non-authoritative
-
-# File capture provenance (when source_type: local_file) — [[HS-5FI0-0036-EPIC-file-system-selection-voice-capture]]
-source_type:      # optional enum: local_file | url — discriminator; url is default/implicit for browser captures
-file_path:        # optional string — absolute path (single file or root folder); present when source_type: local_file
-file_size:        # optional int — file size in bytes
-file_type:        # optional string — MIME type or file extension
-file_modified_at: # optional ISO-8601 — file mtime at capture
-folder_depth:     # optional int — recursion depth when folder captured
-folder_file_count: # optional int — total files in folder/zip capture
-zip_extracted:    # optional bool — true if zip was extracted to temp for ingestion
-zip_source_path:  # optional string — original zip path when zip_extracted: true
-sensitive_files_included: # optional list of { path, pattern_matched, user_confirmed_at } — audit when user overrode sensitive file warning
-```
-
-Body is the ingested content; triage promotes a draft into a task, memory, or research file by editing the frontmatter `type:` and moving the file.
-
-Agent-assisted drafts **should** end the markdown body with a short human-readable provenance line so readers skimming raw files see how the draft was produced; **frontmatter carries the authoritative fields.**
-
-Example footer (console-rendered; values must mirror frontmatter):
-
-```markdown
-
----
-
-_Ingest provenance:_ route `claude` → resolved `anthropic/claude-3-7-sonnet` · _Captured:_ 2026-05-16T12:00:00Z
-```
-
-See uc-ingest-anywhere §Console toggle: Manual vs Agent ingest, HS-DOC-architecture-foundations §What it exposes (API), companion capture + optional spatial hints in uc-voice-ingest-hey-spex §Persistence / §Spatial pointers when `capture_channel: voice`.
-
-**`deliberation_record`** (when present):
-
-Permitted on `draft`, `task`, `epic`, and `review` types — Council session output, append-only across all four ai-deliberation-gate invocation points per adr-0015-council-as-cross-cutting-capability. The host spec retains its existing type; the record is purely advisory and never gates anything (human disposition stays in Gates A/B/C per heyspex-north-star Principle 3).
-
-```yaml
-deliberation_record:
-  latest_run_id: "<uuid>"
-  runs:
-    - run_id: "<uuid>"
-      at: "<ISO-8601>"
-      invocation_point: pre_review | canvas_live | promoted_recheck | review_close
-                                                  # which of the four Council invocation points produced this run
-                                                  # (per [[adr-0015-council-as-cross-cutting-capability]])
-      submission_lens: refined_intent | external_media | promoted_spec_recheck
-                                                  # role objective discriminator — lifts the draft body's
-                                                  # `submission_kind` to the run so promoted-spec contexts carry it
-      parent_run_id: "<uuid>" | null              # loop-suppression input; null on first run for a spec
-      test_preset: free | cheap | production | null  # when [[ai-deliberation-gate]] test_mode was active
-      api_calls: 4                                # optional audit — varies by invocation: 1 (canvas_live),
-                                                  # 3 (review_close, skip rebuttal), 4 (pre_review skip_rebuttal),
-                                                  # 7 (full pre_review or promoted_recheck)
-      roles:
-        - id: tech_lead | program_lead | ux_lead
-          provider: "<string>"
-          model: "<string>"
-          position:
-            disposition: schedule_now | schedule_later | horizon | defer | deprecated | merge | reject | split
-            priority: 0-4
-            roadmap_phase: "<id>"
-            merge_into: "[[HS-NNNN]]"
-            north_star_alignment: aligned | tension | conflict
-            arguments: ["<bullet>"]
-      facilitator:                                # absent on `canvas_live` (single-role) and on
-                                                  # `review_close` when skip_rebuttal is set
-        recommended_disposition: "<enum>"
-        confidence: 0.0-1.0
-        disagreements: ["<role_a vs role_b on topic>"]
-      north_star_conflict:   # present when ≥2 roles report conflict
-        agreed: true
-        summary: "<string>"
-        path_a_change_l1: { summary, typical: false }
-        path_b_reshape_plan: { summary, suggested_edits: [] }
-```
-
-**Storage bound:** `runs[]` is capped at the last 10 entries in frontmatter; older runs archive to `specs/.deliberation-archive/<spec-id>.yaml` (gitignored, audit-only) per adr-0015-council-as-cross-cutting-capability §Consequences.
-
-**`triage_record`** (when present; scout only — not council):
-
-```yaml
-triage_record:
-  at: "<ISO-8601>"
-  model: "<slug>"
-  title_line: "<≤80 chars>"
-  memory_jogger: "<2-3 sentences>"
-  review_category: feature_request | external_media | brainstorm | research | bug | mixed | unclear
-  recommend_council: true | false
-  confidence: 0.0-1.0
-  rationale: "<string>"
-  suggested_actions:
-    - id: run_council | add_context | gate_a_review | defer | promote_quick | discard
-      label: "<string>"
-      primary: true
-  quick_tags: ["<optional>"]
-```
-
-**`suggestions`** (when present; omit block entirely when empty — pre-HS-GCGE-TASK drafts unchanged):
-
-```yaml
-suggestions:
-  - id: "<stable-uuid-within-draft>"
-    kind: roadmap | priority | child_task | consideration
-    payload: {}          # kind-specific proposed fields (epic stub, priority, etc.)
-    rationale: "<one line>"
-    disposition: pending | accepted | edited | declined
-    edited_payload: {}   # optional; present when disposition: edited
-    provenance:
-      llm_route: "<enum>"
-      resolved_model: "<provider/model>"
-      at: "<ISO-8601>"
-```
-
-**`review_record`** (written on Gate A staging commit):
-
-```yaml
-review_record:
-  at: "<ISO-8601>"
-  by: pwher
-  outcomes:
-    - suggestion_id: "<uuid>"
-      disposition: accepted | edited | declined
-      note: "<optional>"
-```
-
-#### `daily`
-
-```yaml
-type: daily
-date:             # required, ISO-8601 date
-```
-
-Body is free-form notes for the day.
-
-## Body structure conventions
-
-Beyond the type-specific required sections noted above, all specs follow these structural conventions:
-
-- The first heading is `# <Name>` (the human-readable title), matching `name:` in frontmatter.
-- Optional first block: a single `> [!note]` / `> [!important]` callout if there's a one-line framing message.
-- Sections use `##` headings. Sub-sections `###`.
-- A spec ends with `## Related specs` (optional) and `## Change log` (required for L1, L2, L3, ADR, and protocol; optional but encouraged elsewhere).
-
-### Recommended sections for long-lived specs
-
-Two SCEH-Pattern conventions (HS-U88E-SP34-EPIC-sceh-patterns-3-and-4-markdown-conventions) define optional `##` sections useful on specs that accumulate work across many sessions:
-
-| Section | Protocol | Use when | Placement |
-|---|---|---|---|
-| `## Session Boundaries` | session-boundary-marker | Multi-session epics, milestones, and HS-REV review docs benefit from a five-column session-by-session trail (`session_id` / `agent` / `started` / `ended` / `summary`). | Immediately above `## Change log`. |
-| `## Conflict Resolution` | conflict-resolution-section | Two or more sessions left contradictory opinions in the body, change log, or HS-REV companions and a reviewer has had to pick. Three-row table (opinions + bold `**resolution**`) with optional memory-extraction routing into `memory-decision` specs. | Below `## Session Boundaries` if present, above `## Change log`. |
-
-Both are **recommended** — opt-in per spec, not enforced by the wikilink validator. They are content commentary about the spec; control-plane runtime state (claim/focus/spec events, handoff context) stays in Neon (control-plane-belongs-in-neon).
-
-## Dependencies
-
-HeySpex inherits beads' four dependency types and adds a normalization choice: dependencies are expressed **both** as structured frontmatter arrays **and** as inline wikilinks in body prose. The frontmatter is canonical for queries; the body wikilinks are for reading flow.
-
-| Type | Frontmatter field | Inverse field | Semantics |
-| --- | --- | --- | --- |
-| **Blocks** | `blocks: [[...]]` | `blocked_by: [[...]]` | Hard. A blocked task is not ready until all `blocked_by` resolve. |
-| **Related** | `related: [[...]]` | `related:` (symmetric) | Soft. Navigational only; no readiness implication. |
-| **Parent-child** | `children: [[...]]` | `parent: [[...]]` | Hierarchical. Children roll up to parent for "completion of parent" calculations. |
-| **Discovered-from** | `discovered_from: [[...]]` | `discovered:` (list) | Provenance. "This task was born while working on X." |
-| **Iterates-on** | `iterates_on: [[...]]` | `iteratedBy:` (computed) | Re-attempt. "This initiative re-attempts an outcome the target shipped but did not fully deliver." No readiness implication; neither doc is demoted. See §Iteration lineage below. |
-
-Rules:
-
-- The indexer maintains both sides of every edge; the Builder only needs to write one side, and the console fills the other on save. (Implementation detail; specified in HS-DOC-architecture-foundations.)
-- The indexer rejects edges that form a cycle in the `blocks` graph or the `parent`/`children` graph.
-- `related` edges are symmetric; the indexer enforces symmetry on save.
-- A task without a `parent:` and not referenced as a child by anyone is treated as a top-level task.
-- `discovered_from` is single-valued; if a task has multiple origins, model the additional ones as `related:`.
-
-## Provenance edges (capture → research → milestone)
-
-The promotion lifecycle — capture observation → research synthesis → milestone commitment — has cross-type provenance edges with strict cardinalities. Ratified by HS-OFR5-M2J3-EPIC-introduce-milestones-as-highest-entity §Architecture; enforced by `scripts/validate-vault-ids.mjs` (HS-HQRM-YJX6-TASK-research-enhances-exactly-one-milestone-validator-and-bidirectional-linkage).
-
-| Edge | Cardinality | Forward field | Reverse field |
-| --- | --- | --- | --- |
-| **Capture → Research** | M:N | `capture.informs_research: [[[HS-RES-…]]]` | `research.sources_captures: [[[HS-CAP-…]]]` |
-| **Research → Milestone** | **M:1** (strict) | `research.enhances: [[HS-MIL-…]]` (single, not array) | `milestone.informed_by: [[[HS-RES-…]]]` |
-| **Research → Epic (spawned)** | 1:N | `research.spawned_epics: [[[HS-EPIC-…]]]` | `epic.derived_from: [[HS-RES-…]]` (single) |
-| **Research → Epic (augmented)** | M:N | `research.enhances_epics: [[[HS-EPIC-…]]]` | (one-sided — no reverse field on epic in v1) |
-| **Research → Diagnose (bug found)** | 1:N | `research.produces_diagnose: [[[HS-DIAG-…]]]` | `diagnose.derived_from: [[HS-RES-…]]` (single) |
-
-Rules:
-
-- **Research is M:1 to milestone — strict.** A single research doc that spans multiple milestones must be split before promotion. The split-action protocol is owned by HS-TQQS-GTH9-TASK-hs-split-research-mcp-tool; the original research stays as the audit archive with `status: closed` and `split_into: [[HS-RES-A]], [[HS-RES-B]]`, while N child research docs each carry `split_from: [[HS-RES-original]]` and their own `enhances:` target.
-- **Open research may omit `enhances:`.** The validator only requires it on `status: closed` research (the promotion-time gate); during exploration the target milestone can still be ambiguous.
-- **`enhances:` is single-valued.** Not an array — the validator rejects array form and points the author at the split flow.
-- **Bidirectional consistency is enforced.** If research X has `enhances: Y`, milestone Y MUST list X in `informed_by:`. If capture C has `informs_research: [X, Y]`, both X.sources_captures and Y.sources_captures MUST include C. The validator surfaces one-sided drift as a hard error on each side.
-- **Captures M:N research is intentional.** A single capture may inform multiple research docs over time (e.g. a "voice capture works" observation that lands in both companion research and console-voice research). The first promotion writes `capture.promoted_to:` (binary pointer); subsequent re-uses extend `capture.informs_research:` without touching `promoted_to:`.
-- **`spawned_epics` vs `enhances_epics`.** `spawned_epics` is the canonical 1:N edge — epics this research *created*, mirrored as `epic.derived_from:` on each child. `enhances_epics` is the rarer case where research *augmented* an already-existing epic; it's a one-sided list with no reverse field in v1.
-- **`produces_diagnose` mirrors `spawned_epics`.** A research investigation may surface a bug, which is promoted into a first-class `HS-DIAG-*` (not new machinery — the existing diagnose entity per resolution-diagnose-workflow). `research.produces_diagnose:` is the canonical 1:N edge, mirrored as `diagnose.derived_from:` on each child, written by `heyspex_promote_research_to_diagnose`. This is the research-side sibling of the capture-side exit `heyspex_promote_capture_to_diagnose` (which writes `diagnose.promoted_from:` ⇔ `capture.promoted_to:`/`informs_diagnose:` instead).
-
-Promotion-action contract (`/hs-promote-research`, HS-2ERO-QQHP-TASK-hs-promote-research-mcp-tool): writes all four sides (research.enhances, research.spawned_epics, milestone.informed_by, epic.derived_from) atomically. The validator is the safety net for hand-edited drift, not the primary write path.
-
-## Iteration lineage (round-to-round re-attempts)
-
-The **third doc-to-doc relation tier**, alongside supersession (terminal, whole-doc) and amends (partial, non-terminal) — ratified via HS-3TZX-T9T6-RES-iteration-loop-lineage-and-capture Part A, built by HS-O97P-T9T6-EPIC-iteration-loop-lineage-relation-tier. It expresses what neither existing tier can: *work shipped and closed, the outcome fell short of the goal, and a NEW family re-attempts the SAME goal.* Supersession would falsify round 1 (it wasn't wrong — it shipped, its review is accurate history); amends would misdescribe it (round 2 contradicts nothing).
-
-### Fields
-
-```yaml
-iterates_on:      # optional, YAML list of wikilinks — lives ONLY on the NEWER doc (one-edit-on-source,
-                  #   same principle as amends). Semantics: "this initiative re-attempts an outcome the
-                  #   target initiative shipped but did not fully deliver." Typically carried by the
-                  #   round-2 research doc pointing at the round-1 research doc — the research chain is
-                  #   the spine (research is evergreen, so the root research id is the durable handle
-                  #   spanning every round; no new entity type).
-# iteratedBy      — COMPUTED reverse map (indexer/validator output, like amendedBy) — never written
-                  #   by hand into frontmatter.
-outcome:          # optional, on TRACKABLE docs only, set by the HUMAN REVIEWER at close — never
-                  #   inferred, never agent-set. Enum: met | partially-met | not-met. Lives ONLY on
-                  #   the closed doc (not echoed onto the round-2 doc; discovery goes through the
-                  #   iteratedBy reverse map).
-outcome_note:     # optional, one-line reviewer prose qualifying the verdict.
-```
-
-### Invariants
-
-- **Nothing is demoted.** Both docs stay `canonical: true`; round 1 keeps `status: closed`. `iterates_on:` is a lineage edge, not a supersession — demoting round 1 to `canonical: false` would falsify the record and hide shipped scope from round 2's breakdown.
-- **`outcome:` is the reviewer's judgment alone.** `status: closed` without an `outcome:` says only "shipped"; it must never be read as "goal met." The verdict is written at reviewer close (the one mutable-at-close moment), per [[session-close-protocol]].
-- **Distinct family keys are correct.** Round 2 is its own initiative with its own children and review, so it takes a new family key; `iterates_on:` is the cross-family edge that replaces the missing shared grep handle.
-
-### Required `## Related / lineage` section on promoted docs
-
-Every promoted doc's outline ends with a resolved-wikilink table (immediately before `## Change log`), authored at promote-time and gated by `heyspex_validate_linkage` (every row must resolve under `specs/`):
-
-```markdown
-## Related / lineage
-
-| Doc | Role |
-|---|---|
-| [[round-1-research]] | Iterates on |
-| [[HS-REV-...]] | Prior attempt's review |
-| [[HS-CAP-...]] | Feedback capture |
-```
-
-Role vocabulary: **Iterates on · Prior attempt's review · Feedback capture · Amends · Superseded by · Pillar · Spawned epics** (extend with prose roles when none fits — e.g. "Source capture", "Enhances").
-
-## Evidence linking
-
-> [!important] "Summaries with receipts"
-> Ratified by adr-0008-branch-brief-and-evidence-schema for HS-7KOO-0022-EPIC-continuity-layer-gaps. Every claim a memory or brief makes should be able to point at a verifiable source. Without evidence, a summary is unfalsifiable; with it, a reader can navigate from claim to proof.
-
-`evidence:` is an optional array on `branch-brief`, `memory-lesson`, `memory-decision`, `memory-reference`, `memory-ui-pattern`, and `task`. Each entry:
-
-```yaml
-evidence:
-  - type: commit          # required — one of the evidence types below
-    ref: "abc123"         # required — the reference, format per type
-    line: 42              # optional — line number (file/diff only)
-    description: "..."     # optional — what this evidence shows
-```
-
-Evidence types:
-
-| Type | `ref` format | Example |
-| --- | --- | --- |
-| `commit` | short or full SHA | `abc123`, `abc123def…` |
-| `file` | repo-relative path, optional `:line` | `src/foo.ts`, `src/foo.ts:42` |
-| `pr` | PR number | `#123` |
-| `diff` | `commit:path` | `abc123:src/pages/dashboard.tsx` |
-| `issue` | issue number | `#42` |
-| `note` | freeform text | `Builder confirmed via Slack 2026-05-15` |
-| `test` | test/gate identifier | `vitest:src/lib/continuity/plan-vs-actual.test.ts`, `tsc:noEmit` |
-
-> [!note] `test` added 2026-08-11 (receipt-on-ship, HS-XGG4-IU2S-EPIC-receipt-on-ship-plan-vs-actual-proof-at). Additive extension per adr-0008-branch-brief-and-evidence-schema §Consequences ("a future change to evidence types … is a normal entity-model edit"); lets Plan Receipts cite test/gate results as typed evidence.
-
-### Inline shorthand
-
-In body prose, evidence may be cited inline as `[evidence:<type>:<ref>]`:
-
-```markdown
-We chose Payment Elements over hosted checkout [evidence:commit:abc123]
-because it gives better customization [evidence:pr:#123].
-```
-
-The indexer harvests inline shorthand and the frontmatter `evidence:` array into the same evidence index; **frontmatter is canonical** for "what grounds this spec?" queries (same rule as `tags:` and dependency edges). Console rendering of evidence references (commit → diff view, file → file viewer at line, pr/issue → git host) is an implementation concern specified downstream, not part of this schema contract.
-
-## Delivery snapshot
-
-> [!note] User-persisted, not auto-maintained
-> See HS-WB81-RBJ8-TASK-spec-delivery-frontmatter-snapshot. The live source of truth for "which commits touched this spec" is always `git log -- <spec_path>`; the `delivery:` block is an *optional persisted snapshot* the Builder takes from the console's On Deck row so the vault carries its own delivery trail.
-
-`delivery:` is an **optional, cross-type** key. It exists only after the Builder has clicked "snapshot to spec" in the console's delivery dropdown. Shape:
-
-```yaml
-delivery:
-  snapshot_at: 2026-05-21T07:00:00-05:00   # ISO timestamp of when the snapshot was taken
-  commits:
-    - sha: 8648ad5e3f...                    # full SHA
-      short_sha: 8648ad5                    # 7-char SHA
-      branch: hs-mvp0520                    # primary branch (local before remote)
-      pushed: true                          # boolean — reachable from origin/*
-      at: 2026-05-21T05:14:32-05:00          # commit author time
-      author: pwher
-      message: "feat(console): per-spec delivery dropdown on On Deck child rows"
-```
-
-Rules:
-
-- One primary branch per row, not the full branch list (live view stays authoritative for fan-out).
-- `message` is the first commit-message line only; full commit bodies live in git, not the vault.
-- `delivery:` may be present on **any** spec type; treat it as a presentational artifact, not a dependency edge — the indexer does not crawl it.
-- A stale snapshot (live count ≠ snapshot count) is rendered as such in the console; the snapshot is never auto-refreshed.
-- Persisted by `PUT /api/specs/[id]/delivery`; no git hook or agent workflow rewrites it.
-
-## Wikilink resolution rules
-
-HeySpex uses Obsidian-compatible wikilinks: `[[target]]` or `[[target|display text]]`.
-
-Resolution algorithm:
-
-1. **Strip extension.** `[[foo]]`, `[[foo.md]]`, and `[[foo|Foo]]` all target the file basename `foo`.
-2. **Case-insensitive match.** The resolver compares lowercased basenames. `[[Foo]]` and `[[foo]]` resolve to the same file.
-3. **No path qualifier needed.** Folders are not part of the resolution. `[[entity-model]]` finds `specs/entity-model.md` regardless of where the linking spec lives. (Consistent with Obsidian's "default" link mode.)
-4. **Aliases.** If a spec's frontmatter has `aliases: [foo, bar]`, both `[[foo]]` and `[[bar]]` also resolve to that spec.
-5. **Forward references are valid.** A wikilink to a non-existent spec is not an error; it is a signal that the linked spec should be written. The indexer records forward references in a `forward_refs` view; the console shows them inline so the Builder can see what's pending.
-6. **Duplicate basenames are forbidden.** Two specs may not share a basename. The indexer rejects writes that would create a duplicate.
-7. **Filename is canonical; do not author id-form links.** The resolver also matches a link target against a spec's frontmatter `id:` (it tries id → basename → alias, in that order). This is a **tolerant fallback** so that hand-typed or legacy `[[HS-DEC-…]]`/`[[HS-TASK-…]]` links still resolve — it is **not** the form to write. Author every link by **filename basename** so the vault stays Obsidian-portable (Obsidian does not resolve by the `id:` field). For memory specs (decisions, lessons, references, ui-patterns) the file is slug-named while its `id` carries a type prefix, so `[[HS-DEC-foo]]` is the id form and `[[foo]]` is the canonical filename form — prefer the latter. The vault was swept to filename form on 2026-05-28 (`scripts/sweep-hs-dec-links-to-basename.mjs`).
-
-Display text:
-
-- `[[entity-model|the entity model]]` renders "the entity model" as a link to `entity-model.md`.
-- This is the same syntax Obsidian uses; HeySpex inherits it unchanged.
-
-## Tags
-
-Tags use the `tags:` array in frontmatter. They are flat strings, no nesting (no `#foo/bar` semantics in v1 beyond convention).
-
-Body-inline `#tag` syntax is allowed for compatibility with Obsidian users; the indexer harvests both frontmatter tags and body inline tags into the same index, but frontmatter is canonical for "is this spec tagged X?" queries.
-
-## Reserved frontmatter keys
-
-The following keys are reserved by HeySpex and must not be repurposed:
-
-- `id`, `name`, `type`, `status`, `priority`, `owner`, `created`, `updated`, `tags`, `related`, `aliases`
-- `blocks`, `blocked_by`, `parent`, `children`, `discovered_from`, `discovered`
-- `assignee`, `started_at`, `closed_at`, `close_reason`, `defer_until`
-- `evidence` (cross-type; see [Evidence linking](#evidence-linking))
-- `delivery` (cross-type; user-persisted git-log snapshot — see [Delivery snapshot](#delivery-snapshot))
-- `legacy_bd_id`, `legacy_dolt_commit`
-- Type-specific fields named above (including `branch-brief`'s `branch`, `goal`, `implements`, `plan`, `actual`, `risks`, `open_questions`, `next_steps`, `decisions`; `milestone`'s `epics`, `target_date`, `informed_by`; the `epic`'s `milestone` parent pointer and optional `derived_from`; `task`'s `split_of`, `split_index`, `handoff_id` (split lineage — envelope lives in body) and optional `affects_paths`; `research`'s `enhances`, `sources_captures`, `spawned_epics`, `enhances_epics`, `produces_diagnose`, `split_into`, `split_from`; `diagnose`'s optional `promoted_from` and `derived_from`; `capture`'s `informs_research`; the `agent` type's `role`, `model`, `allowed_tools`, `disallowed_tools`, `procedures`, `handoffs`, `guardrails`, `lane`, `color`, `owned_paths`, and `source_attribution` import-provenance object). Type-specific fields are additive and do **not** require an ADR (only a new *universal* reserved key does); `source_attribution` was added under HS-GMLJ-K3KR-TASK-lock-the-community-import-design-and-add; `owned_paths` / `affects_paths` under HS-ZMAQ-M15C-TASK-declare-owned-path-globs-on-agent-identi.
-- `reviews` (review type — back-compat alias for `parent:` pointing at the spec under review)
-
-Adding a new universal reserved key requires an ADR.
-
-## Validation
-
-The indexer (see HS-DOC-architecture-foundations §Indexer) runs frontmatter validation on every write:
-
-- All required fields present and of the expected type.
-- `id` matches the entity type's pattern.
-- `id` is unique across the vault.
-- `status` is in the enum.
-- All wikilinks in frontmatter resolve, or are tracked as forward references.
-- No cycles in `blocks` or `parent`.
-- No duplicate basenames.
-
-Validation failures are surfaced in the console and via `hs lint`. They do not block git writes (the vault is plain text and the Builder is trusted), but the indexer marks the affected spec as invalid until corrected.
-
-## Examples
-
-### Minimal task
-
-```markdown
----
-id: HS-O3E0
-name: Fix console keyboard navigation
-type: task
-status: open
-priority: 2
-owner: pwher
-created: 2026-05-14
-updated: 2026-05-14
-kind: bug
-blocked_by:
-  - "[[HS-IS1A-TASK-SpexConsole-routing-rewrite]]"
-related:
-  - "[[HS-582Q-TASK-arrow-key-conflicts]]"
-tags: [console, ux, keyboard]
----
-
-# Fix console keyboard navigation
-
-Arrow keys do not move focus between issues in the list view; only Tab works. Compare to Linear, where ↑/↓ navigates the list.
-
-## Acceptance
-
-- Up/Down arrow keys move focus between rows in `IssuesSurface`.
-- Enter on a focused row opens the detail pane.
-- No regression for input fields (arrow keys still move the caret inside text inputs).
-
-## Change log
-
-| Date | Author | Change |
-| --- | --- | --- |
-| 2026-05-14 | pwher | Created from drafts/triage. |
-```
-
-### Memory lesson
-
-```markdown
----
-id: HS-LES-bd-process-leak
-name: bd CLI process leak
-type: memory-lesson
-status: open
-priority: 1
-owner: pwher
-created: 2026-05-14
-updated: 2026-05-14
-topic: bd-process-leak
-observed: 2026-05-14
-related:
-  - "[[HS-LES-dolt-embedded-windows]]"
-  - "[[adr-0006-replace-beads]]"
-tags: [bd, dolt, windows, process-leak]
----
-
-# bd CLI process leak
-
-## Problem
-
-A single `bd create` issued the prior session sat alive consuming 107 GB working set, plus seven orphaned bd procs at ~67 MB each. RAM hit 80% of 128 GB.
-
-## Fix
-
-At session start, run `Get-Process bd | Sort WorkingSet -Desc` on Windows and kill any orphans before issuing new bd commands. Be wary of invoking `bd create` with `run_in_background` — bd does not always exit cleanly when the parent harness moves on.
-
-## Change log
-
-| Date | Author | Change |
-| --- | --- | --- |
-| 2026-05-14 | pwher | Migrated from bd memory `lessons/bd-process-leak`. |
-```
-
-## Open questions
-
-These are intentionally left for the Builder's confirmation in Phase 5 (migration), to avoid pre-committing the migration translation rules:
-
-1. **Resolved (2026-05-18):** Memory uses subfolders — `memory/lessons`, `memory/decisions`, `memory/references`, plus `protocols/` as a Memory subsection on disk (memory-protocols-subsection-of-memory). **2026-05-20:** added `memory/ui-patterns/` (`memory-ui-pattern`). **2026-05-21:** added `memory/ux-principles/` (`memory-ux-principle`). Console Memory surface: All / Lessons / Decisions / References / **UX Principles** / UI Patterns / Protocols.
-2. The id format for migrated tasks — `HS-NNNN-<slug>` with `legacy_bd_id` preserved. Confirm the slug source (proposal: from `title:` lowercased, truncated to ~40 chars, dash-separated).
-3. Whether to expose `body inline tags` (`#tag` inside prose) as queryable, or treat them as decorative-only. Proposal: queryable but frontmatter `tags:` wins on ties.
-4. Whether the `daily/` notes folder should exist at all in v1 (it's not in L1's use cases). Proposal: include it for Builder convenience; cost is one folder.
-
-## Related specs
-
-- heyspex-north-star — the L1 this entity model serves.
-- HS-DOC-architecture-foundations — the tech that implements the contract this document specifies.
-- uc-capture-intent — first-class typed capture and the phone-to-draft path; promotes drafts per §`draft` below.
-- uc-ingest-anywhere — Manual vs Agent ingest; drives optional `draft` LLM provenance fields and body footer conventions.
-- uc-voice-ingest-hey-spex — Hey Spex wake companion + shortcuts; optional `capture_channel: voice` fields above.
-- migration-from-bd — the L3 spec that uses the IDs/filenames defined here.
-- adr-0001-vault-format — the ADR that locks in markdown + YAML + wikilinks as the file format.
-- adr-0008-branch-brief-and-evidence-schema — the ADR that ratifies the `branch-brief` type and `evidence:` key.
-- adr-0012-roadmap-storage — `roadmap` type, `roadmap_manifest`, horizon backlog, ingest provenance fields.
-- plan-ingest-review-roadmap-workflow — default ingest → review → roadmap admission protocol.
-- ai-deliberation-gate — Gate 0 multi-model debate on drafts.
-- ingest-review-deliberation-roadmap-lifecycle — consolidated ingest/roadmap/council decision.
-- HS-ROADMAP-product-master — product phases + horizon manifest.
-- HS-7KOO-0022-EPIC-continuity-layer-gaps — the Continuity Layer epic these additions serve.
-- HS-BVZT-XBPJ-RES-bd-feature-inventory — the research spec that justifies each row of the schema.
-- memory-protocols-subsection-of-memory — Protocols are a Memory subsection in navigation; epics author protocols.
-
-## Change log
-
-| Date | Author | Change |
-| --- | --- | --- |
-| 2026-05-14 | pwher (with claude opus 4.7) | Initial draft. Derived the entity-type set from L1 use cases plus the bd inventory. Locked in four dependency types (matching bd) and Obsidian-compatible wikilink resolution. Folder layout uses subfolders per type for human navigation; resolution is folder-agnostic. |
-| 2026-05-16 | pwher | §`draft`: companion/voice + optional spatial cursor/click hints (uc-voice-ingest-hey-spex §Spatial pointers). |
-| 2026-05-16 | pwher (with claude opus 4.7) | Added `branch-brief` entity type (folder `branches/`, ID `HS-BB-<slug>`, plan/actual + drift enum) and the cross-type `evidence:` array with inline shorthand. Per adr-0008-branch-brief-and-evidence-schema; closes HS-7E41/0052/0053 of HS-7KOO-0022-EPIC-continuity-layer-gaps. |
-| 2026-05-17 | pwher | Added `roadmap` type + `roadmap_manifest`; `future-considerations/` layout; draft `source_intent_hash` / `review_stage`; task `roadmap_admission` / `ingest_draft`. Per adr-0012-roadmap-storage. |
-| 2026-05-17 | pwher | Draft `deliberation_record` (ai-deliberation-gate); task `close_reason` enum + `superseded_by`; archive = filter not folder. |
-| 2026-05-17 | pwher | Draft `suggestions:` + `review_record:` per HS-EU98-GCGE-TASK-staged-draft-suggestion-schema; omit-when-empty rule. |
-| 2026-05-17 | pwher | `submission_kind`, `companion_dialogue[]`; companion `capture_channel` per companion-external-media-vs-refined-intent-council. |
-| 2026-05-17 | pwher | `capture_bundle_id`, `source_set[]` for companion multi-article bundle submit (companion-capture-inbox-and-bundles, HS-D1YU-OVFO-TASK-bundle-submit-composite-draft-source-set). |
-| 2026-05-17 | pwher | `triage_record` scout schema for Review inbox workshop (review-inbox-workshop-scout-overview). |
-| 2026-05-18 | pwher (with claude opus 4.5) | Added `in_review` status to universal enum — human gate between agent work and closure (HS-YYEO-FLX9-TASK-review-column-human-gate-before-done). |
-| 2026-05-20 | pwher | `canvases/diagrams/` + `canvases/as-built/` for spec diagram dual-surface (spec-diagram-design-vs-as-built-canvas). |
-| 2026-05-20 | pwher | Added `specs/canvases/` for JSON Canvas design files per adr-0013-canvas-vault-format-and-obsidian-interop. |
-| 2026-05-20 | pwher | Task/epic ID formats: random alphanumeric suffix for new specs (vault-id-assignment-protocol); legacy `HS-NNNN` migration IDs retained. |
-| 2026-05-21 | pwher | Added `planning-flow` type (`specs/flows/`); research `bound_epic` / `planning_flow`; epic `research` / `planning_flow` requirements (planning-flow-research-epic-lifecycle). |
-| 2026-05-22 | pwher + Claude Opus 4.7 (1M) | `idea` schema: `research_stage` removed (single binary `promoted_to`); body shape v2 — `# Core Idea` / `## Notes` / `## Concept` (≤1200 chars) / `<details>Details</details>`. See HS-KQ5O-IDFV-EPIC-unified-idea-workflow-v2 / HS-QOAC-IDFL-RES-unified-idea-workflow-v2. |
-| 2026-05-22 | pwher + Claude Opus 4.7 (1M) | **Capture rename:** `type: idea` → `type: capture`; new required `kind:` field (idea / bug-fix / clip / reference / question); folder `specs/captures/` → `specs/captures/`; ID prefix `HS-IDEA-*` → `HS-CAP-*` (legacy preserved in `legacy_idea_id:`); research `source_idea:` → `source_capture:`. Per HS-B2B8-DLQI-EPIC-capture-rename-migration-idea-to-capture; source rationale HS-ZKFN-1FXG-CAP-capture-as-universal-companion-verb-and-parent-term. |
-| 2026-05-24 | Claude Opus 4.7 (1M) | Capture schema: added `capture_status: raw \| expanded` (default `raw`). Flipped to `expanded` by MCP `executeUpdateCapture` on core_idea/concept/agent_expansion writes; force-corrected by console save-time linter when `# Core Idea` body has content. Backfilled across 21 existing captures by `scripts/backfill-capture-status.mjs`. Per HS-20PH-P2WA-TASK-b3-new-frontmatter-field-idea-status (B3 of HS-BDDT-Q1B7-EPIC-idea-capture-modal-v3-single-textbox-cle). |
-| 2026-05-25 | pwher (with Claude Opus 4.7) | **Business layer added.** New entity types `business-positioning` / `business-pricing` / `business-marketing` / `business-model` filed under `specs/business/{positioning,pricing,marketing,model}/`. IDs `HS-BIZ-POS-* / HS-BIZ-PRI-* / HS-BIZ-MKT-* / HS-BIZ-MOD-*`. Browsed in the console on a dedicated **Business** surface that mirrors Memory's category-rail layout. `positioning-2nd-brain-harness-for-specs` migrated from `memory/decisions/` (`type: memory-decision`) to `business/positioning/` (`type: business-positioning`); basename unchanged so wikilinks resolve. |
-| 2026-05-29 | pwher (with Claude Opus 4.8 [1m]) | **`milestone` entity type formalized.** Added folder `specs/milestones/`, Entity-types-table row, ID format `HS-MIL-<suffix>` (4+ uppercase; legacy 4-char mnemonics like `HS-RM22` valid), filename pattern `HS-MIL-<suffix>-<slug>.md`, and a full `#### milestone` schema subsection (`epics`, `target_date`, status enum, explicit "no scalar priority"). Disambiguated the legacy `kind: milestone` task discriminator from the new `type: milestone` entity; added the `milestone:` parent pointer to the `#### epic` schema; registered the new fields under Reserved frontmatter keys. Describes the 33 `HS-MIL-*` files already on disk (seed HS-RM22-IART-MIL-console-ia-restructure). Ratified by introduction lineage HS-VK7C-MILE-EPIC-milestone-entity-type-and-surfacing → HS-OFR5-M2J3-EPIC-introduce-milestones-as-highest-entity (in lieu of a standalone ADR); canonical hierarchy in [[spec-hierarchy]]. Per HS-9AUC-HRMZ-TASK-define-milestone-entity-type-in-entity-m. |
-| 2026-05-26 | pwher (with Claude Opus 4.7) | **`review` entity type formalized.** Added folder `specs/reviews/`, ID format `HS-REV-<suffix>` (suffix matches parent task/epic id 1:1), filename pattern `HS-REV-<suffix>-<slug>.md`, and full `#### review` schema subsection documenting the four required body sections (Acceptance verification / Reviewer notes / Memory candidates / Decision). Documents what CLAUDE.md §Session Completion + ~100 existing review files already implement; provides the authoritative L2 schema for console, indexer, MCP, and future CLI consumers. Per T1 of HS-3K55-0033-EPIC-review-sibling-testing-workflow (grounded against HS-19F9-TEST-MIL-api-testing-dual-path + HS-UKD6-CLR4-RES-close-out-review-screen-jtbd-architecture). |
-| 2026-05-29 | pwher (with Claude Opus 4.7 [1m]) | **Provenance edges formalized (capture → research → milestone).** Added new §Provenance edges section between §Dependencies and §Evidence linking with the cross-type cardinality table (Capture→Research M:N, Research→Milestone M:1 strict, Research→Epic spawned 1:N, Research→Epic augmented M:N). New frontmatter fields: `research.enhances` (M:1 required on closed), `research.sources_captures` (M:N), `research.spawned_epics` (1:N), `research.enhances_epics` (M:N rare), `research.split_into` / `research.split_from` (split-flow audit); `milestone.informed_by` (reverse of enhances); `capture.informs_research` (M:N, distinct from binary `promoted_to`); optional `epic.derived_from` (reverse of spawned_epics). Reserved-keys list updated. Per HS-HQRM-YJX6-TASK-research-enhances-exactly-one-milestone-validator-and-bidirectional-linkage of HS-OFR5-M2J3-EPIC-introduce-milestones-as-highest-entity. |
-| 2026-05-31 | pwher (with claude opus 4.7) | **`pillar` entity type added** (folder `specs/pillars/`, ID format `HS-PILR-<slug>` for canonical or `HS-PILR-<suffix>-<slug>` for customer-scoped, filename matches ID, `status: perpetual` non-terminal). New required fields on every epic: `pillar:` (single primary) and optional `secondary_pillars:` array. Type ratified by introduction lineage HS-EBIL-0011-EPIC-goal-hierarchy-l2-strategic-pillars-l3 following the milestone precedent (no standalone ADR for the entity itself); privacy-boundary for the Pillar Library learning loop is adr-0016-pillar-library-privacy-boundary. **`architecture-pillars.md` renamed to `architecture-foundations.md`** (ID `HS-L2-PILLARS` → `HS-L2-FOUNDATIONS`) to disambiguate from the new entity; 172 wikilinks updated in a single bulk pass. Three "pillar" usages now coexist: the `type: pillar` entity, the unrelated "Pillars 0–5" section names in HS-DOC-architecture-foundations, and the renamed "FIVE COMPONENTS" section in HS-OR8V-0010-EPIC-north-star-vision-first-class-entity (previously "FIVE PILLARS"). L3 Themes (per-epic teleological anchor) retired in the same resolution — collapsed into perpetual Pillars. See HS-AWDI-PILR-RES-pm-perpetual-container-terminology §"Resolution against existing HS-J6K8" for the full rationale. |
-| 2026-06-03 | claude opus 4.7 [1m] · session `local` (with pwher) | **`canonical:` universal field added; two `superseded` enum values deprecated.** Per evergreen-doc-architecture-srp-and-seo-pillars + canonicalization-arbiter-is-link-graph-not-policy + closed-trackable-specs-are-historical-record-not-living-docs: `canonical: true \| false` is now a universal frontmatter field on every spec type (pillars, L1/L2/L3 docs, HS-DOC-*, ADRs, protocols, memory specs, epics, tasks, milestones, reviews). `true` (or absent) = current/authoritative; `false` = historical record. Trigger event for the flip: plan-side specs at the in_review → closed transition (per [[session-close-protocol]] step 4); evergreen docs at supersession (per supersession-protocol). `status: parked` / `status: deferred` keeps `canonical: true`. **Two enum values deprecated forward-only** per superseded-enum-values-deprecated-use-canonical-false-and-superseded-by: `status: superseded` removed from the ADR-status enum; `superseded` removed from the close_reason enum. Both were redundant with `canonical: false` + `superseded_by:`. Forward-only retirement — existing 11 specs (8 ADRs + 3 plan-side) keep their legacy values as historical record per immutability. New writes use `canonical: false` + `superseded_by:` instead. Added the `canonical:` field to the ADR and task schemas; expanded the `superseded_by:` description to clarify it's the pointer (vs. `canonical:` which is the state). |
-| 2026-06-03 | claude opus 4.7 [1m] · session `local` (with pwher) | **`## Lifecycle classes` section added; `research` schema de-coupled from `status: closed`.** New top-level section between §Entity types and §Identity, IDs, and filenames classifying all 24 types into four lifecycle classes — **Evergreen** (`l1`/`l2`/`l3`/`adr`/`pillar`/`protocol`/`memory-*`/`research`/`business-*`), **Trackable plan-side** (`task`/`epic`/`milestone`/`review`/`branch-brief`/`planning-flow`), **Single-shot ingest** (`capture`/`draft`/`daily`), **Per-instance** (`roadmap`). Closes the discoverability gap that produced the research-is-evergreen incident: a reader asking *"can I flip this file's status to `in_review`?"* now has one canonical place to look. Cross-references research-is-evergreen, closed-trackable-specs-are-historical-record-not-living-docs, canonicalization-arbiter-is-link-graph-not-policy, [[session-close-protocol]]. **Research schema (`#### research`) amended**: the `enhances:` field gate changed from "REQUIRED on `status: closed`" to "REQUIRED when set" — bidirectional consistency is enforced whenever the field is present, independent of status. Added a one-line note above the schema declaring research evergreen with a pointer to research-is-evergreen. The matching validator update in `scripts/validate-vault-ids.mjs` is on the deferred list — schema-vs-validator drift is acknowledged in the schema comment until that catches up. |
-| 2026-06-13 | claude opus 4.8 [1m] · session `local` (with pwher) | **`diagnose` entity type added** (folder `specs/diagnoses/`, ID `HS-DIAG-<suffix>`, filename `HS-DIAG-<suffix>-<slug>.md`). A user-reported bug fix as first-class executable work — standalone by default (exempt from the epic→milestone parent rule), optional `parent:` (epic or milestone), required `severity:` (error/warning/info) that maps onto the scheduler's existing priority signals, optional `blocks:` gating edges. Surfaces on the Resolution surface as a derived `kind: "bug"` row that links back to the diagnose. Added entity-types-table row, ID-format row, filename row, `#### diagnose` schema subsection, and Trackable-plan-side lifecycle classification. Ratified by introduction lineage HS-OXBS-BFIX-MIL-bug-fix-diagnose-lane (milestone-precedent, no standalone ADR). Wiring: `vault.ts` (TYPE_TO_FOLDER + KIND_LINKAGE + body skeleton + generateId), `vault-id.ts`, `vault-rules.mjs` (KIND_RULES/KIND_ORDER), `validator.ts`, `validate-vault-ids.mjs`. Per HS-AO2F-1KZK-RES-bug-fix-resolution-task-entity-model-and. |
-| 2026-06-23 | Cursor · session `local` | **Delegation handoff envelope + task split lineage.** Task frontmatter: `split_of`, `split_index`, `handoff_id` (option B from HS-DTL1-CX5K-CAP-task-split-handoff-when-context-runs-low). Handoff envelope SSOT is body (`## Handoff envelope` + fenced yaml) per `schemas/handoff-envelope.schema.json`; validated by `handoff-envelope.mjs` + `validate-vault-ids.mjs`. Engine rules in `vault-rules.mjs` (`TASK_SPLIT_*`). Per HS-PD6K-NCH5-TASK-handoff-envelope-schema-and-split-child / HS-HXE2-YQ5A-EPIC-delegation-defer-work-from-one-agent-to. |
-| 2026-06-23 | Cursor · session `local` | **`owned_paths` / `affects_paths` for parallel-agent stomp-detection.** New `#### agent` schema subsection documents `owned_paths:` (machine-checkable file globs on agent identities). Task schema adds optional `affects_paths:` (advisory module hints on trackable specs). Entity-types table + reserved-keys list updated. Per HS-ZMAQ-M15C-TASK-declare-owned-path-globs-on-agent-identi / HS-8PNX-Q1KC-EPIC-lanes-and-stomp-detection-for-parallel-a. |
-| 2026-07-05 | Claude Sonnet 5 [1m] · session `local` (with pwher) | **`research.produces_diagnose` → `diagnose.derived_from` edge added (research → diagnose intake).** Bugs found during a research investigation now route into the Resolution lane without new diagnose machinery: `research.produces_diagnose:` (optional, list of wikilinks to `HS-DIAG-*`, mirrors `spawned_epics`) reverse-linked by `diagnose.derived_from:` (optional, single wikilink, mirrors `epic.derived_from`). Written by the new `heyspex_promote_research_to_diagnose` tool (`vendor/heyspex-mcp/promote-research-to-diagnose.mjs`), the research-side sibling of `heyspex_promote_capture_to_diagnose`. Also documented `diagnose.promoted_from:` (existing capture-side back-reference, previously undocumented in this schema subsection). Provenance cardinality table + reserved-keys list updated; validated by the `type: research` block of `schemas/heyspex-frontmatter.schema.json`. Per HS-W5VP-MSHY-TASK-research-diagnose-link-send-bugs-to-the of HS-0FTO-MSHY-EPIC-research-to-diagnose-link-send-bugs-foun. |
-| 2026-07-05 | Claude Sonnet 5 [1m] · session `local` (with pwher) | **`code-audit` findings-table format + closure gate.** New `##### Code-audit findings table` subsection under `#### research` documents the required 4-column body table (`Finding \| Severity \| Action (diagnose\|task\|reference) \| Exit (open\|closed)`) and its three defined exits: bug→diagnose (reuses `heyspex_promote_research_to_diagnose`/`research.produces_diagnose`, no new tooling), cleanup→task (new `task.discovered_from:` reverse pointer to the source research doc), non-actionable→reference (the row itself is the exit). Enriched the existing `task.discovered_from:` doc comment to name this use. Added `discovered_from` to the `type: task` block of `schemas/heyspex-frontmatter.schema.json` (previously documented in entity-model.md only, unenforced). Validator rules in `vault-rules.mjs`: `CODE_AUDIT_FINDINGS_MALFORMED` (no/malformed table) and `CODE_AUDIT_FINDINGS_OPEN_ON_CLOSE` (the closure gate — a `closed`/`review_pending` code-audit doc with any `Exit: open` row) — both warn during a new `CODE_AUDIT_GRACE_END` (2026-08-15, mirrors `RESEARCH_TYPE_GRACE_END`) so pre-existing docs like `HS-ZHAB-RES-doc-authoring-contract-audit-required-st` (no `research_type:` set, predates this format) aren't hard-failed, then error. Per HS-7D0I-WL88-TASK-code-audit-research-type-with-a-defined of HS-BI9D-WL88-EPIC-code-audit-research-type-with-a-defined. |
-| 2026-08-14 | Claude Code (Fable 5) · session `5785e74c` (with pwher) | **Iteration lineage — third relation tier added.** New §Iteration lineage section (between §Provenance edges and §Evidence linking): `iterates_on:` (list of wikilinks, newer-doc-only, one-edit-on-source like amends; computed reverse map `iteratedBy`) expresses "re-attempts an outcome the target shipped but did not fully deliver" — the case supersession (would falsify round 1) and amends (nothing is contradicted) both misdescribe. `outcome:` (`met` \| `partially-met` \| `not-met`) + `outcome_note:` — reviewer-set at close on trackable docs, never inferred, closed-doc-only (not echoed onto round 2). Required `## Related / lineage` resolved-wikilink table on promoted docs with role vocabulary. Invariants: both docs stay `canonical: true`, round 1 keeps `status: closed`, round 2 takes its own family key. Dependencies table gained the Iterates-on row; Reviewer-close bullet gained the outcome write. Field-name + echo decisions resolved at breakdown (flagged for owner Walk). Per HS-VGQV-T9T6-TASK-entity-model-iterates-on-relation-tier of HS-O97P-T9T6-EPIC-iteration-loop-lineage-relation-tier, from HS-3TZX-T9T6-RES-iteration-loop-lineage-and-capture Part A. |
+---
+id: HS-L2-ENTITY
+name: HeySpex Entity Model
+type: l2
+status: draft
+priority: 0
+owner: TODO — your name/handle
+created: 2026-05-14
+updated: 2026-05-18
+tags: "[foundation, l2, entity-model, schema]"
+---
+
+
+
+
+
+
+# HeySpex Entity Model
+
+> [!important] Constitutional dependency
+> Every constraint in this document derives from a numbered principle in heyspex-north-star. If a future change to this document contradicts the L1 spec, the change is wrong. When the L1 changes, this document updates downstream.
+
+This L2 spec defines the shape of every artifact that lives in a HeySpex vault: the entity types, their frontmatter schemas, their on-disk layout, the dependency relations between them, and the wikilink resolution rules. It is the contract that the console, the CLI (`hs`), and any AI agent must satisfy when reading or writing the vault.
+
+## Vocabulary
+
+- **Vault.** A folder of plain-text files under git. The on-disk layout is canonical. A single Builder owns one or more vaults; this document specifies the structure of one vault.
+- **Spec.** A single markdown file in the vault. Every spec has YAML frontmatter and a markdown body. The frontmatter declares the spec's type and identity.
+- **Entity type.** The value of the `type:` field in frontmatter. Determines which folder the spec lives in, which other fields are required, and how the spec is rendered in the console.
+- **Hierarchy level.** L1 / L2 / L3. Vision → architecture → use-case. A different axis from entity type. Some entity types are level-tagged (`type: l1`, `type: l2`, `type: l3`); most are not.
+- **Wikilink.** A reference of the form `[[link-target]]`, resolved by filename match across the vault.
+- **Memory (conceptual layer).** Durable project knowledge surfaced together in the console: `memory-lesson`, `memory-decision`, `memory-reference`, `memory-ux-principle`, `memory-ui-pattern`, and `protocol`. Protocols are filed under `specs/protocols/` on disk but are a **subsection of Memory** in navigation and in `hs prime` — not a peer of Memory beside Epics/Tasks. See memory-protocols-subsection-of-memory. Work to *create* or change a protocol remains `type: epic` / `task`.
+
+## Vault root layout
+
+```
+specs/
+├── heyspex-north-star.md          # the L1; one file
+├── entity-model.md                # this document; L2
+├── architecture-foundations.md    # L2 sibling (renamed 2026-05-31 from architecture-pillars.md to disambiguate from the `type: pillar` entity)
+├── principles.md                  # L2 (expansion of L1's principle list)
+├── glossary.md                    # L2 (authoritative term dictionary) — North Star tier
+├── adr/                           # one ADR per file
+│   ├── adr-0001-vault-format.md
+│   ├── adr-0002-derived-index.md
+│   └── ...
+├── use-cases/                     # one L3 use-case spec per file
+│   ├── uc-capture-intent.md
+│   ├── uc-decompose-intent.md
+│   └── ...
+├── tasks/                         # task / feature / bug specs
+│   ├── HS-ZF0T-TASK-<slug>.md          # legacy sequential, or HS-K7M2-<slug>.md (random)
+│   └── ...
+├── milestones/                    # milestone specs (the grouping above epic)
+│   └── HS-MIL-<suffix>-<slug>.md  # e.g. HS-IART-MIL-console-ia-restructure.md
+├── pillars/                       # type: pillar — perpetual categorical containers (Scaling, Reliability, DX, etc.)
+│   └── HS-PILR-<slug>.md          # canonical Pillars; customers may also create HS-PILR-<suffix>-<slug>.md
+├── epics/                         # epic specs
+│   └── HS-0001-EPIC-<slug>.md     # legacy, or HS-EPIC-X9P4-<slug>.md (random)
+├── branches/                      # branch-brief specs (one per git branch)
+│   └── <branch-slug>.md
+├── memory/
+│   ├── lessons/                   # memory-lesson specs
+│   │   └── <slug>.md
+│   ├── decisions/                 # memory-decision specs
+│   │   └── <slug>.md
+│   ├── references/                # memory-reference specs
+│   │   └── <slug>.md
+│   ├── ux-principles/             # memory-ux-principle specs (cross-brand interaction rules)
+│   │   └── <slug>.md
+│   └── ui-patterns/               # memory-ui-pattern specs (reusable interaction/visual rules)
+│       └── <slug>.md
+├── protocols/                     # type: protocol — Memory subsection on disk (how-we-work rules)
+│   └── <slug>.md                  # (not epic/task work; those stay in epics/ and tasks/)
+├── reviews/                       # type: review — HS-REV-<suffix>-<slug>.md companions for in_review parent specs
+│   └── HS-REV-<suffix>-<slug>.md
+├── business/                      # business model / marketing / positioning / pricing
+│   ├── positioning/               # business-positioning specs
+│   │   └── <slug>.md
+│   ├── pricing/                   # business-pricing specs
+│   │   └── <slug>.md
+│   ├── marketing/                 # business-marketing specs
+│   │   └── <slug>.md
+│   └── model/                     # business-model specs
+│       └── <slug>.md
+├── canvases/                      # JSON Canvas design files + .heyspex.yaml sidecars ([[adr-0013-canvas-vault-format-and-obsidian-interop]])
+│   ├── system-design.canvas
+│   ├── system-design.heyspex.yaml
+│   ├── diagrams/                  # per-spec editable design diagrams ([[spec-diagram-design-vs-as-built-canvas]])
+│   │   └── <spec-basename>-design.canvas
+│   ├── as-built/                  # sealed shipped spec diagrams (read-only in HeySpex)
+│   │   └── <spec-basename>.canvas
+│   └── ...
+├── roadmaps/                      # phased roadmap specs (orchestration over tasks/epics)
+│   └── HS-ROADMAP-<slug>.md
+├── roadmap-design-v2/               # Console Roadmap surface v2 design pack (protocol docs; not manifest entities)
+│   ├── roadmap-design-v2-index.md   # hub
+│   ├── roadmap-v2-implementation-checklist.md  # printable when coding
+│   ├── roadmap-v2-implementation-handoff.md  # read order + context
+│   ├── roadmap-v2-tabextend-reference.md
+│   ├── roadmap-v2-narrative-board-ux.md
+│   ├── roadmap-v2-display-titles-and-summaries.md
+│   └── roadmap-v2-*.md              # see index for full map
+├── companion-research-board/        # Chrome + Companion mirrored research board (protocol docs)
+│   ├── companion-research-board-index.md
+│   ├── companion-research-board-dual-surface-mirror.md
+│   ├── companion-research-board-implementation-checklist.md
+│   └── companion-research-board-*.md
+├── future-considerations/         # pre-task research (promote to tasks when scheduled)
+│   └── <slug>.md
+├── research/                      # audit/research/draft notes
+│   ├── HS-XBPJ-RES-bd-feature-inventory.md
+│   └── ...
+├── captures/                      # concise core capture entries — kind: idea | bug-fix | clip | reference | question | spec-import ([[capture-guardrails]])
+│   └── HS-CAP-<suffix>-<slug>.md
+├── flows/                         # planning-flow lifecycle diagrams ([[planning-flow-research-epic-lifecycle]])
+│   └── HS-FLOW-<NNN>-<slug>.md
+├── drafts/                        # ingested-but-untriaged
+│   └── <slug>.md
+├── events/                        # audit-export JSONL — one file per UTC month ([[HS-FD93-AEHR-EPIC-audit-export-heyspex-yaml-and-heyspex-retirement]])
+│   └── YYYY-MM.jsonl              #   committed snapshot of claim/focus/spec events (git-clone-is-backup)
+└── daily/                         # optional daily notes
+    └── 2026-05-14.md
+```
+
+Two committed siblings live **outside** `specs/` at the repo root, written/owned by the control plane:
+
+- **`heyspex.yaml`** — the top-level vault marker (`schema_version`, `console_url`, `vault_root`) written by `hs init` (HS-FD93-AEHR-EPIC-audit-export-heyspex-yaml-and-heyspex-retirement §2). `schema_version: 2` = the post-SCAH Neon-control-plane layout; `1` was the implicit pre-SCAH `.heyspex/`-files layout. The web companion reads it to bootstrap a vault.
+- **`.heyspex/`** — per-vault config home (adr-0009-heyspex-directory-contract): tracked `config.yaml`, `.gitignore`, `*.example` scaffolding templates, and `focus.yaml` (cross-machine pin SSOT, focus-yaml-is-tracked-pin-ssot). On the **free tier** (no Neon) this directory ALSO holds the live runtime state (`active-claims.json`, `claim-history.jsonl`, `focus-history.jsonl`); on the **paid tier** that state lives in Neon and these files are the export's free-tier source only (HS-7FA9-FREE-EPIC-zero-neon-local-only-tier). The audit export (`specs/events/`) reads whichever store is live for the tier.
+
+The L1 lives at the vault root as `heyspex-north-star.md`. The other L2 specs (`entity-model.md`, `architecture-foundations.md`, `principles.md`, `glossary.md`) also live at the root because they are foundational — in the console they surface under the **North Star** rail group, not Business (which is scoped to `business-*` types) or Memory (scoped to `memory-*` types). The glossary carries a `marketing` *tag* because marketing copy consumes its definitions, but its `type: l2` keeps it in the foundational tier. Everything else is filed under a folder matching its entity type.
+
+> [!note] Why folders, not flat?
+> Obsidian works with either, and HeySpex's link resolution treats folders as opaque (see [Wikilink resolution rules](#wikilink-resolution-rules)). Folders exist purely for human navigation and for the indexer's "list all <type>" view. Files can be moved between folders without breaking links.
+
+## Entity types
+
+The table below names every entity type in v1 and points at the frontmatter contract. Each type has its own subsection below with the full schema.
+
+| `type:` value | Folder | Hierarchy level | One-line description |
+| --- | --- | --- | --- |
+| `l1` | root | L1 | The North Star vision; one per vault. |
+| `l2` | root | L2 | Foundational architecture or model documents. |
+| `l3` | `use-cases/` | L3 | Use-case specs that elaborate L1 system use cases. |
+| `adr` | `adr/` | — | Architectural Decision Record. |
+| `task` | `tasks/` | — | The atomic unit of work. Subsumes bd's `task`, `feature`, and `bug` types. |
+| `epic` | `epics/` | — | A grouping of related tasks under a common goal. |
+| `milestone` | `milestones/` | — | The grouping **above** epic: a coherent multi-epic ship that closes when every child epic closes and the milestone's own acceptance gate is met. Distinct from the legacy `kind: milestone` task discriminator (see [`#### task`](#task)). |
+| `diagnose` | `diagnoses/` | — | A user-reported **bug fix** as first-class executable work (claimable, decomposable). Standalone by default — no epic/milestone parent required — with an optional `parent:` (epic or milestone) for organization. Carries `severity:`; surfaces on the Resolution surface as a derived `kind: "bug"` row that links back to the diagnose. Elevates the bug concept that `task` historically subsumed (see [`#### task`](#task)) into its own lane. Ratified by introduction lineage HS-OXBS-BFIX-MIL-bug-fix-diagnose-lane (milestone-precedent, like `milestone`/`pillar`). See HS-AO2F-1KZK-RES-bug-fix-resolution-task-entity-model-and. Proposed (not-yet-ratified) field extensions — a `problem_layer: symptom \| core \| unknown` classifier and an optional bidirectional `caused_by`/`symptoms` link pair — are designed in HS-4QOK-UBJM-RES-diagnose-problem-layer-classification-sy. End-to-end workflow procedure: resolution-diagnose-workflow. |
+| `pillar` | `pillars/` | — | Perpetual categorical container that never closes; cross-cutting axis for epics. Every epic carries `pillar:` (required, single primary) + optional `secondary_pillars:`. Canonical Pillars ship pre-loaded with HeySpex; customers may add scoped Pillars. Orthogonal to `milestone` (a milestone is a shippable increment; a Pillar is a perpetual concern). See HS-PILR-pillars (meta-Pillar) and HS-AWDI-PILR-RES-pm-perpetual-container-terminology (research + 2026-05-31 resolution). |
+| `agent` | `agents/` | — | A durable, user-authored **agent identity** (the "home where agents live"): name, role, preferred tools, model tier, procedures, and persona body. Compiles to the host-native agent formats (`.claude/agents/*.md`, `.cursor/agents/*.md`) — the vault spec is the SSOT, the generated files are derived. Carries HeySpex-only extras (`lane`, `color`, `owned_paths`, `golden_cases`, and `source_attribution` when imported) stripped on compile. `owned_paths` is the machine-checkable file-ownership set for parallel-agent stomp-detection; `lane` remains a human label. An **imported** agent (community-collection per HS-SURM-TMXZ-EPIC-default-agent-roster-and-import-path AC#2, or own-agent per HS-11ME-1NL4-EPIC-import-and-adopt-your-own-existing-agent) records its provenance in `source_attribution` (collection, url, path, commit, license, imported_at); authored agents omit it. Evergreen (does not close). See HS-XNX5-UQHA-MIL-agent-home. |
+| `golden-case` | `agents/golden-cases/` | — | A saved **eval fixture** for one agent identity: the prompt (and optional setup + deterministic graders) the test-before-publish harness runs against a draft agent (HS-R1JM-OAG3-EPIC-agent-testing-harness-try-a-draft-agent). Stored under the `agents/` tree so fixtures version beside the identities they exercise in the same git history. Evergreen (updated in place). Introduced by HS-8AQT-J6FU-TASK-golden-case-vault-artifact-format-and-st. |
+| `branch-brief` | `branches/` | — | "What this git branch is trying to do, and how it actually went." Plan-vs-actual + evidence for one branch. |
+| `memory-lesson` | `memory/lessons/` | — | "Here's what went wrong and how to avoid it." |
+| `memory-decision` | `memory/decisions/` | — | "Here's what we chose and why." |
+| `memory-reference` | `memory/references/` | — | "Here's where to look for X." |
+| `memory-ui-pattern` | `memory/ui-patterns/` | — | "Here's a reusable console interaction/visual pattern to copy." |
+| `memory-ux-principle` | `memory/ux-principles/` | — | "Here's a cross-brand UX rule (what/why) before implementation." |
+| `protocol` | `protocols/` | Memory subsection | Repeatable how-we-work rules for agents/humans (session-close, memory capture, MCP usage). Browsed under Memory → Protocols in console; not a peer nav item beside Memory. |
+| `review` | `reviews/` | — | Companion fill-in workspace for an `in_review` parent spec — acceptance verification, reviewer notes, memory candidates, decision. One per parent, suffix-matched 1:1. |
+| `business-positioning` | `business/positioning/` | — | Brand H1, taglines, audience qualifier, message hierarchy. |
+| `business-pricing` | `business/pricing/` | — | Tier tables, AI add-on terms, discount/refund policy. |
+| `business-marketing` | `business/marketing/` | — | Channels, launches, campaigns, copy decks. |
+| `business-model` | `business/model/` | — | Unit economics, cost structure, monetization decisions. |
+| `roadmap` | `roadmaps/` | — | Phased plan orchestrating tasks/epics; compact `roadmap_manifest` for indexer/CLI (adr-0012-roadmap-storage). |
+| `capture` | `captures/` | — | Concise capture entry; `kind:` field discriminates idea / bug-fix / clip / reference / question / spec-import. Replaces the legacy `type: idea` entity (renamed 2026-05-22 per HS-B2B8-DLQI-EPIC-capture-rename-migration-idea-to-capture). `spec-import` is the **import-origin** kind — one capture per imported foreign doc, created by the bulk spec-import feature (HS-8V8T-8SBG-EPIC-first-connect-rough-import / HS-ROIU-9P4B-EPIC-import-preview-and-confirm); grounding HS-J7T5-VEW8-RES-import-specs-one-click-feature-pipeline. |
+| `research` | `research/` | — | Audit reports, feature inventories, exploratory notes. |
+| `planning-flow` | `flows/` | — | Epic lifecycle orchestration diagram (mermaid source + canvas projection). |
+| `draft` | `drafts/` | — | Ingested content awaiting triage. |
+| `daily` | `daily/` | — | Optional daily-note scratchpad. |
+| `run-retrospective` | `dev-factory/reports/retrospectives/` (outside `specs/`, sibling to `heyspex.yaml`/`.heyspex/`) | — | A **generated** run-close record — never hand-authored, not scheduled/claimable, not a wikilink-addressable spec. One file per COO-dispatcher run, `<runId>.md` (`runId` = the run's milestone id), produced deterministically by `dev-factory/lib/retrospective.mjs` from `run-events.jsonl` + the gate ledger + `coo-dispatcher-state.json`. Frontmatter: `runId`, `generatedAt`, `shippedUnits[]` (gate-verified units), `autoAppliedDecisions[]` (dispatcher auto-applies), `stoppedReason`, `restartCondition`, `ownerGates[]` (pending owner-only gates). Body: the three Retrospective sections (what went well / what could be improved / actionable next steps). Read by What's Next's Retrospective hero (Assisted/Autonomous fronts) — see HS-4HI5-JEPA-EPIC-what-s-next-multi-run-mode-run-dashboard and the-retrospective-is-a-generated-run-rec.
+
+Adding a new entity type requires an ADR. `branch-brief` was added by adr-0008-branch-brief-and-evidence-schema; `roadmap` by adr-0012-roadmap-storage; all other core types ratified at adr-0001-vault-format. `milestone` is the exception that proves the rule: the type was used informally first — 33 `HS-MIL-*` files (e.g. HS-RM22-IART-MIL-console-ia-restructure) were hand-authored before formalization — so rather than a standalone ADR, the convention is ratified by its introduction lineage, HS-VK7C-MILE-EPIC-milestone-entity-type-and-surfacing (this schema row, the validator, MCP support) followed by HS-OFR5-M2J3-EPIC-introduce-milestones-as-highest-entity (required-parent-on-epics + the roadmap drilldown). The canonical hierarchy these two epics serve is documented in [[spec-hierarchy]].
+
+`pillar` follows the same milestone-precedent (no standalone "introduce the entity type" ADR): ratified by its introduction lineage HS-EBIL-0011-EPIC-goal-hierarchy-l2-strategic-pillars-l3 (the L2 perpetual-Pillars epic, sibling of HS-OR8V-0010-EPIC-north-star-vision-first-class-entity in HS-J6K8-NSPL-MIL-north-star-and-strategic-pillars-hierarchy) plus the design captured in HS-AWDI-PILR-RES-pm-perpetual-container-terminology; the privacy-boundary side of the work (aggregate-learning telemetry on the Pillar Library) is in adr-0016-pillar-library-privacy-boundary. The 2026-05-31 resolution that produced the Pillar tier also retired the previously planned L3 Themes tier (per-epic teleological anchoring collapsed into perpetual Pillars). First canonical Pillar filed: HS-PILR-pillars (the meta-Pillar; dogfooding instance).
+
+`agent` follows the same milestone/pillar-precedent (no standalone "introduce the entity type" ADR): ratified by its introduction lineage HS-XNX5-UQHA-MIL-agent-home (this schema row, the frontmatter-schema branch, the `KIND_RULES`/`TYPE_TO_FOLDER` registration, and the compiler that exports identities to host-native `.claude/agents`/`.cursor/agents` formats). The agent identity is the durable, user-authored counterpart to the ephemeral control-plane presence (`active_claims`) — the vault holds *who an agent is*, the control plane holds *what it is doing now*. Positioning context: HS-O46R-R30X-RES-agent-layer-as-the-demand-side-twin-of-t.
+
+`golden-case` follows the same introduction-lineage precedent under HS-R1JM-OAG3-EPIC-agent-testing-harness-try-a-draft-agent / HS-8AQT-J6FU-TASK-golden-case-vault-artifact-format-and-st: a first-class vault artifact for agent eval fixtures (not JSON sidecars or console-only blobs). Bodies follow a fixed section contract; optional deterministic graders validate against `specs/schemas/golden-case-body.schema.json`.
+
+## Lifecycle classes
+
+Entity types fall into four lifecycle classes. The class determines which subset of the [universal status enum](#frontmatter-schemas) a type uses, when its `canonical:` flag flips, and what the close-out ritual is. **A reader asking *"can I flip this file's status to `in_review`?"* should consult this section first — the answer depends entirely on which class the file's type belongs to.**
+
+### Evergreen (living reference substrate)
+
+`l1` · `l2` · `l3` · `adr` · `pillar` · `agent` · `golden-case` · `protocol` · `memory-lesson` · `memory-decision` · `memory-reference` · `memory-ui-pattern` · `memory-ux-principle` · `research` · `business-positioning` · `business-pricing` · `business-marketing` · `business-model`
+
+These are **standalone reference artifacts**. `status: open` is the resting state and stays the resting state for the doc's entire life. There are no `in_review` or `closed` transitions — the close-as-historical-record ritual does not apply.
+
+- **Updates** happen in-place: amend the body, bump `updated:`, append a change-log row.
+- **Supersession** is the only "lifecycle event" — record it via relational fields (`supersedes:` / `superseded_by:` on ADRs, `superseded_by:` on memories and research, `canonical: false` as the universal drift tombstone per canonicalization-arbiter-is-link-graph-not-policy). The original stays as the historical record at `status: open`.
+- **Research lineage** to downstream artifacts is recorded via `enhances:`, `spawned_epics:`, `bound_epic:`, `incorporated_into:` — these are relational edges, **not** status transitions. See research-is-evergreen for the full rule and the deferred MCP-tool / UI-epic / validator surfaces still being remediated.
+
+Session-close protocol carve-out: an agent who touched an evergreen doc this session **must not** flip its status. See [[session-close-protocol]] step 1.
+
+### Trackable plan-side (open → in_progress → in_review → closed)
+
+`task` · `epic` · `milestone` · `diagnose` · `review` · `branch-brief` · `planning-flow`
+
+These are **work containers** with a definite scope and a moment at which they're done. They follow the full status flow and are **frozen at close** per closed-trackable-specs-are-historical-record-not-living-docs — the body becomes historical record of the plan as it was at the moment of close.
+
+- **Session close** flips completed-this-session specs to `status: in_review` and creates an `HS-REV-<suffix>` companion ([[session-close-protocol]]).
+- **Reviewer close** flips `in_review → closed`, flips `canonical: true → false`, optionally sets the `outcome:`/`outcome_note:` verdict (`met` | `partially-met` | `not-met` — reviewer judgment, never inferred; see §Iteration lineage), and freezes the frontmatter forever after.
+- **`branch-brief`** closes when the branch ships; **`planning-flow`** closes with its bound epic.
+
+### Single-shot ingest (triage-driven; promotion replaces closure)
+
+`capture` · `draft` · `daily`
+
+These are **inbound surfaces** scoped to one input session. They don't close in the lifecycle sense — they get **promoted** (capture → research / task / epic; draft → some other type) or remain as a dated scratchpad (daily).
+
+- **`capture`** carries `promoted_to:` as a binary pointer to the first downstream artifact and `informs_research:` as the M:N lineage list (see the `capture` schema below).
+- **`draft`** is triaged by editing the `type:` field in place and moving the file to the destination folder.
+- **`daily`** is a single-date scratchpad — no status semantics; the date IS the lifecycle.
+
+### Per-instance (class declared at filing time)
+
+`roadmap`
+
+`roadmap` is the one type whose lifecycle class depends on the specific roadmap. A perpetual product roadmap is evergreen; a per-quarter ship plan is trackable. Each `HS-ROADMAP-*` declares its class via its own `status:` value at filing: roadmaps that never close stay `open`; roadmaps with a defined ship horizon use the trackable flow. See adr-0012-roadmap-storage for the compact-manifest design that supports both shapes.
+
+### Cross-reference summary
+
+| Class | Status values used | Close-as-historical-record? | `canonical: false` trigger |
+|---|---|---|---|
+| Evergreen | `open` (resting state) | No | Supersession (relational edge) |
+| Trackable plan-side | `open` → `in_progress` → `in_review` → `closed` (plus `deferred`) | Yes — frozen at close | Close-out write |
+| Single-shot ingest | `open` (capture/draft pre-promotion) / N/A (daily) | No — promoted or archived by date | Not used |
+| Per-instance | Declared at filing | Per-instance | Per-instance |
+
+## Identity, IDs, and filenames
+
+> [!important] Identifier format migration in progress (updated 2026-08-11)
+> The vault is migrating to **file-key-first** (era 3) ordering: `HS-<file key>-<family key>-<type label>-<title slug>` — the leading token after `HS-` is the **unique per-file ID**, not the family (HS-6B0S-Q9YG-RES-naming-system-v3-file-key-first, rulings naming-v3-7-rulings-hs-namespace-kept; owner re-confirmed the token order 2026-08-11). On disk today most files are still **family-first** (era 2, `HS-<family key>-<type label>-…`) or legacy type-first (era 1); the vault-wide rename is built and **pending owner review/execution** (HS-L6Y4-01D7-EPIC-deterministic-rename-with-link-rewrite). The type label's position (1st/2nd/3rd token) tells you a filename's era — never guess which token is the file ID by position alone; read frontmatter `file_id:`/`id:`. The ID-format and filename tables below still show older orderings pending the flip; the token **names** are canonical in every era. Plain-language explainer: how-spec-ids-and-naming-work.
+
+### Identifier tokens (file key · family key · type label · title slug)
+
+A managed spec's basename decomposes into named tokens. Canonical names per glossary §Identifier anatomy and HS-37O7-T9KP-RES-identifier-token-terminology-family-key (external-validated; supersedes the "pipeline ID / type token / file ID" names in HS-MF8M-CCVE-RES-family-first-spec-identifier-format-hs-i).
+
+| Token | Example | Role |
+| --- | --- | --- |
+| **File key** | `L6Y4` | The per-file 4+ char uppercase-alphanumeric key (at least one letter), **unique vault-wide** — the identity and one-token citation handle for exactly one file. Recorded in frontmatter `file_id:` (SSOT) and embedded in the filename; becomes the `id:` itself (`id: HS-L6Y4`) under era 3. Server-minted, never hand-picked. |
+| **Family key** | `P2TR` | The shared 4+ char alphanumeric code that groups one initiative's specs — an epic and all its child tasks, research, and reviews — into one greppable **family** (`grep HS-P2TR` returns the whole family). Shared across the family; uniqueness is enforced on the full **basename** per kind, never on the family key alone (see vault-id-assignment-protocol §Shared-suffix families). |
+| **Type label** | `TASK` | The entity-kind token (`TASK`, `EPIC`, `MILESTONE`, `RESEARCH`, `REVIEW`, …). A **human-readable hint only**. |
+| **Title slug** | `verification-state-schema` | The lowercased-hyphenated descriptive tail derived from `title:` — the part that makes each basename unique within a family. |
+
+**Filename shapes (era = type-label position):**
+- **File-key-first (era 3, ratified target):** `HS-<file key>-<family key>-<type label>-<title slug>.md` → `HS-L6Y4-01D7-EPIC-deterministic-rename-with-link-rewrite.md` — lands vault-wide with HS-L6Y4-01D7-EPIC-deterministic-rename-with-link-rewrite.
+- **Family-first (era 2, current on disk / current minting):** `HS-<family key>-<type label>-[<file key>-]<title slug>.md` → `HS-P2TR-TASK-verification-state-schema.md`, `HS-0G910-EPIC-G3D3-api-foundation-keys-scopes-error.md`
+- **Type-first (era 1, legacy):** `HS-<type label>-<family key>-<title slug>.md` → `HS-TASK-P2TR-verification-state-schema.md`
+
+**Routing rule (SSOT for entity type):** code MUST determine a spec's entity type from the frontmatter **`type:`** field (and its directory), **never** by parsing the type label out of the filename. The type label is a convenience hint that survives out of directory context (wikilinks, search results, clipboard, terminal output); it is **not** authoritative and must never drive a mutation, a route, or a reclassification on its own. This is the semantic-identifier guardrail from HS-MF8M-CCVE-RES-family-first-spec-identifier-format-hs-i (don't route on parsed-ID semantics).
+
+**Retired / avoid:** **"suffix"** (the legacy name for the family key — self-contradictory once the family key leads), **"pipeline ID"** (overloaded with CI/CD + the feature-pipeline graph), **"prefix" / "type prefix"** for the family key (industry convention encodes *type*, not a family). The legacy term `<suffix>` still appears in the tables below and in the `legacy_slug_only` naming atoms until the Phase 3 codegen flip.
+
+### ID format
+
+| Entity type | ID format | Example |
+| --- | --- | --- |
+| `l1` | `HS-L1` | `HS-L1` |
+| `l2` | `HS-L2-<UPPER>` | `HS-L2-ENTITY`, `HS-L2-FOUNDATIONS` |
+| `l3` | `HS-UC-<short>` | `HS-UC-CAPTURE` |
+| `adr` | `HS-ADR-NNNN` (zero-padded sequence) | `HS-ADR-0001` |
+| `task` | `HS-TASK-<suffix>` — `<suffix>` is 4+ random A-Z0-9 (vault-id-assignment-protocol). Pre-2026-05-22 entries (`HS-NNNN`, `HS-<4+ A-Z0-9>`) were migrated to this prefix. | `HS-TASK-K7M2` |
+| `epic` | `HS-EPIC-<suffix>` — same rules | `HS-DE8L`, `HS-V888` |
+| `milestone` | `HS-MIL-<suffix>` — `<suffix>` is 4+ uppercase `A–Z0–9` (vault-id-assignment-protocol); legacy 4-character mnemonic IDs (e.g. `HS-RM22`) remain valid | `HS-RM22`, `HS-1JC8` |
+| `diagnose` | `HS-DIAG-<suffix>` — `<suffix>` is 4+ random A-Z0-9 (vault-id-assignment-protocol) | `HS-DIAG-K7M2` |
+| `pillar` | `HS-PILR-<slug>` (canonical; slug uniquely identifies the concept; no random suffix) or `HS-PILR-<suffix>-<slug>` (customer-scoped; random 4+ A-Z0-9) | `HS-PILR-pillars`, `HS-PILR-scaling`, `HS-PILR-K7M2-team-onboarding` |
+| `branch-brief` | `HS-BB-<slug>` | `HS-BB-feature-checkout-redesign` |
+| `memory-lesson` | `HS-LES-<slug>` | `HS-LES-bd-process-leak` |
+| `memory-decision` | `HS-DEC-<slug>` | `HS-DEC-dep-relate-for-epic-children` |
+| `memory-reference` | `HS-REF-<slug>` | `HS-REF-dolt-time-travel-docs` |
+| `memory-ui-pattern` | `HS-UIP-<slug>` | `HS-UIP-rail-active-vs-keyboard-cursor` |
+| `memory-ux-principle` | `HS-UXP-<slug>` | `HS-UXP-toggle-current-state-semantics` |
+| `protocol` | `HS-PROTO-<slug>` | `HS-PROTO-session-close` |
+| `review` | `HS-REV-<suffix>` — `<suffix>` matches the parent task/epic id 1:1 (e.g. parent `HS-76RX` → review `HS-QMHO`). Detection: [`extractSpecSuffix` in `console/src/lib/vault.ts:155`](../console/src/lib/vault.ts). | `HS-QMHO`, `HS-R3HO`, `HS-CCEQ` |
+| `business-positioning` | `HS-BIZ-POS-<slug>` | `HS-BIZ-POS-2nd-brain-harness-for-specs` |
+| `business-pricing` | `HS-BIZ-PRI-<slug>` | `HS-BIZ-PRI-tiers-and-byok-2026-05` |
+| `business-marketing` | `HS-BIZ-MKT-<slug>` | `HS-BIZ-MKT-launch-playbook-companion` |
+| `business-model` | `HS-BIZ-MOD-<slug>` | `HS-BIZ-MOD-flat-per-vault-economics` |
+| `roadmap` | `HS-ROADMAP-<SLUG>` | `HS-ROADMAP-PRODUCT` |
+| `research` | `HS-RES-<suffix>` — legacy `HS-RES-NNN` or random `HS-RES-<4+ A-Z0-9>` (vault-id-assignment-protocol) | `HS-RES-001`, `HS-RES-K7M2` |
+| `capture` | `HS-CAP-<suffix>` — same rules; legacy `HS-IDEA-<suffix>` preserved in `legacy_idea_id:` for archaeology | `HS-CAP-JKLN`, `HS-CAP-OAP3` |
+| `agent` | `HS-AGENT-<suffix>` — `<suffix>` is 4+ random A-Z0-9 (vault-id-assignment-protocol) | `HS-634I` |
+| `golden-case` | `HS-GCASE-<suffix>` — same rules | `HS-HPIO` |
+| `planning-flow` | `HS-FLOW-NNN` | `HS-FLOW-001` |
+| `draft` | `HS-DRAFT-<slug>` | `HS-DRAFT-2026-05-14-1130-article-link` |
+| `daily` | `HS-DAILY-YYYY-MM-DD` | `HS-DAILY-2026-05-14` |
+
+**New task/epic/research/capture IDs** (console `POST /api/specs`, MCP `heyspex_save_research`, agents): allocate a random 4-character suffix from `A–Z` and `0–9`, checking the full vault for collisions (frontmatter `id` and filename prefix). When every combination at the current length is taken, the suffix grows to 5 characters, then 6, and so on. Legacy sequential IDs (`HS-NNNN`, `HS-RES-NNN`, `HS-IDEA-*`, slug-only research filenames) remain valid in the read-path until HS-23PN-9HVY-TASK-capture-rename-repo-wide-wikilink-rewrite retires them. Validate with `npm run validate:vault-ids` at the repo root.
+
+### Filename derivation
+
+The filename is **derived from the ID + an optional slug**, lowercased, with the same prefix the ID uses minus the `HS-` prefix (kept lowercase in filenames for readability):
+
+| Entity | Filename pattern | Example |
+| --- | --- | --- |
+| `l1` | `heyspex-north-star.md` (literal, only one) | `heyspex-north-star.md` |
+| `l2` | `<topic>.md` (literal slug) | `entity-model.md` |
+| `l3` | `uc-<short>.md` | `uc-capture-intent.md` |
+| `adr` | `adr-NNNN-<slug>.md` | `adr-0001-vault-format.md` |
+| `task` | `HS-TASK-<suffix>-<slug>.md` | `HS-TASK-K7M2-fix-foo.md` |
+| `epic` | `HS-EPIC-<suffix>-<slug>.md` | `HS-0007-EPIC-console-resilience.md`, `HS-W9ZE-EPIC-design-system-enforcement-auto-surface-u.md` |
+| `milestone` | `HS-MIL-<suffix>-<slug>.md` | `HS-IART-MIL-console-ia-restructure.md` |
+| `diagnose` | `HS-DIAG-<suffix>-<slug>.md` | `HS-DIAG-K7M2-console-startup-lag.md` |
+| `pillar` | `HS-PILR-<slug>.md` (canonical; slug IS the ID with no random suffix) or `HS-PILR-<suffix>-<slug>.md` (customer-scoped) | `HS-PILR-pillars.md`, `HS-PILR-K7M2-team-onboarding.md` |
+| `branch-brief` | `<branch-slug>.md` | `feature-checkout-redesign.md` |
+| `memory-lesson` | `<slug>.md` | `bd-process-leak.md` |
+| `memory-decision` | `<slug>.md` | `dep-relate-for-epic-children.md` |
+| `memory-reference` | `<slug>.md` | `dolt-time-travel-docs.md` |
+| `memory-ui-pattern` | `<slug>.md` | `rail-active-vs-keyboard-cursor.md` |
+| `memory-ux-principle` | `<slug>.md` | `toggle-current-state-semantics.md` |
+| `protocol` | `<slug>.md` | `session-close-protocol.md` |
+| `review` | `HS-REV-<suffix>-<slug>.md` (slug truncated from parent's slug, ≤40 chars) | `HS-SK1L-REV-hs-idea-skill-four-beats-layered-confirms.md` |
+| `research` | `HS-RES-<suffix>-<slug>.md` (legacy: `<slug>.md` only) | `HS-RES-K7M2-agent-governance.md` |
+| `capture` | `HS-CAP-<suffix>-<slug>.md` | `HS-CAP-JKLN-vault-triage.md` |
+| `agent` | `HS-AGENT-<suffix>-<slug>.md` | `HS-9TNK-AGENT-code-reviewer.md` |
+| `golden-case` | `HS-GCASE-<suffix>-<slug>.md` | `HS-R4VW-GCASE-review-missing-ac.md` |
+| `planning-flow` | `HS-FLOW-<NNN>-<slug>.md` | `HS-FLOW-001-epic-planning-flow-studio.md` |
+| `draft` | `<slug>.md` | `2026-05-14-1130-article-link.md` |
+| `daily` | `YYYY-MM-DD.md` | `2026-05-14.md` |
+
+Slug rules: lowercase, ASCII, dash-separated, no trailing punctuation, no leading number for non-task types.
+
+> [!note] Branch-brief slug
+> For `branch-brief` the slug is **derived from the git branch name**: lowercased, every run of non-`[a-z0-9]` characters collapsed to a single `-`, trailing `-` stripped. `feature/checkout-redesign` → `feature-checkout-redesign`. The raw, unsanitized branch name is preserved in the required `branch:` field — the slug is for the filesystem and wikilink resolution only; git lookups use `branch:`. Ratified in adr-0008-branch-brief-and-evidence-schema.
+
+> [!note] Why not put the ID in the filename for memories?
+> bd memory keys are content-derived (`lessons/bd-process-leak`), and the Builder already thinks in those terms. The filename `bd-process-leak.md` IS the key, the ID is the metadata. Wikilink resolution finds the file by name; the `HS-LES-` prefix in the `id:` field is for the index and for stable cross-references.
+
+### ID + filename for the migration
+
+The migration plan (migration-from-bd) maps each bd issue to a new HeySpex task ID by sorting bd issues by `created_at` and assigning `HS-U2K9`, `HS-FMWM`, etc., in that order. The original bd ID is preserved as `legacy_bd_id` in frontmatter so cross-references in old commits/logs remain resolvable.
+
+## Frontmatter schemas
+
+Every spec opens with a YAML frontmatter block. The schemas below define **required** fields (must be present and non-empty) and **optional** fields (may be omitted).
+
+Universal fields (every spec has these):
+
+```yaml
+id:        # required, string, matches the entity type's ID format
+name:      # required, string, human-readable title
+type:      # required, one of the entity type values above
+status:    # required, see status enum below
+priority:  # required, integer 0–4 (0 = highest)
+owner:     # required, string (email or handle) — the ORIGINATING + accountable human (doubles as author).
+           #   See §Authorship provenance below.
+created:   # required, ISO-8601 date (YYYY-MM-DD)
+updated:   # required, ISO-8601 date
+contributors: # optional, list of "Name <email>" — OTHER humans who later enhanced the doc (append-only;
+              #   OMIT when empty). Auto-stamped, never hand-maintained. See §Authorship provenance.
+assisted_by:  # optional, list of "AGENT" or "AGENT:MODEL" — agents/IDEs + model that assisted (append-only;
+              #   OMIT when empty). Auto-stamped, never hand-maintained. See §Authorship provenance.
+tags:      # optional, list of strings
+related:   # optional, list of wikilinks (alternative to inline body links)
+what_matters: # optional, enum: star | heart — per-spec user-priority signal
+```
+
+**`what_matters`** is the per-spec user-priority signal that replaced the retired What Matters column (scheduler-and-whats-next-what-matters-column-mechanics, HS-78E7-Y9OJ-EPIC-deterministic-priority-scheduler). It is optional and two-level:
+
+- `star` (★) — *priority*: "consider this please."
+- `heart` (♥) — *very important*: "appreciate this being next if at all possible." A stronger signal than `star`.
+- absent — unflagged (no default is injected).
+
+The value is held verbatim; an unrecognized value is tolerated by the parser and emits a warn-only `INVALID_WHAT_MATTERS` validator notice rather than an error. A Phase 7b scheduler stage consumes it for ordering.
+
+### Authorship provenance
+
+Three universal fields carry GitHub-faithful provenance, following the cross-foundation `Assisted-by:` convention (Linux Kernel, Fedora, LLVM, OpenTelemetry) that keeps the human as the sole accountable author and records AI as a tool that *assisted*, not a co-author. Origin: HS-N1WG-W48S-RES-git-github-authorship-attribution-best-p → HS-Y4JH-IKIM-EPIC-authorship-provenance-frontmatter-owner. The SSOT question (frontmatter vs git history) is resolved in provenance-frontmatter-is-ssot-not-git-echo.
+
+| Field | Who | Item format | Cardinality |
+| --- | --- | --- | --- |
+| `owner` | the **originating + accountable** human (doubles as author) | handle or email (e.g. `pwher`) | single scalar |
+| `contributors` | **other** humans who later enhanced the doc | `Name <email>` — GitHub form, round-trips with the `Co-authored-by:` trailer | append-only list |
+| `assisted_by` | agents/IDEs + model that assisted | `AGENT` or `AGENT:MODEL` — e.g. `Claude Opus 4.8`, `Cursor` | append-only list |
+
+Semantics (apply to every entity kind):
+
+- **`owner` is universally required** and unchanged in type — only its meaning is enriched here (originator + accountable, not merely a pointer). A later ownership *transfer* is not preserved in frontmatter; git history (first-commit author) retains the original creator. Acceptable trade per HS-N1WG-W48S-RES-git-github-authorship-attribution-best-p.
+- **`contributors` and `assisted_by` are universal-but-optional and omit-when-empty** — they are not emitted as empty lists, so a solo-vault doc stays clean and only grows a list once a second human or an agent touches the doc.
+- **Append-only + de-dup, never reorder/remove.** A new acting human ≠ `owner` is appended to `contributors`; an acting agent is appended to `assisted_by`; an entry already present is not duplicated.
+- **Auto-stamped, never hand-maintained.** Seeded at creation (`owner` from the resolved user, `assisted_by` from the acting agent) and appended on edit, sourced from the existing claim/session trail (Neon `active_claims`). Authoring/wiring lives in HS-Y4JH-IKIM-EPIC-authorship-provenance-frontmatter-owner.
+
+> [!note] Schema addition self-gating
+> Per entity-model-self-gates-schema-changes-via-adr, new reserved frontmatter keys are normally gated behind an ADR. `contributors`/`assisted_by` are admitted here **without a standalone ADR** under the same milestone-precedent the `milestone` and `pillar` entity types used: they are additive, optional, omit-when-empty enrichments of the existing universal `owner` field (not a new entity type or a new lifecycle), ratified by their introduction lineage HS-N1WG-W48S-RES-git-github-authorship-attribution-best-p → HS-Y4JH-IKIM-EPIC-authorship-provenance-frontmatter-owner. The decision rationale is recorded in provenance-frontmatter-is-ssot-not-git-echo.
+
+### Artifact linkage
+
+An optional `artifact:` mapping records a published Claude Artifact that this spec/doc is the vault source for, so the artifact is never the only copy of its content — HS-6YIS-5GSW-EPIC-artifacts-as-vault-documents. **Universal** — unlike the type-specific schemas below, it attaches to ANY entity kind (a task, an epic, a research doc, a memory doc, or a non-frontmatter file like a roadmap page — see the HTML variant below), because a published artifact can belong to a doc at any level, not one lifecycle stage.
+
+```yaml
+artifact: { title: "…", url: "https://claude.ai/code/artifact/…", version: "…", updated: "2026-08-23" }
+# title:    required when artifact: is present — the artifact's display title (matches its published <title>/heading).
+# url:      required — the published URL.
+# version:  optional, string — the last-published version stamp this vault file was confirmed against. This is
+#           a LOCAL claim, not a live read: it is the freshness anchor for the push-first stale-guard
+#           (HS-6YIS-5GSW-EPIC part 2) — before publishing this file over the artifact, the publishing session
+#           reads the LIVE page and confirms it is not ahead of this stamp, THEN writes the new version back
+#           here after a successful publish. Never hand-edited to "catch up" without actually reading the live
+#           page first (the incident this field exists to prevent: [[a-published-artifact-and-its-vault-copy]]).
+# updated:  optional, ISO-8601 date — when this vault file was last published/stamped against the artifact.
+```
+
+Either a single-line flow mapping (above) or an equivalent nested block mapping is valid YAML; the artifact-publish tooling (HS-6YIS-5GSW-EPIC-artifacts-as-vault-documents part 2, `scripts/hs-artifact.mjs`) reads and writes the flow-mapping form. Omit the whole `artifact:` key when the doc has no published artifact (omit-when-empty, same posture as `contributors`/`assisted_by`).
+
+**Non-frontmatter vault files** (a raw HTML page under `specs/roadmap/`, for example, has no YAML frontmatter at all): the same four fields are carried as a single machine-readable `ARTIFACT-STAMP: {...}` JSON line inside the file's existing leading `<!-- -->` source-of-truth comment, read/written by the same tooling. This is the shape `specs/roadmap/heyspex-sprint-roadmap0829.html` uses.
+
+> [!note] Schema addition self-gating
+> Per entity-model-self-gates-schema-changes-via-adr, `artifact:` is admitted here **without a standalone ADR** under the same milestone-precedent as `contributors`/`assisted_by` above: additive, optional, omit-when-empty, not a new entity type or lifecycle — ratified by its introduction lineage, the owner's immediate order following the incident recorded in a-published-artifact-and-its-vault-copy → HS-6YIS-5GSW-EPIC-artifacts-as-vault-documents.
+
+Status enum (universal):
+
+- `draft` — under active authorship, not yet ratified.
+- `open` — ratified and available to work against (for tasks, epics) or stable (for L1/L2/L3/ADR).
+- `in_progress` — claimed and being executed (tasks only).
+- `in_review` — implementation complete, awaiting human verification before closure (tasks only).
+- `closed` — done (tasks) or superseded (ADRs).
+- `deferred` — **deprecated** (2026-06-24 per parked-is-the-single-hold-status-deferre). Use `status: parked` for indefinite hold or `defer_until:` for dated snooze instead. Kept for read-back-compat only.
+
+### Type-specific schemas
+
+#### `l1`
+
+```yaml
+type: l1
+aliases:   # optional, list of alternative names
+brand:     # optional, mapping with canonical/variants/pronunciation/comma
+domains:   # optional, list of relevant domains
+version:        # optional, monotonic integer — bumped on every material edit to the record.
+               #   The alignment-drift detector ([[HS-E3D3-RDFT-EPIC-alignment-drift-detector-into-resolution]])
+               #   compares the version an epic was last aligned against (its `alignment_baseline`)
+               #   to this current version; a bump past the baseline surfaces a `drift` resolution item.
+last_edited_at: # optional, ISO-8601 timestamp of the last edit to the record. Timestamp FALLBACK for
+               #   drift detection when an epic carries no per-layer `alignment_baseline`: the layer's
+               #   `last_edited_at` newer than the epic's `alignment_reviewed_at` means drift.
+```
+
+Only one `l1` exists per vault. The `version` / `last_edited_at` fields are the versioning prerequisites carried from HS-OR8V-0010-EPIC-north-star-vision-first-class-entity; they make the L1 record a drift baseline anchor for the alignment-drift detector.
+
+#### `l2`
+
+Universal fields only. No required L2-specific fields.
+
+#### `l3` (use case)
+
+```yaml
+type: l3
+actors:           # required, list of actor names from L1
+trigger:          # required, string — what initiates this use case
+outcomes:         # required, list — observable end states
+depends_on:       # optional, list of wikilinks to other use cases
+```
+
+#### `adr`
+
+```yaml
+type: adr
+decision_date:    # required, ISO-8601 date
+deciders:         # required, list of strings
+supersedes:       # optional, wikilink to ADR this replaces
+superseded_by:    # optional, wikilink to ADR replacing this
+status:           # adr-status enum: proposed | accepted | deprecated
+                  #   `superseded` is DEPRECATED 2026-06-03 per [[superseded-enum-values-deprecated-use-canonical-false-and-superseded-by]]
+                  #   New writes: set `canonical: false` + `superseded_by: '[[<successor>]]'` instead. Existing
+                  #   ADRs that already carry `status: superseded` stay as historical record per the
+                  #   immutability principle ([[closed-trackable-specs-are-historical-record-not-living-docs]]) —
+                  #   readers infer `canonical: false` from the legacy value.
+canonical:        # universal flag — true (or absent) = current/authoritative; false = historical record
+                  #   (current canonical is at `superseded_by:`). Flipped at supersession-time via
+                  #   [[supersession-protocol]]; frozen thereafter.
+```
+
+The ADR-specific `status` enum overrides the universal status enum for ADRs. The `canonical:` field applies to ADRs the same way it does to every spec type.
+
+#### `task`
+
+```yaml
+type: task
+kind:             # one of: infra | foundation | feature | polish (scheduler tier — SSOT is
+                  #   SCHEDULER_KIND_VOCAB in console/src/lib/indexer/vault-rules.mjs). Legacy bd
+                  #   kinds (bug | spike | story | milestone) are retired; migrate via
+                  #   scripts/migrate-to-scheduler-metadata.mjs. Bugs now have their own lane
+                  #   (kind: bug-fix capture → HS-DIAG-* diagnose spec → Resolution surface).
+assignee:         # optional, string
+started_at:       # optional, ISO-8601 datetime — set on first transition to in_progress
+closed_at:        # optional, ISO-8601 datetime
+close_reason:     # optional, enum: shipped | deprecated | obsolete | wont_fix | duplicate
+                  #   shipped → "Done" archive view; deprecated* → "Deprecated" archive view
+                  #   `superseded` is DEPRECATED 2026-06-03 per [[superseded-enum-values-deprecated-use-canonical-false-and-superseded-by]]
+                  #   New writes that involve supersession: omit `close_reason` (or use another value
+                  #   like `deprecated`) and set `canonical: false` + `superseded_by:` instead.
+                  #   Existing closed specs with `close_reason: superseded` stay as historical record
+                  #   per immutability ([[closed-trackable-specs-are-historical-record-not-living-docs]]).
+defer_until:      # optional, ISO-8601 date — dated snooze evaluated by isDeferredNow(); scheduler-invisible
+                  #   until the date, then auto-returns with no status change ([[parked-is-the-single-hold-status-deferre]]).
+                  #   Distinct from `status: parked` (indefinite hold). Do NOT pair with deprecated `status: deferred`.
+target:           # optional, string — repo-relative path(s) of the file(s) an autonomous builder edits
+                  #   for this task (comma-separated for multi-file). DISPATCH METADATA for the dev-factory
+                  #   overnight loop: its backlog selector only dispatches an open, dependency-ready task
+                  #   that carries target:; without it the task is skipped with a warning. Hand-editing this
+                  #   field is allowed (it is not status). Owner-approved 2026-07-04 (HS-BMAW go-live);
+                  #   interim docs lived in dev-factory/README.md §Vault-task target: frontmatter.
+test:             # optional, string — the test file that gates the autonomous build of this task
+                  #   (scoped vitest run / self-test). When omitted the gate falls back to tsc --noEmit
+                  #   plus the module's own self-test conventions. Pairs with target: above.
+suggested_model:  # optional, string — breakdown-authored Ollama model id for local builder dispatch
+                  #   (e.g. qwen3-coder:30b). Honored as first candidate in scheduler/backlog-selector;
+                  #   falls back through routing-table build chain when unavailable.
+suggested_machine:# optional, string — machine key from routing-table (specops-gpu0, basement-geek, …).
+                  #   Scheduler tries this machine first when reachable + capable.
+recommended_num_ctx: # optional, integer — Ollama num_ctx bucket (16384 | 32768 | 65536 | 131072).
+                  #   pick-num-ctx.mjs honors when ≤ machine ceiling (spec-ops 65536, basement 131072).
+estimated_context_tokens: # optional, integer — breakdown estimate of prompt tokens (target + deps + spec).
+context_files:    # optional, list of repo-relative paths — passed to builder.mjs as --extra (types, deps).
+                  #   Omit the target file (builder always reads it). Body duplicate: ## Builder brief.
+fit_assessment:   # optional, enum: safe | tight | overflow — breakdown confidence in context fit.
+parallel_safe:    # optional, boolean — false when task must not run concurrently (shared config/schema).
+affects_paths:    # optional, list of repo-relative paths — read/write set for stomp detection at dispatch.
+parallel_group:   # optional, string — wave id; tasks in same group may run together when paths disjoint.
+builder_profile:  # optional on child tasks only when inherited from epic; see builder-fleet-capability-reference.
+canonical:        # universal flag — true (or absent) = current/authoritative; false = historical record.
+                  #   Flipped to false during the in_review → closed transition for plan-side specs per
+                  #   [[session-close-protocol]] §Reviewer responsibilities step 4, or at supersession per
+                  #   [[supersession-protocol]]. `status: parked` keeps `canonical: true` (paused, not historical).
+superseded_by:    # optional, wikilink — pointer to the current canonical when canonical: false.
+                  #   Required when canonical: false AND there is a successor (per [[supersession-protocol]]).
+                  #   When close_reason was historically deprecated|duplicate, this field can still point
+                  #   at the successor; the legacy enum value stays as historical record.
+
+# Dependency edges (see "Dependencies" section below)
+blocks:           # optional, list of wikilinks — this task blocks these
+blocked_by:       # optional, list of wikilinks — these tasks block this one
+related:          # optional, list of wikilinks — soft, navigational
+parent:           # optional, single wikilink — hierarchical parent
+children:         # optional, list of wikilinks — hierarchical children
+discovered_from:  # optional, single wikilink — provenance edge ("this task was born while
+                  #   working on X"). Also the code-audit **cleanup→task exit**: a task filed
+                  #   from a `research_type: code-audit` finding row (Action: task) sets this to
+                  #   the source `[[HS-RES-…]]` (see §research "Code-audit findings table" /
+                  #   [[HS-7D0I-WL88-TASK-code-audit-research-type-with-a-defined]]).
+
+# Delegation / task-split lineage ([[HS-HXE2-YQ5A-EPIC-delegation-defer-work-from-one-agent-to]],
+# [[HS-DTL1-CX5K-CAP-task-split-handoff-when-context-runs-low]], [[HS-PD6K-NCH5-TASK-handoff-envelope-schema-and-split-child]])
+split_of:         # optional, single wikilink — parent task or epic this spec continues (option B:
+                  #   random child id + frontmatter linkage). Must pair with split_index.
+split_index:      # optional, positive integer — 1-based sequence among siblings split from the
+                  #   same split_of parent. Required when split_of is set.
+handoff_id:       # optional, string — dedup key for idempotent defer re-posts
+                  #   ([[HS-PJN4-W146-TASK-defer-idempotency-handoff-id-and-cross-a]]).
+
+# Ingest + roadmap admission ([[plan-ingest-review-roadmap-workflow]], [[adr-0012-roadmap-storage]])
+ingest_draft:           # optional, wikilink to draft this spec was promoted from
+forked_from:            # optional, wikilink — source spec when forked from sealed as-built diagram ([[HS-G8JS-F6P1-TASK-fork-spec-from-as-built-canvas]])
+forked_from_canvas:     # optional, string — vault-relative as-built canvas path
+has_diagram:            # optional, boolean — spec contains architecture mermaid; indexes Shipped gallery
+source_intent_hash:     # optional, copied from draft at promote time
+roadmap_admission:      # optional, enum: pending | scheduled | horizon | declined
+roadmap_phase:          # optional, string — phase id from a HS-ROADMAP-* manifest (e.g. M3)
+                        # horizon backlog: set priority: 4 and/or tag horizon; roadmap_admission: horizon
+
+# Optional structured content; preferred form is markdown sections in body
+acceptance:       # optional, list of acceptance criteria. Each entry is EITHER a plain string
+                  #   (prose criterion — stays fully valid) OR an object carrying a runnable check:
+                  #     - text: "<the criterion>"
+                  #       verification:        # optional — how a machine proves this criterion
+                  #         kind: test | lint | types | command | guard | evidence
+                  #         run:  "<command or test path>"   # required for machine kinds
+                  #         expect: exit-0 | no-net-new      # default exit-0
+                  #   `kind: evidence` names an evidence type a human/receipt records instead of a
+                  #   command. Prose-only criteria are receipt-marked "human-verified" honestly.
+                  #   Backward compatible by construction ([[HS-MNW5-IU2S-EPIC-executable-acceptance-criteria-and]]);
+                  #   kinds/expects mirror the checks-manifest contract ([[checks-manifest-authoring]],
+                  #   parser: spex-console/src/lib/cli/checks-manifest.ts).
+skills:           # optional, list of strings
+context:          # optional, list of strings
+evidence:         # optional, evidence array — sources proving acceptance met
+                  #   (see "Evidence linking" below)
+
+# Council session output ([[adr-0015-council-as-cross-cutting-capability]])
+deliberation_record: # optional; multi-LLM debate output, append-only `runs[]`. Permitted on task/epic/review
+                     # in addition to draft. Schema lives under `draft` §`deliberation_record` above. Attaches
+                     # on promoted-spec recheck (invocation #3) via `/hs-next` claim path; never gates work.
+
+# Parallel-agent module hints ([[HS-ZMAQ-M15C-TASK-declare-owned-path-globs-on-agent-identi]])
+affects_paths:    # optional, list of repo-relative glob strings — coarse module hints for
+                  #   overlap detection when multiple agents work in parallel; advisory in v1
+                  #   (same posture as the advisory `lane:` label on agent identities).
+
+# Migration provenance
+legacy_bd_id:     # optional, string — original bd id for migrated entries
+```
+
+##### Handoff envelope (body)
+
+When an agent defers or splits remaining work into a child task, the **handoff envelope** carries the next agent's starting context. SSOT is the **body**, not frontmatter — a `## Handoff envelope` heading followed by a fenced ` ```yaml ` block matching `schemas/handoff-envelope.schema.json`:
+
+```yaml
+reason: "Why the defer/split happened (context budget, blocked, lane hand-off)"
+summary_done:
+  - "Work completed before the handoff"
+remaining:
+  - "Actionable items for the picking-up agent"
+success_criteria:
+  - "How the reviewer knows the deferred work is done"
+```
+
+Field semantics align with the WIP ledger (`remaining` / verified-style `summary_done`) plus delegation-specific `reason` and `success_criteria` per HS-SUMD-4T35-RES-parallel-agent-coordination-handoff-and. A task with `split_of:` **must** include this section; `scripts/validate-vault-ids.mjs` enforces shape. The defer command (HS-MS3T-1U0Z-TASK-hs-defer-mcp-tool-and-slash-command) authors both the lineage frontmatter and this block.
+
+#### `agent`
+
+Durable agent identity (HS-XNX5-UQHA-MIL-agent-home). Evergreen — does not close. Compiles to `.claude/agents/<name>.md` and `.cursor/agents/<name>.md`; the vault spec is the SSOT.
+
+```yaml
+type: agent
+role:             # required, string — human-readable role title (also used as description fallback on compile)
+model:            # optional, enum: opus | sonnet | haiku
+description:      # optional, string — host-native description on compile
+goal:             # optional, string — HeySpex-resident intent label (not compiled)
+allowed_tools:    # optional, list of strings — compiled to host `tools:` when present
+disallowed_tools: # optional, list of strings — compiled to host `disallowedTools:` when present
+procedures:       # optional, list of wikilinks — HeySpex-resident procedure refs
+handoffs:         # optional, list — HeySpex-resident handoff targets
+guardrails:       # optional, list of strings — HeySpex-resident; persona body carries compiled guardrails
+lane:             # optional, string — human label for parallel work (advisory in v1)
+isolation:        # optional, enum: default | worktree — operator guidance for checkout
+                  #   isolation when parallel agents each need a dev server; advisory in v1
+                  #   ([[parallel-agent-isolation-guidance]]). `worktree` = use a dedicated git
+                  #   worktree before implementation. HeySpex-only — stripped on compile (like `lane`).
+color:            # optional, string — console roster accent (HeySpex-only)
+owned_paths:      # optional, list of repo-relative glob strings — machine-checkable file/module
+                  #   ownership for stomp-detection ([[HS-8PNX-Q1KC-EPIC-lanes-and-stomp-detection-for-parallel-a]]).
+                  #   Example: spex-console/src/lib/scheduler/**, vendor/heyspex-mcp/**. HeySpex-only — stripped on compile.
+golden_cases:     # optional, list of wikilinks to HS-GCASE-* fixtures owned by this agent.
+                  #   Reverse of each case's `agent:` pointer. HeySpex-only — stripped on compile
+                  #   ([[HS-8AQT-J6FU-TASK-golden-case-vault-artifact-format-and-st]]).
+source_attribution: # optional object — import provenance for community/own-agent imports only
+tags:             # required for roster grouping — MUST include `agent` plus at least one
+                  #   `purpose/*` tag (see Purpose tags below). Plain frontmatter array;
+                  #   no agent-only grouping engine ([[HS-IAYA-5345-TASK-lock-agent-purpose-taxonomy-and-tag-conv]]).
+```
+
+**Purpose tags** (HS-E2VS-LBUS-EPIC-roster-organization-and-discovery-for-a, HS-WDHW-0009-EPIC-tag-taxonomy-tag-browser-obsidian-style): agent identities reuse the vault's nested-tag namespaces — a dedicated **`purpose/`** namespace (seventh namespace alongside 0009's `area/`, `type/`, `surface/`, `theme/`, `dep/`, `stage/`) for roster discovery. Values are multi-select tags in `tags:`; grouping UI and `GET /api/agents` read them later (HS-NRND-UF9J-TASK-expose-agent-tags-in-get-api-agents-rost).
+
+| Tag | When to use |
+|-----|-------------|
+| `purpose/reviewer` | Verify acceptance criteria, review diffs, read-only audit before close-out |
+| `purpose/researcher` | Synthesize cited research into durable `HS-RES-*` specs |
+| `purpose/planner` | Ground plans/epics, stress-test assumptions at the plan→execute boundary |
+| `purpose/triager` | Intake routing — captures, resolution items, smallest-fix triage |
+| `purpose/implementer` | Build, edit, deploy — agents that modify code or infra |
+| `purpose/writer` | Prose/docs authoring (reserved; no starter roster member yet) |
+
+Rules:
+
+1. **Required:** every shipped `type: agent` spec carries **at least one** `purpose/*` tag in `tags:` (in addition to the `agent` marker).
+2. **Primary purpose:** the **first** `purpose/*` tag in `tags:` array order is the roster section key. Downstream surfaces expose it as `primaryPurpose` (computed server-side — not a separate frontmatter field). When an agent legitimately spans multiple purposes, list the primary group first and secondary `purpose/*` tags after.
+3. **`lane:` is not a substitute:** `lane` is parallel-work coordination (advisory, HeySpex-only, stripped on compile). `purpose/*` is vault-resident discovery metadata that flows to the API. They often align but are independent fields.
+
+#### `golden-case`
+
+Saved eval fixture for the agent testing harness (HS-R1JM-OAG3-EPIC-agent-testing-harness-try-a-draft-agent). Evergreen — updated in place as the agent evolves; does not close. One golden case exercises exactly one `type: agent` identity. The eval spawn (HS-YNIE-ZDQ7-TASK-transient-eval-spawn-and-trajectory-capt) reads the body; the verdict engine (HS-ZOHQ-MOOE-TASK-verdict-engine-deterministic-graders-plu) consumes optional deterministic graders. Expected trajectories (regression baselines) are **run artifacts**, not stored in the fixture at v1 — they land in run history later (HS-ZR0Z-TS11-TASK-run-history-storage).
+
+```yaml
+type: golden-case
+agent:            # required, wikilink to HS-AGENT-* — the identity under test
+tags:             # should include golden-case, agents, testing
+related:          # optional wikilinks — e.g. the task spec used as setup context
+```
+
+**Bidirectional linkage:** each golden case carries `agent:`; the agent MAY carry `golden_cases:` (list of wikilinks). Filing via `createSpec` / `heyspex_file_spec` with `frontmatter.agent` auto-appends to the agent's `golden_cases:` array (same pattern as task→epic `children:`).
+
+**Required body sections:**
+
+| Section | Required | Purpose |
+| --- | --- | --- |
+| `## Prompt` | yes | The user message the eval spawn sends to the draft agent (≥12 characters). |
+| `## Setup` | no | Freeform context — wikilinks to task specs, files in scope, env hints. |
+| `## Deterministic graders` | no | Fenced `yaml` block matching `specs/schemas/golden-case-body.schema.json`. Keys the reproducible pass/fail signal; LLM-judge critique remains advisory per OAG3 AC#4. |
+
+**On-disk layout:** `specs/agents/golden-cases/HS-GCASE-<suffix>-<slug>.md` — nested under `agents/` so fixtures travel in the same git subtree as agent identities.
+
+#### `epic`
+
+Same as `task` schema (including optional `affects_paths:`). The `type: epic` is what differentiates. An epic typically has many `children:` and few `blocks:`/`blocked_by:`.
+
+**Planning flow requirements** (planning-flow-research-epic-lifecycle): every epic MUST include `research:` and `planning_flow:` wikilinks. Console Epic Studio and `POST /api/specs` enforce this for newly filed epics.
+
+```yaml
+research:         # required for new epics — wikilink to HS-RES-*
+planning_flow:    # required for new epics — wikilink to HS-FLOW-*
+milestone:        # REQUIRED — single wikilink to the parent HS-MIL-* this epic belongs to.
+                  #   The inverse of the milestone's `epics:` array (write both sides;
+                  #   `scripts/validate-vault-ids.mjs` rejects one-sided drift).
+                  #   Grace window: missing `milestone:` is a validator warning until
+                  #   2026-06-26, then escalates to an error
+                  #   ([[HS-V5UA-T5PX-TASK-required-milestone-parent-on-epic-validator-and-grace-window]],
+                  #   part of [[HS-OFR5-M2J3-EPIC-introduce-milestones-as-highest-entity]]).
+                  #   Pre-rule orphan epics live at
+                  #   [[HS-3DJS-ORPH-MIL-uncategorized-pre-2026-05-26-epics]]
+                  #   pending walk-the-floor reassignment.
+derived_from:     # optional, single wikilink to HS-RES-* — the research that spawned this epic.
+                  #   Reverse of `research.spawned_epics:` (1:N). See §Provenance edges.
+```
+
+**Alignment fields** (drift-detection prerequisites; HS-E3D3-RDFT-EPIC-alignment-drift-detector-into-resolution, owned by HS-KA1E-0012-EPIC-creation-guardrails-agent-pushback for the vault-wide backfill):
+
+```yaml
+alignment_rationale: # optional (backfill in progress), string — a wikilink to the Pillar / L1 principle
+                     #   this epic advances PLUS a one-line "why", e.g.
+                     #   "[[HS-PILR-architecture]] — advances the foundations concern by converging detection paths".
+                     #   Distinct from the membership `pillar:` field: `pillar:` categorizes; `alignment_rationale`
+                     #   carries the teleological "why" the drift detector reasons over. The wikilink target
+                     #   SHOULD match the epic's `pillar:`. An `alignment_rationale` that resolves to no layer
+                     #   record surfaces as an `orphan` resolution item.
+alignment_baseline:  # optional, mapping { <layer-id>: <int version>, anti_goals?: <fingerprint> } — the layer
+                     #   versions this epic was last aligned against. PRIMARY drift baseline: when a referenced
+                     #   layer's current `version` exceeds the baseline here, a `drift` item is emitted. The
+                     #   `anti_goals` key stamps the L1 anti-goal fingerprint so a changed anti-goal set re-checks
+                     #   every active + recently-closed epic. Absent → the detector falls back to
+                     #   `alignment_reviewed_at` vs the layer's `last_edited_at`; absent both → no drift (never a
+                     #   false positive). Stamped by the alignment checkpoint on re-alignment.
+```
+
+#### `milestone`
+
+The grouping **above** epic: a coherent multi-epic ship (a restructure or release) that closes when every child epic closes and the milestone's own acceptance gate is met. Formalized by HS-VK7C-MILE-EPIC-milestone-entity-type-and-surfacing; the canonical hierarchy and filing rules live in [[spec-hierarchy]]. The 33 `HS-MIL-*` files on disk (seed: HS-RM22-IART-MIL-console-ia-restructure) predate this schema row and are described by it retroactively.
+
+```yaml
+type: milestone
+status:           # one of: open | in_progress | closed (subset of the universal enum)
+epics:            # list of wikilinks to every child epic — the mirror of each child epic's
+                  #   `milestone:` pointer. Write both sides (bidirectional linkage; see [[spec-hierarchy]]).
+informed_by:      # optional, list of wikilinks to HS-RES-* — research docs that enhance this milestone.
+                  #   Reverse of `research.enhances:` (each research enhances exactly one milestone, M:1;
+                  #   one milestone may be informed by many research docs over time). Bidirectional
+                  #   consistency enforced by `scripts/validate-vault-ids.mjs`. See §Provenance edges.
+target_date:      # optional, ISO-8601 date or empty string "" — the intended ship date
+tags:             # optional, list of strings
+related:          # optional, list of wikilinks
+```
+
+**No scalar `priority:` field.** Milestone ordering is the **output** of the deterministic priority scheduler, never a stored scalar (deterministic-priority-scheduler-supersedes-scored-priority, HS-78E7-Y9OJ-EPIC-deterministic-priority-scheduler). This deliberately diverges from the universal "`priority:` required" rule above — the same way current epics and tasks omit the scalar. Do not add a `priority:` to a milestone.
+
+Sub-milestones are **out of scope**: large milestones are split horizontally (more milestones at the same level), not nested ([[spec-hierarchy]] §Open questions). There is no `milestone:` (parent-milestone) field on a milestone.
+
+Required body sections ([[spec-hierarchy]] §Frontmatter requirements per level): rationale ("why this is a milestone, not loose epics"), an acceptance gate (numbered closure conditions), suggested landing order, and out-of-scope.
+
+#### `diagnose`
+
+A user-reported **bug fix** as first-class executable work — claimable and decomposable like a task, but typed so it reads as "a reported bug to fix," not planned roadmap work. Introduced by HS-OXBS-BFIX-MIL-bug-fix-diagnose-lane (milestone-precedent, no standalone ADR). Standalone by default; an optional `parent:` (epic OR milestone) groups related fixes. Surfaces on the Resolution surface as a derived `kind: "bug"` row (the row is derived; this spec is the work — see blockers-are-gating-subset-of-resolution and HS-AO2F-1KZK-RES-bug-fix-resolution-task-entity-model-and).
+
+```yaml
+type: diagnose
+status:           # universal enum: open | in_progress | in_review | closed | …
+severity:         # REQUIRED — one of: error | warning | info. Maps onto the scheduler's
+                  #   existing priority signals (channel B): a higher-severity diagnose
+                  #   competes higher for on-deck. Drives the derived bug row's color.
+parent:           # OPTIONAL — single wikilink to an HS-EPIC-* or HS-MIL-* parent.
+                  #   Standalone (absent) is the DEFAULT and is exempt from the
+                  #   epic→milestone mandatory-parent rule. One-way pointer (no auto back-link).
+depends_on:       # optional, list of wikilinks — tasks/specs that must close first.
+blocks:           # optional, list of wikilinks to HS-EPIC-*/HS-TASK-* this fix gates.
+                  #   Surfaces as a gating item in that spec's On-Deck overlay (channel A).
+promoted_from:    # optional, single wikilink to HS-CAP-* — set when this diagnose was promoted
+                  #   from a bug-report capture via `heyspex_promote_capture_to_diagnose`.
+                  #   Reverse of `capture.promoted_to:` (first-promotion).
+derived_from:     # optional, single wikilink to HS-RES-* — the research that surfaced this bug,
+                  #   set when this diagnose was promoted from a research investigation via
+                  #   `heyspex_promote_research_to_diagnose` (mirrors `epic.derived_from`).
+                  #   Reverse of `research.produces_diagnose:` (1:N).
+tags:             # optional, list of strings
+related:          # optional, list of wikilinks
+```
+
+**No scalar `priority:`** — like task/epic/milestone, ordering is the scheduler's output; `severity:` is the diagnose's contribution to that ranking, not a stored priority.
+
+Required body sections: Symptom, Reproduction, Root cause, Fix, Acceptance criteria.
+
+#### `pillar`
+
+Perpetual categorical container that never closes — the cross-cutting axis to which every epic associates via a primary `pillar:` field. Pillars are the structural primitive that makes HeySpex's "preserve context across time" claim true rather than aspirational ("Linear and Jira are queues; HeySpex is context" — see heyspex-market-positioning). Introduced 2026-05-31 per HS-AWDI-PILR-RES-pm-perpetual-container-terminology; ratified by introduction lineage HS-EBIL-0011-EPIC-goal-hierarchy-l2-strategic-pillars-l3 (milestone precedent, no standalone ADR for the entity itself). The meta-Pillar — the Pillar about Pillars themselves, dogfooding instance — is HS-PILR-pillars.
+
+```yaml
+type: pillar
+status:           # `perpetual` — non-terminal. Pillars never transition to closed/in_review/etc.
+                  #   Universal status enum does NOT apply.
+canonical:        # required, boolean
+                  #   true  → curated by HeySpex team; ships pre-loaded in customer vaults; read-only (fork to customize)
+                  #   false → customer-scoped Pillar (filed by the customer with high friction)
+library_tier:     # optional enum: meta | foundational | discretionary (placeholder; library taxonomy TBD)
+secondary_pillars: # always present; usually empty []. Reserved for future cross-Pillar linking.
+version:          # optional, monotonic integer — same semantics as the `l1` `version` field above.
+                  #   A Pillar edit that materially changes scope bumps this; epics aligned against the
+                  #   prior version surface as `drift` items ([[HS-E3D3-RDFT-EPIC-alignment-drift-detector-into-resolution]]).
+last_edited_at:   # optional, ISO-8601 timestamp of the last edit — drift timestamp fallback (see `l1`).
+related:          # optional, list of wikilinks
+tags:             # optional, list of strings
+```
+
+The `version` / `last_edited_at` fields are the versioning prerequisites carried from HS-EBIL-0011-EPIC-goal-hierarchy-l2-strategic-pillars-l3; together with the L1 fields they let the alignment-drift detector tell a material Pillar revision apart from a no-op touch.
+
+**Per-epic membership** (new fields on every epic, added 2026-05-31 by HS-EBIL-0011-EPIC-goal-hierarchy-l2-strategic-pillars-l3):
+
+```yaml
+pillar:             # required on every epic, single wikilink to a Pillar.
+                    #   The home for library/learning. Forces "what perpetual concern does this advance?"
+                    #   at filing time. HARD-BLOCKED at the filing boundary (owner decision 2026-06-18):
+                    #   POST /api/specs / heyspex_file_spec refuse an epic with no resolvable HS-PILR pillar
+                    #   (400 pillar_required). Legacy pillar-less epics are caught by the EPIC_MISSING_PILLAR
+                    #   vault-rule — warning (Resolution backfill queue) until 2026-07-31, then error.
+                    #   Full rules: [[pillar-assignment-protocol]].
+secondary_pillars:  # optional, list of wikilinks to Pillars.
+                    #   For genuinely cross-cutting work ("Add caching layer" is primarily Scaling but also Reliability).
+                    #   Tasks inherit their epic's primary pillar; do not set secondary on tasks.
+```
+
+**Authored as the work surfaces themes.** Pillars are created over time, not enumerated up front — there are deliberately only a few today and many more are expected. When filing an epic surfaces a theme with no pillar yet, the agent is prompted to author one (`heyspex_file_spec({ type: "pillar", name })`); the owner may also author a pillar standalone whenever a theme is foreseen. The procedure is pillar-assignment-protocol.
+
+**Milestones surface a derived pillar roll-up.** A milestone has **no authored `pillar:` field** — it is a dated ship that groups epics, which may belong to different pillars. Instead a milestone *surfaces* the de-duped set of pillars its child epics carry (computed in `getSpec`, rendered on the milestone detail drawer). The roll-up is derived and may list multiple pillars, so it never drifts from the epics' `pillar:` fields.
+
+**Status semantics.** Pillars carry `status: perpetual` as a single non-terminal value, distinct from the universal enum. The close-out protocol skips Pillars; the scheduler skips Pillars as on-deck candidates (only their epics are scheduled); review-doc flow does not apply. A Pillar's body grows over time as epics close and lessons accumulate against the concern — accumulation IS the point.
+
+**Body sections.** Required: a one-line "why this Pillar exists" hook; `## In scope` / `## Out of scope`; `## Anticipated epics`; `## Library status` (canonical | customer-scoped). The body is a living document, not a frozen artifact.
+
+**Disambiguation — three distinct uses of "pillar" in this vault:**
+
+1. **`type: pillar` entities (`HS-PILR-*`)** — this section. Perpetual product concerns (Scaling, Reliability, DX, etc.). Queryable, schematized.
+2. **HS-DOC-architecture-foundations** (renamed 2026-05-31 from `architecture-pillars`) — L2 doc that names the five technical foundations of the system (vault, indexer, console, CLI, sync mesh) and refers to them as "Pillars 0–5" in internal section headers. Unrelated to (1); the section names are preserved for now and may be renamed in a future cosmetic pass.
+3. **HS-OR8V-0010-EPIC-north-star-vision-first-class-entity's FIVE COMPONENTS section** — five implementation parts of that epic. Previously named "FIVE PILLARS"; renamed 2026-05-31 to remove the overload.
+
+Only sense (1) is a queryable entity. (2) and (3) use the word as a non-schematized noun within their own documents.
+
+#### `branch-brief`
+
+A durable "plan receipt" for one git branch. Ratified by adr-0008-branch-brief-and-evidence-schema; closes the Continuity Layer schema gaps (HS-7KOO-0022-EPIC-continuity-layer-gaps). One brief per branch; re-generation overwrites the file in place (git history is the version trail). Generated by HS-838Y-ALDY-TASK-branch-brief-generation.
+
+```yaml
+type: branch-brief
+branch:           # required, string — the raw (unsanitized) git branch name
+repo:             # optional, string — repo name if multi-repo
+goal:             # required, string — what this branch is trying to accomplish
+implements:       # optional, list of wikilinks — tasks/epics this branch implements
+plan:             # optional, list of { step: int, description: string }
+                  #   the ORIGINAL intent. Sourced (priority order) from:
+                  #   1. the linked implementing spec's acceptance criteria
+                  #      (its `acceptance:` array, else its `## Acceptance` body)
+                  #   2. a manual plan authored here (exploratory branches)
+                  #   Commit messages / PR bodies are NOT v1 plan sources.
+actual:           # optional, list of { step: int, description: string,
+                  #   status: <drift enum>, evidence: [<evidence ref>] }
+                  #   what was implemented, captured at brief-generation time.
+risks:            # optional, list of strings — identified risks/concerns
+open_questions:   # optional, list of strings — unresolved questions
+next_steps:       # optional, list of strings — recommended next actions
+decisions:        # optional, list of wikilinks — memory-decisions made on this branch
+evidence:         # optional, evidence array (see "Evidence linking" below)
+```
+
+**Drift enum** (the `status:` of each `actual` step) — defined once here, reused by HS-838Y-ALDY-TASK-branch-brief-generation and any drift tooling (HS-CM22-0019-EPIC-post-edit-alignment-drift-detection):
+
+| Value | Meaning |
+| --- | --- |
+| `match` | Implementation achieves the planned step. |
+| `drift` | Implementation differs from the plan in a material way. |
+| `missing` | Planned step not implemented. |
+| `extra` | Implemented change that was not in the plan. |
+
+Required body sections: `## Goal`, `## Plan vs Actual` (a table rendering `plan`/`actual` with an `Evidence` column), and — when any step is `drift`/`missing`/`extra` — a `## Drift Analysis` section explaining each, with risk and a recommendation. Optional: `## Decisions`, `## Risks`, `## Open Questions`, `## Next Steps`, `## Evidence`. The frontmatter `plan`/`actual` arrays are canonical for queries; the body table is the human view (same canonical-frontmatter rule as dependencies and tags).
+
+#### `memory-lesson`
+
+```yaml
+type: memory-lesson
+topic:            # required, short string — the subject
+observed:         # required, ISO-8601 date — when the lesson was learned
+related:          # optional, list of wikilinks
+evidence:         # optional, evidence array — sources grounding the problem/fix
+                  #   (see "Evidence linking" below)
+```
+
+The body of a memory-lesson spec has two required sections: `## Problem` and `## Fix`.
+
+#### `memory-decision`
+
+```yaml
+type: memory-decision
+topic:            # required, short string
+decided:          # required, ISO-8601 date
+deciders:         # required, list of strings
+supersedes:       # optional, wikilink to a prior decision
+evidence:         # optional, evidence array — sources grounding the rationale
+                  #   (see "Evidence linking" below)
+```
+
+The body has two required sections: `## Decision` and `## Rationale`. (An ADR is a heavier-weight decision; a `memory-decision` is the day-to-day choice that doesn't warrant an ADR but should still be persisted.)
+
+#### `memory-reference`
+
+```yaml
+type: memory-reference
+topic:            # required, short string
+url:              # optional, URL the reference points at
+evidence:         # optional, evidence array — additional grounded sources
+                  #   (see "Evidence linking" below)
+```
+
+Body is the brief context for why this reference matters.
+
+#### `memory-ui-pattern`
+
+```yaml
+type: memory-ui-pattern
+topic:            # required, short string — the pattern name/slug
+documented:       # required, ISO-8601 date — when the pattern was captured
+related:          # optional, list of wikilinks
+evidence:         # optional, evidence array
+```
+
+Reusable **console interaction and visual patterns** (keyboard ownership, two-layer highlights, drill-in between panes). Distinct from `memory-ux-principle` (cross-brand rules) and `memory-decision` (a one-time choice). Body sections: `## Pattern`, `## When to apply`, `## Rules`, `## Implementation` (file map + copy-paste shape). See rail-active-vs-keyboard-cursor.
+
+#### `memory-ux-principle`
+
+```yaml
+type: memory-ux-principle
+topic:            # required, short string — the principle name/slug
+documented:       # required, ISO-8601 date — when the principle was captured
+related:          # optional, list of wikilinks
+evidence:         # optional, evidence array
+```
+
+Cross-brand **interaction rules** (Apple HIG, Material, Linear, Nielsen) — product-agnostic **what/why**. Distinct from `memory-ui-pattern` (HeySpex **how**). Body sections: `## Principle`, `## When to apply`, `## Rules`, `## Related UI patterns`, `## Sources`. See toggle-current-state-semantics and ux-principles-vs-ui-patterns.
+
+#### `protocol`
+
+Part of the **Memory** layer (memory-protocols-subsection-of-memory). Epics/tasks that *implement* or *revise* a protocol stay in `epics/` / `tasks/`; only the finished operational doc is `type: protocol`.
+
+```yaml
+type: protocol
+scope:            # required, one of: session | project | vault | tool
+version:          # optional, semver-ish version of the protocol
+```
+
+Body describes the protocol with numbered steps.
+
+#### `review`
+
+Companion fill-in workspace for a parent spec at `status: in_review`. One review doc per parent spec; created by the agent at the moment of flipping the parent to `in_review`. The reviewer (human) walks acceptance criteria, reads the agent's session observations, scores memory candidates, and records pass/reopen. Naming: `HS-REV-<suffix>-<slug>.md` where `<suffix>` matches the parent's id 1:1 (`HS-76RX` → `HS-SK1L-REV-…`, `HS-KQ5O` → `HS-IDFV-REV-…`).
+
+```yaml
+type: review
+parent:           # required, single wikilink — the spec under review
+reviews:          # optional, single wikilink — same as parent (legacy alias retained for back-compat reads)
+                  # parent: is the canonical edge; reviews: is kept for older docs
+deliberation_record: # optional; Council session output for invocation #4 (review close-out)
+                     # ([[adr-0015-council-as-cross-cutting-capability]]). Schema lives under `draft`
+                     # §`deliberation_record` above. Attached when the human triggers council during
+                     # `/hs-review` close-out; never gates the human's pass/reopen decision.
+```
+
+Body has four required sections — the unified workspace:
+
+- `## Acceptance verification` — checkboxes mirroring the parent spec's acceptance criteria; reviewer ticks them during verification and adds inline deviation notes. For epic-level reviews, expand into a manual testing walkthrough (fast-fail commands, click-by-click steps, expected behavior the reviewer can follow top-to-bottom).
+- `## Reviewer notes` — free-form workspace. **The agent writes implementation observations here during the work session** (architecture choices, judgment calls, surprises, gotchas). The reviewer adds deviation/surprise notes during the testing pass. This prose is the raw material the close-out memory-extraction pass reads.
+- `## Memory candidates` — table of proposed lessons / decisions / UI patterns / references derived from the Reviewer notes. Each row scored against the four-axis rubric (non-derivability / reusability / surprise-cost / concreteness, 0–3 each, threshold ≥ 7/12) and **MUST include a "Conflict check" column** noting `New`, `Refines [[existing-memory]]`, or `Conflict [[existing-memory]]`. A `Conflict` row is a red flag and must be resolved before accepting. Owned by HS-35JN-REVD-TASK-review-doc-fill-in-template-and-memory-extraction.
+- `## Decision: close or reopen` — explicit pass/fail outcome with reasoning, plus a checkbox indicating whether to materialize accepted memory candidates.
+
+Cross-link from the parent spec: every parent spec at `in_review` MUST add a `## Review` section pointing to its companion: `Reviewer workspace for this spec lives at [[HS-REV-<suffix>-<slug>]] — pre-review checklist, manual verification steps, reviewer notes, and memory candidates extracted at close-out.`
+
+The console shows a "Review" button on cards only when the parent spec is `status: in_review` and an `HS-REV-<suffix>-*` companion exists (detection: `console/src/lib/vault.ts:155 extractSpecSuffix`). Once the parent moves to `closed`, the button disappears but the wikilink in the parent body remains.
+
+The four-section unified-workspace template and the close-out flow are specified in HS-35JN-REVD-TASK-review-doc-fill-in-template-and-memory-extraction and CLAUDE.md §Session Completion. The MCP tool that loads a review doc into agent context (`heyspex_review_on_deck` + `/hs-review`) is specified in HS-XRO1-RVDC-TASK-heyspex-review-on-deck-mcp-and-hs-review. The legacy `{basename}.review.md` sibling naming was migrated by `scripts/migrate-review-doc-naming.mjs` — do not use it for new docs.
+
+#### `business-positioning` / `business-pricing` / `business-marketing` / `business-model`
+
+Parallel layer to Memory for **business-side** knowledge: how the product is positioned, priced, marketed, and the business model itself. Like Memory, browsed in the console on its own surface (**Business**) with category filters.
+
+```yaml
+type: business-positioning  # or business-pricing | business-marketing | business-model
+topic:            # required, short string — the subject (e.g. "homepage-h1", "tier-table")
+status:           # universal status enum — draft | open | in_progress | in_review | closed | deferred
+                  #   `active` is allowed as a synonym for `open` on migrated docs.
+related:          # optional, list of wikilinks
+evidence:         # optional, evidence array — sources grounding the claim/decision
+```
+
+Body is free-form prose; the recommended shape is a one-line H1 frame, then sections that match the doc's purpose (e.g. **Decision** / **Why each word is load-bearing** for positioning; **Tier table** / **AI add-on** / **What this also unlocks** for pricing).
+
+Distinct from `memory-decision` — memory captures *how-we-work* decisions for agents/humans inside the project; business docs capture *what-we-sell-and-how* decisions for the outside world. A pricing change is a `business-pricing` doc; a "don't mock the database in tests" rule is a `memory-decision`.
+
+#### `capture`
+
+Concise core-intent capture **before** research (capture-guardrails). Replaces the legacy `type: idea` entity (renamed 2026-05-22 per HS-B2B8-DLQI-EPIC-capture-rename-migration-idea-to-capture, source rationale HS-ZKFN-1FXG-CAP-capture-as-universal-companion-verb-and-parent-term). Not a draft inbox item and not a research doc.
+
+```yaml
+type: capture
+kind:             # required, one of: idea | bug-fix | clip | reference | question | spec-import | feedback
+                  #   idea       → speculative concept worth exploring (default — migrated entries land here)
+                  #   bug-fix    → defect observation paired with proposed fix
+                  #   clip       → web/document excerpt saved verbatim for later use
+                  #   reference  → a pointer to an external resource worth keeping
+                  #   question   → an open question to revisit when more context lands
+                  #   spec-import→ an imported foreign doc (README / top-level project doc) landed as a RAW
+                  #               capture by the bulk spec-import feature ([[HS-8V8T-8SBG-EPIC-first-connect-rough-import]]);
+                  #               source doc in ## Source Material; carries source_repo/source_path for
+                  #               (repo, vault) idempotency; stays RAW for manual triage. The
+                  #               "pin → run feature pipeline" exit ([[HS-J7T5-VEW8-RES-import-specs-one-click-feature-pipeline]])
+                  #               is a deferred follow-on — NOT wired in this wave.
+                  #   feedback   → app feedback / bug report / product idea / support question captured through
+                  #               a deterministic (no-AI) intake channel ([[HS-KQEW-I5DV-EPIC-feedback-capture-type-deterministic]]);
+                  #               classified by `routeFeedback()` ([[HS-FUII-EI9R-TASK-deterministic-feedback-router-module-no]]) toward diagnose/research/
+                  #               answered, or stays `feedback` when unmatched. Optional structured fields below
+                  #               (declared alongside `source:` further down this block — see `example`/
+                  #               `user_story`/`situation`).
+example:          # optional, string — a concrete example/repro illustrating the feedback (e.g. steps to reproduce a bug).
+                  #   Only ever populated on `kind: feedback` captures; never forced, never required by the schema.
+user_story:       # optional, string — "as a user, I want to… so that…" framing for a feedback-sourced product idea.
+                  #   Same optionality as `example`.
+situation:        # optional, string — the situational context the user was in when the feedback arose.
+                  #   Same optionality as `example`.
+capture_status:   # required, one of: raw | expanded — default raw
+                  #   raw      → no Core Idea content yet (single textarea / quick capture)
+                  #   expanded → Core Idea / Concept / Details has been written (modal v3 or agent rewrite)
+                  #   Flips raw → expanded automatically when an agent writes to core_idea,
+                  #   concept, or agent_expansion via executeUpdateCapture (vendor/heyspex-mcp).
+                  #   Console save-time linter force-corrects raw → expanded when `# Core Idea`
+                  #   body has content. See [[HS-BDDT-Q1B7-EPIC-idea-capture-modal-v3-single-textbox-cle]].
+promoted_to:      # binary: null (not promoted) or "[[HS-RES-<suffix>-<slug>]]" (promoted to research).
+                  #   Records the FIRST research doc this capture was promoted into; not the full set.
+                  #   For the M:N "every research doc this capture informs" view, see `informs_research:`.
+informs_research: # optional, list of wikilinks to HS-RES-* — every research doc this capture informs (M:N).
+                  #   Reverse of `research.sources_captures:`. Distinct from `promoted_to:` (binary
+                  #   first-promotion pointer); a capture may appear in multiple research docs over time.
+                  #   Bidirectional consistency enforced by `scripts/validate-vault-ids.mjs`. See §Provenance edges.
+source:           # optional capture channel (console, cli, companion, agent, …). On `kind: feedback` captures this
+                  #   also doubles as the free-text originating-channel/page-context signal `routeFeedback()`
+                  #   reads ([[HS-FUII-EI9R-TASK-deterministic-feedback-router-module-no]]) — still optional, never forced.
+related:          # optional wikilinks
+legacy_idea_id:   # optional, string — original HS-IDEA-* id for migrated entries (archaeology)
+```
+
+`promoted_to` is the **single binary promotion field** (HS-KQ5O-IDFV-EPIC-unified-idea-workflow-v2 / HS-QOAC-IDFL-RES-unified-idea-workflow-v2). `research_stage` was removed 2026-05-22; intermediate "promoted-but-research-not-written-yet" state lives in `.heyspex/research-focus.yaml`, not in the spec.
+
+`kind:` is the taxonomy field locked in by HS-B2B8-DLQI-EPIC-capture-rename-migration-idea-to-capture Milestone A. Migration of pre-2026-05-22 `type: idea` entries set `kind: idea` for every record; new captures pick the kind at creation time. The enum was extended from 5 to 6 values on 2026-07-10 — `spec-import` added as the **import-origin** kind for the bulk spec-import feature (HS-8V8T-8SBG-EPIC-first-connect-rough-import / HS-ROIU-9P4B-EPIC-import-preview-and-confirm, grounding HS-J7T5-VEW8-RES-import-specs-one-click-feature-pipeline). `spec-import` was added as a documentation/protocol convention only, not to the hard validator enum — `scripts/validate-vault-schema` (`schemas/heyspex-frontmatter.schema.json`) only required that a capture carry a `kind:` and a `capture_status:`, so `spec-import` slipped past AJV. `feedback` (7th value, HS-KQEW-I5DV-EPIC-feedback-capture-type-deterministic / HS-PUK1-48ZZ-TASK-add-feedback-capture-kind-optional) was added to BOTH the doc above and the hard AJV `kind` enum in `schemas/heyspex-frontmatter.schema.json` — a `kind: feedback` capture passes `scripts/validate-vault-schema.mjs` the same way the original five values do. Further consolidation (getting `spec-import` onto the hard enum too) is still deferred.
+
+Body **must** use four named sections — `# Core Idea` / `## Notes` (verbatim human words inside `"quotes"`) / `## Concept` (AI brief summary, ≤1200 chars hard / ≤800 soft) / `<details>Details</details>` (AI synthesis / deep dive, collapsed by default). Core Idea ≤280 chars soft / ≤500 hard. (The body section names retain the legacy "Idea" / "Notes" / "Concept" / "Details" wording even for captures whose `kind:` is not `idea`; the headings are a fixed scaffold, not a taxonomy field — agents and humans use the same four-section shape for every kind.) Legacy `# Core idea` / `## Notes` / `<details>Expanded idea (agent)</details>` is read back-compat during the deprecation window; writes always emit v2. AI may write to any section but: (a) never alters words inside a quote, (b) `## Notes` format-wrap is confirm-free, (c) `# Core Idea` / `## Concept` / `## Details` writes require user confirm. Agents must not add research sections (Executive Summary, Findings, Sources) to capture files — only the separate research doc after `/hs-res` (capture-guardrails).
+
+#### `research`
+
+Research is **evergreen** per the lifecycle-class taxonomy above and the canonical decision research-is-evergreen. `status: open` is the resting state for the doc's entire life — there are no `in_review` or `closed` transitions. Lineage to downstream artifacts is recorded through the relational fields below (`enhances:`, `spawned_epics:`, `bound_epic:`, `incorporated_into:`, `superseded_by:`), **never** through a status flip.
+
+```yaml
+type: research
+research_type:    # REQUIRED, enum — the declared purpose of this research doc, set at creation
+                  #   ([[HS-45YJ-120I-EPIC-research-type-field-the-declared-purpose]]). Coherent with the
+                  #   capture `kind:` vocabulary (`idea | bug-fix | clip | reference | question`) one
+                  #   level up the lifecycle, but not identical — research_type describes what the
+                  #   research is FOR, not what kind of capture seeded it. Five values:
+                  #     new-feature  — grounds a not-yet-built capability or product surface
+                  #     enhancement  — improves or extends something already shipped
+                  #     diagnose     — investigates a bug, defect, or quality problem
+                  #     code-audit   — reviews existing code/architecture with no specific bug in hand
+                  #     reference    — captures external/background knowledge for reuse (the default)
+                  #   Enforced by `schemas/heyspex-frontmatter.schema.json`. Missing on a pre-existing
+                  #   doc is a WARNING during the grace window (`RESEARCH_TYPE_GRACE_END` in
+                  #   `spex-console/src/lib/indexer/vault-rules.mjs`, mirroring `EPIC_PILLAR_GRACE_END`),
+                  #   then a hard error. Deterministic kind→research_type suggestion is out of scope
+                  #   here — owned by [[HS-6CFV-MVC1-EPIC-deterministic-type-assist-suggest-resear]].
+scope:            # optional, enum — how broad a search context this research was run at:
+                  #     internal — specs/, memories, ADRs only
+                  #     codebase — the repo (console/, vendor/, scripts/, etc.)
+                  #     external — web search
+                  #     all      — vault + codebase + web
+                  #   Default "internal" when omitted. This is a CONSISTENCY fix, not a new
+                  #   requirement — scope is NOT required and has no grace window
+                  #   ([[HS-NGD1-TASK-consolidate-and-fix-the-research-scope-field]]). Written the
+                  #   same way (same enum, same default) by `heyspex_save_research`,
+                  #   `heyspex_promote_capture`, and `heyspex_complete_research`. Validated as a
+                  #   string enum by `schemas/heyspex-frontmatter.schema.json` (distinct from the
+                  #   unrelated freetext `scope:` on `type: protocol`).
+enhances:         # REQUIRED when set — bidirectional consistency rule. If `enhances:` exists, the
+                  #   target milestone MUST list this research in `informed_by:` (see §Provenance edges).
+                  #   Single wikilink to the HS-MIL-* this research enhances. Not an array (M:1 rule).
+                  #   Open research may omit during exploration; the validator enforces bidirectional
+                  #   consistency whenever the field IS set. A research doc that spans multiple
+                  #   milestones must be split first ([[HS-TQQS-GTH9-TASK-hs-split-research-mcp-tool]]).
+                  #   NOTE: `scripts/validate-vault-ids.mjs` still gates on the legacy
+                  #   `status: closed` framing — validator catch-up to this "when set" framing is on
+                  #   the deferred list in [[research-is-evergreen]].
+sources_captures: # optional, list of wikilinks to HS-CAP-* — captures this research aggregates (M:N).
+                  #   Reverse of `capture.informs_research:`. Bidirectional consistency enforced.
+spawned_epics:    # optional, list of wikilinks to HS-EPIC-* — epics this research spawned (1:N).
+                  #   Reverse of `epic.derived_from:`.
+enhances_epics:   # optional, list of wikilinks to HS-EPIC-* — already-existing epics this research
+                  #   augmented (M:N, rare). One-sided in v1 — no reverse field on epic.
+produces_diagnose: # optional, list of wikilinks to HS-DIAG-* — bugs found during this research and
+                  #   promoted to a diagnose (1:N, mirrors `spawned_epics`). Reverse of
+                  #   `diagnose.derived_from:`. Written by `heyspex_promote_research_to_diagnose`
+                  #   ([[HS-W5VP-MSHY-TASK-research-diagnose-link-send-bugs-to-the]]); reuses the existing
+                  #   diagnose machinery — see [[resolution-diagnose-workflow]].
+split_into:       # optional, list of wikilinks — on the original (archive) research when split;
+                  #   names the child research docs that carry forward.
+split_from:       # optional, single wikilink — on a research created by splitting from an ancestor;
+                  #   mirror of `split_into:` on the ancestor.
+source_capture:   # optional wikilink to HS-CAP-* — legacy single-capture seed pointer; retained for
+                  #   read-side back-compat. New research uses `sources_captures:` (M:N) as canonical.
+planning_flow:    # optional until flow filed; then wikilink to HS-FLOW-*
+bound_epic:       # optional; set when epic filed — locks findings to append-only ([[planning-flow-research-epic-lifecycle]])
+forked_from:      # optional, wikilink — source HS-RES when forked for a new epic
+```
+
+Body is the research note. After `bound_epic:` is set, findings sections are append-only; new epic scope uses `## Scope for <epic name>` addendum sections.
+
+##### Code-audit findings table (`research_type: code-audit`)
+
+A `research_type: code-audit` doc's body **must** carry a findings table — the authored standard for "reviewed the code, found N things, here's what happens to each" (HS-7D0I-WL88-TASK-code-audit-research-type-with-a-defined). Four columns, in this order:
+
+| Finding | Severity | Action (diagnose\|task\|reference) | Exit (open\|closed) |
+| --- | --- | --- | --- |
+| One-line description of what was found | freetext (e.g. high/med/low) | `diagnose` \| `task` \| `reference` | `open` \| `closed` |
+
+Every row's `Action` maps to exactly one of three defined exits — no fourth "just leave it" option:
+
+- **`diagnose`** — a real bug. Promote it with the existing `heyspex_promote_research_to_diagnose` tool (HS-W5VP-MSHY-TASK-research-diagnose-link-send-bugs-to-the), which writes `research.produces_diagnose:` / `diagnose.derived_from:` (see §Provenance edges). Not new machinery — reuse it.
+- **`task`** — a cleanup/follow-up with no bug attached. File a task and set its `discovered_from: [[HS-RES-…]]` back to this research doc (see `task.discovered_from` above and §Dependencies "Discovered-from").
+- **`reference`** — non-actionable; the row itself IS the exit. Set `Exit: closed` directly, no further linkage required.
+
+**Enforcement** (`spex-console/src/lib/indexer/vault-rules.mjs`):
+
+- `CODE_AUDIT_FINDINGS_MALFORMED` — no findings table, or one that doesn't match the 4-column header shape, or a data row with an unrecognized `Action`/`Exit` value. Warning during the `CODE_AUDIT_GRACE_END` grace window (mirrors `RESEARCH_TYPE_GRACE_END`'s pattern — pre-existing code-audit docs like `HS-ZHAB-RES-doc-authoring-contract-audit-required-st` predate this format and are exempt while the window is open), then a hard error.
+- `CODE_AUDIT_FINDINGS_OPEN_ON_CLOSE` — the **closure gate**: a code-audit doc at `status: closed` or `review_pending` with any finding row whose `Exit` is `open`. Warning during the same grace window, then error — blocks closing a code-audit doc until every finding has exited.
+
+#### `planning-flow`
+
+Orchestration artifact for epic filing (planning-flow-research-epic-lifecycle). Body contains a `## Planning flow` section with fenced `mermaid` (semantic source for canvas projection per spec-diagram-design-vs-as-built-canvas).
+
+```yaml
+type: planning-flow
+research:         # required, wikilink to HS-RES-*
+decisions:        # optional, list of wikilinks — memory-decision or adr
+epic:             # optional until epic filed; then wikilink to HS-EPIC-*
+has_diagram:      # required, true — indexes canvas bridge + Shipped gallery when closed
+related:          # optional, wikilinks to tasks and supporting specs
+```
+
+#### `roadmap`
+
+```yaml
+type: roadmap
+roadmap_manifest:   # required, machine-readable phase index (see below)
+related_roadmaps:   # optional, wikilinks to other HS-ROADMAP-* specs
+```
+
+`roadmap_manifest` shape (indexer validates; agents request via `--compact`):
+
+```yaml
+roadmap_manifest:
+  version: 1
+  phases:
+    - id: M2                    # short stable id
+      name: Indexer MVP
+      tasks: [HS-V3YS, HS-1BML]   # HS-NNNN or HS-EPIC-NNNN ids
+  horizon:                      # may not ship — priority-4 / tag:horizon backlog
+    - HS-WYHZ
+  initiatives:                  # optional links to other roadmap docs
+    - HS-ROADMAP-VOICE-CHROME
+```
+
+Body is the human narrative (goals, exit criteria, risks). **Do not duplicate** the task list in prose without mirroring ids in `roadmap_manifest` — the manifest is the console/CLI source of truth for ordering.
+
+Horizon items use native `HS-NNNN` ids (or wikilinks to `future-considerations/` research until promoted). No separate FC id namespace (adr-0012-roadmap-storage).
+
+#### `draft`
+
+```yaml
+type: draft
+source:           # optional, where this draft came from (URL, "phone capture", "screenshot", etc.)
+captured_at:      # required, ISO-8601 datetime
+source_intent_hash: # optional but required on Agent ingest; SHA-256 of canonical capture blob ([[plan-ingest-review-roadmap-workflow]])
+source_intent:    # optional verbatim excerpt (≤2 KB) of human inputs at capture time
+agent_output_hash: # optional; SHA-256 of structured Agent preview at Save-to-drafts
+review_stage:     # optional, enum: inbox | deliberating | staging | review | promoted | rejected
+council_requested: # optional bool | null — per-submit override; null = apply deliberation.triggers policy ([[council-opt-in-pre-review-conditioning]])
+triage_record:    # optional; scout pre-pass ([[council-triage-scout-optional-llm]], [[review-inbox-workshop-scout-overview]])
+deliberation_record: # optional; Gate 0 output ([[ai-deliberation-gate]]) — append-only runs
+suggestions:      # optional; staged Gate A records ([[HS-EU98-GCGE-TASK-staged-draft-suggestion-schema]]) — omit when empty
+review_record:    # optional; Gate A commit audit — who/when/per-suggestion outcomes
+ingest_mode:      # optional, enum: manual | agent_llm — default manual when omitted
+capture_scope:    # optional, enum: selection | full — did a highlight scope the body? (HS-M54O); absent ⇒ full
+purpose:          # optional free string — the user's stated "why" for capturing (HS-7S40)
+context_blocks:   # optional list of { source: typed | voice, text, at: ISO-8601 } — enrichment
+                  # added on the intent card (HS-JQ7O/0077), each bound to this draft's trace_id.
+                  # Append-only within a trace_id; ordered by `at`. Absent ⇒ no extra context.
+llm_route:        # optional, required when ingest_mode is agent_llm — builder-selected route from console picker:
+                  # chatgpt | gemini | claude | auto | ... (enum grows with integrations; must stay in sync with UI labels)
+llm_resolved_at: # optional, ISO-8601 datetime when ingest_mode agent_llm — when the routed model finished
+resolved_model:  # optional free string or structured id — actual provider/model id after routing (meaningful when llm_route: auto or when aliases map to concrete models)
+submission_kind:  # optional, enum: external_media | refined_intent — Gate 0 epistemic mode ([[companion-external-media-vs-refined-intent-council]]); companion defaults external_media
+capture_channel:  # optional, enum: manual_ui | cli | voice | extension | companion | ...
+companion_dialogue: # optional append-only [{ role: user|assistant, text, at }] — pre-send chat about capture ([[HS-67TW-2966-TASK-companion-pre-council-context-dialogue]]); omit when empty
+capture_group_id:  # optional string — shared id linking multiple captures made in one multi-capture
+                   # companion session; drafts sharing this id render as a connected set on the
+                   # Captures surface, ordered by capture_group_seq. Distinct from capture_bundle_id
+                   # below (one composite draft with multiple sources) — this links multiple SEPARATE
+                   # draft files. Omit for standalone single captures.
+capture_group_seq: # optional positive integer — 1-based position within capture_group_id's group.
+                   # Only meaningful when capture_group_id is set.
+capture_bundle_id: # optional UUID — companion-local bundle id when submitted from Capture inbox ([[companion-capture-inbox-and-bundles]])
+source_set:       # optional — multi-source bundle; list of members, each with { url | file_path, title, member_trace_id, member_note, file_size?, file_type? }
+                  # For web captures: url (required), title, member_trace_id, member_note ([[HS-D1YU-OVFO-TASK-bundle-submit-composite-draft-source-set]])
+                  # For file captures: file_path (required), title (filename), file_size, file_type, member_trace_id, member_note ([[HS-5FI0-0036-EPIC-file-system-selection-voice-capture]])
+                  # Omit for single-source captures
+wake_used:        # optional bool — companion wake phrase invoked (vs shortcut-only capture)
+foreground_app:   # optional string — OS-visible focused app title/name at capture time
+spoken_command_tail: # optional sanitized transcript excerpt when capture_channel includes voice (see [[uc-voice-ingest-hey-spex]])
+shortcut_binding_id: # optional stable identifier for whichever hotkey initiated capture
+voice_companion_semver: # optional — installed companion semantic version emitting the draft
+pointer_screen_x: # optional — mouse pointer X in screen px, sampled once at ingest trigger
+pointer_screen_y: # mouse pointer Y (screen px)
+pointer_dpi_scale:
+pointer_sampled_at: # ISO-8601
+last_click_screen_x:
+last_click_screen_y:
+last_click_at:
+spatial_hint_ttl_ms:
+chrome_viewport_ratio_x:
+chrome_viewport_ratio_y:
+pointer_dom_hint: # optional heuristic from Chrome elementFromPoint; non-authoritative
+
+# File capture provenance (when source_type: local_file) — [[HS-5FI0-0036-EPIC-file-system-selection-voice-capture]]
+source_type:      # optional enum: local_file | url — discriminator; url is default/implicit for browser captures
+file_path:        # optional string — absolute path (single file or root folder); present when source_type: local_file
+file_size:        # optional int — file size in bytes
+file_type:        # optional string — MIME type or file extension
+file_modified_at: # optional ISO-8601 — file mtime at capture
+folder_depth:     # optional int — recursion depth when folder captured
+folder_file_count: # optional int — total files in folder/zip capture
+zip_extracted:    # optional bool — true if zip was extracted to temp for ingestion
+zip_source_path:  # optional string — original zip path when zip_extracted: true
+sensitive_files_included: # optional list of { path, pattern_matched, user_confirmed_at } — audit when user overrode sensitive file warning
+```
+
+Body is the ingested content; triage promotes a draft into a task, memory, or research file by editing the frontmatter `type:` and moving the file.
+
+Agent-assisted drafts **should** end the markdown body with a short human-readable provenance line so readers skimming raw files see how the draft was produced; **frontmatter carries the authoritative fields.**
+
+Example footer (console-rendered; values must mirror frontmatter):
+
+```markdown
+
+---
+
+_Ingest provenance:_ route `claude` → resolved `anthropic/claude-3-7-sonnet` · _Captured:_ 2026-05-16T12:00:00Z
+```
+
+See uc-ingest-anywhere §Console toggle: Manual vs Agent ingest, HS-DOC-architecture-foundations §What it exposes (API), companion capture + optional spatial hints in uc-voice-ingest-hey-spex §Persistence / §Spatial pointers when `capture_channel: voice`.
+
+**`deliberation_record`** (when present):
+
+Permitted on `draft`, `task`, `epic`, and `review` types — Council session output, append-only across all four ai-deliberation-gate invocation points per adr-0015-council-as-cross-cutting-capability. The host spec retains its existing type; the record is purely advisory and never gates anything (human disposition stays in Gates A/B/C per heyspex-north-star Principle 3).
+
+```yaml
+deliberation_record:
+  latest_run_id: "<uuid>"
+  runs:
+    - run_id: "<uuid>"
+      at: "<ISO-8601>"
+      invocation_point: pre_review | canvas_live | promoted_recheck | review_close
+                                                  # which of the four Council invocation points produced this run
+                                                  # (per [[adr-0015-council-as-cross-cutting-capability]])
+      submission_lens: refined_intent | external_media | promoted_spec_recheck
+                                                  # role objective discriminator — lifts the draft body's
+                                                  # `submission_kind` to the run so promoted-spec contexts carry it
+      parent_run_id: "<uuid>" | null              # loop-suppression input; null on first run for a spec
+      test_preset: free | cheap | production | null  # when [[ai-deliberation-gate]] test_mode was active
+      api_calls: 4                                # optional audit — varies by invocation: 1 (canvas_live),
+                                                  # 3 (review_close, skip rebuttal), 4 (pre_review skip_rebuttal),
+                                                  # 7 (full pre_review or promoted_recheck)
+      roles:
+        - id: tech_lead | program_lead | ux_lead
+          provider: "<string>"
+          model: "<string>"
+          position:
+            disposition: schedule_now | schedule_later | horizon | defer | deprecated | merge | reject | split
+            priority: 0-4
+            roadmap_phase: "<id>"
+            merge_into: "[[HS-NNNN]]"
+            north_star_alignment: aligned | tension | conflict
+            arguments: ["<bullet>"]
+      facilitator:                                # absent on `canvas_live` (single-role) and on
+                                                  # `review_close` when skip_rebuttal is set
+        recommended_disposition: "<enum>"
+        confidence: 0.0-1.0
+        disagreements: ["<role_a vs role_b on topic>"]
+      north_star_conflict:   # present when ≥2 roles report conflict
+        agreed: true
+        summary: "<string>"
+        path_a_change_l1: { summary, typical: false }
+        path_b_reshape_plan: { summary, suggested_edits: [] }
+```
+
+**Storage bound:** `runs[]` is capped at the last 10 entries in frontmatter; older runs archive to `specs/.deliberation-archive/<spec-id>.yaml` (gitignored, audit-only) per adr-0015-council-as-cross-cutting-capability §Consequences.
+
+**`triage_record`** (when present; scout only — not council):
+
+```yaml
+triage_record:
+  at: "<ISO-8601>"
+  model: "<slug>"
+  title_line: "<≤80 chars>"
+  memory_jogger: "<2-3 sentences>"
+  review_category: feature_request | external_media | brainstorm | research | bug | mixed | unclear
+  recommend_council: true | false
+  confidence: 0.0-1.0
+  rationale: "<string>"
+  suggested_actions:
+    - id: run_council | add_context | gate_a_review | defer | promote_quick | discard
+      label: "<string>"
+      primary: true
+  quick_tags: ["<optional>"]
+```
+
+**`suggestions`** (when present; omit block entirely when empty — pre-HS-GCGE-TASK drafts unchanged):
+
+```yaml
+suggestions:
+  - id: "<stable-uuid-within-draft>"
+    kind: roadmap | priority | child_task | consideration
+    payload: {}          # kind-specific proposed fields (epic stub, priority, etc.)
+    rationale: "<one line>"
+    disposition: pending | accepted | edited | declined
+    edited_payload: {}   # optional; present when disposition: edited
+    provenance:
+      llm_route: "<enum>"
+      resolved_model: "<provider/model>"
+      at: "<ISO-8601>"
+```
+
+**`review_record`** (written on Gate A staging commit):
+
+```yaml
+review_record:
+  at: "<ISO-8601>"
+  by: pwher
+  outcomes:
+    - suggestion_id: "<uuid>"
+      disposition: accepted | edited | declined
+      note: "<optional>"
+```
+
+#### `daily`
+
+```yaml
+type: daily
+date:             # required, ISO-8601 date
+```
+
+Body is free-form notes for the day.
+
+## Body structure conventions
+
+Beyond the type-specific required sections noted above, all specs follow these structural conventions:
+
+- The first heading is `# <Name>` (the human-readable title), matching `name:` in frontmatter.
+- Optional first block: a single `> [!note]` / `> [!important]` callout if there's a one-line framing message.
+- Sections use `##` headings. Sub-sections `###`.
+- A spec ends with `## Related specs` (optional) and `## Change log` (required for L1, L2, L3, ADR, and protocol; optional but encouraged elsewhere).
+
+### Recommended sections for long-lived specs
+
+Two SCEH-Pattern conventions (HS-U88E-SP34-EPIC-sceh-patterns-3-and-4-markdown-conventions) define optional `##` sections useful on specs that accumulate work across many sessions:
+
+| Section | Protocol | Use when | Placement |
+|---|---|---|---|
+| `## Session Boundaries` | session-boundary-marker | Multi-session epics, milestones, and HS-REV review docs benefit from a five-column session-by-session trail (`session_id` / `agent` / `started` / `ended` / `summary`). | Immediately above `## Change log`. |
+| `## Conflict Resolution` | conflict-resolution-section | Two or more sessions left contradictory opinions in the body, change log, or HS-REV companions and a reviewer has had to pick. Three-row table (opinions + bold `**resolution**`) with optional memory-extraction routing into `memory-decision` specs. | Below `## Session Boundaries` if present, above `## Change log`. |
+
+Both are **recommended** — opt-in per spec, not enforced by the wikilink validator. They are content commentary about the spec; control-plane runtime state (claim/focus/spec events, handoff context) stays in Neon (control-plane-belongs-in-neon).
+
+## Dependencies
+
+HeySpex inherits beads' four dependency types and adds a normalization choice: dependencies are expressed **both** as structured frontmatter arrays **and** as inline wikilinks in body prose. The frontmatter is canonical for queries; the body wikilinks are for reading flow.
+
+| Type | Frontmatter field | Inverse field | Semantics |
+| --- | --- | --- | --- |
+| **Blocks** | `blocks: [[...]]` | `blocked_by: [[...]]` | Hard. A blocked task is not ready until all `blocked_by` resolve. |
+| **Related** | `related: [[...]]` | `related:` (symmetric) | Soft. Navigational only; no readiness implication. |
+| **Parent-child** | `children: [[...]]` | `parent: [[...]]` | Hierarchical. Children roll up to parent for "completion of parent" calculations. |
+| **Discovered-from** | `discovered_from: [[...]]` | `discovered:` (list) | Provenance. "This task was born while working on X." |
+| **Iterates-on** | `iterates_on: [[...]]` | `iteratedBy:` (computed) | Re-attempt. "This initiative re-attempts an outcome the target shipped but did not fully deliver." No readiness implication; neither doc is demoted. See §Iteration lineage below. |
+
+Rules:
+
+- The indexer maintains both sides of every edge; the Builder only needs to write one side, and the console fills the other on save. (Implementation detail; specified in HS-DOC-architecture-foundations.)
+- The indexer rejects edges that form a cycle in the `blocks` graph or the `parent`/`children` graph.
+- `related` edges are symmetric; the indexer enforces symmetry on save.
+- A task without a `parent:` and not referenced as a child by anyone is treated as a top-level task.
+- `discovered_from` is single-valued; if a task has multiple origins, model the additional ones as `related:`.
+
+## Provenance edges (capture → research → milestone)
+
+The promotion lifecycle — capture observation → research synthesis → milestone commitment — has cross-type provenance edges with strict cardinalities. Ratified by HS-OFR5-M2J3-EPIC-introduce-milestones-as-highest-entity §Architecture; enforced by `scripts/validate-vault-ids.mjs` (HS-HQRM-YJX6-TASK-research-enhances-exactly-one-milestone-validator-and-bidirectional-linkage).
+
+| Edge | Cardinality | Forward field | Reverse field |
+| --- | --- | --- | --- |
+| **Capture → Research** | M:N | `capture.informs_research: [[[HS-RES-…]]]` | `research.sources_captures: [[[HS-CAP-…]]]` |
+| **Research → Milestone** | **M:1** (strict) | `research.enhances: [[HS-MIL-…]]` (single, not array) | `milestone.informed_by: [[[HS-RES-…]]]` |
+| **Research → Epic (spawned)** | 1:N | `research.spawned_epics: [[[HS-EPIC-…]]]` | `epic.derived_from: [[HS-RES-…]]` (single) |
+| **Research → Epic (augmented)** | M:N | `research.enhances_epics: [[[HS-EPIC-…]]]` | (one-sided — no reverse field on epic in v1) |
+| **Research → Diagnose (bug found)** | 1:N | `research.produces_diagnose: [[[HS-DIAG-…]]]` | `diagnose.derived_from: [[HS-RES-…]]` (single) |
+
+Rules:
+
+- **Research is M:1 to milestone — strict.** A single research doc that spans multiple milestones must be split before promotion. The split-action protocol is owned by HS-TQQS-GTH9-TASK-hs-split-research-mcp-tool; the original research stays as the audit archive with `status: closed` and `split_into: [[HS-RES-A]], [[HS-RES-B]]`, while N child research docs each carry `split_from: [[HS-RES-original]]` and their own `enhances:` target.
+- **Open research may omit `enhances:`.** The validator only requires it on `status: closed` research (the promotion-time gate); during exploration the target milestone can still be ambiguous.
+- **`enhances:` is single-valued.** Not an array — the validator rejects array form and points the author at the split flow.
+- **Bidirectional consistency is enforced.** If research X has `enhances: Y`, milestone Y MUST list X in `informed_by:`. If capture C has `informs_research: [X, Y]`, both X.sources_captures and Y.sources_captures MUST include C. The validator surfaces one-sided drift as a hard error on each side.
+- **Captures M:N research is intentional.** A single capture may inform multiple research docs over time (e.g. a "voice capture works" observation that lands in both companion research and console-voice research). The first promotion writes `capture.promoted_to:` (binary pointer); subsequent re-uses extend `capture.informs_research:` without touching `promoted_to:`.
+- **`spawned_epics` vs `enhances_epics`.** `spawned_epics` is the canonical 1:N edge — epics this research *created*, mirrored as `epic.derived_from:` on each child. `enhances_epics` is the rarer case where research *augmented* an already-existing epic; it's a one-sided list with no reverse field in v1.
+- **`produces_diagnose` mirrors `spawned_epics`.** A research investigation may surface a bug, which is promoted into a first-class `HS-DIAG-*` (not new machinery — the existing diagnose entity per resolution-diagnose-workflow). `research.produces_diagnose:` is the canonical 1:N edge, mirrored as `diagnose.derived_from:` on each child, written by `heyspex_promote_research_to_diagnose`. This is the research-side sibling of the capture-side exit `heyspex_promote_capture_to_diagnose` (which writes `diagnose.promoted_from:` ⇔ `capture.promoted_to:`/`informs_diagnose:` instead).
+
+Promotion-action contract (`/hs-promote-research`, HS-2ERO-QQHP-TASK-hs-promote-research-mcp-tool): writes all four sides (research.enhances, research.spawned_epics, milestone.informed_by, epic.derived_from) atomically. The validator is the safety net for hand-edited drift, not the primary write path.
+
+## Iteration lineage (round-to-round re-attempts)
+
+The **third doc-to-doc relation tier**, alongside supersession (terminal, whole-doc) and amends (partial, non-terminal) — ratified via HS-3TZX-T9T6-RES-iteration-loop-lineage-and-capture Part A, built by HS-O97P-T9T6-EPIC-iteration-loop-lineage-relation-tier. It expresses what neither existing tier can: *work shipped and closed, the outcome fell short of the goal, and a NEW family re-attempts the SAME goal.* Supersession would falsify round 1 (it wasn't wrong — it shipped, its review is accurate history); amends would misdescribe it (round 2 contradicts nothing).
+
+### Fields
+
+```yaml
+iterates_on:      # optional, YAML list of wikilinks — lives ONLY on the NEWER doc (one-edit-on-source,
+                  #   same principle as amends). Semantics: "this initiative re-attempts an outcome the
+                  #   target initiative shipped but did not fully deliver." Typically carried by the
+                  #   round-2 research doc pointing at the round-1 research doc — the research chain is
+                  #   the spine (research is evergreen, so the root research id is the durable handle
+                  #   spanning every round; no new entity type).
+# iteratedBy      — COMPUTED reverse map (indexer/validator output, like amendedBy) — never written
+                  #   by hand into frontmatter.
+outcome:          # optional, on TRACKABLE docs only, set by the HUMAN REVIEWER at close — never
+                  #   inferred, never agent-set. Enum: met | partially-met | not-met. Lives ONLY on
+                  #   the closed doc (not echoed onto the round-2 doc; discovery goes through the
+                  #   iteratedBy reverse map).
+outcome_note:     # optional, one-line reviewer prose qualifying the verdict.
+```
+
+### Invariants
+
+- **Nothing is demoted.** Both docs stay `canonical: true`; round 1 keeps `status: closed`. `iterates_on:` is a lineage edge, not a supersession — demoting round 1 to `canonical: false` would falsify the record and hide shipped scope from round 2's breakdown.
+- **`outcome:` is the reviewer's judgment alone.** `status: closed` without an `outcome:` says only "shipped"; it must never be read as "goal met." The verdict is written at reviewer close (the one mutable-at-close moment), per [[session-close-protocol]].
+- **Distinct family keys are correct.** Round 2 is its own initiative with its own children and review, so it takes a new family key; `iterates_on:` is the cross-family edge that replaces the missing shared grep handle.
+
+### Required `## Related / lineage` section on promoted docs
+
+Every promoted doc's outline ends with a resolved-wikilink table (immediately before `## Change log`), authored at promote-time and gated by `heyspex_validate_linkage` (every row must resolve under `specs/`):
+
+```markdown
+## Related / lineage
+
+| Doc | Role |
+|---|---|
+| [[round-1-research]] | Iterates on |
+| [[HS-REV-...]] | Prior attempt's review |
+| [[HS-CAP-...]] | Feedback capture |
+```
+
+Role vocabulary: **Iterates on · Prior attempt's review · Feedback capture · Amends · Superseded by · Pillar · Spawned epics** (extend with prose roles when none fits — e.g. "Source capture", "Enhances").
+
+## Evidence linking
+
+> [!important] "Summaries with receipts"
+> Ratified by adr-0008-branch-brief-and-evidence-schema for HS-7KOO-0022-EPIC-continuity-layer-gaps. Every claim a memory or brief makes should be able to point at a verifiable source. Without evidence, a summary is unfalsifiable; with it, a reader can navigate from claim to proof.
+
+`evidence:` is an optional array on `branch-brief`, `memory-lesson`, `memory-decision`, `memory-reference`, `memory-ui-pattern`, and `task`. Each entry:
+
+```yaml
+evidence:
+  - type: commit          # required — one of the evidence types below
+    ref: "abc123"         # required — the reference, format per type
+    line: 42              # optional — line number (file/diff only)
+    description: "..."     # optional — what this evidence shows
+```
+
+Evidence types:
+
+| Type | `ref` format | Example |
+| --- | --- | --- |
+| `commit` | short or full SHA | `abc123`, `abc123def…` |
+| `file` | repo-relative path, optional `:line` | `src/foo.ts`, `src/foo.ts:42` |
+| `pr` | PR number | `#123` |
+| `diff` | `commit:path` | `abc123:src/pages/dashboard.tsx` |
+| `issue` | issue number | `#42` |
+| `note` | freeform text | `Builder confirmed via Slack 2026-05-15` |
+| `test` | test/gate identifier | `vitest:src/lib/continuity/plan-vs-actual.test.ts`, `tsc:noEmit` |
+
+> [!note] `test` added 2026-08-11 (receipt-on-ship, HS-XGG4-IU2S-EPIC-receipt-on-ship-plan-vs-actual-proof-at). Additive extension per adr-0008-branch-brief-and-evidence-schema §Consequences ("a future change to evidence types … is a normal entity-model edit"); lets Plan Receipts cite test/gate results as typed evidence.
+
+### Inline shorthand
+
+In body prose, evidence may be cited inline as `[evidence:<type>:<ref>]`:
+
+```markdown
+We chose Payment Elements over hosted checkout [evidence:commit:abc123]
+because it gives better customization [evidence:pr:#123].
+```
+
+The indexer harvests inline shorthand and the frontmatter `evidence:` array into the same evidence index; **frontmatter is canonical** for "what grounds this spec?" queries (same rule as `tags:` and dependency edges). Console rendering of evidence references (commit → diff view, file → file viewer at line, pr/issue → git host) is an implementation concern specified downstream, not part of this schema contract.
+
+## Delivery snapshot
+
+> [!note] User-persisted, not auto-maintained
+> See HS-WB81-RBJ8-TASK-spec-delivery-frontmatter-snapshot. The live source of truth for "which commits touched this spec" is always `git log -- <spec_path>`; the `delivery:` block is an *optional persisted snapshot* the Builder takes from the console's On Deck row so the vault carries its own delivery trail.
+
+`delivery:` is an **optional, cross-type** key. It exists only after the Builder has clicked "snapshot to spec" in the console's delivery dropdown. Shape:
+
+```yaml
+delivery:
+  snapshot_at: 2026-05-21T07:00:00-05:00   # ISO timestamp of when the snapshot was taken
+  commits:
+    - sha: 8648ad5e3f...                    # full SHA
+      short_sha: 8648ad5                    # 7-char SHA
+      branch: hs-mvp0520                    # primary branch (local before remote)
+      pushed: true                          # boolean — reachable from origin/*
+      at: 2026-05-21T05:14:32-05:00          # commit author time
+      author: pwher
+      message: "feat(console): per-spec delivery dropdown on On Deck child rows"
+```
+
+Rules:
+
+- One primary branch per row, not the full branch list (live view stays authoritative for fan-out).
+- `message` is the first commit-message line only; full commit bodies live in git, not the vault.
+- `delivery:` may be present on **any** spec type; treat it as a presentational artifact, not a dependency edge — the indexer does not crawl it.
+- A stale snapshot (live count ≠ snapshot count) is rendered as such in the console; the snapshot is never auto-refreshed.
+- Persisted by `PUT /api/specs/[id]/delivery`; no git hook or agent workflow rewrites it.
+
+## Wikilink resolution rules
+
+HeySpex uses Obsidian-compatible wikilinks: `[[target]]` or `[[target|display text]]`.
+
+Resolution algorithm:
+
+1. **Strip extension.** `[[foo]]`, `[[foo.md]]`, and `[[foo|Foo]]` all target the file basename `foo`.
+2. **Case-insensitive match.** The resolver compares lowercased basenames. `[[Foo]]` and `[[foo]]` resolve to the same file.
+3. **No path qualifier needed.** Folders are not part of the resolution. `[[entity-model]]` finds `specs/entity-model.md` regardless of where the linking spec lives. (Consistent with Obsidian's "default" link mode.)
+4. **Aliases.** If a spec's frontmatter has `aliases: [foo, bar]`, both `[[foo]]` and `[[bar]]` also resolve to that spec.
+5. **Forward references are valid.** A wikilink to a non-existent spec is not an error; it is a signal that the linked spec should be written. The indexer records forward references in a `forward_refs` view; the console shows them inline so the Builder can see what's pending.
+6. **Duplicate basenames are forbidden.** Two specs may not share a basename. The indexer rejects writes that would create a duplicate.
+7. **Filename is canonical; do not author id-form links.** The resolver also matches a link target against a spec's frontmatter `id:` (it tries id → basename → alias, in that order). This is a **tolerant fallback** so that hand-typed or legacy `[[HS-DEC-…]]`/`[[HS-TASK-…]]` links still resolve — it is **not** the form to write. Author every link by **filename basename** so the vault stays Obsidian-portable (Obsidian does not resolve by the `id:` field). For memory specs (decisions, lessons, references, ui-patterns) the file is slug-named while its `id` carries a type prefix, so `[[HS-DEC-foo]]` is the id form and `[[foo]]` is the canonical filename form — prefer the latter. The vault was swept to filename form on 2026-05-28 (`scripts/sweep-hs-dec-links-to-basename.mjs`).
+
+Display text:
+
+- `[[entity-model|the entity model]]` renders "the entity model" as a link to `entity-model.md`.
+- This is the same syntax Obsidian uses; HeySpex inherits it unchanged.
+
+## Tags
+
+Tags use the `tags:` array in frontmatter. They are flat strings, no nesting (no `#foo/bar` semantics in v1 beyond convention).
+
+Body-inline `#tag` syntax is allowed for compatibility with Obsidian users; the indexer harvests both frontmatter tags and body inline tags into the same index, but frontmatter is canonical for "is this spec tagged X?" queries.
+
+## Reserved frontmatter keys
+
+The following keys are reserved by HeySpex and must not be repurposed:
+
+- `id`, `name`, `type`, `status`, `priority`, `owner`, `created`, `updated`, `tags`, `related`, `aliases`
+- `blocks`, `blocked_by`, `parent`, `children`, `discovered_from`, `discovered`
+- `assignee`, `started_at`, `closed_at`, `close_reason`, `defer_until`
+- `evidence` (cross-type; see [Evidence linking](#evidence-linking))
+- `delivery` (cross-type; user-persisted git-log snapshot — see [Delivery snapshot](#delivery-snapshot))
+- `legacy_bd_id`, `legacy_dolt_commit`
+- Type-specific fields named above (including `branch-brief`'s `branch`, `goal`, `implements`, `plan`, `actual`, `risks`, `open_questions`, `next_steps`, `decisions`; `milestone`'s `epics`, `target_date`, `informed_by`; the `epic`'s `milestone` parent pointer and optional `derived_from`; `task`'s `split_of`, `split_index`, `handoff_id` (split lineage — envelope lives in body) and optional `affects_paths`; `research`'s `enhances`, `sources_captures`, `spawned_epics`, `enhances_epics`, `produces_diagnose`, `split_into`, `split_from`; `diagnose`'s optional `promoted_from` and `derived_from`; `capture`'s `informs_research`; the `agent` type's `role`, `model`, `allowed_tools`, `disallowed_tools`, `procedures`, `handoffs`, `guardrails`, `lane`, `color`, `owned_paths`, and `source_attribution` import-provenance object). Type-specific fields are additive and do **not** require an ADR (only a new *universal* reserved key does); `source_attribution` was added under HS-GMLJ-K3KR-TASK-lock-the-community-import-design-and-add; `owned_paths` / `affects_paths` under HS-ZMAQ-M15C-TASK-declare-owned-path-globs-on-agent-identi.
+- `reviews` (review type — back-compat alias for `parent:` pointing at the spec under review)
+
+Adding a new universal reserved key requires an ADR.
+
+## Validation
+
+The indexer (see HS-DOC-architecture-foundations §Indexer) runs frontmatter validation on every write:
+
+- All required fields present and of the expected type.
+- `id` matches the entity type's pattern.
+- `id` is unique across the vault.
+- `status` is in the enum.
+- All wikilinks in frontmatter resolve, or are tracked as forward references.
+- No cycles in `blocks` or `parent`.
+- No duplicate basenames.
+
+Validation failures are surfaced in the console and via `hs lint`. They do not block git writes (the vault is plain text and the Builder is trusted), but the indexer marks the affected spec as invalid until corrected.
+
+## Examples
+
+### Minimal task
+
+```markdown
+---
+id: HS-O3E0
+name: Fix console keyboard navigation
+type: task
+status: open
+priority: 2
+owner: pwher
+created: 2026-05-14
+updated: 2026-05-14
+kind: bug
+blocked_by:
+  - "[[HS-IS1A-TASK-SpexConsole-routing-rewrite]]"
+related:
+  - "[[HS-582Q-TASK-arrow-key-conflicts]]"
+tags: [console, ux, keyboard]
+---
+
+# Fix console keyboard navigation
+
+Arrow keys do not move focus between issues in the list view; only Tab works. Compare to Linear, where ↑/↓ navigates the list.
+
+## Acceptance
+
+- Up/Down arrow keys move focus between rows in `IssuesSurface`.
+- Enter on a focused row opens the detail pane.
+- No regression for input fields (arrow keys still move the caret inside text inputs).
+
+## Change log
+
+| Date | Author | Change |
+| --- | --- | --- |
+| 2026-05-14 | pwher | Created from drafts/triage. |
+```
+
+### Memory lesson
+
+```markdown
+---
+id: HS-LES-bd-process-leak
+name: bd CLI process leak
+type: memory-lesson
+status: open
+priority: 1
+owner: pwher
+created: 2026-05-14
+updated: 2026-05-14
+topic: bd-process-leak
+observed: 2026-05-14
+related:
+  - "[[HS-LES-dolt-embedded-windows]]"
+  - "[[adr-0006-replace-beads]]"
+tags: [bd, dolt, windows, process-leak]
+---
+
+# bd CLI process leak
+
+## Problem
+
+A single `bd create` issued the prior session sat alive consuming 107 GB working set, plus seven orphaned bd procs at ~67 MB each. RAM hit 80% of 128 GB.
+
+## Fix
+
+At session start, run `Get-Process bd | Sort WorkingSet -Desc` on Windows and kill any orphans before issuing new bd commands. Be wary of invoking `bd create` with `run_in_background` — bd does not always exit cleanly when the parent harness moves on.
+
+## Change log
+
+| Date | Author | Change |
+| --- | --- | --- |
+| 2026-05-14 | pwher | Migrated from bd memory `lessons/bd-process-leak`. |
+```
+
+## Open questions
+
+These are intentionally left for the Builder's confirmation in Phase 5 (migration), to avoid pre-committing the migration translation rules:
+
+1. **Resolved (2026-05-18):** Memory uses subfolders — `memory/lessons`, `memory/decisions`, `memory/references`, plus `protocols/` as a Memory subsection on disk (memory-protocols-subsection-of-memory). **2026-05-20:** added `memory/ui-patterns/` (`memory-ui-pattern`). **2026-05-21:** added `memory/ux-principles/` (`memory-ux-principle`). Console Memory surface: All / Lessons / Decisions / References / **UX Principles** / UI Patterns / Protocols.
+2. The id format for migrated tasks — `HS-NNNN-<slug>` with `legacy_bd_id` preserved. Confirm the slug source (proposal: from `title:` lowercased, truncated to ~40 chars, dash-separated).
+3. Whether to expose `body inline tags` (`#tag` inside prose) as queryable, or treat them as decorative-only. Proposal: queryable but frontmatter `tags:` wins on ties.
+4. Whether the `daily/` notes folder should exist at all in v1 (it's not in L1's use cases). Proposal: include it for Builder convenience; cost is one folder.
+
+## Related specs
+
+- heyspex-north-star — the L1 this entity model serves.
+- HS-DOC-architecture-foundations — the tech that implements the contract this document specifies.
+- uc-capture-intent — first-class typed capture and the phone-to-draft path; promotes drafts per §`draft` below.
+- uc-ingest-anywhere — Manual vs Agent ingest; drives optional `draft` LLM provenance fields and body footer conventions.
+- uc-voice-ingest-hey-spex — Hey Spex wake companion + shortcuts; optional `capture_channel: voice` fields above.
+- migration-from-bd — the L3 spec that uses the IDs/filenames defined here.
+- adr-0001-vault-format — the ADR that locks in markdown + YAML + wikilinks as the file format.
+- adr-0008-branch-brief-and-evidence-schema — the ADR that ratifies the `branch-brief` type and `evidence:` key.
+- adr-0012-roadmap-storage — `roadmap` type, `roadmap_manifest`, horizon backlog, ingest provenance fields.
+- plan-ingest-review-roadmap-workflow — default ingest → review → roadmap admission protocol.
+- ai-deliberation-gate — Gate 0 multi-model debate on drafts.
+- ingest-review-deliberation-roadmap-lifecycle — consolidated ingest/roadmap/council decision.
+- HS-ROADMAP-product-master — product phases + horizon manifest.
+- HS-7KOO-0022-EPIC-continuity-layer-gaps — the Continuity Layer epic these additions serve.
+- HS-BVZT-XBPJ-RES-bd-feature-inventory — the research spec that justifies each row of the schema.
+- memory-protocols-subsection-of-memory — Protocols are a Memory subsection in navigation; epics author protocols.
+
+## Change log
+
+| Date | Author | Change |
+| --- | --- | --- |
+| 2026-05-14 | pwher (with claude opus 4.7) | Initial draft. Derived the entity-type set from L1 use cases plus the bd inventory. Locked in four dependency types (matching bd) and Obsidian-compatible wikilink resolution. Folder layout uses subfolders per type for human navigation; resolution is folder-agnostic. |
+| 2026-05-16 | pwher | §`draft`: companion/voice + optional spatial cursor/click hints (uc-voice-ingest-hey-spex §Spatial pointers). |
+| 2026-05-16 | pwher (with claude opus 4.7) | Added `branch-brief` entity type (folder `branches/`, ID `HS-BB-<slug>`, plan/actual + drift enum) and the cross-type `evidence:` array with inline shorthand. Per adr-0008-branch-brief-and-evidence-schema; closes HS-7E41/0052/0053 of HS-7KOO-0022-EPIC-continuity-layer-gaps. |
+| 2026-05-17 | pwher | Added `roadmap` type + `roadmap_manifest`; `future-considerations/` layout; draft `source_intent_hash` / `review_stage`; task `roadmap_admission` / `ingest_draft`. Per adr-0012-roadmap-storage. |
+| 2026-05-17 | pwher | Draft `deliberation_record` (ai-deliberation-gate); task `close_reason` enum + `superseded_by`; archive = filter not folder. |
+| 2026-05-17 | pwher | Draft `suggestions:` + `review_record:` per HS-EU98-GCGE-TASK-staged-draft-suggestion-schema; omit-when-empty rule. |
+| 2026-05-17 | pwher | `submission_kind`, `companion_dialogue[]`; companion `capture_channel` per companion-external-media-vs-refined-intent-council. |
+| 2026-05-17 | pwher | `capture_bundle_id`, `source_set[]` for companion multi-article bundle submit (companion-capture-inbox-and-bundles, HS-D1YU-OVFO-TASK-bundle-submit-composite-draft-source-set). |
+| 2026-05-17 | pwher | `triage_record` scout schema for Review inbox workshop (review-inbox-workshop-scout-overview). |
+| 2026-05-18 | pwher (with claude opus 4.5) | Added `in_review` status to universal enum — human gate between agent work and closure (HS-YYEO-FLX9-TASK-review-column-human-gate-before-done). |
+| 2026-05-20 | pwher | `canvases/diagrams/` + `canvases/as-built/` for spec diagram dual-surface (spec-diagram-design-vs-as-built-canvas). |
+| 2026-05-20 | pwher | Added `specs/canvases/` for JSON Canvas design files per adr-0013-canvas-vault-format-and-obsidian-interop. |
+| 2026-05-20 | pwher | Task/epic ID formats: random alphanumeric suffix for new specs (vault-id-assignment-protocol); legacy `HS-NNNN` migration IDs retained. |
+| 2026-05-21 | pwher | Added `planning-flow` type (`specs/flows/`); research `bound_epic` / `planning_flow`; epic `research` / `planning_flow` requirements (planning-flow-research-epic-lifecycle). |
+| 2026-05-22 | pwher + Claude Opus 4.7 (1M) | `idea` schema: `research_stage` removed (single binary `promoted_to`); body shape v2 — `# Core Idea` / `## Notes` / `## Concept` (≤1200 chars) / `<details>Details</details>`. See HS-KQ5O-IDFV-EPIC-unified-idea-workflow-v2 / HS-QOAC-IDFL-RES-unified-idea-workflow-v2. |
+| 2026-05-22 | pwher + Claude Opus 4.7 (1M) | **Capture rename:** `type: idea` → `type: capture`; new required `kind:` field (idea / bug-fix / clip / reference / question); folder `specs/captures/` → `specs/captures/`; ID prefix `HS-IDEA-*` → `HS-CAP-*` (legacy preserved in `legacy_idea_id:`); research `source_idea:` → `source_capture:`. Per HS-B2B8-DLQI-EPIC-capture-rename-migration-idea-to-capture; source rationale HS-ZKFN-1FXG-CAP-capture-as-universal-companion-verb-and-parent-term. |
+| 2026-05-24 | Claude Opus 4.7 (1M) | Capture schema: added `capture_status: raw \| expanded` (default `raw`). Flipped to `expanded` by MCP `executeUpdateCapture` on core_idea/concept/agent_expansion writes; force-corrected by console save-time linter when `# Core Idea` body has content. Backfilled across 21 existing captures by `scripts/backfill-capture-status.mjs`. Per HS-20PH-P2WA-TASK-b3-new-frontmatter-field-idea-status (B3 of HS-BDDT-Q1B7-EPIC-idea-capture-modal-v3-single-textbox-cle). |
+| 2026-05-25 | pwher (with Claude Opus 4.7) | **Business layer added.** New entity types `business-positioning` / `business-pricing` / `business-marketing` / `business-model` filed under `specs/business/{positioning,pricing,marketing,model}/`. IDs `HS-BIZ-POS-* / HS-BIZ-PRI-* / HS-BIZ-MKT-* / HS-BIZ-MOD-*`. Browsed in the console on a dedicated **Business** surface that mirrors Memory's category-rail layout. `positioning-2nd-brain-harness-for-specs` migrated from `memory/decisions/` (`type: memory-decision`) to `business/positioning/` (`type: business-positioning`); basename unchanged so wikilinks resolve. |
+| 2026-05-29 | pwher (with Claude Opus 4.8 [1m]) | **`milestone` entity type formalized.** Added folder `specs/milestones/`, Entity-types-table row, ID format `HS-MIL-<suffix>` (4+ uppercase; legacy 4-char mnemonics like `HS-RM22` valid), filename pattern `HS-MIL-<suffix>-<slug>.md`, and a full `#### milestone` schema subsection (`epics`, `target_date`, status enum, explicit "no scalar priority"). Disambiguated the legacy `kind: milestone` task discriminator from the new `type: milestone` entity; added the `milestone:` parent pointer to the `#### epic` schema; registered the new fields under Reserved frontmatter keys. Describes the 33 `HS-MIL-*` files already on disk (seed HS-RM22-IART-MIL-console-ia-restructure). Ratified by introduction lineage HS-VK7C-MILE-EPIC-milestone-entity-type-and-surfacing → HS-OFR5-M2J3-EPIC-introduce-milestones-as-highest-entity (in lieu of a standalone ADR); canonical hierarchy in [[spec-hierarchy]]. Per HS-9AUC-HRMZ-TASK-define-milestone-entity-type-in-entity-m. |
+| 2026-05-26 | pwher (with Claude Opus 4.7) | **`review` entity type formalized.** Added folder `specs/reviews/`, ID format `HS-REV-<suffix>` (suffix matches parent task/epic id 1:1), filename pattern `HS-REV-<suffix>-<slug>.md`, and full `#### review` schema subsection documenting the four required body sections (Acceptance verification / Reviewer notes / Memory candidates / Decision). Documents what CLAUDE.md §Session Completion + ~100 existing review files already implement; provides the authoritative L2 schema for console, indexer, MCP, and future CLI consumers. Per T1 of HS-3K55-0033-EPIC-review-sibling-testing-workflow (grounded against HS-19F9-TEST-MIL-api-testing-dual-path + HS-UKD6-CLR4-RES-close-out-review-screen-jtbd-architecture). |
+| 2026-05-29 | pwher (with Claude Opus 4.7 [1m]) | **Provenance edges formalized (capture → research → milestone).** Added new §Provenance edges section between §Dependencies and §Evidence linking with the cross-type cardinality table (Capture→Research M:N, Research→Milestone M:1 strict, Research→Epic spawned 1:N, Research→Epic augmented M:N). New frontmatter fields: `research.enhances` (M:1 required on closed), `research.sources_captures` (M:N), `research.spawned_epics` (1:N), `research.enhances_epics` (M:N rare), `research.split_into` / `research.split_from` (split-flow audit); `milestone.informed_by` (reverse of enhances); `capture.informs_research` (M:N, distinct from binary `promoted_to`); optional `epic.derived_from` (reverse of spawned_epics). Reserved-keys list updated. Per HS-HQRM-YJX6-TASK-research-enhances-exactly-one-milestone-validator-and-bidirectional-linkage of HS-OFR5-M2J3-EPIC-introduce-milestones-as-highest-entity. |
+| 2026-05-31 | pwher (with claude opus 4.7) | **`pillar` entity type added** (folder `specs/pillars/`, ID format `HS-PILR-<slug>` for canonical or `HS-PILR-<suffix>-<slug>` for customer-scoped, filename matches ID, `status: perpetual` non-terminal). New required fields on every epic: `pillar:` (single primary) and optional `secondary_pillars:` array. Type ratified by introduction lineage HS-EBIL-0011-EPIC-goal-hierarchy-l2-strategic-pillars-l3 following the milestone precedent (no standalone ADR for the entity itself); privacy-boundary for the Pillar Library learning loop is adr-0016-pillar-library-privacy-boundary. **`architecture-pillars.md` renamed to `architecture-foundations.md`** (ID `HS-L2-PILLARS` → `HS-L2-FOUNDATIONS`) to disambiguate from the new entity; 172 wikilinks updated in a single bulk pass. Three "pillar" usages now coexist: the `type: pillar` entity, the unrelated "Pillars 0–5" section names in HS-DOC-architecture-foundations, and the renamed "FIVE COMPONENTS" section in HS-OR8V-0010-EPIC-north-star-vision-first-class-entity (previously "FIVE PILLARS"). L3 Themes (per-epic teleological anchor) retired in the same resolution — collapsed into perpetual Pillars. See HS-AWDI-PILR-RES-pm-perpetual-container-terminology §"Resolution against existing HS-J6K8" for the full rationale. |
+| 2026-06-03 | claude opus 4.7 [1m] · session `local` (with pwher) | **`canonical:` universal field added; two `superseded` enum values deprecated.** Per evergreen-doc-architecture-srp-and-seo-pillars + canonicalization-arbiter-is-link-graph-not-policy + closed-trackable-specs-are-historical-record-not-living-docs: `canonical: true \| false` is now a universal frontmatter field on every spec type (pillars, L1/L2/L3 docs, HS-DOC-*, ADRs, protocols, memory specs, epics, tasks, milestones, reviews). `true` (or absent) = current/authoritative; `false` = historical record. Trigger event for the flip: plan-side specs at the in_review → closed transition (per [[session-close-protocol]] step 4); evergreen docs at supersession (per supersession-protocol). `status: parked` / `status: deferred` keeps `canonical: true`. **Two enum values deprecated forward-only** per superseded-enum-values-deprecated-use-canonical-false-and-superseded-by: `status: superseded` removed from the ADR-status enum; `superseded` removed from the close_reason enum. Both were redundant with `canonical: false` + `superseded_by:`. Forward-only retirement — existing 11 specs (8 ADRs + 3 plan-side) keep their legacy values as historical record per immutability. New writes use `canonical: false` + `superseded_by:` instead. Added the `canonical:` field to the ADR and task schemas; expanded the `superseded_by:` description to clarify it's the pointer (vs. `canonical:` which is the state). |
+| 2026-06-03 | claude opus 4.7 [1m] · session `local` (with pwher) | **`## Lifecycle classes` section added; `research` schema de-coupled from `status: closed`.** New top-level section between §Entity types and §Identity, IDs, and filenames classifying all 24 types into four lifecycle classes — **Evergreen** (`l1`/`l2`/`l3`/`adr`/`pillar`/`protocol`/`memory-*`/`research`/`business-*`), **Trackable plan-side** (`task`/`epic`/`milestone`/`review`/`branch-brief`/`planning-flow`), **Single-shot ingest** (`capture`/`draft`/`daily`), **Per-instance** (`roadmap`). Closes the discoverability gap that produced the research-is-evergreen incident: a reader asking *"can I flip this file's status to `in_review`?"* now has one canonical place to look. Cross-references research-is-evergreen, closed-trackable-specs-are-historical-record-not-living-docs, canonicalization-arbiter-is-link-graph-not-policy, [[session-close-protocol]]. **Research schema (`#### research`) amended**: the `enhances:` field gate changed from "REQUIRED on `status: closed`" to "REQUIRED when set" — bidirectional consistency is enforced whenever the field is present, independent of status. Added a one-line note above the schema declaring research evergreen with a pointer to research-is-evergreen. The matching validator update in `scripts/validate-vault-ids.mjs` is on the deferred list — schema-vs-validator drift is acknowledged in the schema comment until that catches up. |
+| 2026-06-13 | claude opus 4.8 [1m] · session `local` (with pwher) | **`diagnose` entity type added** (folder `specs/diagnoses/`, ID `HS-DIAG-<suffix>`, filename `HS-DIAG-<suffix>-<slug>.md`). A user-reported bug fix as first-class executable work — standalone by default (exempt from the epic→milestone parent rule), optional `parent:` (epic or milestone), required `severity:` (error/warning/info) that maps onto the scheduler's existing priority signals, optional `blocks:` gating edges. Surfaces on the Resolution surface as a derived `kind: "bug"` row that links back to the diagnose. Added entity-types-table row, ID-format row, filename row, `#### diagnose` schema subsection, and Trackable-plan-side lifecycle classification. Ratified by introduction lineage HS-OXBS-BFIX-MIL-bug-fix-diagnose-lane (milestone-precedent, no standalone ADR). Wiring: `vault.ts` (TYPE_TO_FOLDER + KIND_LINKAGE + body skeleton + generateId), `vault-id.ts`, `vault-rules.mjs` (KIND_RULES/KIND_ORDER), `validator.ts`, `validate-vault-ids.mjs`. Per HS-AO2F-1KZK-RES-bug-fix-resolution-task-entity-model-and. |
+| 2026-06-23 | Cursor · session `local` | **Delegation handoff envelope + task split lineage.** Task frontmatter: `split_of`, `split_index`, `handoff_id` (option B from HS-DTL1-CX5K-CAP-task-split-handoff-when-context-runs-low). Handoff envelope SSOT is body (`## Handoff envelope` + fenced yaml) per `schemas/handoff-envelope.schema.json`; validated by `handoff-envelope.mjs` + `validate-vault-ids.mjs`. Engine rules in `vault-rules.mjs` (`TASK_SPLIT_*`). Per HS-PD6K-NCH5-TASK-handoff-envelope-schema-and-split-child / HS-HXE2-YQ5A-EPIC-delegation-defer-work-from-one-agent-to. |
+| 2026-06-23 | Cursor · session `local` | **`owned_paths` / `affects_paths` for parallel-agent stomp-detection.** New `#### agent` schema subsection documents `owned_paths:` (machine-checkable file globs on agent identities). Task schema adds optional `affects_paths:` (advisory module hints on trackable specs). Entity-types table + reserved-keys list updated. Per HS-ZMAQ-M15C-TASK-declare-owned-path-globs-on-agent-identi / HS-8PNX-Q1KC-EPIC-lanes-and-stomp-detection-for-parallel-a. |
+| 2026-07-05 | Claude Sonnet 5 [1m] · session `local` (with pwher) | **`research.produces_diagnose` → `diagnose.derived_from` edge added (research → diagnose intake).** Bugs found during a research investigation now route into the Resolution lane without new diagnose machinery: `research.produces_diagnose:` (optional, list of wikilinks to `HS-DIAG-*`, mirrors `spawned_epics`) reverse-linked by `diagnose.derived_from:` (optional, single wikilink, mirrors `epic.derived_from`). Written by the new `heyspex_promote_research_to_diagnose` tool (`vendor/heyspex-mcp/promote-research-to-diagnose.mjs`), the research-side sibling of `heyspex_promote_capture_to_diagnose`. Also documented `diagnose.promoted_from:` (existing capture-side back-reference, previously undocumented in this schema subsection). Provenance cardinality table + reserved-keys list updated; validated by the `type: research` block of `schemas/heyspex-frontmatter.schema.json`. Per HS-W5VP-MSHY-TASK-research-diagnose-link-send-bugs-to-the of HS-0FTO-MSHY-EPIC-research-to-diagnose-link-send-bugs-foun. |
+| 2026-07-05 | Claude Sonnet 5 [1m] · session `local` (with pwher) | **`code-audit` findings-table format + closure gate.** New `##### Code-audit findings table` subsection under `#### research` documents the required 4-column body table (`Finding \| Severity \| Action (diagnose\|task\|reference) \| Exit (open\|closed)`) and its three defined exits: bug→diagnose (reuses `heyspex_promote_research_to_diagnose`/`research.produces_diagnose`, no new tooling), cleanup→task (new `task.discovered_from:` reverse pointer to the source research doc), non-actionable→reference (the row itself is the exit). Enriched the existing `task.discovered_from:` doc comment to name this use. Added `discovered_from` to the `type: task` block of `schemas/heyspex-frontmatter.schema.json` (previously documented in entity-model.md only, unenforced). Validator rules in `vault-rules.mjs`: `CODE_AUDIT_FINDINGS_MALFORMED` (no/malformed table) and `CODE_AUDIT_FINDINGS_OPEN_ON_CLOSE` (the closure gate — a `closed`/`review_pending` code-audit doc with any `Exit: open` row) — both warn during a new `CODE_AUDIT_GRACE_END` (2026-08-15, mirrors `RESEARCH_TYPE_GRACE_END`) so pre-existing docs like `HS-ZHAB-RES-doc-authoring-contract-audit-required-st` (no `research_type:` set, predates this format) aren't hard-failed, then error. Per HS-7D0I-WL88-TASK-code-audit-research-type-with-a-defined of HS-BI9D-WL88-EPIC-code-audit-research-type-with-a-defined. |
+| 2026-08-14 | Claude Code (Fable 5) · session `5785e74c` (with pwher) | **Iteration lineage — third relation tier added.** New §Iteration lineage section (between §Provenance edges and §Evidence linking): `iterates_on:` (list of wikilinks, newer-doc-only, one-edit-on-source like amends; computed reverse map `iteratedBy`) expresses "re-attempts an outcome the target shipped but did not fully deliver" — the case supersession (would falsify round 1) and amends (nothing is contradicted) both misdescribe. `outcome:` (`met` \| `partially-met` \| `not-met`) + `outcome_note:` — reviewer-set at close on trackable docs, never inferred, closed-doc-only (not echoed onto round 2). Required `## Related / lineage` resolved-wikilink table on promoted docs with role vocabulary. Invariants: both docs stay `canonical: true`, round 1 keeps `status: closed`, round 2 takes its own family key. Dependencies table gained the Iterates-on row; Reviewer-close bullet gained the outcome write. Field-name + echo decisions resolved at breakdown (flagged for owner Walk). Per HS-VGQV-T9T6-TASK-entity-model-iterates-on-relation-tier of HS-O97P-T9T6-EPIC-iteration-loop-lineage-relation-tier, from HS-3TZX-T9T6-RES-iteration-loop-lineage-and-capture Part A. |