storymapper 0.1.0

package/skill/reference/spec-evolution.md

@@ -0,0 +1,52 @@
+# Spec evolution & test definitions (governance)
+
+> Reference for the Story Mapper skill. The governance model (SM-92/SM-93): how
+> spec changes flow, when test-definitions become runnable, what stops
+> `complete_ticket`. Three layers, each with a different enforcement mode:
+
+| Layer | What it does | Who enforces |
+|---|---|---|
+| **HARD** (tool-blocked) | Returns `isError` with `{kind, errors[], message:{title, reason, suggestion, skillRef}}`. The call doesn't go through. | `publish_test_definition`, `reopen_test_definition`, `test_exec_start`, `complete_ticket`, `ticket_update` (frozen-def case). |
+| **SOFT** (warning) | Response includes `warnings:[{kind, context, message:{…}}]`. The write happens. | `ticket_update` on a `ready+` ticket with a spec patch (acceptanceCriteria / description / definitionOfReady). |
+| **SKILL-only** (this section) | Not enforced by code. Respect it regardless. | Me. |
+
+### Test-definition lifecycle
+A `test-definition` is a feature-bound catalog artifact, not a work item. Two states:
+
+- `draft` — being authored. NOT runnable (`test_exec_start` → `DEFINITION_DRAFT`).
+- `published` — locked in. Runnable. `ticket_update` rejects step/prereq edits
+  (`DEFINITION_FROZEN`); use `update_test_definition_metadata` for cosmetic
+  fields, or the `modifies` path below to evolve the spec.
+
+Promote via `publish_test_definition` (gates: ≥1 step, ≥1 `tests`-link, every
+step has `expectedResult`, target ≥ `ready`). Revert via
+`reopen_test_definition` (blocks with `ACTIVE_EXECUTION` if a run is in-progress).
+
+### Spec changes via `modifies`-tickets, not in-place edits
+When you need to change a ticket's spec AFTER it reached `ready+`:
+
+1. Create a NEW ticket describing the change.
+2. `link_create({sourceTicketId: newTicket, targetTicketId: original, linkTypeId: "modifies"})`.
+3. Work the new ticket.
+4. Linked test-definitions become `derivedHealth: stale`, so the next
+   `complete_ticket` on the original surfaces `STALE_LINKED_DEF` until you re-run
+   the affected definitions via `test_exec_start`.
+
+`modifies` is cycle-checked, giving full traceability of which tickets reshape
+which features.
+
+### Workflow shorthand
+```
+Story (ready+, AC frozen)
+  ↓ derive
+test-definition (draft) → publish_test_definition → published
+  ↓ test_exec_start
+test-execution (in-progress) → record steps → auto-flip to done
+  ↑
+Spec changes? → new modifies-ticket → linked definitions go stale
+                                     → re-run before complete_ticket
+```
+
+When a gate fires, read `message.suggestion` — it spells out the next MCP
+call(s). `get_config` / `set_config` (`section: "governance"`) read/replace the
+config (full replace; unknown predicate names are rejected with `UNKNOWN_PREDICATE`).

package/skill/reference/tools.md

