heyspex 0.1.0 → 0.2.1

package/dist/cli-templates/customer-vault/specs/protocols/spec-hierarchy.md

@@ -5,11 +5,9 @@ type: protocol
 status: draft
 priority: 0
 scope: vault
-owner: pwher
-assisted_by:
-  - Claude Code
-created: "2026-05-27"
-updated: "2026-07-04"
+owner: TODO — your name/handle
+created: '2026-05-27'
+updated: '2026-07-04'
 tags:
   - vault
   - specs
@@ -26,26 +24,16 @@ triggers:
   - protocol_edit
 related:
   - "[[entity-model]]"
-  - "vault-id-assignment-protocol"
-  - "session-close-protocol"
+  - "[[session-close-protocol]]"
   - "[[memory-protocol]]"
-  - "plan-ingest-agent-workflow"
-  - "plan-ingest-review-roadmap-workflow"
-  - "roadmap-protocol"
-  - "HS-VK7C-MILE-EPIC-milestone-entity-type-and-surfacing"
-  - "HS-1JC8-HMNJ-MIL-status-and-roadmap-surface-refactor"
-  - "HS-RM22-IART-MIL-console-ia-restructure"
-  - "HS-VLB8-VQZ8-EPIC-sharpen-alignment-gate-claim-target-clar"
-  - "HS-6A4P-MNBD-EPIC-milestone-needs-breakdown-awareness"
-  - "pre-execution-alignment-gate"
-  - "supersession-protocol"
 summary: |
   Governs the Milestone to Epic to Task hierarchy: filing rules, how acceptance criteria propagate and freeze, the Expected Breakage section, sequencing language constraints, and the change-log review seed close-out steps.
+
 ---
 
 # Spec hierarchy protocol — Milestone → Epic → Task → child tasks
 
-The **canonical hierarchy** of trackable work in HeySpex. Every piece of trackable work belongs at exactly one level of this hierarchy. Agents filing new work use this protocol to decide _which level_ a new spec belongs at, _what frontmatter_ it needs, and _how much autonomy_ they have at each level.
+The **canonical hierarchy** of trackable work in HeySpex. Every piece of trackable work belongs at exactly one level of this hierarchy. Agents filing new work use this protocol to decide *which level* a new spec belongs at, *what frontmatter* it needs, and *how much autonomy* they have at each level.
 
 This protocol exists because the hierarchy was previously implicit — codified in example specs (`HS-HMNJ-MIL`, `HS-84HT-EPIC`) and partially in `entity-model.md`, but never written as a single authoritative procedure an agent can read. Pattern-matching off example files leads to drift; this doc is what agents read **before** filing a milestone, epic, or task.
 
@@ -53,36 +41,35 @@ The Milestone entity type itself is **in-flight**: HS-VK7C-MILE-EPIC-milestone-e
 
 ## The four levels
 
-| Level          | Folder              | ID format          | What it is                                                                                                                                                              | Status today                                           |
-| -------------- | ------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
-| **Milestone**  | `specs/milestones/` | `HS-MIL-<suffix>`  | A coherent multi-epic ship. Closes when every child epic closes and the milestone's own acceptance gate is met.                                                         | Entity exists (4 filed); type formalization in HS-VK7C |
-| **Epic**       | `specs/epics/`      | `HS-EPIC-<suffix>` | A bounded body of work, typically 1–10 tasks. Has one parent milestone (required after HS-OFR5) and N children tasks.                                                   | Stable                                                 |
-| **Task**       | `specs/tasks/`      | `HS-TASK-<suffix>` | An atomic unit of agent-executable work. Has one parent epic. May or may not have child tasks (agent's call — see §Agent autonomy).                                     | Stable                                                 |
-| **Child task** | `specs/tasks/`      | `HS-TASK-<suffix>` | A task with `parent:` pointing at another task (not an epic). Used when an agent fans out a task during execution. Same shape as a task; differentiated only by parent. | Stable                                                 |
+| Level | Folder | ID format | What it is | Status today |
+|---|---|---|---|---|
+| **Milestone** | `specs/milestones/` | `HS-MIL-<suffix>` | A coherent multi-epic ship. Closes when every child epic closes and the milestone's own acceptance gate is met. | Entity exists (4 filed); type formalization in HS-VK7C |
+| **Epic** | `specs/epics/` | `HS-EPIC-<suffix>` | A bounded body of work, typically 1–10 tasks. Has one parent milestone (required after HS-OFR5) and N children tasks. | Stable |
+| **Task** | `specs/tasks/` | `HS-TASK-<suffix>` | An atomic unit of agent-executable work. Has one parent epic. May or may not have child tasks (agent's call — see §Agent autonomy). | Stable |
+| **Child task** | `specs/tasks/` | `HS-TASK-<suffix>` | A task with `parent:` pointing at another task (not an epic). Used when an agent fans out a task during execution. Same shape as a task; differentiated only by parent. | Stable |
 
 Suffix format for all four: 4+ uppercase alphanumeric per vault-id-assignment-protocol. Legacy zero-padded epic IDs (`HS-0029-EPIC`) and 4-character mnemonic milestone IDs (`HS-HMNJ-MIL`) both remain valid.
 
 **Shared-suffix families:** when a task is filed under an epic, it inherits the epic's 4-char suffix (e.g. epic `HS-D5YF-EPIC-…` → tasks `HS-TASK-D5YF-<slug>.md`). The slug keeps each filename unique; a bare `HS-TASK-<suffix>` alone is a **family token**, not a unique handle — wikilinks must use the full basename. Retroactive re-suffixing of existing tasks is out of scope. Full rules: vault-id-assignment-protocol §Shared-suffix families; decision: bare-hs-task-suffix-is-a-family-token-af.
 
-## What each level is _for_
+## What each level is *for*
 
-| If the work…                                                                                                                       | …file it as                    |
-| ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
-| Spans multiple epics, has its own acceptance gate, and represents a coherent ship                                                  | Milestone                      |
-| Is a single bounded ship — one outcome, 1–10 tasks, one DoD                                                                        | Epic                           |
-| Is one atomic unit of agent execution (under one context window, usually)                                                          | Task                           |
-| Is sub-work discovered _during_ a task that wasn't in the original task's scope but must complete before the parent task can close | Child task                     |
-| Is a **user-reported bug fix** — executable, but not planned roadmap work that belongs under an epic                               | Diagnose (see §Diagnose below) |
+| If the work… | …file it as |
+|---|---|
+| Spans multiple epics, has its own acceptance gate, and represents a coherent ship | Milestone |
+| Is a single bounded ship — one outcome, 1–10 tasks, one DoD | Epic |
+| Is one atomic unit of agent execution (under one context window, usually) | Task |
+| Is sub-work discovered *during* a task that wasn't in the original task's scope but must complete before the parent task can close | Child task |
+| Is a **user-reported bug fix** — executable, but not planned roadmap work that belongs under an epic | Diagnose (see §Diagnose below) |
 
 **Anti-patterns** — these are not separate levels and should not be filed as such:
-
 - A "phase" or "sprint" inside an epic → those are sections in the epic body or sub-tasks, not a new level.
 - A "follow-up" that's discovered after a task closes → file as a new task under the same epic (not a child of the closed task).
 - A "research" finding that needs implementation → research lives in `specs/research/`; the implementation work is filed as task(s) under an epic, with `discovered_from: [[<research>]]` linking back.
 
 ### Diagnose — the bug-fix lane (a sibling executable entity, outside the milestone→epic→task chain)
 
-A **`diagnose`** (`specs/diagnoses/`, `HS-DIAG-<suffix>`) is a user-reported bug fix as first-class executable work. It is **not** a fifth level of the planning hierarchy — it sits _beside_ it:
+A **`diagnose`** (`specs/diagnoses/`, `HS-DIAG-<suffix>`) is a user-reported bug fix as first-class executable work. It is **not** a fifth level of the planning hierarchy — it sits *beside* it:
 
 - **Standalone by default.** A diagnose needs **no** parent. It is explicitly **exempt** from the epic→milestone mandatory-parent rule. An optional `parent:` (an `HS-EPIC-*` **or** `HS-MIL-*`) groups related fixes when more organization helps — but absence is the normal, valid state (the same "top-level" allowance [[entity-model]] grants tasks, made intentional and typed).
 - **Claimable like a task — while it is a ONE-FIX bug.** A one-fix diagnose is its own `ClaimTarget` (level `"task"`-equivalent — a leaf), and that is the common path. It is not the only one: a write-up whose own `## Fix` section lists **several separately-verifiable fixes** goes through the **breakdown stage** instead (`heyspex_promote_diagnose` — the same stage `heyspex_promote_research` uses, taking a bug write-up as its second input kind, HS-ALBV-BFIX-EPIC-breakdown-stage-accepts-a-diagnose). Grounding runs first (what open milestone/epic already covers this area?), then placement descends: a matching epic gets **tasks**, a matching milestone with no fitting epic gets **one new epic**, and only when neither exists is a milestone minted — that one asks the owner first. Every epic spawned this way carries a milestone that resolves on disk, with no exemption.
@@ -93,11 +80,11 @@ A **`diagnose`** (`specs/diagnoses/`, `HS-DIAG-<suffix>`) is a user-reported bug
 
 **Single-intent test — the deliverable, not the surface count.** When deciding whether work belongs at one level or splits horizontally, the "intent" for SRP-for-plans is the **deliverable** (the milestone's acceptance gate / the epic's DoD / the task's PR), **not** the surface count. A migration epic with N file-tasks is single-intent — the deliverable is "the migration is done." A bundled "platform refresh" milestone whose acceptance gate names three independently-acceptable ships is multi-intent — split it horizontally per §"Milestone sizing — epic cap" below. This is the plan-side counterpart of the doc-side rule in doc-canonicalization-protocol (per evergreen-doc-architecture-srp-and-seo-pillars); both protocols share one principle, applied at different surfaces.
 
-**Closed specs are historical record — frozen + immutable.** Trackable plan-side specs (epics / tasks / milestones / reviews) are _living documents_ while their status is `open` / `in_progress` / `in_review`. The moment they close (`status: closed`), the body is **frozen**: no further edits to scope, acceptance criteria, narrative, or `related:` links. The closed spec captures the plan exactly as it was at the moment of close — and that's its job from then on. The actual delivered behavior is the git history of the shipped change; the closed spec is the _plan that closed_, preserved as historical record. Full rule + the four implicit references it generalizes + what you CAN still touch on a closed spec (the close-out change-log row; `status:`; `close_reason:`; `superseded_by:`) + where new information goes instead (new task / new memory / supersession): closed-trackable-specs-are-historical-record-not-living-docs. The Shipped console surface that displays the archive: HS-ZUVY-S1A6-EPIC-shipped-surface-closure-event-archive-wi. The storage convention (archive = filter not folder; closed specs stay in their normal folders): [[entity-model]] §close_reason.
+**Closed specs are historical record — frozen + immutable.** Trackable plan-side specs (epics / tasks / milestones / reviews) are *living documents* while their status is `open` / `in_progress` / `in_review`. The moment they close (`status: closed`), the body is **frozen**: no further edits to scope, acceptance criteria, narrative, or `related:` links. The closed spec captures the plan exactly as it was at the moment of close — and that's its job from then on. The actual delivered behavior is the git history of the shipped change; the closed spec is the *plan that closed*, preserved as historical record. Full rule + the four implicit references it generalizes + what you CAN still touch on a closed spec (the close-out change-log row; `status:`; `close_reason:`; `superseded_by:`) + where new information goes instead (new task / new memory / supersession): closed-trackable-specs-are-historical-record-not-living-docs. The Shipped console surface that displays the archive: HS-ZUVY-S1A6-EPIC-shipped-surface-closure-event-archive-wi. The storage convention (archive = filter not folder; closed specs stay in their normal folders): [[entity-model]] §close_reason.
 
 ### Sequencing language — disambiguate "after X"
 
-When a task body or scope item references another spec as a precondition for some piece of work ("land after X," "after X closes," "this happens after X"), the wording must name _which signal_ the agent should wait for. Pick exactly one:
+When a task body or scope item references another spec as a precondition for some piece of work ("land after X," "after X closes," "this happens after X"), the wording must name *which signal* the agent should wait for. Pick exactly one:
 
 - **"after X's code lands"** — wait until X's implementation is in the working tree, regardless of X's status. Use when the dependent work describes X's final code state (typically: comment rewrites, doc updates, edits that reference X's predicate signature / env var / new column).
 - **"after X closes"** — wait until X's `status: closed` (the reviewer's commit). Use **only** when the trigger is genuinely the close-out event itself — e.g., audit-only timing, archive sweeps, "do this after the reviewer signs off because the next step depends on the sign-off."
@@ -107,7 +94,7 @@ The bare **"after X"** is banned: in MVP mode where the reviewer is the owner an
 
 **Reading legacy specs that use bare "after X":** default to "after X's code lands" — it's the cheaper read in MVP mode and matches the spec author's typical intent (they wanted the dependent work to describe X's final semantics, not to wait on the reviewer's clock). Treat the close-out reading as the exception, required only when the surrounding context makes the close-out signal explicit.
 
-This rule generalizes the feedback_mvp_mode_after_x_closes_means_after_code_lands incident pattern. The matching enforcement at session close (the **Deferred items audit** subsection in the HS-REV template) catches over-deferral that slipped past this rule — see session-close-protocol §HS-REV companion template §`## Reviewer notes` §`### Deferred items audit`.
+This rule generalizes the feedback_mvp_mode_after_x_closes_means_after_code_lands incident pattern. The matching enforcement at session close (the **Deferred items audit** subsection in the HS-REV template) catches over-deferral that slipped past this rule — see [[session-close-protocol]] §HS-REV companion template §`## Reviewer notes` §`### Deferred items audit`.
 
 ### Milestone sizing — epic cap
 
@@ -130,37 +117,35 @@ When filing a milestone/epic set from a completed research doc (the `heyspex_pro
 
 **Decision rule (agents + tools):**
 
-| Situation                                            | Action                                                                                                              |
-| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| Research promotion (default)                         | `target_milestone: "NEW"` + `new_milestone_name`                                                                    |
-| Research clearly extends one open milestone's thesis | May attach — target must be `status: open` only                                                                     |
-| Agent would cram into nearest plausible milestone    | **Stop** — file NEW instead                                                                                         |
-| Research spans multiple milestone theses             | Split first (HS-TQQS-GTH9-TASK-hs-split-research-mcp-tool), then promote each child to NEW or its one open best-fit |
+| Situation | Action |
+|-----------|--------|
+| Research promotion (default) | `target_milestone: "NEW"` + `new_milestone_name` |
+| Research clearly extends one open milestone's thesis | May attach — target must be `status: open` only |
+| Agent would cram into nearest plausible milestone | **Stop** — file NEW instead |
+| Research spans multiple milestone theses | Split first (HS-TQQS-GTH9-TASK-hs-split-research-mcp-tool), then promote each child to NEW or its one open best-fit |
 
 **Existing-milestone attach gate (enforced in `promote-research.mjs`):**
 
-| Target milestone `status:`                                                     | Spawn epics allowed?                                                                                                                           |
-| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `open`                                                                         | Yes (still requires clear thesis fit — agent judgment)                                                                                         |
-| `in_progress`                                                                  | **Blocked by default.** Rare owner exception only: `attach_to_in_progress_milestone: true` + `attach_override_reason` (≥40 chars, audit trail) |
-| `in_review`, `review_pending`, `closed`, `parked`, `deferred`, `hibernated`, … | **Blocked** — use NEW                                                                                                                          |
+| Target milestone `status:` | Spawn epics allowed? |
+|----------------------------|----------------------|
+| `open` | Yes (still requires clear thesis fit — agent judgment) |
+| `in_progress` | **Blocked by default.** Rare owner exception only: `attach_to_in_progress_milestone: true` + `attach_override_reason` (≥40 chars, audit trail) |
+| `in_review`, `review_pending`, `closed`, `parked`, `deferred`, `hibernated`, … | **Blocked** — use NEW |
 
-Still check existing milestones first — but as a high-bar gate, not an eager search. Attach to an existing milestone **only** when the research clearly extends that milestone's single thesis and shared infrastructure (best-fit is obvious, not merely that _a_ fit exists). Absent that clear best-fit, file a new milestone. Filing a new milestone is a strategic decision — confirm it with the owner per the autonomy table below. Rationale: the common case is one research doc → one new milestone; cramming epics into the nearest plausible existing milestone is a helpful-but-wrong habit that over-stuffs milestones and blurs their thesis. Basis: HS-Q7X7-MDHQ-RES-flat-9-epic-milestone-cap-and-research-t.
+Still check existing milestones first — but as a high-bar gate, not an eager search. Attach to an existing milestone **only** when the research clearly extends that milestone's single thesis and shared infrastructure (best-fit is obvious, not merely that *a* fit exists). Absent that clear best-fit, file a new milestone. Filing a new milestone is a strategic decision — confirm it with the owner per the autonomy table below. Rationale: the common case is one research doc → one new milestone; cramming epics into the nearest plausible existing milestone is a helpful-but-wrong habit that over-stuffs milestones and blurs their thesis. Basis: HS-Q7X7-MDHQ-RES-flat-9-epic-milestone-cap-and-research-t.
 
 ## Frontmatter requirements per level
 
 All four levels share the base shape from [[entity-model]]: `id`, `name`, `type`, `status`, `owner`, `created`, `updated`, `tags`, `related`.
 
-**Author `summary:` at file time.** A plain-language `summary:` is written as part of the act of filing — the same step as giving the spec a name. **Planning phase (milestone + epic):** summary at plan ingest / research promotion / milestone breakdown — milestones and epics are filed in this wave only, never with tasks. **Execution phase (task):** summary only when filing from What's Next → Launch → `/hs-next` breakdown. Pass `summary` to `heyspex_file_spec` / include it in the `POST /api/specs` body. Full contract: spec-summary-authoring.
+**Author `summary:` at file time.** A plain-language `summary:` is written as part of the act of filing — the same step as giving the spec a name. **Planning phase (milestone + epic):** summary at plan ingest / research promotion / milestone breakdown — milestones and epics are filed in this wave only, never with tasks. **Execution phase (task):** summary only when filing from What's Next → Launch → `/hs-next` breakdown. Pass `summary` to `heyspex_file_spec` / include it in the `POST /api/specs` body. Full contract: [[spec-summary-authoring]].
 
 **Milestone-specific** (`type: milestone`):
-
 - `epics:` — array of `[[wikilinks]]` to every child epic (mirror of each child epic's `milestone:` pointer)
 - `target_date:` — optional ISO date or empty string
 - Body must include: `## Explain Like I'm 12` **as the first body section** (see below), a `## Intended outcome` re-derived from the source research's outcome (see §Intended outcome — re-derived at every level), rationale ("why this is a milestone, not loose epics"), acceptance gate (numbered closure conditions), suggested landing order (sequencing guidance, not a complete roster or a count), out-of-scope, and `## Expected Breakage & Consequences` (see below). The body must **not** re-list the child epics as a roster or state their count — see §Child rosters live in frontmatter, not prose.
 
 **Epic-specific** (`type: epic`):
-
 - `milestone:` — `[[wikilink]]` to parent milestone (will be **required** post-HS-OFR5; today recommended)
 - `pillar:` — **required** `[[wikilink]]` to the perpetual `HS-PILR` theme this epic's learning belongs to. **Hard-blocked at filing**: `POST /api/specs` / `heyspex_file_spec` refuse an epic with no resolvable pillar (`400 pillar_required`). When none fits, author a net-new pillar first. Full rules: pillar-assignment-protocol.
 - `children:` — array of `[[wikilinks]]` to every child task
@@ -169,10 +154,9 @@ All four levels share the base shape from [[entity-model]]: `id`, `name`, `type`
 - `requires_user_testing:` — boolean
 - `builder_profile:` — optional at plan ingest: `mechanical` | `architectural` | `mixed` — signals anticipated local builder class for breakdown (builder-fleet-capability-reference).
 - Body must include: `## Explain Like I'm 12` **as the first body section** (see below), a `## Intended outcome` re-derived from the parent milestone's outcome (see §Intended outcome — re-derived at every level), scope, acceptance criteria, out-of-scope, and `## Expected Breakage & Consequences` (see below). Optional at plan ingest: **`## Builder fleet notes`** (cross-file blast radius, expected model/machine class, breakdown constraints — see builder-fleet-capability-reference). The body must **not** enumerate the child tasks as a roster or state their count — see §Child rosters live in frontmatter, not prose.
-- Body must include `## Why this epic exists` — the **substantive priority rationale** the scheduler "Why" surfaces (the mechanical tier/layer order is computed; _why the work matters_ must be authored). See §Why-this-epic-exists rationale below. Auto-scaffolded with prompts (`canonical-frontmatter-templates` §epic / `BODY_SKELETONS.epic`).
+- Body must include `## Why this epic exists` — the **substantive priority rationale** the scheduler "Why" surfaces (the mechanical tier/layer order is computed; *why the work matters* must be authored). See §Why-this-epic-exists rationale below. Auto-scaffolded with prompts (`canonical-frontmatter-templates` §epic / `BODY_SKELETONS.epic`).
 
 **Task-specific** (`type: task`):
-
 - `parent:` — `[[wikilink]]` to parent epic (or to a parent task, for child-task case)
 - `kind:` — same enum as epic
 - `effort:` — same scale as epic
@@ -188,11 +172,11 @@ All four levels share the base shape from [[entity-model]]: `id`, `name`, `type`
 
 ## Intended outcome — re-derived at every level (not copied)
 
-Every level carries an intended-outcome section — `## Conclusion & intended outcome` on the research doc, `## Intended outcome` on milestone/epic/task. It **cascades by re-derivation, never copy-down** (grounded in HS-K4D4-2I29-RES-outcome-cascade-through-a-requirements-h: GORE/KAOS refine DOWN by asking HOW and justify UP by asking WHY; the OKR rule that copying a parent's wording down the hierarchy is the core failure mode — "the appearance of order while stripping out ownership" — whose cure is _translation_).
+Every level carries an intended-outcome section — `## Conclusion & intended outcome` on the research doc, `## Intended outcome` on milestone/epic/task. It **cascades by re-derivation, never copy-down** (grounded in HS-K4D4-2I29-RES-outcome-cascade-through-a-requirements-h: GORE/KAOS refine DOWN by asking HOW and justify UP by asking WHY; the OKR rule that copying a parent's wording down the hierarchy is the core failure mode — "the appearance of order while stripping out ownership" — whose cure is *translation*).
 
-At each level the section must (a) state the outcome **at that altitude** (the milestone/epic/task's own contribution, not the parent's words), (b) draw an explicit **↑ link** to the parent outcome it moves, and (c) name the **mechanism of contribution** — _how_ it moves the parent. A child outcome that reads like a paste of its parent is **outcome theater**; rewrite it.
+At each level the section must (a) state the outcome **at that altitude** (the milestone/epic/task's own contribution, not the parent's words), (b) draw an explicit **↑ link** to the parent outcome it moves, and (c) name the **mechanism of contribution** — *how* it moves the parent. A child outcome that reads like a paste of its parent is **outcome theater**; rewrite it.
 
-**The task level is the verification bridge.** A leaf (task) outcome must be expressed as conditions an agent can **monitor and control** — and those conditions are exactly what the task's `## Acceptance criteria` are, each traceable ↑ to the epic outcome. This is the KAOS leaf-operationalization rule: refinement terminates only when a goal is realizable and testable. So the acceptance criteria are _derived from_ the intended outcome, not invented separately.
+**The task level is the verification bridge.** A leaf (task) outcome must be expressed as conditions an agent can **monitor and control** — and those conditions are exactly what the task's `## Acceptance criteria` are, each traceable ↑ to the epic outcome. This is the KAOS leaf-operationalization rule: refinement terminates only when a goal is realizable and testable. So the acceptance criteria are *derived from* the intended outcome, not invented separately.
 
 The materializers inject these sections automatically (`promote-capture.mjs` research stub; `promote-research.mjs` milestone + epic; `BODY_SKELETONS` in `spex-console/src/lib/vault.ts` for epic/task/milestone). Hand-authored specs add them per [[canonical-frontmatter-templates]].
 
@@ -212,9 +196,9 @@ Owner ruling 2026-08-15 (HS-KJFZ-Z12C-CAP-every-milestone-and-every-epic-carries
 
 **Auto-scaffolded at creation.** `spex-console/src/lib/vault.ts` `createSpec` injects the heading, an altitude-appropriate prompt, and the ten properties below as an authoring comment — env-gated by `HEYSPEX_AUTO_ELI12_EMBED`, positioned first in the body. Same dual treatment as `## Memories` and `## Expected Breakage & Consequences`: creation-time embed, author fills it.
 
-**Milestone links, epic does not.** A milestone's section links to heyspex-north-star §Explain Like I'm 12 for what the whole product is, and covers only the parts of the product that bear on _this_ milestone. Owner instruction: "we don't need HeySpex to be re-explained every time. But the important points of HeySpex that are relevant can be helpful." An epic explains its own chunk and carries **no** such link — the parent milestone already covers the wider picture.
+**Milestone links, epic does not.** A milestone's section links to heyspex-north-star §Explain Like I'm 12 for what the whole product is, and covers only the parts of the product that bear on *this* milestone. Owner instruction: "we don't need HeySpex to be re-explained every time. But the important points of HeySpex that are relevant can be helpful." An epic explains its own chunk and carries **no** such link — the parent milestone already covers the wider picture.
 
-**Never a paraphrase of `summary:`.** The two do different jobs (spec-summary-authoring). If the summary can be pasted in here, the section is wrong.
+**Never a paraphrase of `summary:`.** The two do different jobs ([[spec-summary-authoring]]). If the summary can be pasted in here, the section is wrong.
 
 ### Rule 0 — grounding outranks style (read this before the ten)
 
@@ -237,13 +221,13 @@ The ten style rules push toward invention. Read them knowing that:
 
 Naming an outside product carries **the relationship the source states** — uses it, replaces it, self-hosts it, pays for it. Never read the relationship off the product's name.
 
-**Worked failure — 2026-08-15.** A draft section for the SpexCrawl milestone opened: _"Today HeySpex pays a service called Firecrawl to do that."_ Every one of the ten style rules is satisfied by that sentence. It is false. The thing being reproduced is open-source Firecrawl, self-hosted on the owner's own hardware at no cost, and a self-hosted deployment never calls the company at all (spexcrawl-parity-target-is-self-hosted). The word "paying" did appear in the source, in a different sentence about a different thing, and the pull toward plain words moved it onto the wrong subject. A style rule with no grounding rule is a machine for producing well-written falsehoods, at whatever rate you run it.
+**Worked failure — 2026-08-15.** A draft section for the SpexCrawl milestone opened: *"Today HeySpex pays a service called Firecrawl to do that."* Every one of the ten style rules is satisfied by that sentence. It is false. The thing being reproduced is open-source Firecrawl, self-hosted on the owner's own hardware at no cost, and a self-hosted deployment never calls the company at all (spexcrawl-parity-target-is-self-hosted). The word "paying" did appear in the source, in a different sentence about a different thing, and the pull toward plain words moved it onto the wrong subject. A style rule with no grounding rule is a machine for producing well-written falsehoods, at whatever rate you run it.
 
 ### Written by a machine? Then money, ownership, and scale are off the table
 
 A human author writing this section gets Rule 0 and is trusted with it. **Anything writing the section unattended does not get that trust**, because the failure is not decidable by a checker.
 
-This was tested, not assumed. A grounding critic was built for exactly this job: it reads the source and each claim, and must quote the sentence that supports it. On 2026-08-15 it was run against both DeepSeek V4 Flash and DeepSeek V4 Pro drafting the SpexCrawl milestone. **Both models wrote that HeySpex pays for page fetching, and the critic passed both** — because "paying to fetch pages in the cloud" does appear in the source, in a sentence about what the new design _avoids_. The critic matched the words and missed the subject, which is the same mistake it was hired to catch.
+This was tested, not assumed. A grounding critic was built for exactly this job: it reads the source and each claim, and must quote the sentence that supports it. On 2026-08-15 it was run against both DeepSeek V4 Flash and DeepSeek V4 Pro drafting the SpexCrawl milestone. **Both models wrote that HeySpex pays for page fetching, and the critic passed both** — because "paying to fetch pages in the cloud" does appear in the source, in a sentence about what the new design *avoids*. The critic matched the words and missed the subject, which is the same mistake it was hired to catch.
 
 So for unattended writing the whole class is refused rather than checked. `lintEli12(..., { strict: true })` in `scripts/eli12-lint.mjs` makes any sentence touching money, ownership, or scale a hard error, and the generator is told the class is out of scope even when the source states it. A spec whose explanation genuinely needs such a claim fails the lint and goes to a human. That is the correct direction to fail.
 
@@ -283,13 +267,13 @@ Same handling as `## Expected Breakage & Consequences` below: an unfilled scaffo
 
 ## Expected Breakage & Consequences (required body section)
 
-> **The premise:** to make something better you usually have to break it first. Implementing real work _raises_ the error/failure count before it settles — adding one `surface id` legitimately took a tree from 10 → 17 tsc errors because `layout-panes.ts` needed a resolution entry and a test fixture was now missing a field. Those were **expected consequences**, not regressions. This section makes that anticipation explicit so the executing agent and the reviewer read a transient rise as normal, and so the cascade is enumerated _before_ it is hit.
+> **The premise:** to make something better you usually have to break it first. Implementing real work *raises* the error/failure count before it settles — adding one `surface id` legitimately took a tree from 10 → 17 tsc errors because `layout-panes.ts` needed a resolution entry and a test fixture was now missing a field. Those were **expected consequences**, not regressions. This section makes that anticipation explicit so the executing agent and the reviewer read a transient rise as normal, and so the cascade is enumerated *before* it is hit.
 
-Every milestone, epic, and task carries a `## Expected Breakage & Consequences` section. It is **auto-scaffolded at creation** (`spex-console/src/lib/vault.ts` `createSpec`, env-gated by `HEYSPEX_AUTO_BREAKAGE_EMBED`, placed below `## Memories`), **surfaced in the `/hs-next` execution brief** (above NEXT STEP, via `enrichOnDeckWithExpectedBreakage` in `vendor/heyspex-mcp/cli.mjs`), and **reconciled at close** (the HS-REV `### Breakage reconciliation` table — see session-close-protocol). It mirrors the dual-layer (creation-time embed + runtime injection) treatment of `## Memories` per HS-U2M6-IMMF-TASK-memory-recall-hardening-runtime-injectio.
+Every milestone, epic, and task carries a `## Expected Breakage & Consequences` section. It is **auto-scaffolded at creation** (`spex-console/src/lib/vault.ts` `createSpec`, env-gated by `HEYSPEX_AUTO_BREAKAGE_EMBED`, placed below `## Memories`), **surfaced in the `/hs-next` execution brief** (above NEXT STEP, via `enrichOnDeckWithExpectedBreakage` in `vendor/heyspex-mcp/cli.mjs`), and **reconciled at close** (the HS-REV `### Breakage reconciliation` table — see [[session-close-protocol]]). It mirrors the dual-layer (creation-time embed + runtime injection) treatment of `## Memories` per HS-U2M6-IMMF-TASK-memory-recall-hardening-runtime-injectio.
 
 The section holds **two distinct halves** — keep them separate, because a non-breaking side-effect is not the same as breakage:
 
-1. **Breakage** — things that will _error or fail_ until fixed in-scope (type/contract consumers, test fixtures/snapshots, call sites). Pair this with a **Baseline → Exit** contract: the tsc/test error count before work starts, and the exit condition (every net-new error resolved before flipping to `in_review`, back to ≤ baseline).
+1. **Breakage** — things that will *error or fail* until fixed in-scope (type/contract consumers, test fixtures/snapshots, call sites). Pair this with a **Baseline → Exit** contract: the tsc/test error count before work starts, and the exit condition (every net-new error resolved before flipping to `in_review`, back to ≤ baseline).
 2. **Consequences / side-effects** — intended ripples that change behavior but do **not** break (a removed field, a changed default, a downstream behavior shift). These are real and worth recording even though nothing "fails."
 
 **Altitude-appropriate content:**
@@ -302,11 +286,11 @@ The scaffold ships with placeholder prompts; the author replaces them (it is **n
 
 **Expected Breakage cascade (planning → breakdown → execution).** The section **cascades by allocation, not copy-down** — same re-derivation principle as :
 
-| Phase         | When authored                                                 | Altitude                                                                      | Allocates from                                                                         |
-| ------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
-| **Milestone** | Plan ingest / research promotion (plan-ingest-agent-workflow) | Cross-epic seams and integration points that may break as the milestone lands | Research scope + milestone thesis                                                      |
-| **Epic**      | Epic filing under the milestone (planning phase)              | Subsystems/files this epic's changes ripple into                              | Parent milestone's breakage (where relevant)                                           |
-| **Task**      | `/hs-next` breakdown only (pre-execution-alignment-gate)      | Concrete files/fixtures/call sites + baseline→exit contract                   | Parent epic's blast radius **and** milestone seams surfaced in the decomposition brief |
+| Phase | When authored | Altitude | Allocates from |
+|---|---|---|---|
+| **Milestone** | Plan ingest / research promotion (plan-ingest-agent-workflow) | Cross-epic seams and integration points that may break as the milestone lands | Research scope + milestone thesis |
+| **Epic** | Epic filing under the milestone (planning phase) | Subsystems/files this epic's changes ripple into | Parent milestone's breakage (where relevant) |
+| **Task** | `/hs-next` breakdown only (pre-execution-alignment-gate) | Concrete files/fixtures/call sites + baseline→exit contract | Parent epic's blast radius **and** milestone seams surfaced in the decomposition brief |
 
 At **task breakdown**, read the parent epic's and milestone's `## Expected Breakage & Consequences` sections first (the `/hs-next` decomposition brief surfaces them verbatim under **Expected Breakage — parent context**). Each task **pre-allocates fix-up scope** from those parent sections — drill down to specifics; do not paste parent prose or invent breakage in isolation. If a parent section is still the unfilled scaffold, fill it before decomposing (or note explicitly in each task why breakage is none).
 
@@ -319,13 +303,11 @@ Implementing this will transiently raise the tsc/test error count — that's exp
 Enumerate the cascade so a rise reads as normal, not a regression.
 
 **Breakage (will error/fail until fixed in-scope):**
-
 - Type/contract consumers: `<files referencing the changed symbol>`
 - Test fixtures/snapshots: `<state literals / snapshots needing the new field>`
 - Call sites: `<…>`
 
 **Consequences / side-effects (intended, non-breaking):**
-
 - `<changed default / removed field / downstream behavior shift>`
 
 **Baseline → Exit:** tsc = `<N>` errors / tests `<green | N failing>` before work.
@@ -334,13 +316,13 @@ Exit: every net-new error resolved before flipping to `in_review` (back to ≤ `
 
 ## Why-this-epic-exists rationale (substantive priority, not mechanical order)
 
-The deterministic scheduler explains **how** a spec ranked — tier, dependency layer, what-matters, criticality (the mechanical "Why"). It cannot explain the **substantive why**: _why this work matters and why it belongs at the top now_. That has to be **authored**. Without it, the "Why" is factual but thin. Research + framework grounding: HS-XMSD-W8OZ-RES-authoring-substantive-priority-rationale (Cost of Delay/WSJF, Shape Up appetite, RICE, Definition-of-Ready); the mechanical layer it complements: HS-AVSG-7J97-RES-how-the-scheduler-explains-itself-determ.
+The deterministic scheduler explains **how** a spec ranked — tier, dependency layer, what-matters, criticality (the mechanical "Why"). It cannot explain the **substantive why**: *why this work matters and why it belongs at the top now*. That has to be **authored**. Without it, the "Why" is factual but thin. Research + framework grounding: HS-XMSD-W8OZ-RES-authoring-substantive-priority-rationale (Cost of Delay/WSJF, Shape Up appetite, RICE, Definition-of-Ready); the mechanical layer it complements: HS-AVSG-7J97-RES-how-the-scheduler-explains-itself-determ.
 
 Every epic's `## Why this epic exists` section carries up to four **plain-language** prompts — no scores, no numeric fields (the scalar-priority anti-pattern HS-141W-PRIO-RES-priority-and-scoring-systems-2026 rejected):
 
-- **Problem right now (required at filing):** one sentence — the specific problem this solves _and_ why now (not next cycle). This is the qualitative minimum Cost of Delay: it names the problem and the time-criticality in one breath.
+- **Problem right now (required at filing):** one sentence — the specific problem this solves *and* why now (not next cycle). This is the qualitative minimum Cost of Delay: it names the problem and the time-criticality in one breath.
 - **What this unlocks (required when `kind: infra` or `foundation`):** what future work shipping this makes possible. The authored complement to the scheduler's criticality stage (the graph counts downstream specs; the author says why they matter).
-- **Skip cost (write before pinning this as on-deck):** "If we skip this cycle, we lose: …" — a _specific_ consequence, not "it's important."
+- **Skip cost (write before pinning this as on-deck):** "If we skip this cycle, we lose: …" — a *specific* consequence, not "it's important."
 - **Confidence note (optional):** flag any part of the rationale where confidence is low (RICE's bias-brake; also keeps an agent from treating shaky rationale as ground truth).
 
 **Rationale strengthens as a spec rises (progressive elaboration / Definition-of-Ready).** A spec far down the queue needs only the lightweight Problem (+ Unlocks). As it approaches the **top / on-deck pin**, it should also carry the **Skip cost** sentence — the closer to execution, the more specific the justification. This is enforced as a **soft nudge at the pin action** (the pin UI prompts for the skip-cost sentence), **never a hard block** — keep it progressive elaboration, not a phase-gate (HS-XMSD §Definition-of-Ready caveat). The `what_matters` (★/♥) flag remains the coarse value band and always appears in the "Why".
@@ -349,11 +331,11 @@ Every epic's `## Why this epic exists` section carries up to four **plain-langua
 
 Linkage is **bidirectional and explicit** — agents MUST update both sides when filing a new spec:
 
-| Edge              | Parent's field                | Child's field               |
-| ----------------- | ----------------------------- | --------------------------- |
-| Milestone → Epic  | `epics: ["[[HS-EPIC-…]]"]`    | `milestone: "[[HS-MIL-…]]"` |
-| Epic → Task       | `children: ["[[HS-TASK-…]]"]` | `parent: "[[HS-EPIC-…]]"`   |
-| Task → Child task | `children: ["[[HS-TASK-…]]"]` | `parent: "[[HS-TASK-…]]"`   |
+| Edge | Parent's field | Child's field |
+|---|---|---|
+| Milestone → Epic | `epics: ["[[HS-EPIC-…]]"]` | `milestone: "[[HS-MIL-…]]"` |
+| Epic → Task | `children: ["[[HS-TASK-…]]"]` | `parent: "[[HS-EPIC-…]]"` |
+| Task → Child task | `children: ["[[HS-TASK-…]]"]` | `parent: "[[HS-TASK-…]]"` |
 
 **`heyspex_file_spec` does NOT wire the parent's `children[]` back-reference.** It creates the task file and sets the task's own `parent:` field, but the parent epic's `children:` array is a separate write. The signal is the response: if `parent` or `milestone` come back `null`, the back-reference was not written. Always call `heyspex_register_spec(spec_id, parent_id)` immediately after every `heyspex_file_spec` call — it writes both sides atomically and is idempotent (see §Filing procedure step 5).
 
@@ -383,20 +365,20 @@ After filing, run `heyspex_validate_linkage` (MCP) to confirm both sides are pre
 
 This is the part agents most often get wrong. The default is **ask first** for structural changes, **decide on your own** for execution-level fanout.
 
-| Action                                                     | Agent autonomy                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **File a new milestone**                                   | **Ask the user.** Milestones are strategic decisions; do not file unilaterally.                                                                                                                                                                                                                                                                                                                                                                              |
-| **File a new epic under an existing milestone**            | **Ask the user**, unless the epic clearly maps to a single audit/finding/incident already named by the user. When in doubt, ask. **File the epic with `children: []`** — do not fan out tasks in the same pass (see the next row). **The parent milestone must be open** (non-claim-terminal — `open`/`in_progress`/`draft`/`parked`); filing under an `in_review`/`closed` milestone is hard-blocked with `parent_milestone_not_open` (see §Linkage rules). |
-| **Fan out tasks under a new epic**                         | **Never at epic-creation / planning time.** Tasks are created **just-in-time at execution**, when the epic becomes the on-deck `ClaimTarget` (via `/hs-next`) — that breakdown is the _first step of executing the epic_, not a planning activity. At doc-creation and during clarification, offer **milestone + epics only**. See the §empty-state grain-split note below and deterministic-priority-scheduler-supersedes-scored-priority.                  |
-| **Add a child task during execution of a parent task**     | **Decide autonomously.** This is the canonical place agents have authority — when executing a task uncovers sub-work, fan out into child tasks without asking. Link via `parent:` to the task you're executing.                                                                                                                                                                                                                                              |
-| **Reorder child tasks within a task**                      | **Decide autonomously.** Sequence and decomposition of child tasks is the agent's call.                                                                                                                                                                                                                                                                                                                                                                      |
-| **Add a `related:` link to another spec**                  | **Decide autonomously.** Cross-linking is low-risk.                                                                                                                                                                                                                                                                                                                                                                                                          |
-| **Change a spec's `parent:` or `milestone:` field**        | **Ask the user.** Restructuring linkage changes the roadmap rendering and other agents' context.                                                                                                                                                                                                                                                                                                                                                             |
-| **Change a spec's `status:` from anything to `in_review`** | **Decide autonomously** when acceptance criteria are met (per session-close-protocol).                                                                                                                                                                                                                                                                                                                                                                       |
-| **Change a spec's `status:` to `closed`**                  | **Never.** Only the reviewer (human) flips to `closed`. Agent terminal action is `in_review`.                                                                                                                                                                                                                                                                                                                                                                |
-| **Create a memory doc**                                    | **Decide autonomously** when a lesson/decision/UI pattern emerges (per CLAUDE.md §Automatic knowledge capture).                                                                                                                                                                                                                                                                                                                                              |
-| **Modify a protocol doc (this kind of file)**              | **Ask the user.** Protocols are stable contracts; treat changes the same as ADR changes.                                                                                                                                                                                                                                                                                                                                                                     |
-| **File a new diagnose (standalone bug fix)**               | **Decide autonomously** when a bug is reported and the symptom/scope is clear — standalone (no parent) is the default. **Ask the user** before giving it a `parent:` (epic/milestone) or a `blocks:` edge, since both change roadmap/on-deck rendering.                                                                                                                                                                                                      |
+| Action | Agent autonomy |
+|---|---|
+| **File a new milestone** | **Ask the user.** Milestones are strategic decisions; do not file unilaterally. |
+| **File a new epic under an existing milestone** | **Ask the user**, unless the epic clearly maps to a single audit/finding/incident already named by the user. When in doubt, ask. **File the epic with `children: []`** — do not fan out tasks in the same pass (see the next row). **The parent milestone must be open** (non-claim-terminal — `open`/`in_progress`/`draft`/`parked`); filing under an `in_review`/`closed` milestone is hard-blocked with `parent_milestone_not_open` (see §Linkage rules). |
+| **Fan out tasks under a new epic** | **Never at epic-creation / planning time.** Tasks are created **just-in-time at execution**, when the epic becomes the on-deck `ClaimTarget` (via `/hs-next`) — that breakdown is the *first step of executing the epic*, not a planning activity. At doc-creation and during clarification, offer **milestone + epics only**. See the §empty-state grain-split note below and deterministic-priority-scheduler-supersedes-scored-priority. |
+| **Add a child task during execution of a parent task** | **Decide autonomously.** This is the canonical place agents have authority — when executing a task uncovers sub-work, fan out into child tasks without asking. Link via `parent:` to the task you're executing. |
+| **Reorder child tasks within a task** | **Decide autonomously.** Sequence and decomposition of child tasks is the agent's call. |
+| **Add a `related:` link to another spec** | **Decide autonomously.** Cross-linking is low-risk. |
+| **Change a spec's `parent:` or `milestone:` field** | **Ask the user.** Restructuring linkage changes the roadmap rendering and other agents' context. |
+| **Change a spec's `status:` from anything to `in_review`** | **Decide autonomously** when acceptance criteria are met (per [[session-close-protocol]]). |
+| **Change a spec's `status:` to `closed`** | **Never.** Only the reviewer (human) flips to `closed`. Agent terminal action is `in_review`. |
+| **Create a memory doc** | **Decide autonomously** when a lesson/decision/UI pattern emerges (per CLAUDE.md §Automatic knowledge capture). |
+| **Modify a protocol doc (this kind of file)** | **Ask the user.** Protocols are stable contracts; treat changes the same as ADR changes. |
+| **File a new diagnose (standalone bug fix)** | **Decide autonomously** when a bug is reported and the symptom/scope is clear — standalone (no parent) is the default. **Ask the user** before giving it a `parent:` (epic/milestone) or a `blocks:` edge, since both change roadmap/on-deck rendering. |
 
 **How the empty-state grain-split is surfaced (2026-06-01).** The two "no children yet" states are NOT the same severity, and the console signals them differently (HS-6A4P On Deck split, pre-execution-alignment-gate):
 
@@ -407,63 +389,63 @@ This is the part agents most often get wrong. The default is **ask first** for s
 
 ## Claim eligibility & `ClaimTarget`
 
-**The single eligibility rule:** _a spec is claimable iff it is its own current `ClaimTarget`_. The console claim endpoint (`POST /api/specs/:id/claim`) enforces this — any POST whose target is not the current `ClaimTarget` returns `409 claim_blocked_by_descendants` with the actual current target's id in the response payload (HS-B0Z7 of HS-VLB8). This is the **vault invariant** that backs the legibility surface in `/hs-next`: the brief always names what is actually claimable, and the claim never silently lands on the wrong level.
+**The single eligibility rule:** *a spec is claimable iff it is its own current `ClaimTarget`*. The console claim endpoint (`POST /api/specs/:id/claim`) enforces this — any POST whose target is not the current `ClaimTarget` returns `409 claim_blocked_by_descendants` with the actual current target's id in the response payload (HS-B0Z7 of HS-VLB8). This is the **vault invariant** that backs the legibility surface in `/hs-next`: the brief always names what is actually claimable, and the claim never silently lands on the wrong level.
 
 ### `ClaimTarget` type
 
 `computeClaimTarget(spec, vaultRoot, alignmentState)` (`vendor/heyspex-mcp/blocker-resolver.mjs`; TypeScript mirror in `spex-console/src/lib/scheduler/claim-eligibility.ts`) returns a 7-field record:
 
-| Field                  | Shape                                                    | Notes                                                                                                                             |
-| ---------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `level`                | `"task" \| "epic" \| "milestone"`                        | What grain the user is actually authorizing.                                                                                      |
-| `spec_id`              | `string`                                                 | The id the user will claim — **not necessarily the spec id `/hs-next` is currently looking at**.                                  |
-| `title`                | `string`                                                 | Display title (frontmatter `name:`).                                                                                              |
-| `intent_verb`          | plain English                                            | "implement it" / "break it into Tasks" / "break it into Epics" — see §Intent verbs below.                                         |
-| `tone_token`           | `--status-neutral \| --status-ready \| --status-pending` | UI tone per HS-6A4P-MNBD-EPIC-milestone-needs-breakdown-awareness.                                                                |
-| `hierarchy_breadcrumb` | `string[]`                                               | Root → leaf id chain (e.g. `["HS-AGEX-MIL", "HS-VQZ8-EPIC", "HS-NJPH-TASK"]`).                                                    |
-| `alignment_state`      | `"fresh" \| "drift_detected" \| "unknown"`               | Transparency only — the alignment gate is upstream; this field reports the gate's verdict on the brief, it does not re-decide it. |
+| Field | Shape | Notes |
+|---|---|---|
+| `level` | `"task" \| "epic" \| "milestone"` | What grain the user is actually authorizing. |
+| `spec_id` | `string` | The id the user will claim — **not necessarily the spec id `/hs-next` is currently looking at**. |
+| `title` | `string` | Display title (frontmatter `name:`). |
+| `intent_verb` | plain English | "implement it" / "break it into Tasks" / "break it into Epics" — see §Intent verbs below. |
+| `tone_token` | `--status-neutral \| --status-ready \| --status-pending` | UI tone per HS-6A4P-MNBD-EPIC-milestone-needs-breakdown-awareness. |
+| `hierarchy_breadcrumb` | `string[]` | Root → leaf id chain (e.g. `["HS-AGEX-MIL", "HS-VQZ8-EPIC", "HS-NJPH-TASK"]`). |
+| `alignment_state` | `"fresh" \| "drift_detected" \| "unknown"` | Transparency only — the alignment gate is upstream; this field reports the gate's verdict on the brief, it does not re-decide it. |
 
 ### The three corollary rules
 
-| Spec kind                                         | Resolution                                                                                                                                                                                                                                                                                    |
-| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Task**                                          | Always its own `ClaimTarget` (level `"task"`).                                                                                                                                                                                                                                                |
-| **Diagnose (not broken down)**                    | Its own `ClaimTarget` (a leaf, level `"task"`-equivalent, intent "implement it"). No parent to recurse from; directly claimable. The one-fix case, and the common one.                                                                                                                        |
-| **Diagnose that spawned work**                    | NOT claimable — `rollup_state: "tracked_by_work"`, carrying `tracked_by` with the specs it spawned. Claim one of those instead. It is not terminal: the bug is still live, and it closes only when its reproduction stops reproducing (HS-ALBV-BFIX-EPIC-breakdown-stage-accepts-a-diagnose). |
-| **Epic with open children**                       | Recurses through `children:` in manifest order; returns the first non-terminal-status descendant. The Epic itself is NOT claimable while it has any open Task.                                                                                                                                |
-| **Epic with no open children** (drained or fresh) | Its own `ClaimTarget` — intent depends on child rollup state (see §Rollup states below).                                                                                                                                                                                                      |
-| **Milestone with open epics**                     | Recurses through `epics:`; returns the first non-terminal descendant (which itself may recurse one more level).                                                                                                                                                                               |
-| **Milestone with no open epics**                  | Its own `ClaimTarget` — intent depends on child rollup state (see §Rollup states below).                                                                                                                                                                                                      |
+| Spec kind | Resolution |
+|---|---|
+| **Task** | Always its own `ClaimTarget` (level `"task"`). |
+| **Diagnose (not broken down)** | Its own `ClaimTarget` (a leaf, level `"task"`-equivalent, intent "implement it"). No parent to recurse from; directly claimable. The one-fix case, and the common one. |
+| **Diagnose that spawned work** | NOT claimable — `rollup_state: "tracked_by_work"`, carrying `tracked_by` with the specs it spawned. Claim one of those instead. It is not terminal: the bug is still live, and it closes only when its reproduction stops reproducing (HS-ALBV-BFIX-EPIC-breakdown-stage-accepts-a-diagnose). |
+| **Epic with open children** | Recurses through `children:` in manifest order; returns the first non-terminal-status descendant. The Epic itself is NOT claimable while it has any open Task. |
+| **Epic with no open children** (drained or fresh) | Its own `ClaimTarget` — intent depends on child rollup state (see §Rollup states below). |
+| **Milestone with open epics** | Recurses through `epics:`; returns the first non-terminal descendant (which itself may recurse one more level). |
+| **Milestone with no open epics** | Its own `ClaimTarget` — intent depends on child rollup state (see §Rollup states below). |
 
 Terminal statuses that block recursion into a descendant: `closed`, `shipped`, `in_review`, `review_pending`, `archived`, `cancelled`, `duplicate`, `hibernated`, `superseded`.
 
-> **A review backlog is never a claim blocker, and never needs owner permission to work past.** `in_review` / `review_pending` are _terminal for recursion_ precisely because they are build-complete — the code is already in the tree. Specs sitting unreviewed are the expected steady state under a batched review grain (`mvp_mode.review_backlog_never_blocks: true`, owner ruling 2026-08-14), so the `ClaimTarget` is claimed on the normal handshake no matter how deep the review queue is. Never tell the owner to Pass/commit first, never offer to redirect the claim, never ask permission to proceed past pending reviews. Only a **real** dependency blocks — the new work needs code or a decision the other spec has not produced yet; name that dependency specifically and keep going. Full rule: session-close-protocol §MVP Mode variant item 5. Enforced in `blocker-resolver.mjs` (`STATUS_SEVERITY` → `soft_review`, never `hard`).
+> **A review backlog is never a claim blocker, and never needs owner permission to work past.** `in_review` / `review_pending` are *terminal for recursion* precisely because they are build-complete — the code is already in the tree. Specs sitting unreviewed are the expected steady state under a batched review grain (`mvp_mode.review_backlog_never_blocks: true`, owner ruling 2026-08-14), so the `ClaimTarget` is claimed on the normal handshake no matter how deep the review queue is. Never tell the owner to Pass/commit first, never offer to redirect the claim, never ask permission to proceed past pending reviews. Only a **real** dependency blocks — the new work needs code or a decision the other spec has not produced yet; name that dependency specifically and keep going. Full rule: [[session-close-protocol]] §MVP Mode variant item 5. Enforced in `blocker-resolver.mjs` (`STATUS_SEVERITY` → `soft_review`, never `hard`).
 
 ### Rollup states (HS-Q7IG)
 
 When every child is terminal (no `open` / `in_progress` descendant), `computeClaimTarget` classifies the parent instead of defaulting to "break it into Tasks/Epics":
 
-| Child rollup                                                                                                                  | `rollup_state`              | Intent verb                                   | Meaning                                                                                                                                                                                     |
-| ----------------------------------------------------------------------------------------------------------------------------- | --------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| No `children:` / `epics:` entries                                                                                             | _(absent)_ or `no_children` | _break it into Tasks_ / _break it into Epics_ | Normal just-in-time breakdown — the happy path.                                                                                                                                             |
-| ≥1 child `in_review` / `review_pending`, rest terminal                                                                        | `reviewer_blocked`          | _wait for reviewer_                           | **Strict (task grain) only:** breakdown/implementation is done but each child still needs its own review before the parent can close. `/hs-next` must **not** offer to claim for breakdown. |
-| Every child build-complete below the active review grain (`in_review` / `review_pending` / `closed`, no `open`/`in_progress`) | `ready_for_close`           | _flip to in_review_                           | **MVP (milestone grain) and Standard (epic grain):** children at `in_review` below the grain are build-complete, not blockers — parent close-out (flip + HS-REV) is claimable.              |
-| Every child `closed` / cancelled / etc., none awaiting review                                                                 | `ready_for_close`           | _flip to in_review_                           | Children are fully terminal; agent close-out is the next write.                                                                                                                             |
+| Child rollup | `rollup_state` | Intent verb | Meaning |
+|---|---|---|---|
+| No `children:` / `epics:` entries | *(absent)* or `no_children` | *break it into Tasks* / *break it into Epics* | Normal just-in-time breakdown — the happy path. |
+| ≥1 child `in_review` / `review_pending`, rest terminal | `reviewer_blocked` | *wait for reviewer* | **Strict (task grain) only:** breakdown/implementation is done but each child still needs its own review before the parent can close. `/hs-next` must **not** offer to claim for breakdown. |
+| Every child build-complete below the active review grain (`in_review` / `review_pending` / `closed`, no `open`/`in_progress`) | `ready_for_close` | *flip to in_review* | **MVP (milestone grain) and Standard (epic grain):** children at `in_review` below the grain are build-complete, not blockers — parent close-out (flip + HS-REV) is claimable. |
+| Every child `closed` / cancelled / etc., none awaiting review | `ready_for_close` | *flip to in_review* | Children are fully terminal; agent close-out is the next write. |
 
 ### Intent verbs (plain English, per user preference)
 
 The on-deck brief uses **plain action verbs** rather than vault jargon ("decompose"). Per feedback_avoid_decompose_in_ux_copy:
 
-| Level                                                    | Verb                  |
-| -------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------ |
-| Task                                                     | _implement it_        |
-| Epic with no children (fresh)                            | _break it into Tasks_ |
-| Epic with all children awaiting review                   | _wait for reviewer_   | Strict (task grain): children must close before parent.                        |
-| Epic with all children build-complete below review grain | _flip to in_review_   | MVP / Standard: claim for parent close-out even when children are `in_review`. |
-| Epic with all children closed (none in review)           | _flip to in_review_   |
-| Milestone with no epics (fresh)                          | _break it into Epics_ |
-| Milestone with all epics awaiting review                 | _wait for reviewer_   |
-| Milestone with all epics closed (none in review)         | _flip to in_review_   |
+| Level | Verb |
+|---|---|
+| Task | *implement it* |
+| Epic with no children (fresh) | *break it into Tasks* |
+| Epic with all children awaiting review | *wait for reviewer* | Strict (task grain): children must close before parent. |
+| Epic with all children build-complete below review grain | *flip to in_review* | MVP / Standard: claim for parent close-out even when children are `in_review`. |
+| Epic with all children closed (none in review) | *flip to in_review* |
+| Milestone with no epics (fresh) | *break it into Epics* |
+| Milestone with all epics awaiting review | *wait for reviewer* |
+| Milestone with all epics closed (none in review) | *flip to in_review* |
 
 System slugs (`uc-decompose-intent`, `extractDecompositionContext`, etc.) keep their identifiers — only the human-facing copy switches.
 
@@ -485,17 +467,17 @@ A drift-detected brief still names a single claimable target; the user picks `[1
 
 ## Related procedures
 
-| Procedure                           | What it covers                                                                           |
-| ----------------------------------- | ---------------------------------------------------------------------------------------- |
-| [[entity-model]]                    | Frontmatter schema, valid status values, valid types, wikilink resolution rules          |
-| vault-id-assignment-protocol        | Random suffix allocation, ID collision handling                                          |
-| plan-ingest-agent-workflow          | Creating specs from implementation plans, manifest registration, linkage validation      |
-| plan-ingest-review-roadmap-workflow | Same flow with a human review gate                                                       |
-| roadmap-protocol                    | How the roadmap manifest is structured, what columns specs render in                     |
-| session-close-protocol              | The `in_review` → `closed` handoff between agent and reviewer                            |
-| [[memory-protocol]]                 | When to file memories (lessons / decisions / references / UI patterns)                   |
-| internal-linking-protocol           | Preserve wikilinks + retrieval signal when re-parenting or restructuring trackable specs |
-| mcp-slash-surface-protocol          | MCP tools the agent uses to interact with the vault                                      |
+| Procedure | What it covers |
+|---|---|
+| [[entity-model]] | Frontmatter schema, valid status values, valid types, wikilink resolution rules |
+| vault-id-assignment-protocol | Random suffix allocation, ID collision handling |
+| plan-ingest-agent-workflow | Creating specs from implementation plans, manifest registration, linkage validation |
+| plan-ingest-review-roadmap-workflow | Same flow with a human review gate |
+| roadmap-protocol | How the roadmap manifest is structured, what columns specs render in |
+| [[session-close-protocol]] | The `in_review` → `closed` handoff between agent and reviewer |
+| [[memory-protocol]] | When to file memories (lessons / decisions / references / UI patterns) |
+| internal-linking-protocol | Preserve wikilinks + retrieval signal when re-parenting or restructuring trackable specs |
+| mcp-slash-surface-protocol | MCP tools the agent uses to interact with the vault |
 
 ## Discovery & enforcement
 
@@ -518,31 +500,31 @@ The robust solution — a procedure registry, an MCP `heyspex_get_procedure` too
 
 ## Change log
 
-| Date       | Author                                                 | Change                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| ---------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 2026-05-27 | pwher (with claude opus 4.7)                           | Initial draft. Codifies the Milestone → Epic → Task → child task hierarchy that was previously implicit. Filed alongside the agent-procedure-discovery planning epic. Status `draft` until reviewed; flip to `open` after first cross-agent use confirms it answers the questions agents actually have.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| 2026-05-28 | pwher (with claude opus 4.8 [1m])                      | Conflict fix (Builder-approved protocol edit): `kind:` enum corrected from `feature\|bug\|spike\|story\|polish` to the scheduler tier vocabulary `infra\|foundation\|feature\|polish` actually read by HS-78E7-Y9OJ-EPIC-deterministic-priority-scheduler and used by every real epic (MILE=infra, M2J3/Y9OJ=foundation). Surfaced during the HS-SSOT-MIL conflict check.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| 2026-05-30 | claude opus 4.7 [1m] · session `local`                 | Added `### Milestone sizing — epic cap` subsection under §What each level is _for_: soft cap 8, at-cap 9–10, hard cap 10, owner-override exception with inline `## Exception — over-cap rationale` requirement, and a filing flow for over-cap proposals. Codifies the previously informal cap surfaced at HS-QOAL-JN9H-TASK-manifest-schema-v3-and-horizon-retirement close-out (PFAG=9, CMCH=11, IART=11). Filed under HS-SP9M-MCAP-TASK-over-cap-milestone-splits-pfag-cmch-iart per HS-OFR5-M2J3-EPIC-introduce-milestones-as-highest-entity; owner permitted the three current over-cap milestones to remain unsplit under the new exception clause.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| 2026-06-03 | claude opus 4.7 [1m] · session `local` (with pwher)    | Added the **"Single-intent test — the deliverable, not the surface count"** clarification under §"What each level is _for_" §Anti-patterns. Per HS-UEF3-S1HX-RES-seo-style-information-architecture-for-t §Q9 findings: a migration epic with N file-tasks is single-intent; a bundled milestone whose acceptance gate names three independently-acceptable ships is multi-intent. Cross-links to doc-canonicalization-protocol + evergreen-doc-architecture-srp-and-seo-pillars so plan-side and doc-side SRP share one principle. One-sentence amendment — explicitly NOT a new plan-side protocol; SSOT for plan-side questions stays in this protocol.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| 2026-06-03 | claude opus 4.7 [1m] · session `local` (with pwher)    | Added the **"Closed specs are historical record — frozen + immutable"** clarification under §"What each level is _for_" §Anti-patterns. User flagged the principle as foundational and previously undocumented: _"Epics are stale once implemented — by design. Immediately locked and frozen and never updated again."_ The principle existed implicitly across four references (supersession-protocol, this protocol's prior anti-pattern about post-close follow-ups, edit-protocol-in-place-with-version-preamble, spec-literal-is-intent-not-literal-update-on-rename); now named explicitly in the foundational memory-decision closed-trackable-specs-are-historical-record-not-living-docs under HS-PILR-pillars. Cross-links to HS-ZUVY-S1A6-EPIC-shipped-surface-closure-event-archive-wi (the console surface that displays the historical record) and to [[entity-model]] §close_reason (the storage convention: archive = filter not folder).                                                                                                                                                                                                                                                                  |
-| 2026-06-04 | claude opus 4.7 [1m] · session `local` (with pwher)    | Reconciled stale "milestones cannot be created via `POST /api/specs`" directive in §Filing procedure (and removed the matching §Open questions / in-flight bullet) after verifying HS-VK7C-MILE-EPIC-milestone-entity-type-and-surfacing and HS-Y855-1AX3-TASK-recognize-milestone-in-console-type-regi both closed 2026-05-31 — `TYPE_TO_FOLDER` now has `milestone: "milestones"` and `createSpec()` handles `type: "milestone"` (`spex-console/src/lib/vault.ts:1263, 1605-1614`). The prior line cited a now-nonexistent `vault.ts:897`, a tell that no agent re-grepped after the implementation moved. Surfaced by the user flagging the directive as a memory candidate for review; rejected the memory because the corrected truth is derivable from current code.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| 2026-06-05 | claude opus 4.7 [1m] · session `local`                 | **T5 added §Claim eligibility & `ClaimTarget`** (HS-VLB8 / HS-IYD8). Codifies the vault invariant _a spec is claimable iff it is its own current `ClaimTarget`_, the 7-field type, three corollary rules (Task / Epic-with-open-children / Epic-empty / Milestone-with-open-epics / Milestone-empty), plain-English intent verbs ("implement it" / "break it into Tasks" / "break it into Epics" — per feedback_avoid_decompose_in_ux_copy), tone tokens linking HS-6A4P, the two SSOT invariants (structural truth from disk; time truth from git), and the upstream/downstream relationship with pre-execution-alignment-gate. Implementation references: `vendor/heyspex-mcp/blocker-resolver.mjs` (HS-USOP), `spex-console/src/lib/scheduler/claim-eligibility.ts` (HS-B0Z7). Also upgraded `heyspex_preflight({ intent: "claim_spec" })` to return this protocol as `required`.                                                                                                                                                                                                                                                                                                                                        |
-| 2026-06-07 | claude opus 4.7 [1m] · session `local` (with pwher)    | **Added §"Sequencing language — disambiguate 'after X'"** under §What each level is _for_. Bans bare "after X" wording in task bodies; requires one of three explicit phrasings ("after X's code lands" / "after X closes" / a behavioral marker). Sets the default-read rule for legacy bare-"after-X" specs to "after X's code lands" (cheapest read in MVP mode where close-out is a reviewer formality). Companion enforcement on the close side (the `### Deferred items audit` subsection in the HS-REV template): session-close-protocol. Driven by the feedback_mvp_mode_after_x_closes_means_after_code_lands incident during HS-7FOD where bare "after DV1T" in the task body led an agent to defer six in-tree edits to a future session for no real gate.                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| 2026-06-18 | claude opus 4.8 [1m] · session `local` (with pwher)    | **Added §"Child rosters live in frontmatter, not prose (single source of truth)"** and amended the milestone/epic §Frontmatter-requirements body lines: a parent's prose body must **not** re-list the child set or hard-code a count (no "## The N epics" roster table, no "all six child epics" wording); the `epics:`/`children:` frontmatter array is the single source of truth, rendered live by the console. Landing order stays allowed as sequencing guidance, not a roster. Owner-approved (option A) fix for HS-FMRH-SVCZ-DIAG-parent-spec-prose-body-drifts-from-its-f — the write path patches the parent's frontmatter array but never re-syncs its body, so any prose roster/count silently drifts (HS-4PTZ-MVMD-MIL-mvp-mode-relax-review-commit-pre-launch body said "six" while its array held nine).                                                                                                                                                                                                                                                                                                                                                                                                     |
-| 2026-06-07 | claude opus 4.7 [1m] · session `local` (with pwher)    | **Added `## Memories` body-convention note** to §Frontmatter requirements per level → Task-specific. Tasks should include a `## Memories` section as the first body section (auto-populated by `POST /api/specs` when filed under an epic parent; hand-authored manually otherwise). Companion of the new step 1c in plan-ingest-agent-workflow and the runtime-injection enricher in HS-U2M6-IMMF-TASK-memory-recall-hardening-runtime-injectio. The two surfaces together (creation-time embedding + runtime injection) cover each other's failure modes — see feedback_creation_time_memory_embedding_complements_runtime_recall.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| 2026-06-13 | claude opus 4.8 [1m] · session `local` (with pwher)    | **Added §"Diagnose — the bug-fix lane"** plus a "What each level is for" row, an Agent-autonomy row ("File a new diagnose"), and a Claim-eligibility corollary row. A `diagnose` (`specs/diagnoses/`, `HS-DIAG-*`) is a user-reported bug fix as a sibling executable entity _outside_ the milestone→epic→task chain: standalone-by-default (exempt from the epic→milestone parent rule), optional epic/milestone `parent:`, always its own leaf `ClaimTarget`, advising the scheduler via `severity:` + `blocks:` (resolution-advises-scheduler-via-severity-and-gating). Ratified by introduction lineage HS-OXBS. Per HS-AO2F-1KZK-RES-bug-fix-resolution-task-entity-model-and.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| 2026-06-20 | claude opus 4.8 [1m] · session `local` (with pwher)    | **Added the "parent milestone must still be accepting work" rule** to §Linkage rules (new paragraph after the bidirectional table) and a clause to the §Agent-autonomy "File a new epic under an existing milestone" row. An epic may only be filed under a milestone that is **not claim-terminal** (`open`/`in_progress`/`draft`/`parked`); filing under an `in_review`/`closed`/… milestone is hard-blocked at `POST /api/specs` / `heyspex_file_spec` with `400 parent_milestone_not_open`, plus a defense-in-depth throw in `createSpec` — back-linking the child would otherwise mutate a frozen parent's `epics:` array (closed-trackable-specs-are-historical-record-not-living-docs). Reuses `CLAIM_TERMINAL_STATUSES` (now exported from `spex-console/src/lib/scheduler/claim-eligibility.ts`) so claim-terminality and child-acceptance are one rule. Owner-approved fix for HS-05ND-2DMM-DIAG-epic-can-be-filed-under-a-non-open-in-re (from capture HS-R22Q-OBO9-CAP-filing-an-epic-under-a-milestone-that-is); scope is prevention-only (existing in-review milestones left as-is) and epic→milestone only.                                                                                                  |
-| 2026-06-20 | claude opus 4.8 [1m] · session `local` (with pwher)    | **Made `summary:` an authoring step of filing** — added "Author `summary:` at file time" to §Frontmatter requirements (after the base-shape line) and a clause to §Filing procedure step 4. A plain-language `summary:` is now written as part of creating every milestone/epic/task, not deferred to claim time (the `/hs-next` claim flow was the only checkpoint, so specs created-but-not-claimed — e.g. the HS-QYXP-PI91-MIL-capture-workflow-v3-fast-brain-offload-h family — slipped through bare). Authoring expectation only, **not** a blocking gate: refuse-to-commit-without-one stays rejected per HS-G7OW-Q3HK-EPIC-spec-frontmatter-summary-field-policy-an. Owner-requested.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| 2026-06-21 | claude opus 4.8 [1m] · session `local` (with pwher)    | **Added §"Why-this-epic-exists rationale"** + an §Epic-specific body bullet. Every epic's `## Why this epic exists` section now carries four plain-language prompts (Problem-right-now, What-this-unlocks, Skip-cost, Confidence) so the scheduler "Why" can surface the _substantive_ priority rationale, not just the mechanical tier/layer order. Rationale **strengthens as a spec rises** (progressive elaboration / Definition-of-Ready): Problem(+Unlocks) at filing, Skip-cost before the on-deck pin — enforced as a **soft pin nudge, never a hard gate**. No numeric scores / no `value`/`time_criticality` frontmatter (the scalar anti-pattern HS-141W-PRIO-RES-priority-and-scoring-systems-2026 rejected); `what_matters` (★/♥) stays the coarse value band and always shows in the Why (`buildWhyNow`). Mirrored in `canonical-frontmatter-templates` §epic + `BODY_SKELETONS.epic` (`spex-console/src/lib/vault.ts`). Research: HS-XMSD-W8OZ-RES-authoring-substantive-priority-rationale; mechanical layer it complements: HS-AVSG-7J97-RES-how-the-scheduler-explains-itself-determ. Owner-approved (soft-nudge option).                                                                                 |
-| 2026-06-22 | Cursor · Composer (with pwher)                         | §Filing procedure step 2: split ID allocation into planning (milestone/epic) vs execution (task at `/hs-next` only). Authoring-phase parity sweep with plan-ingest, skills, and agent contracts.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| 2026-06-24 | Claude Code · session `2a8cade3` (with pwher)          | **Hardened §Linkage rules + §Filing procedure step 5** to make `heyspex_register_spec` a mandatory post-file step. `heyspex_file_spec` does NOT auto-wire `children[]` on the parent; the filed task is invisible in the UI until `heyspex_register_spec(spec_id, parent_id)` writes both sides. Removed the stale "planned, not shipped" note (both tools now ship). Incident: HS-8XZA-LJUP-DIAG-heyspex-file-spec-does-not-auto-wire-chi.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| 2026-06-24 | Cursor · local                                         | **Added shared-suffix family note** under §The four levels (inherits epic suffix; bare `HS-TASK-<suffix>` is a family token; basename required). Cross-links vault-id-assignment-protocol §Shared-suffix families and bare-hs-task-suffix-is-a-family-token-af. (HS-M96C).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| 2026-06-24 | Cursor · local                                         | Cross-linked internal-linking-protocol in §Related procedures + §Linkage rules (re-parent / restructure moves). Implements HS-CGJ6-XPGV-RES-internal-linking-and-wikilink-best-pract.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| 2026-06-25 | claude opus 4.8 [1m] · session `0b396d62` (with pwher) | **(A)** Collapsed §"Milestone sizing — epic cap" from the soft-8 / at-cap-9–10 / hard-10 ladder to a **flat hard cap of 9 epics**, owner-override only; rewrote the rationale to lead with the console Milestone-card **3×3 grid** (scheduler + chip-budget now secondary). **(B)** Added §"Research → milestone/epic filing — default to a new milestone": on the `heyspex_promote_research` path the default is a NEW milestone; attaching to an existing one is a high-bar exception (clear best-fit only). Cross-referenced from research-capture-protocol and plan-ingest-agent-workflow. Both implemented directly off research HS-Q7X7-MDHQ-RES-flat-9-epic-milestone-cap-and-research-t (prose-only, owner-approved).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| 2026-07-07 | Cursor                                                 | **Mandatory NEW-milestone default on research promotion** — expanded §"Research → milestone/epic filing" with decision table + `promote-research.mjs` enforcement (open-only attach; in_progress owner-gated via `attach_to_in_progress_milestone` + `attach_override_reason`). Cross-linked from research-capture-protocol.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Every level carries an intended-outcome section that **cascades by re-derivation, not copy-down**: state the outcome at that altitude, draw an explicit ↑ link to the parent outcome, and name the **mechanism of contribution** (a paste of the parent is "outcome theater"). The **task** outcome must be stated as **monitorable + controllable conditions that seed the `## Acceptance criteria`** — the KAOS leaf-operationalization rule, so acceptance criteria are _derived from_ the outcome, not invented separately. Materializers: `promote-capture.mjs` / `promote-research.mjs` / `BODY_SKELETONS` (epic/task/milestone) in `spex-console/src/lib/vault.ts`. Grounded in HS-K4D4-2I29-RES-outcome-cascade-through-a-requirements-h (GORE/KAOS HOW-down/WHY-up + OKR translate-not-cascade). Companion edits: `research-capture-protocol`, `plan-ingest-agent-workflow`, `canonical-frontmatter-templates`. Owner-directed. |
-| 2026-07-04 | Claude Code (HS-I949-TASK)                             | Added a one-line pointer next to the grain-split empty-state note ("How the empty-state grain-split is surfaced"): breakdown must resolve inbound `amends:` first before decomposing an epic or milestone. See pre-execution-alignment-gate §"Resolve inbound amendments before decomposing" and supersession-protocol §Amends.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| 2026-07-07 | Cursor · Composer (with pwher)                         | **Added §Expected Breakage cascade** under §Expected Breakage & Consequences: milestone (plan ingest) → epic (planning) → task (`/hs-next` breakdown) allocates by altitude; task breakdown must read parent epic + milestone sections (plan-ingest-agent-workflow, pre-execution-alignment-gate; `alignment-gate.mjs` **Expected Breakage — parent context** block). Owner-directed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| 2026-08-14 | Claude Code (Opus 5) · with pwher                      | **§Claim eligibility: added the "review backlog is never a claim blocker" callout.** `in_review` / `review_pending` are terminal-for-recursion because they are build-complete; an unreviewed queue never gates the next claim and never needs owner permission to work past. Mirrors session-close-protocol §MVP Mode variant item 5 and `mvp_mode.review_backlog_never_blocks`. Owner ruling.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| 2026-08-15 | Claude Code (Opus 5) · with pwher                      | **Added §Explain Like I'm 12 (required body section — milestone + epic)**, and added the section to the milestone + epic "Body must include" rows as the FIRST body section. Ten checkable writing properties observed from the approved example held verbatim in heyspex-north-star; milestone links there, epic does not; creation-time only (owner ruled **no backfill** of the ~3,400 existing specs); unfilled scaffold handled at breakdown like `## Expected Breakage & Consequences`, filing is not gated. Classification: template-shape. Owner ruling via HS-KJFZ-Z12C-CAP-every-milestone-and-every-epic-carries-a → HS-W5O3-K8AG-RES-explain-like-i-m-12-as-a-required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| 2026-08-15 | Claude Code (Opus 5) · with pwher                      | **Added §Rule 0 — grounding outranks style**, after the owner caught a drafted section claiming "HeySpex pays a service called Firecrawl". Every one of the ten style properties passed that sentence and it is false. Several style rules actively push toward invention, so Rule 0 now outranks them: every sentence is a rewrite of something the source says, and money / ownership / scale are never inferred. Added §"Written by a machine?" — a grounding critic was built for this and DOES NOT WORK (both DeepSeek V4 Flash and Pro reproduced the same false claim through it), so unattended writing refuses the whole class instead. Revised §Backfill: the no-backfill ruling was widened the same day to open + in_progress milestones and epics, generated sections carry a "not written by the author" marker, and a spec that cannot clear the strict lint is skipped rather than written.                                                                                                                                                                                                                                                                                                                 |
-| 2026-08-22 | Claude Code · session `45051d11` (with pwher)          | **§Diagnose rewritten: the leaf claim is the ONE-FIX case, not the only case.** The old bullet said a diagnose is _always_ its own `ClaimTarget`, which left a bug needing several separate fixes with nowhere to put them. It now says a one-fix write-up is the claimable leaf and a multi-fix one goes through the breakdown stage (`heyspex_promote_diagnose` — the same stage as `heyspex_promote_research`, second input kind), with grounding before sizing, placement descending (epic gets tasks, milestone gets one epic, milestone minted last and owner-confirmed), and a resolvable milestone on everything spawned with no exemption. Two bullets added: **links, not parenting** (`spawned_epics:`/`spawned_tasks:` <-> `derived_from:`; the diagnose's own `parent:` keeps its bug-grouping job and is never touched, because an epic parented to a bug report does not render on the roadmap) and **closes on its reproduction, not on its children**. The claim-eligibility corollary row split in two: a not-broken-down diagnose is the claimable leaf; one that spawned work returns `rollup_state: "tracked_by_work"` and is not claimable. Per HS-ALBV-BFIX-EPIC-breakdown-stage-accepts-a-diagnose. |
+| Date | Author | Change |
+|---|---|---|
+| 2026-05-27 | pwher (with claude opus 4.7) | Initial draft. Codifies the Milestone → Epic → Task → child task hierarchy that was previously implicit. Filed alongside the agent-procedure-discovery planning epic. Status `draft` until reviewed; flip to `open` after first cross-agent use confirms it answers the questions agents actually have. |
+| 2026-05-28 | pwher (with claude opus 4.8 [1m]) | Conflict fix (Builder-approved protocol edit): `kind:` enum corrected from `feature\|bug\|spike\|story\|polish` to the scheduler tier vocabulary `infra\|foundation\|feature\|polish` actually read by HS-78E7-Y9OJ-EPIC-deterministic-priority-scheduler and used by every real epic (MILE=infra, M2J3/Y9OJ=foundation). Surfaced during the HS-SSOT-MIL conflict check. |
+| 2026-05-30 | claude opus 4.7 [1m] · session `local` | Added `### Milestone sizing — epic cap` subsection under §What each level is *for*: soft cap 8, at-cap 9–10, hard cap 10, owner-override exception with inline `## Exception — over-cap rationale` requirement, and a filing flow for over-cap proposals. Codifies the previously informal cap surfaced at HS-QOAL-JN9H-TASK-manifest-schema-v3-and-horizon-retirement close-out (PFAG=9, CMCH=11, IART=11). Filed under HS-SP9M-MCAP-TASK-over-cap-milestone-splits-pfag-cmch-iart per HS-OFR5-M2J3-EPIC-introduce-milestones-as-highest-entity; owner permitted the three current over-cap milestones to remain unsplit under the new exception clause. |
+| 2026-06-03 | claude opus 4.7 [1m] · session `local` (with pwher) | Added the **"Single-intent test — the deliverable, not the surface count"** clarification under §"What each level is *for*" §Anti-patterns. Per HS-UEF3-S1HX-RES-seo-style-information-architecture-for-t §Q9 findings: a migration epic with N file-tasks is single-intent; a bundled milestone whose acceptance gate names three independently-acceptable ships is multi-intent. Cross-links to doc-canonicalization-protocol + evergreen-doc-architecture-srp-and-seo-pillars so plan-side and doc-side SRP share one principle. One-sentence amendment — explicitly NOT a new plan-side protocol; SSOT for plan-side questions stays in this protocol. |
+| 2026-06-03 | claude opus 4.7 [1m] · session `local` (with pwher) | Added the **"Closed specs are historical record — frozen + immutable"** clarification under §"What each level is *for*" §Anti-patterns. User flagged the principle as foundational and previously undocumented: *"Epics are stale once implemented — by design. Immediately locked and frozen and never updated again."* The principle existed implicitly across four references (supersession-protocol, this protocol's prior anti-pattern about post-close follow-ups, edit-protocol-in-place-with-version-preamble, spec-literal-is-intent-not-literal-update-on-rename); now named explicitly in the foundational memory-decision closed-trackable-specs-are-historical-record-not-living-docs under HS-PILR-pillars. Cross-links to HS-ZUVY-S1A6-EPIC-shipped-surface-closure-event-archive-wi (the console surface that displays the historical record) and to [[entity-model]] §close_reason (the storage convention: archive = filter not folder). |
+| 2026-06-04 | claude opus 4.7 [1m] · session `local` (with pwher) | Reconciled stale "milestones cannot be created via `POST /api/specs`" directive in §Filing procedure (and removed the matching §Open questions / in-flight bullet) after verifying HS-VK7C-MILE-EPIC-milestone-entity-type-and-surfacing and HS-Y855-1AX3-TASK-recognize-milestone-in-console-type-regi both closed 2026-05-31 — `TYPE_TO_FOLDER` now has `milestone: "milestones"` and `createSpec()` handles `type: "milestone"` (`spex-console/src/lib/vault.ts:1263, 1605-1614`). The prior line cited a now-nonexistent `vault.ts:897`, a tell that no agent re-grepped after the implementation moved. Surfaced by the user flagging the directive as a memory candidate for review; rejected the memory because the corrected truth is derivable from current code. |
+| 2026-06-05 | claude opus 4.7 [1m] · session `local` | **T5 added §Claim eligibility & `ClaimTarget`** (HS-VLB8 / HS-IYD8). Codifies the vault invariant *a spec is claimable iff it is its own current `ClaimTarget`*, the 7-field type, three corollary rules (Task / Epic-with-open-children / Epic-empty / Milestone-with-open-epics / Milestone-empty), plain-English intent verbs ("implement it" / "break it into Tasks" / "break it into Epics" — per feedback_avoid_decompose_in_ux_copy), tone tokens linking HS-6A4P, the two SSOT invariants (structural truth from disk; time truth from git), and the upstream/downstream relationship with pre-execution-alignment-gate. Implementation references: `vendor/heyspex-mcp/blocker-resolver.mjs` (HS-USOP), `spex-console/src/lib/scheduler/claim-eligibility.ts` (HS-B0Z7). Also upgraded `heyspex_preflight({ intent: "claim_spec" })` to return this protocol as `required`. |
+| 2026-06-07 | claude opus 4.7 [1m] · session `local` (with pwher) | **Added §"Sequencing language — disambiguate 'after X'"** under §What each level is *for*. Bans bare "after X" wording in task bodies; requires one of three explicit phrasings ("after X's code lands" / "after X closes" / a behavioral marker). Sets the default-read rule for legacy bare-"after-X" specs to "after X's code lands" (cheapest read in MVP mode where close-out is a reviewer formality). Companion enforcement on the close side (the `### Deferred items audit` subsection in the HS-REV template): [[session-close-protocol]]. Driven by the feedback_mvp_mode_after_x_closes_means_after_code_lands incident during HS-7FOD where bare "after DV1T" in the task body led an agent to defer six in-tree edits to a future session for no real gate. |
+| 2026-06-18 | claude opus 4.8 [1m] · session `local` (with pwher) | **Added §"Child rosters live in frontmatter, not prose (single source of truth)"** and amended the milestone/epic §Frontmatter-requirements body lines: a parent's prose body must **not** re-list the child set or hard-code a count (no "## The N epics" roster table, no "all six child epics" wording); the `epics:`/`children:` frontmatter array is the single source of truth, rendered live by the console. Landing order stays allowed as sequencing guidance, not a roster. Owner-approved (option A) fix for HS-FMRH-SVCZ-DIAG-parent-spec-prose-body-drifts-from-its-f — the write path patches the parent's frontmatter array but never re-syncs its body, so any prose roster/count silently drifts (HS-4PTZ-MVMD-MIL-mvp-mode-relax-review-commit-pre-launch body said "six" while its array held nine). |
+| 2026-06-07 | claude opus 4.7 [1m] · session `local` (with pwher) | **Added `## Memories` body-convention note** to §Frontmatter requirements per level → Task-specific. Tasks should include a `## Memories` section as the first body section (auto-populated by `POST /api/specs` when filed under an epic parent; hand-authored manually otherwise). Companion of the new step 1c in plan-ingest-agent-workflow and the runtime-injection enricher in HS-U2M6-IMMF-TASK-memory-recall-hardening-runtime-injectio. The two surfaces together (creation-time embedding + runtime injection) cover each other's failure modes — see feedback_creation_time_memory_embedding_complements_runtime_recall. |
+| 2026-06-13 | claude opus 4.8 [1m] · session `local` (with pwher) | **Added §"Diagnose — the bug-fix lane"** plus a "What each level is for" row, an Agent-autonomy row ("File a new diagnose"), and a Claim-eligibility corollary row. A `diagnose` (`specs/diagnoses/`, `HS-DIAG-*`) is a user-reported bug fix as a sibling executable entity *outside* the milestone→epic→task chain: standalone-by-default (exempt from the epic→milestone parent rule), optional epic/milestone `parent:`, always its own leaf `ClaimTarget`, advising the scheduler via `severity:` + `blocks:` (resolution-advises-scheduler-via-severity-and-gating). Ratified by introduction lineage HS-OXBS. Per HS-AO2F-1KZK-RES-bug-fix-resolution-task-entity-model-and. |
+| 2026-06-20 | claude opus 4.8 [1m] · session `local` (with pwher) | **Added the "parent milestone must still be accepting work" rule** to §Linkage rules (new paragraph after the bidirectional table) and a clause to the §Agent-autonomy "File a new epic under an existing milestone" row. An epic may only be filed under a milestone that is **not claim-terminal** (`open`/`in_progress`/`draft`/`parked`); filing under an `in_review`/`closed`/… milestone is hard-blocked at `POST /api/specs` / `heyspex_file_spec` with `400 parent_milestone_not_open`, plus a defense-in-depth throw in `createSpec` — back-linking the child would otherwise mutate a frozen parent's `epics:` array (closed-trackable-specs-are-historical-record-not-living-docs). Reuses `CLAIM_TERMINAL_STATUSES` (now exported from `spex-console/src/lib/scheduler/claim-eligibility.ts`) so claim-terminality and child-acceptance are one rule. Owner-approved fix for HS-05ND-2DMM-DIAG-epic-can-be-filed-under-a-non-open-in-re (from capture HS-R22Q-OBO9-CAP-filing-an-epic-under-a-milestone-that-is); scope is prevention-only (existing in-review milestones left as-is) and epic→milestone only. |
+| 2026-06-20 | claude opus 4.8 [1m] · session `local` (with pwher) | **Made `summary:` an authoring step of filing** — added "Author `summary:` at file time" to §Frontmatter requirements (after the base-shape line) and a clause to §Filing procedure step 4. A plain-language `summary:` is now written as part of creating every milestone/epic/task, not deferred to claim time (the `/hs-next` claim flow was the only checkpoint, so specs created-but-not-claimed — e.g. the HS-QYXP-PI91-MIL-capture-workflow-v3-fast-brain-offload-h family — slipped through bare). Authoring expectation only, **not** a blocking gate: refuse-to-commit-without-one stays rejected per HS-G7OW-Q3HK-EPIC-spec-frontmatter-summary-field-policy-an. Owner-requested. |
+| 2026-06-21 | claude opus 4.8 [1m] · session `local` (with pwher) | **Added §"Why-this-epic-exists rationale"** + an §Epic-specific body bullet. Every epic's `## Why this epic exists` section now carries four plain-language prompts (Problem-right-now, What-this-unlocks, Skip-cost, Confidence) so the scheduler "Why" can surface the *substantive* priority rationale, not just the mechanical tier/layer order. Rationale **strengthens as a spec rises** (progressive elaboration / Definition-of-Ready): Problem(+Unlocks) at filing, Skip-cost before the on-deck pin — enforced as a **soft pin nudge, never a hard gate**. No numeric scores / no `value`/`time_criticality` frontmatter (the scalar anti-pattern HS-141W-PRIO-RES-priority-and-scoring-systems-2026 rejected); `what_matters` (★/♥) stays the coarse value band and always shows in the Why (`buildWhyNow`). Mirrored in `canonical-frontmatter-templates` §epic + `BODY_SKELETONS.epic` (`spex-console/src/lib/vault.ts`). Research: HS-XMSD-W8OZ-RES-authoring-substantive-priority-rationale; mechanical layer it complements: HS-AVSG-7J97-RES-how-the-scheduler-explains-itself-determ. Owner-approved (soft-nudge option). |
+| 2026-06-22 | Cursor · Composer (with pwher) | §Filing procedure step 2: split ID allocation into planning (milestone/epic) vs execution (task at `/hs-next` only). Authoring-phase parity sweep with plan-ingest, skills, and agent contracts. |
+| 2026-06-24 | Claude Code · session `2a8cade3` (with pwher) | **Hardened §Linkage rules + §Filing procedure step 5** to make `heyspex_register_spec` a mandatory post-file step. `heyspex_file_spec` does NOT auto-wire `children[]` on the parent; the filed task is invisible in the UI until `heyspex_register_spec(spec_id, parent_id)` writes both sides. Removed the stale "planned, not shipped" note (both tools now ship). Incident: HS-8XZA-LJUP-DIAG-heyspex-file-spec-does-not-auto-wire-chi. |
+| 2026-06-24 | Cursor · local | **Added shared-suffix family note** under §The four levels (inherits epic suffix; bare `HS-TASK-<suffix>` is a family token; basename required). Cross-links vault-id-assignment-protocol §Shared-suffix families and bare-hs-task-suffix-is-a-family-token-af. (HS-M96C). |
+| 2026-06-24 | Cursor · local | Cross-linked internal-linking-protocol in §Related procedures + §Linkage rules (re-parent / restructure moves). Implements HS-CGJ6-XPGV-RES-internal-linking-and-wikilink-best-pract. |
+| 2026-06-25 | claude opus 4.8 [1m] · session `0b396d62` (with pwher) | **(A)** Collapsed §"Milestone sizing — epic cap" from the soft-8 / at-cap-9–10 / hard-10 ladder to a **flat hard cap of 9 epics**, owner-override only; rewrote the rationale to lead with the console Milestone-card **3×3 grid** (scheduler + chip-budget now secondary). **(B)** Added §"Research → milestone/epic filing — default to a new milestone": on the `heyspex_promote_research` path the default is a NEW milestone; attaching to an existing one is a high-bar exception (clear best-fit only). Cross-referenced from research-capture-protocol and plan-ingest-agent-workflow. Both implemented directly off research HS-Q7X7-MDHQ-RES-flat-9-epic-milestone-cap-and-research-t (prose-only, owner-approved). |
+| 2026-07-07 | Cursor | **Mandatory NEW-milestone default on research promotion** — expanded §"Research → milestone/epic filing" with decision table + `promote-research.mjs` enforcement (open-only attach; in_progress owner-gated via `attach_to_in_progress_milestone` + `attach_override_reason`). Cross-linked from research-capture-protocol. | Every level carries an intended-outcome section that **cascades by re-derivation, not copy-down**: state the outcome at that altitude, draw an explicit ↑ link to the parent outcome, and name the **mechanism of contribution** (a paste of the parent is "outcome theater"). The **task** outcome must be stated as **monitorable + controllable conditions that seed the `## Acceptance criteria`** — the KAOS leaf-operationalization rule, so acceptance criteria are *derived from* the outcome, not invented separately. Materializers: `promote-capture.mjs` / `promote-research.mjs` / `BODY_SKELETONS` (epic/task/milestone) in `spex-console/src/lib/vault.ts`. Grounded in HS-K4D4-2I29-RES-outcome-cascade-through-a-requirements-h (GORE/KAOS HOW-down/WHY-up + OKR translate-not-cascade). Companion edits: `research-capture-protocol`, `plan-ingest-agent-workflow`, `canonical-frontmatter-templates`. Owner-directed. |
+| 2026-07-04 | Claude Code (HS-I949-TASK) | Added a one-line pointer next to the grain-split empty-state note ("How the empty-state grain-split is surfaced"): breakdown must resolve inbound `amends:` first before decomposing an epic or milestone. See pre-execution-alignment-gate §"Resolve inbound amendments before decomposing" and supersession-protocol §Amends. |
+| 2026-07-07 | Cursor · Composer (with pwher) | **Added §Expected Breakage cascade** under §Expected Breakage & Consequences: milestone (plan ingest) → epic (planning) → task (`/hs-next` breakdown) allocates by altitude; task breakdown must read parent epic + milestone sections (plan-ingest-agent-workflow, pre-execution-alignment-gate; `alignment-gate.mjs` **Expected Breakage — parent context** block). Owner-directed. |
+| 2026-08-14 | Claude Code (Opus 5) · with pwher | **§Claim eligibility: added the "review backlog is never a claim blocker" callout.** `in_review` / `review_pending` are terminal-for-recursion because they are build-complete; an unreviewed queue never gates the next claim and never needs owner permission to work past. Mirrors [[session-close-protocol]] §MVP Mode variant item 5 and `mvp_mode.review_backlog_never_blocks`. Owner ruling. |
+| 2026-08-15 | Claude Code (Opus 5) · with pwher | **Added §Explain Like I'm 12 (required body section — milestone + epic)**, and added the section to the milestone + epic "Body must include" rows as the FIRST body section. Ten checkable writing properties observed from the approved example held verbatim in heyspex-north-star; milestone links there, epic does not; creation-time only (owner ruled **no backfill** of the ~3,400 existing specs); unfilled scaffold handled at breakdown like `## Expected Breakage & Consequences`, filing is not gated. Classification: template-shape. Owner ruling via HS-KJFZ-Z12C-CAP-every-milestone-and-every-epic-carries-a → HS-W5O3-K8AG-RES-explain-like-i-m-12-as-a-required. |
+| 2026-08-15 | Claude Code (Opus 5) · with pwher | **Added §Rule 0 — grounding outranks style**, after the owner caught a drafted section claiming "HeySpex pays a service called Firecrawl". Every one of the ten style properties passed that sentence and it is false. Several style rules actively push toward invention, so Rule 0 now outranks them: every sentence is a rewrite of something the source says, and money / ownership / scale are never inferred. Added §"Written by a machine?" — a grounding critic was built for this and DOES NOT WORK (both DeepSeek V4 Flash and Pro reproduced the same false claim through it), so unattended writing refuses the whole class instead. Revised §Backfill: the no-backfill ruling was widened the same day to open + in_progress milestones and epics, generated sections carry a "not written by the author" marker, and a spec that cannot clear the strict lint is skipped rather than written. |
+| 2026-08-22 | Claude Code · session `45051d11` (with pwher) | **§Diagnose rewritten: the leaf claim is the ONE-FIX case, not the only case.** The old bullet said a diagnose is *always* its own `ClaimTarget`, which left a bug needing several separate fixes with nowhere to put them. It now says a one-fix write-up is the claimable leaf and a multi-fix one goes through the breakdown stage (`heyspex_promote_diagnose` — the same stage as `heyspex_promote_research`, second input kind), with grounding before sizing, placement descending (epic gets tasks, milestone gets one epic, milestone minted last and owner-confirmed), and a resolvable milestone on everything spawned with no exemption. Two bullets added: **links, not parenting** (`spawned_epics:`/`spawned_tasks:` <-> `derived_from:`; the diagnose's own `parent:` keeps its bug-grouping job and is never touched, because an epic parented to a bug report does not render on the roadmap) and **closes on its reproduction, not on its children**. The claim-eligibility corollary row split in two: a not-broken-down diagnose is the claimable leaf; one that spawned work returns `rollup_state: "tracked_by_work"` and is not claimable. Per HS-ALBV-BFIX-EPIC-breakdown-stage-accepts-a-diagnose. |