@@ -0,0 +1,156 @@
+# Tool catalogue — when to use what (full detail)
+
+> Reference for the Story Mapper skill. The core SKILL.md (§5) carries a compact
+> one-line index; this file has the full when-to-use tables + response shapes.
+
+**Response shapes — compact by default (SM-123).** To keep token cost low, the
+write tools and reads return a **compact** payload by default and let you opt
+into the full object only when you need it:
+
+- **Ticket-returning mutators** (`ticket_create`, `ticket_update`,
+  `change_ticket_status`, `mark_ready`, `complete_ticket`) return
+  `{revision, savedAt, ticket: {id, ticketKey, type, status, title, position}}`.
+  Pass **`verbose: true`** to get the full ticket (frozen DoR/DoD, AC, links).
+- **`set_checklist_item`** returns just `{revision, savedAt, item: {id, checked}}`;
+  `verbose: true` for the full ticket.
+- **`ticket_get`** returns the full ticket by default; pass `compact: true` for
+  the summary, or `fields: [...]` to pick named fields. **`list_tickets`** takes
+  `compact: true`.
+- `reorder` (tickets), the bulk tools, the link tools, and the test-definition /
+  test-execution step+prereq tools are already compact. The test-definition
+  lifecycle tools (`publish_test_definition`, `reopen_test_definition`,
+  `update_test_definition_metadata`) and `test_exec_start` return the full
+  ticket because their meaningful fields (lifecycle, steps, executionSteps)
+  aren't in the summary.
+
+Rule of thumb: act on the compact response (it carries `id`/`ticketKey`/`status`/
+`position`); only add `verbose: true` when you must read a field the summary
+doesn't carry.
+
+### Discovery — "what is here?"
+Cheap reads, no side effects. Call before acting in an unfamiliar project.
+
+| Tool | When |
+|------|------|
+| `list_projects` | "Show me all projects" / orient yourself first. |
+| `project_get` | Full snapshot of one project. Use sparingly — big payload. |
+| `list_tickets` | Just the tickets. Filters (AND-combined): `status`, `type`, `releaseId`, `processStepId`, `epicId` (resolves via `contains`). Pass `"none"` or `""` for *absence* (backlog tickets, orphans). Pass `compact: true` for `{id, ticketKey, type, status, title, position}` only — shrinks an ~80-ticket project from ~400 KB to ~10 KB. The right read for most "what's in progress" / Map-Check questions. |
+| `list_releases`, `list_process_steps` | Layout dimensions of the story map. |
+| `get_config` | Read a project config section: `section ∈ definitions \| workflow \| kanban_columns \| governance \| link_types`. Returns `{section, value}`. For `section: "workflow"`, pass `type=` for the effective per-ticket-type workflow. |
+| `resolve_definitions_for_ticket` | Effective DoR/DoD for a *specific* ticket (after byType merge + current checked-state). |
+| `list_links_for_ticket` | Links touching a ticket. `direction: forward` (owned) / `backward` (pointing here) / `both`. The impact-analysis workhorse. |
+| `next_actionable` | "What can I start NOW?" — the do-next queue: work items that are `todo`, DoR-met (or already `ready`), and not blocked by an unresolved blocking/precedence predecessor. Optional `releaseId` / `type`. Prefer this over eyeballing `list_tickets` when picking the next task. |
+| `generate_product_doc` | "Describe the product as it stands." Folds the tickets into a Markdown product description — each epic is a feature with its release, derived status (shipped/in-progress/planned), realising stories + AC, and (with `includeTests`) its linked test-definitions + health. Optional `releaseId` scopes to one release; optional `types` is an allowlist of content types — pass e.g. `["epic","user-story","technical-task-backend","technical-task-ui"]` for a PRD so bugs + tests are excluded. It's the deterministic, traceable skeleton (direction B) — narrate/refine the prose yourself. Pass `saveAsAttachment: true` (+ optional `attachmentFilename`) to write the rendered doc back as a project-level attachment — the SM-182 round-trip. |
+| `get_trace_coverage` | Direction-A coverage (mirror of the fold): per requirement, counts incoming `realises` + `tests` and classifies `covered` / `over-covered` / `orphan` / `suspect`. Optional `moduleId` scope. "Is the PRD fully covered, what's missing?" |
+| `get_drift_report` | Round-trip / drift between the PRD and the tickets (SM-182): `orphanRequirements`, `suspectRequirements`, `danglingLinks` (realises/tests anchor whose target was deleted or isn't a requirement), `supersededTrace` (realises anchored on a superseded feature version). `summary.clean=true` = no drift. Run after structural ticket changes, then re-`generate_product_doc` to close the loop. |
+
+### Setup — "let's start"
+| Tool | When |
+|------|------|
+| `project_create` | Brand-new initiative. Pass `id`, `name`, `ticketPrefix`. Optionally seed `workflow`, `definitions`, `ticketTypes`, `entityTypeConfig`. |
+| `project_update` | Patch the project header (name, description, definitions, workflow, boards). |
+| `request_switch_project` | After `project_create`, ask the browser to switch so the user lands on it. |
+| `release_create` | Add a release row. Use real names (`v1.0`, `Beta`). |
+| `process_step_create` | Add a backbone column. Names describe *user-visible value*, not job-titles. |
+| `set_config` | Replace a config section (full replace, no merge): `section ∈ definitions \| workflow \| kanban_columns \| governance \| link_types`, `value` = the new block (object for definitions/workflow/governance, array for kanban_columns/link_types). workflow needs ≥1 status; governance rejects unknown predicates; definitions only affect FUTURE tickets. |
+
+### Authoring tickets — "capture this work"
+| Tool | When |
+|------|------|
+| `ticket_create` | New ticket. Specify `type` + `title`. `position.{releaseId, epicId, processStepId}` to land it in a cell; omit to drop in the backlog. Never go past `status: backlog` on create. **`acceptanceCriteria:[{text}]` IS settable at creation** (SM-260) — no create-then-update. Do NOT pass `prerequisites`/`steps`/`links` arrays here — they no-op through the MCP bridge; use the dedicated tools. |
+| `ticket_update` | Change title, description, labels, `acceptanceCriteria`, type, position, `definitionOfReady`/`definitionOfDone`. AC items use key **`text`**. **Position is a partial merge** (SM-260): patch `{releaseId}` to move the release only — omitted keys are kept, explicit `null` clears. Same array caveat: don't patch `prerequisites`/`steps`/`links` here. |
+| `ticket_delete` | Soft-delete. Stays in revision history; restorable. |
+
+**Acceptance criteria are a first-class field, never inline prose.** Every
+testable expectation goes into `acceptanceCriteria[]` as a discrete item — NOT
+bullets inside `description`. Reasons:
+
+- The Ticket-Detail Modal renders `acceptanceCriteria[]` as a sortable,
+  individually-editable list. AC in prose are invisible to that UI and to the
+  DoR/DoD machinery.
+- The DoR-item *"Acceptance criteria are defined"* is meant to be satisfied by
+  the array being populated. AC in prose make the DoR check vacuously true while
+  the ticket is actually unready.
+- AC are the contract for `complete_ticket` — a reviewer reads them as a
+  checklist; a wall of prose can't serve that.
+
+Pass `acceptanceCriteria` as objects `{text: "..."}` (the system fills `id` and
+`completed: false`). Keep the description for *context* (the why, the symptom,
+constraints). When you meet an older ticket with AC in the description, migrate
+them into the array, trim the prose section, then check `dor-acceptance`.
+
+### Typed links — "express dependencies + traceability"
+| Tool | When |
+|------|------|
+| `link_create` | Add `source --linkTypeId--> target`. Cycle-checked for precedence/blocking/containment/`modifies`. Throws `LINK_SELF`, `LINK_TARGET_MISSING`, `LINK_DUPLICATE`, `LINK_CYCLE`. Use the specific type. |
+| `link_delete` | Remove a link by `linkId` (no-op if gone). |
+| `list_links_for_ticket` | Read links (see Discovery). Use before structural edits — every backward link is something you may break. |
+| `get_config` / `set_config` (`section: "link_types"`) | Read / replace the catalogue. |
+
+Containment (epic→story) is set via `position.epicId` at create time, NOT
+`link_create`.
+
+### Movement — "reorganise"
+| Tool | When |
+|------|------|
+| `reorder` (`entity: "tickets"`) | Pure ordering OR bulk move into a cell/epic. `orderedIds[]` + optional `scope: {releaseId, processStepId, epicId}`. With `scope`, every listed ticket moves into that container (setting `scope.epicId` creates the `contains` link); without it, only `sortOrder` changes. The tool for "drag this story into that epic", "shuffle backlog priorities", "move the whole epic into another release". |
+| `reorder` (`entity: "releases"` / `"process_steps"`) | Same idea for the story-map dimensions (no `scope`). |
+
+### Bulk operations — "do this to many at once"
+Best-effort by default (per-item failures reported, the rest proceed); pass
+`opts.atomic: true` to roll back all on any failure.
+
+| Tool | When |
+|------|------|
+| `bulk_change_status` | Move many tickets to one `targetStatus`. Per-item gate validation; failures return their `kind`/`missing`. |
+| `bulk_ticket_update` | Apply one `patch` to many tickets. Respects spec-frozen gates; collects `SPEC_FROZEN_EDIT` warnings. |
+| `bulk_link_create` | Create the same `linkTypeId` from many `sourceTicketIds[]` to one `targetTicketId` (e.g. tag many tickets as `modifies` one feature). |
+
+### Workflow transitions — "advance this ticket"
+| Tool | When |
+|------|------|
+| `change_ticket_status` | Generic status change. Respects DoR/DoD gates if the transition has them. |
+| `mark_ready` | Shortcut for `→ ready`. Surfaces a clear `kind: "DoR", missing[]` on gate failure. |
+| `complete_ticket` | Shortcut for `→ done`. ALWAYS use this (not `change_ticket_status: done`) so the DoD + governance gates fire explicitly. Coding-agent contract. Pass `checkDoD:true` (SM-260) to tick every required DoD item in the same call instead of N× `set_checklist_item` — but only when those items are genuinely true (don't auto-tick an "independent review" item that didn't happen). |
+| `set_checklist_item` | Check/uncheck a single DoR/DoD item: `gate: "dor"\|"dod"`, `checked: true\|false`. Inline-persisted. Compact response by default (`{item:{id,checked}}`); pass `verbose:true` for the full ticket. |
+
+### Test types — "specify once, run repeatedly"
+The **definition** is reusable and carries the spec; the **execution** is
+per-run and carries the result.
+
+| Tool | When |
+|------|------|
+| `ticket_create type=test-definition` | New test spec. After create, `link_create … tests …` to the feature it validates (the gate enforces this before it can leave backlog). |
+| `test_def_prereq_add` / `test_def_prereq_update` / `test_def_prereq_remove` | Manage the prerequisites list. |
+| `test_def_prereq_check` / `test_def_prereq_uncheck` | Tick a prereq on the definition itself (rare — usually checked on the execution). |
+| `test_def_step_add` / `test_def_step_update` / `test_def_step_remove` / `test_def_step_reorder` | Manage the 3-tuple steps (`step` / `data` / `expectedResult`). Use `_reorder`, never `ticket_update`. |
+| `publish_test_definition` | Promote `draft → published` (runnable). Fires gates (≥1 step, ≥1 `tests`-link, every step has `expectedResult`, target ≥ `ready`). |
+| `reopen_test_definition` | Demote `published → draft`. Blocks (`ACTIVE_EXECUTION`) if a run is in-progress. |
+| `update_test_definition_metadata` | Edit title/description/labels on a published definition (spec stays frozen). |
+| `test_exec_start` | Spawn an execution from a published definition. Clones steps, links `executes` → definition, starts `in-progress`. |
+| `test_exec_record` | Record one step: `{status, actualResult, note?}`. Status auto-flips to `done` when the outcome settles. |
+| `test_exec_set_outcome` | Manual outcome override. Pass `"auto"` to clear. Status syncs. |
+| `test_exec_history` | Past runs of a definition, reverse-chrono. "Did this ever pass?" |
+
+### Attachments — "binary reference docs (PRDs, designs)"
+Files live on disk next to the DB; the agent reads/writes them over the channel
+(base64 for small, a downloadUrl for large) — never via filesystem paths.
+
+Two scopes: **project-level** (omit `ticketId`) for an initiative-wide source
+doc like a PRD/PLD, and **ticket-level** (pass `ticketId`) for an item-specific
+doc. There are no free-floating attachments — every one belongs to a project,
+optionally to a ticket.
+
+| Tool | When |
+|------|------|
+| `attachment_put` | Upload a binary (base64): `{projectId, filename, contentBase64, mimeType?, ticketId?}`. Max 25 MB. **OMIT `ticketId` for a project-level source PRD/PLD** — that's how you bring a spec into the tool to read + decompose it. Pass `ticketId` only to attach to one specific ticket. |
+| `attachment_list` | Metadata only (no content). `ticketId` scopes to one ticket; `ticketId:"none"` lists project-level attachments only; omit for everything. |
+| `attachment_get` | Always returns metadata + `downloadUrl`; inlines `contentBase64` for files ≤256 KB. For a big PDF, fetch the URL out-of-band instead of bloating the context. |
+| `attachment_delete` | Remove an attachment by id. |
+
+### Reflection — "look back"
+| Tool | When |
+|------|------|
+| `list_revisions` | Reverse-chrono history. Each entry has an `op` label + `actor`. |
+| `get_revision` | Inspect a single revision's snapshot. |
+| `restore_revision` | Roll back to a revision. Creates a NEW revision (itself undoable). **Confirm with the user first.** |

package/skill/reference/workflows.md

@@ -0,0 +1,203 @@
+# End-to-end workflows
+
+> Reference for the Story Mapper skill. The core SKILL.md (§4) carries the
+> discipline rules; this file has the step-by-step playbooks.
+
+### Plan a new initiative (greenfield)
+1. `project_create` with a kebab-case `id`, a human `name`, a `ticketPrefix`.
+2. `request_switch_project` so the user lands on it.
+3. `release_create` at least one release (a v1, or "MVP").
+4. **Decompose the user's journey FIRST**, then `process_step_create` one step
+   per *distinct phase* the user (or agent) passes through, in order. Err toward
+   MORE, finer phases — coarse catch-all steps (e.g. just 3 buckets) cram many
+   unrelated epics into one column and lose the journey's shape. Each step =
+   "what kind of value happens here", never the team's org chart. Decompose the
+   journey before placing any epics/stories, so each lands at the right phase.
+5. Optionally `set_config` (`section: "workflow"` / `"definitions"`) if the defaults don't fit.
+6. Capture top-level features as `ticket_create type=epic`, drop into cells via
+   `reorder` with `scope`.
+7. Decompose each epic into 2–6 stories (`ticket_create type=user-story`,
+   created in backlog), then `reorder` with
+   `scope: {releaseId, processStepId, epicId}` to land them under the epic.
+8. **Link as you go** — `link_create` `predecessor-of` / `blocks` between
+   stories with real ordering or dependency. This powers the Dependency view and
+   sprint sequencing.
+9. Pause. Let the user see the structure. Talk through it.
+
+### Decompose a source PRD/PLD into tickets (direction A) — the requirements layer
+When the starting point is a written spec (a PRD/PLD), the doc precedes the
+tickets. Don't decompose straight into epics/stories — first turn the document
+into a **traceable requirements layer** (DOORS/ReqIF-style): the source is
+sliced into atomic `requirement` SpecObjects that become the addressable truth,
+and implementation tickets anchor back to them. The doc itself stays as
+provenance; the slice chain is what you trace against.
+
+**Slicing is two-stage, and the second stage is yours.** The server does a
+*structural* coarse-slice at headings; you do the *content* analysis that turns
+each coarse slice into the atomic requirements it actually contains. Don't
+mistake one heading section for one requirement — a single section usually
+bundles several testable assertions. One coarse slice → **1..n** requirements.
+
+1. **Bring the spec in.** `project_create` → `attachment_put` with the PRD **and
+   no `ticketId`** (omitting it = project-level). In the browser the user can do
+   the same: the New-project dialog has a dropzone, and Project ▸ Attachments…
+   manages project-level docs.
+2. **Stage 1 — coarse-slice (the server, structural).**
+   `ingest_slice_candidates` on the attachment id → the server converts it to
+   Markdown (officeparser-free stack: md/txt native, docx via fflate, pdf via
+   pdf2json — no OCR, no CDN) and pre-slices at headings into an ordered list of
+   candidate sections, each with a DOORS-style `sectionPath` ("2.1") + char
+   range. This is purely structural — every heading becomes one candidate, so
+   nothing is silently dropped. There is **no H1 special-case**: the numbering is
+   structural (depth-based), and a document with a single H1 wrapper is fine —
+   the generalisation to "what is actually a requirement" happens in stage 2, not
+   by reshaping the slice tree.
+3. **Open a spec module.** `spec_module_create` with `title` +
+   `sourceAttachmentId` — the per-document container (DOORS module). Its
+   requirements are board-excluded and ordered by sectionPath.
+4. **Stage 2 — content analysis (you, the agent).** Read each coarse slice's
+   prose and identify the individual atomic requirements inside it — **one
+   `requirement_create` per testable assertion**, not one per heading. A slice
+   that says "the user can log in with email+password, reset a forgotten
+   password, and stay signed in for 30 days" is **three** requirements, not one.
+   For every requirement you extract from a slice:
+   - pass the **slice's `sectionPath`** (all requirements distilled from the same
+     coarse slice share it — that is what groups them under the source section in
+     View ▸ Requirements);
+   - pass `sourceAnchor` `{attachmentId, sectionId, charStart, charEnd}` pointing
+     at the **specific span** that requirement came from (the n requirements of
+     one slice differ here — distinct char-ranges within the slice). `sectionId`
+     is provenance only; set it to the slice's `sectionPath` for consistency.
+     Grouping into the document section is driven by the requirement's own
+     `sectionPath`, never by `sectionId` — so the span is what distinguishes the
+     n requirements, and `sectionPath` is what keeps them together.
+   The requirement IS the unit of truth — not the doc, and not the coarse slice.
+   A coarse slice with only boilerplate/intro prose may yield **zero**
+   requirements — that's a legitimate gap, not a miss.
+5. **Build + anchor traceability.** As you implement, `link_create` **`realises`**
+   from the implementing story/epic → the requirement (DOORS *satisfies*), and
+   `tests` from a test-definition → the requirement (*validates*). Anchor as you
+   create, not after.
+6. **Check completeness + correctness.** `get_trace_coverage` (optionally
+   `moduleId`-scoped) classifies every requirement: `covered` (1 realises) /
+   `over-covered` (>1) / `orphan` (none) / `suspect` (tested, not implemented).
+   The user reviews in **View ▸ Requirements** — a full-page DOORS module view:
+   source prose next to each slice (verify the slicing is faithful), un-sliced
+   sections flagged as gaps (verify completeness), coverage badge + clickable
+   realising/testing tickets per requirement, inline-editable statements, and a
+   "create implementing ticket" action on orphans.
+7. **Keep it a living document — round-trip + drift (SM-182).** As the tickets
+   evolve after the first slice, the doc and the code drift apart. `get_drift_report`
+   (optionally `moduleId`-scoped) surfaces four signals on the trace graph:
+   `orphanRequirements` (a requirement no ticket realises), `suspectRequirements`
+   (only `tests`, no implementer), `danglingLinks` (a realises/tests anchor whose
+   target was deleted or isn't a requirement), and `supersededTrace` (a realises
+   anchored on a superseded/historical feature version — the implementation moved
+   on but the anchor stayed). `summary.clean=true` means no drift. Run it after
+   structural ticket changes; fix the anchors; then **regenerate the doc** with
+   `generate_product_doc { saveAsAttachment: true }` to write the current
+   description back as a project-level attachment next to the source PRD — the
+   loop closes.
+8. **Pause before mass-creating** — same rule as greenfield. Slice + propose the
+   requirement chain, let the user see it, then build.
+
+`tests/mcp-prd-slicing-demo.js` drives this whole round from an example PRD
+(`npm run prd-demo`); pass `--data-dir=./.storymap-data --http-url=…` to watch
+it populate a live browser via `request_switch_project`.
+
+### Execute a sprint
+1. **Map-Check first.** `list_tickets status="backlog"` (add `compact:true`)
+   sorted by `sortOrder` — the user may have shuffled since my last read.
+2. Propose the next-priority ticket to the user. Wait for confirmation.
+3. Once confirmed: check DoR via `resolve_definitions_for_ticket`.
+4. `set_checklist_item` (gate `"dor"`, checked:true) for each required item that's met.
+5. `mark_ready` to graduate the story. (Gate failure tells you which items are
+   missing — relay them.)
+6. As the user picks it up: `change_ticket_status → in-progress`.
+7. When up for review: `→ review`.
+8. `set_checklist_item` (gate `"dod"`, checked:true) for each met item.
+9. `complete_ticket` — DoD + governance gates fire, ticket lands in *Done*.
+10. After done: stop. Go back to step 1 (Map-Check) before the next ticket —
+    **unless** the bundle rule below applies.
+
+For a batch of already-ready stories, `bulk_change_status` moves them together.
+
+### Bundle related stories — don't pause after every data-layer ticket
+Within an epic (or a logical implementation sequence), implement **related
+stories in one bundle** instead of stopping after every ticket. Stopping after
+every "done" shreds multi-story work into pauses with no signal value.
+
+**Auto-complete criteria** (decide per-story):
+
+- **Pure data-layer / MCP-tool / core-op / validation story** — no UI change,
+  no visible browser effect, AC fully covered by automated tests, all green →
+  check DoD + `complete_ticket` directly, then continue to the next story.
+  Surface the auto-complete decision in the reply + commit message.
+- **UI story** — ALWAYS pause for the user to smoke. The visible effect IS the
+  verification; without a human in the loop the DoD-review item has no signal.
+- **Hybrid story** — auto-complete the data-layer sub-steps; the final pause
+  comes for the UI smoke at the end.
+
+**Bundle flow**: pick the lead story → Map-Check → walk all stories, deciding
+auto-complete vs. user-smoke per story → mid-bundle commits (especially before a
+UI-touching story, for a clean rollback point) → pause at the bundle end (or
+when the next story needs UI smoke). The **first** ticket of a bundle is still
+proposed + confirmed; only *subsequent purely-automatable* stories skip the
+user-pause while their tests are green.
+
+### Plan from dependencies — sequence + impact + traceability
+- **Sequence + ready-pick**: capture the work as tickets, add typed links for
+  the relationships you know (`predecessor-of` when B depends on A's outcome,
+  `blocks` when A gates B, `relates-to` for soft cross-refs). The Dependency
+  view shows which tickets are ready (no unresolved upstream) — pick from the
+  ready set, preferring nodes that unblock the most downstream work. (`next_actionable`
+  computes this ready set directly.)
+- **Impact analysis** (before a structural change): `list_links_for_ticket` on
+  the ticket you're about to touch — every **backward** link depends on current
+  behaviour and may break. Do this before renames, type changes, deletions,
+  API-surface changes.
+- **Traceability**: from a goal (epic) walk `contains` into stories, then
+  domain links into the tickets that realise it. Answers "is feature X covered?"
+- **Link as you create**: when a ticket depends on another, add the link
+  *immediately* — hidden dependencies become surprise blockers.
+
+### Validate a feature with the test loop
+Tests are tickets in the same workflow you already manage.
+
+1. **Define once.** `ticket_create type=test-definition` with a clear title;
+   `link_create … tests …` to the feature; fill prereqs + steps
+   (`step` / `data` / `expectedResult`) via `test_def_prereq_add` /
+   `test_def_step_add`. The definition has NO outcome.
+   `publish_test_definition` when complete.
+2. **Run.** `test_exec_start(definitionId, env?)` clones steps into a new
+   test-execution (status `in-progress`), links `executes` → definition. Cloned
+   steps are frozen — they reflect the definition at run time.
+3. **Record.** Walk steps: `test_exec_record(execId, stepId, {status,
+   actualResult, note?})`.
+4. **Auto-coupling.** Once every step is non-pending (or `outcomeOverride` set),
+   the execution auto-flips to `done`; the browser pill updates live.
+5. **Iterate on failure.** Fix the code, then `test_exec_start` AGAIN — a NEW
+   execution. The failed run stays in history as a permanent record.
+6. **Close the feature.** Only `complete_ticket(featureId)` after a passing
+   execution exists. Check via `test_exec_history(definitionId)`.
+
+Don't skip the loop because the change "feels small" — even pure-data tickets
+benefit from a 2-step definition (does it parse? does it round-trip?), a
+permanent regression-net contribution.
+
+### Reorganise
+- *"Split this epic"* → `ticket_create` smaller stories, `reorder` them
+  under the original epic, optionally `ticket_delete` the original if it's now
+  just a label. (A native split-epic tool is roadmap, not built — do it by hand.)
+- *"Move epic A into another release"* → `reorder` with
+  `scope: {releaseId: newR, processStepId: <epic's step>, epicId: null}`.
+- *"Bump this story up the backlog"* → `reorder` with the new
+  `orderedIds[]`, no scope.
+- Before any of these, `list_links_for_ticket` / the Dependency view to see what
+  depends on what.
+
+### Look back
+- `list_revisions` to see what happened since the last meeting.
+- `get_revision` on an entry to compare snapshots.
+- `restore_revision` to roll back. **Always confirm first** — it clobbers
+  current state (though it's itself undoable).