orbitmap 0.5.0 → 0.7.0

package/dist/agent-instructions.js

@@ -137,13 +137,49 @@ TL;DRs, areas, mission, task counts, the pair). Pair unchanged → the intent ha
 moved: SAY SO in one line and keep working from what you hold — no full fetch. Pair
 changed → re-fetch (\`intent show IN-x\`, with \`--no-logs\` when the log tail is not
 needed) and remember the new pair in the focus file.`;
+// ── Shared block: the KEEP/DROP TEST (IS-vw765j) ───────────────────────────────
+//
+// ONE definition rendered into all four gate skills. It used to be four byte-identical
+// copies, which is why the contradiction below survived so long: `code_change` is a
+// caller-authorable type, yet the drop list forbade exactly what such an entry is — a
+// fact git already holds. Six worker-built tasks on IN-5pdqkq produced 1 blocker, 8
+// decisions, 12 notes and ZERO code_change entries, every worker obeying the rules
+// correctly. The exemption below resolves it; keeping the block in one place is what
+// makes the next correction a one-line change.
+//
+// The bullet indent differs between skills (execute uses `- `, the three gate skills
+// `   - `), so the caller passes it in; continuation lines sit two spaces further in.
+export function worklogKeepDropTest(indent = '') {
+    const c = `${indent}  `;
+    return `${indent}- KEEP/DROP TEST — log a \`decision\` when ANY of these is true: an alternative was
+${c}considered and REJECTED (record which, and why it lost); a non-obvious assumption or
+${c}constraint was LOCKED IN; a choice was made that a later reader would otherwise
+${c}re-litigate. Do NOT log: restating the outcome, design or plan (they are already
+${c}fields on the intent); confirming something already written down elsewhere; mechanical
+${c}facts recoverable from git, CI or the tracker (test counts, file lists, commit hashes);
+${c}progress narration ("started X", "working on Y").
+${c}KEEP → "Parallelised the build across four subagents; the Laravel slices were split by
+${c}file ownership to avoid collisions in one working tree." — records the rejected
+${c}alternative (one agent per repo) and why it lost.
+${c}DROP → "make verify green at 2415 passed after merging all four agents." — a mechanical
+${c}fact already in the commit message and the CI output.
+${c}EXEMPTION — \`code_change\` is the one type the "mechanical facts" rule does NOT
+${c}forbid. Work that ships closes with ONE entry naming WHAT shipped and where: the
+${c}shape of the change, never a file listing, which the \`[TS-x]\` commit already
+${c}carries. Use it too for changes git CANNOT see — a config flipped in a dashboard, a
+${c}migration run against a live database, an external system mutated. Without this a
+${c}task records why every decision was made and never what was built.`;
+}
 // ── Skill: orbitmap (core) — §8.3 ──────────────────────────────────────────────
 export const SKILL_ORBITMAP_FRONTMATTER = `---
 name: orbitmap
 description: >
-  OrbitMap project management via the orbitmap CLI. Use when the user mentions OrbitMap,
-  orbit, tasks, backlog, missions, intents, ideas, issues, vibes, or asks to track,
-  plan, or log work. Entry point: object model, context resolution, command reference.
+  OrbitMap project management via the orbitmap CLI — the entry point other orbitmap-*
+  skills require. Use whenever the user wants to build, add, change or fix something, in
+  whatever words they use — do not wait for OrbitMap vocabulary — as well as when they
+  mention OrbitMap, orbit, tasks, backlog, missions, intents, ideas, issues, vibes, or ask
+  to track, plan, or log work. Covers the object model, context resolution, and command
+  reference.
 ---`;
 export const SKILL_ORBITMAP_BODY = `# OrbitMap CLI — core
 
@@ -164,10 +200,9 @@ MCP tool schemas are the authority. Never edit the workspace data files directly
 ## General behaviour
 - Always prioritise the user's direct request. If the user asks you to do something
   (read a file, write code, answer a question), handle that first.
-- Only interact with OrbitMap when the user explicitly asks you to (e.g. "check my
-  tasks", "start a task", "what's on my backlog", "log this idea").
 - When the user mentions OrbitMap, orbit, task, backlog, or project-management concepts
-  in the context of tracking work, use \`orbitmap\` commands to handle the request.
+  in the context of tracking work — in whatever words they use — use \`orbitmap\` commands
+  to handle the request.
 
 ## Object model
 - Workspace = team level. Area = repo-level scope (formerly Project) — tasks, vibes and
@@ -177,6 +212,14 @@ MCP tool schemas are the authority. Never edit the workspace data files directly
   outside a task. Task (TS-) = unit of work.
 - Entity numbers (TS-xxxxxx etc.) are accepted by every command that takes an id.
 
+## Naming workitems in output
+Refer to a workitem by its NAME together with its key, at first mention in any message,
+summary or report — "Align skills and validators (IN-b2h63q)". NEVER a bare key: a key
+alone is unreadable to the user, who tracks the work by name. Keep no key-to-name mapping
+anywhere — not in a file, not in memory. Every list, \`show\` and context response already
+pairs the two, so take the name from the response you already have; if you do not have it,
+fetch the item rather than emitting the key on its own.
+
 ${SESSION_FOCUS_SECTION}
 
 ${FRESHNESS_SECTION}
@@ -189,10 +232,9 @@ ${FRESHNESS_SECTION}
   lists and no bodies — fetch deeper on demand (\`orbitmap intent show IN-x\`,
   \`orbitmap tasks --intent IN-x\`, \`orbitmap doc <slug>\`). Never list areas and never
   ask the user "which area?" before you have read it.
-- You work in a WORKSPACE, not inside a single area. Missions, intents
-  and documents are workspace-level and take no area — a document is exactly ONE copy,
-  global to the workspace, never per-area. Tasks, vibes, issues and ideas are
-  AREA-scoped.
+- You work in a WORKSPACE, not inside a single area. Missions and intents are
+  workspace-level and take no area. Documents live at area OR workspace level.
+  Tasks, vibes, issues and ideas are AREA-scoped.
 - Missions and intents outrank individual tasks. Asked to work on "what matters", take the
   active mission and open intents from context and pick work that serves them.
 - The area follows from the directory, never from a question to the user:
@@ -248,7 +290,7 @@ backlog, todo, in_progress, in_review, review_changes, done, blocked.
 - Tasks: \`orbitmap tasks [--status s1,s2] [--intent IN-x]\`, \`orbitmap task TS-x\`,
   \`orbitmap get <ID>\`,
   \`orbitmap start [TS-x]\`, \`orbitmap status TS-x <status> [--delivery <d>]\`,
-  \`orbitmap create "title" [--intent IN-x|--mission MS-x] [--priority p]\`,
+  \`orbitmap create "title" [--intent IN-x] [--priority p]\`,
   \`orbitmap subtask TS-parent "title"\`, \`orbitmap assign TS-x [agent]\`,
   \`orbitmap dep add|remove TS-a TS-b\`, \`orbitmap log TS-x "msg" --type <t>\`
 - Issues: \`orbitmap issue register|list|show|status|resolve\`
@@ -276,7 +318,7 @@ description: >
   the user's), and "work on TS-x" runs a single tracked task (starting/resuming,
   logging, finishing with the correct status, git branches and delivery status). Use
   whenever executing a planned intent or implementing, resuming, or finishing a
-  tracked task.
+  tracked task. Requires the \`orbitmap\` core skill.
 ---`;
 export const SKILL_EXECUTE_BODY = `# Executing OrbitMap work
 
@@ -393,13 +435,18 @@ MCP tool schemas are the authority. Never edit the workspace data files directly
    delivered or honestly blocked and the gates are green vs baseline. An unfixable intent
    test or a design contradiction → STOP and ask the user: that is intent-level risk, the
    one thing that interrupts.
-8. **Report + resume note.** Leave every repo checked out on its BASE branch — the
-   intent branch is named in the report, not left underfoot. Report in chat: what
-   shipped, what was decided, what is blocked and why, deviations from the plan, gate
-   results vs baseline. Write ONE resume
-   point: \`orbitmap log IN-x "Resume point: …" --type note\`. The intent STAYS \`build\`;
-   merging and closing are the USER'S. The merge EVENT — whoever performs it — is what
-   later flips the tasks to \`--delivery merged\`.
+8. **Report + move the intent to in_review.** Leave every repo checked out on its BASE
+   branch — the intent branch is named in the report, not left underfoot. Report in
+   chat: what shipped, what was decided, what is blocked and why, deviations from the
+   plan, gate results vs baseline. Write ONE resume
+   point: \`orbitmap log IN-x "Resume point: …" --type note\`. Before the transition, run
+   \`orbitmap intent show IN-x --slim\` and verify every task is \`in_review\`, \`done\`, or
+   \`blocked\` with a logged blocker — an \`in_progress\` task means a fold step was
+   skipped; fix it before moving on. Then end the run:
+   \`orbitmap intent update IN-x --status in_review --log <entries>\` — the transition's
+   response carries an Instructions section (it will ask for release notes); FOLLOW it.
+   Merging and closing to \`done\` are the USER'S. The merge EVENT — whoever performs
+   it — is what later flips the tasks to \`--delivery merged\`.
 
 **No subagent runtime?** Same flow, serial: do steps 4–7 yourself, task by task, with the
 worker contract as your own build rules. The contract is the outcome, not the parallelism.
@@ -421,7 +468,7 @@ digraph orbitmap_execute {
     "Regressions or intent-test failures?" [shape=diamond];
     "Fix findings, scoped tests per fix" [shape=box];
     "Intent-level risk: stop and ask the user" [shape=box];
-    "Report + resume note; intent stays build; user merges" [shape=doublecircle];
+    "Report + resume note; intent update --status in_review; user merges" [shape=doublecircle];
 
     "Premise: intent at build, tasks with instructions?" -> "Refuse politely; point at the missing gate" [label="no"];
     "Premise: intent at build, tasks with instructions?" -> "Baseline: full gate per touched repo, results recorded" [label="yes"];
@@ -439,7 +486,7 @@ digraph orbitmap_execute {
     "Regressions or intent-test failures?" -> "Fix findings, scoped tests per fix" [label="yes"];
     "Fix findings, scoped tests per fix" -> "Impact pass: full gate per repo, diff vs baseline (+contract steps)" [label="re-run"];
     "Fix findings, scoped tests per fix" -> "Intent-level risk: stop and ask the user" [label="unfixable / contradiction"];
-    "Regressions or intent-test failures?" -> "Report + resume note; intent stays build; user merges" [label="no"];
+    "Regressions or intent-test failures?" -> "Report + resume note; intent update --status in_review; user merges" [label="no"];
 }
 \`\`\`
 
@@ -476,18 +523,7 @@ digraph orbitmap_execute {
   \`blocker\` goes in as \`note\`, with \`--meta\` carrying any unusual structure. There is
   deliberately NO \`other\` type. NEVER write \`status_change\` — the server authors it on
   every transition and the API rejects it from clients.
-- KEEP/DROP TEST — log a \`decision\` when ANY of these is true: an alternative was
-  considered and REJECTED (record which, and why it lost); a non-obvious assumption or
-  constraint was LOCKED IN; a choice was made that a later reader would otherwise
-  re-litigate. Do NOT log: restating the outcome, design or plan (they are already
-  fields on the intent); confirming something already written down elsewhere; mechanical
-  facts recoverable from git, CI or the tracker (test counts, file lists, commit hashes);
-  progress narration ("started X", "working on Y").
-  KEEP → "Parallelised the build across four subagents; the Laravel slices were split by
-  file ownership to avoid collisions in one working tree." — records the rejected
-  alternative (one agent per repo) and why it lost.
-  DROP → "make verify green at 2415 passed after merging all four agents." — a mechanical
-  fact already in the commit message and the CI output.
+${worklogKeepDropTest()}
 - Promote to the parent intent — TWO filters, BOTH must pass: the entry is a \`decision\` or
   \`blocker\` (never \`note\`/\`code_change\`), AND it passes the keep/drop test. Then ALSO
   write a SECOND, separately-worded entry for a reader who never saw the task:
@@ -533,7 +569,9 @@ digraph orbitmap_execute {
 
 ## Rules
 - Flow A never merges, never pushes to the default branch, never closes tasks or the
-  intent as \`done\` — the run ends at \`in_review\` on the intent branch, intent at \`build\`.
+  intent as \`done\` — the run ends with \`orbitmap intent update IN-x --status in_review
+  --log …\` (follow the Instructions the transition returns); merging and \`done\` are
+  the user's.
 - Baseline before any change; "no new bugs" = no failure absent from the baseline.
 - The fix loop is goal-based — no round cap; termination is delivered-or-blocked plus
   green gates, never a retry budget.
@@ -599,6 +637,12 @@ it blocks, a discovery or risk outside your boundary, what a failing check revea
 NOT file lists, test counts, or progress narration. 1–3 entries on a normal task —
 losing nothing is the goal, volume is not.
 
+Close with ONE \`code_change\` entry naming WHAT you shipped and where — the shape of the
+change, never a file listing, which the \`[TS-x]\` commit already carries. It is the one
+type the "not mechanical facts" rule above does not forbid: without it your task records
+why every decision was made and never what was built. Use it too for anything git cannot
+see — a config flipped in a dashboard, a migration run against a live database.
+
 ## Report — your final text goes to the orchestrator, not to a user
 Structure it as:
 - **Files changed** — every file, one line each on what changed and why.
@@ -620,7 +664,7 @@ description: >
   cross-task notes in the intent plan field, and a doc-update-after-green step; then creates
   the tasks and hands off to orbitmap-execute. Use for "plan this intent", "break this down
   into tasks", an intent entering \`plan\` status — and for general planning (missions,
-  intents, promoting ideas, triaging issues).
+  intents, promoting ideas, triaging issues). Requires the \`orbitmap\` core skill.
 ---`;
 export const SKILL_PLAN_BODY = `# Planning a design into executable tasks
 
@@ -723,18 +767,7 @@ task/issue that has an intent; the CLI enforces this.
      \`orbitmap intent update IN-x --areas <slug>,<slug>\` (the distinct areas of the
      tasks you are creating). Declared areas feed session-focus matching for every later
      session.
-   - KEEP/DROP TEST — log a \`decision\` when ANY of these is true: an alternative was
-     considered and REJECTED (record which, and why it lost); a non-obvious assumption or
-     constraint was LOCKED IN; a choice was made that a later reader would otherwise
-     re-litigate. Do NOT log: restating the outcome, design or plan (they are already
-     fields on the intent); confirming something already written down elsewhere; mechanical
-     facts recoverable from git, CI or the tracker (test counts, file lists, commit hashes);
-     progress narration ("started X", "working on Y").
-     KEEP → "Parallelised the build across four subagents; the Laravel slices were split by
-     file ownership to avoid collisions in one working tree." — records the rejected
-     alternative (one agent per repo) and why it lost.
-     DROP → "make verify green at 2415 passed after merging all four agents." — a mechanical
-     fact already in the commit message and the CI output.
+${worklogKeepDropTest('   ')}
    - LOG IT THE MOMENT IT IS AGREED, not batched at the end:
      \`orbitmap log IN-x "<the decision and why — task shape, sequencing, area>" --type decision\`.
      An abandoned session must still leave its decisions recorded.
@@ -755,8 +788,10 @@ task/issue that has an intent; the CLI enforces this.
    add or fix tasks and re-check. Do NOT proceed while a gap remains.
 7. Write cross-task PLANNING NOTES + a short SUMMARY to the intent \`plan\` field —
    \`orbitmap intent update IN-x --plan "<notes>"\`: decisions valid for all tasks,
-   sequencing rationale, and the coverage argument. This REPLACES any seed notes that were
-   in the field — you have already absorbed them.
+   sequencing rationale, and the coverage argument. AUTHOR THE FIELD AS: a summary
+   paragraph first, then a line containing only \`---\`, then the body. The server reads the
+   part before \`---\` as the field's TL;DR and flags a field written without one.
+   This REPLACES any seed notes that were in the field — you have already absorbed them.
 8. Ensure a final DOC-UPDATE task exists: after the implementation is done and all tests
    are green, update the OrbitMap documentation (see the \`orbitmap-docs\` skill).
 9. SELF-REVIEW the plan with fresh eyes (see the Self-review section) and fix issues inline.
@@ -847,12 +882,15 @@ triaging issues):
 - **Missions:** \`orbitmap mission list|show MS-x\`; \`orbitmap mission create "name"
   [--outcome "…"] [--start d] [--end d]\`; \`orbitmap mission status MS-x
   active|completed|cancelled\` (activating fails while another is active — complete/cancel
-  it first); \`orbitmap mission link|unlink MS-x IN-y|TS-y|IS-y|ID-y\`. A mission status
+  it first); \`orbitmap mission link|unlink MS-x --type task|issue|idea|intent --id <uuid>\`
+  (the linked object goes by UUID — this endpoint rejects display numbers). A mission status
   change takes the same repeatable \`--log <type>:<content>\` and is refused (422) without
   at least one entry — \`cancelled\` above all needs its \`decision:"<why abandoned>"\`.
   \`orbitmap log MS-x "…" --type …\` logs against a mission outside a transition.
-- **Intents:** \`orbitmap intent create "name" [--outcome "…"] [--design "…"] [--plan "…"]
-  [--mission MS-x]\`, statuses new → design → plan → build → done (or cancelled). The
+- **Intents:** \`orbitmap intent create "name" [--outcome "…"] [--design "…"] [--plan "…"]\`
+  (there is no \`--mission\` flag — attach after creation with \`orbitmap mission link MS-x
+  --type intent --id <uuid>\`), statuses new → design → plan → build → done (or
+  cancelled). The
   \`outcome\` is the north star, \`design\` the agreed solution, \`plan\` the agreed build
   plan — produced by the \`orbitmap-brainstorm\` / \`orbitmap-design\` / \`orbitmap-plan\`
   gates respectively.
@@ -897,7 +935,8 @@ description: >
   time until the outcome is AGREED, writes that outcome to the intent's outcome field, and
   files useful asides to the design (and, when relevant, plan) fields for the later gates.
   Use for "I have an idea", "brainstorm this", "let's think through X", "what should we
-  build/do about X", shaping an intent's outcome, or an intent at \`new\` status.
+  build/do about X", shaping an intent's outcome, or an intent at \`new\` status. Requires
+  the \`orbitmap\` core skill.
 ---`;
 export const SKILL_BRAINSTORM_BODY = `# Framing an idea into an outcome
 
@@ -943,6 +982,9 @@ you hand to \`orbitmap-design\` (and, through the plan field, to \`orbitmap-plan
   ONE question. Prefer proposing a sensible default for the user to correct over an open
   interrogation. Aim for the few highest-leverage questions — "one question at a time" sets
   the pace, not the total count.
+- **Answer before asking.** When the user's turn contains a question, answer it first —
+  completely — before asking your own. Never return a question with a question; an
+  unanswered user question makes every next question feel like an interrogation.
 - **Lead with a recommendation.** Present options and the outcome conversationally, leading
   with the option you recommend and WHY — never a flat, neutral menu with no steer.
 - **YAGNI.** Cut every want that does not serve the outcome; a smaller outcome ships.
@@ -992,18 +1034,7 @@ you hand to \`orbitmap-design\` (and, through the plan field, to \`orbitmap-plan
    and for whom, what success looks like, the constraints. As you go, capture the user's
    opinions, preferences and context as notes; these outrank your own ideas in the design
    stage, so record them faithfully.
-   - KEEP/DROP TEST — log a \`decision\` when ANY of these is true: an alternative was
-     considered and REJECTED (record which, and why it lost); a non-obvious assumption or
-     constraint was LOCKED IN; a choice was made that a later reader would otherwise
-     re-litigate. Do NOT log: restating the outcome, design or plan (they are already
-     fields on the intent); confirming something already written down elsewhere; mechanical
-     facts recoverable from git, CI or the tracker (test counts, file lists, commit hashes);
-     progress narration ("started X", "working on Y").
-     KEEP → "Parallelised the build across four subagents; the Laravel slices were split by
-     file ownership to avoid collisions in one working tree." — records the rejected
-     alternative (one agent per repo) and why it lost.
-     DROP → "make verify green at 2415 passed after merging all four agents." — a mechanical
-     fact already in the commit message and the CI output.
+${worklogKeepDropTest('   ')}
    - LOG IT THE MOMENT IT PASSES, not batched at the end: \`orbitmap log IN-x "<what was
      decided and why>" --type decision\`. An abandoned session must still leave its decisions
      recorded. If the intent does not exist yet, create it (step 4) at the first passing
@@ -1019,7 +1050,10 @@ you hand to \`orbitmap-design\` (and, through the plan field, to \`orbitmap-plan
 4. Persist (create or refine). Update an existing unprocessed intent, or create one:
    \`orbitmap intent update IN-x --outcome "<agreed outcome>" [--design "<design notes>"] [--plan "<plan notes>"]\`
    / \`orbitmap intent create "<name>" --outcome "<agreed outcome>" [--design "…"] [--plan "…"]\`.
-   The agreed **outcome** goes in the outcome field. Route the captured notes by type —
+   The agreed **outcome** goes in the outcome field. AUTHOR EVERY FIELD THE SAME WAY: a
+   summary paragraph first, then a line containing only \`---\`, then the body. The server
+   reads the part before \`---\` as the field's TL;DR and flags a field written without one.
+   Route the captured notes by type —
    HOW / tech / UX → the **design** field; build-order / task ideas / execution risks → the
    **plan** field (OPTIONAL — only if the conversation produced any). Mark the user's notes
    as the user's in both fields; you may add your own, kept separate. The design gate reads
@@ -1108,7 +1142,8 @@ description: >
   technical spec, and UX (when there's UI), one question at a time, then writes the
   result to the intent's design field. Use for "design this intent", "let's design X", or
   an intent entering \`design\` status. Use it once the outcome is agreed; if the outcome is
-  still missing or vague, step aside to \`orbitmap-brainstorm\` first.
+  still missing or vague, step aside to \`orbitmap-brainstorm\` first. Requires the
+  \`orbitmap\` core skill.
 ---`;
 export const SKILL_DESIGN_BODY = `# Designing an intent's solution
 
@@ -1152,6 +1187,9 @@ holds a real design doc instead of raw notes, treat it as existing design to ref
   ONE question. Prefer proposing a sensible default for the user to correct over an open
   interrogation. Aim for the few highest-leverage questions — "one question at a time" sets
   the pace, not the total count.
+- **Answer before asking.** When the user's turn contains a question, answer it first —
+  completely — before asking your own. Never return a question with a question; an
+  unanswered user question makes every next question feel like an interrogation.
 - **Lead with a recommendation.** When you propose approaches or technical options, lead
   with the one you recommend and WHY — never a flat, neutral menu with no steer.
 - **YAGNI.** Cut every part of the design that does not serve the outcome; a smaller
@@ -1207,18 +1245,7 @@ well-bounded units are easier to build, review, and reason about.
    cases, data/API shape. Continuously check whether the emerging design actually delivers
    the outcome, and surface any gap where it would not. Capture the user's decisions and
    the reasoning behind them as you go — those decisions are part of the design.
-   - KEEP/DROP TEST — log a \`decision\` when ANY of these is true: an alternative was
-     considered and REJECTED (record which, and why it lost); a non-obvious assumption or
-     constraint was LOCKED IN; a choice was made that a later reader would otherwise
-     re-litigate. Do NOT log: restating the outcome, design or plan (they are already
-     fields on the intent); confirming something already written down elsewhere; mechanical
-     facts recoverable from git, CI or the tracker (test counts, file lists, commit hashes);
-     progress narration ("started X", "working on Y").
-     KEEP → "Parallelised the build across four subagents; the Laravel slices were split by
-     file ownership to avoid collisions in one working tree." — records the rejected
-     alternative (one agent per repo) and why it lost.
-     DROP → "make verify green at 2415 passed after merging all four agents." — a mechanical
-     fact already in the commit message and the CI output.
+${worklogKeepDropTest('   ')}
    - LOG IT THE MOMENT IT IS AGREED, not batched at the end: \`orbitmap log IN-x "<the choice
      and why, incl. what it rules out>" --type decision\`. An abandoned session must still
      leave its decisions recorded.
@@ -1249,7 +1276,10 @@ well-bounded units are easier to build, review, and reason about.
 5. Present the draft in sections scaled to their complexity (a few sentences when simple,
    more when nuanced); after each section ask whether it looks right, and get the user's
    approval before writing anything.
-6. Write it: \`orbitmap intent update IN-x --design "<doc>"\`. This REPLACES any framing
+6. Write it: \`orbitmap intent update IN-x --design "<doc>"\`. AUTHOR THE FIELD AS: a
+   summary paragraph first, then a line containing only \`---\`, then the body. The server
+   reads the part before \`---\` as the field's TL;DR and flags a field written without one.
+   This REPLACES any framing
    notes that were in the field — you have already absorbed them into the doc. When the
    spec names the repos the build will touch, declare them on the intent in the same
    update — \`--areas <slug>,<slug>\` — so session-focus matching works from declared data.
@@ -1347,14 +1377,14 @@ name: orbitmap-docs
 description: >
   Reading and updating OrbitMap documents (specs, architecture, guides, decisions).
   Use when the user asks to read, import, or update project documentation tracked in
-  OrbitMap.
+  OrbitMap. Requires the \`orbitmap\` core skill.
 ---`;
 export const SKILL_DOCS_BODY = `# OrbitMap documents
 
-Documents are workspace-level: exactly ONE copy per workspace, never per-area. No document
-command takes an area, and their metadata (slug, when to use) already rides the context
-payload your session focus was matched from (see Session focus in the \`orbitmap\` skill —
-ensure, don't re-call).
+Documents live at area or workspace level: \`orbitmap docs\` lists every document you can
+reach — your areas' documents plus the workspace-level ones — and their metadata (slug,
+when to use) already rides the context payload your session focus was matched from (see
+Session focus in the \`orbitmap\` skill — ensure, don't re-call).
 
 ## Goal
 Read and update OrbitMap documents efficiently: pull only the context you need (TOC →
@@ -1379,8 +1409,10 @@ for the full content, read that file instead of printing the content into the
 conversation.
 
 ## Editing
-- Import a new document: \`orbitmap doc-import <file.md> --title "…" --type
-  spec|architecture|api|guide|decision|changelog|other [--context "…"]\`.
+- Import a new document: \`orbitmap doc-import <title> --file <file.md> --type
+  spec|architecture|api|guide|decision|changelog|other [--context "…"]\`. It lands
+  area-level, resolved from the current directory; add \`--workspace-id <slug-or-uuid>\`
+  to create it workspace-level instead.
 - Update: \`orbitmap doc-update <slug> --file <file.md>\` (replaces content, bumps
   version).
 - To change an OrbitMap document, ALWAYS go through these commands — NEVER edit files
@@ -1431,7 +1463,7 @@ export const SKILLS = [
     },
 ];
 // ── The thin always-on hook (CLAUDE.md / AGENTS.md) ────────────────────────────
-// Claude variant — §8.2, verbatim (without the markers, which buildClaudeHook adds).
+// Claude variant — §8.2, verbatim (without the markers, which buildClaudeBlock adds).
 export const THIN_HOOK_CLAUDE = `## OrbitMap
 
 Work is tracked in OrbitMap via the \`orbitmap\` CLI. You work in a WORKSPACE, which can span
@@ -1440,11 +1472,13 @@ the workspace itself, not to any one repo.
 Load the OrbitMap skills whenever the user wants to build, add, change or fix something, in
 whatever words they use — do not wait for OrbitMap vocabulary. Load them too when they talk
 about tracking work (backlog, tasks, missions, intents, ideas, issues, documents, planning).
+Load the core skill 'orbitmap' first, before any other orbitmap-* skill — they all build on it.
 Nothing gets built before it is framed: a feature, component or behaviour change gets an intent
 — outcome (brainstorm) → design → plan → build (execute), one gate at a time, written to the
 intent as you go. Small self-contained work (a typo, an obvious one-file fix) is just a task.
 NEVER finish a task, intent or mission without a final \`orbitmap log\` entry and a status update;
-the final entry closes a record that already exists. Finished work defaults to \`in_review\`, not \`done\`.`;
+the final entry closes a record that already exists. Finished work defaults to \`in_review\`, not \`done\`.
+OrbitMap tool responses may carry an Instructions section — act on it before continuing.`;
 // Non-Claude variant: same rules, but points at the inlined sections below instead of
 // skills that these agents cannot load.
 export const THIN_HOOK_GENERIC = `## OrbitMap
@@ -1459,7 +1493,8 @@ Nothing gets built before it is framed: a feature, component or behaviour change
 — outcome (brainstorm) → design → plan → build (execute), one gate at a time, written to the
 intent as you go. Small self-contained work (a typo, an obvious one-file fix) is just a task.
 NEVER finish a task, intent or mission without a final \`orbitmap log\` entry and a status update;
-the final entry closes a record that already exists. Finished work defaults to \`in_review\`, not \`done\`.`;
+the final entry closes a record that already exists. Finished work defaults to \`in_review\`, not \`done\`.
+OrbitMap tool responses may carry an Instructions section — act on it before continuing.`;
 // ── Assembly helpers ───────────────────────────────────────────────────────────
 /** Build one SKILL.md file (frontmatter + body) for Claude. */
 export function buildSkillFile(skill) {
@@ -1482,7 +1517,7 @@ export const SKILL_SCOPE_CAVEAT_PROJECT = 'These skills are installed at PROJECT
  * `scope` is where the accompanying skill files were installed — see
  * {@link SKILL_SCOPE_CAVEAT_PROJECT}.
  */
-export function buildClaudeHook(scope = 'user') {
+export function buildClaudeBlock(scope = 'user') {
     const body = scope === 'project' ? `${THIN_HOOK_CLAUDE}\n${SKILL_SCOPE_CAVEAT_PROJECT}` : THIN_HOOK_CLAUDE;
     return `${MARKER_START}\n${body}\n${MARKER_END}`;
 }

package/dist/agent-instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-instructions.js","sourceRoot":"","sources":["../src/agent-instructions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-instructions.js","sourceRoot":"","sources":["../src/agent-instructions.ts"],"names":[],"mappings":"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"}

package/dist/commands/create.d.ts

@@ -11,5 +11,6 @@ export declare function createCommand(title: string, options: {
     instructions?: string;
     fromIssue?: string;
     intent?: string;
+    mission?: string;
     orbit?: string;
 }): Promise<void>;

package/dist/commands/create.js

@@ -1,15 +1,25 @@
 import { createAdapter } from '../adapters/factory.js';
 import { confirmWriteTarget } from '../write-target.js';
-import { formatOutput, printError, printSuccess } from '../output.js';
+import { formatOutput, printError, printSuccess, printValidationError } from '../output.js';
 export async function createCommand(title, options) {
+    // Mutually exclusive by design (TS-bh8d25): a task under an intent reaches its
+    // mission THROUGH the intent, so the server rejects both together with a 422.
+    // Rejecting here — before the write-target prompt and before any request — turns
+    // that round trip into an immediate, actionable message.
+    if (options.intent && options.mission) {
+        printValidationError('--intent and --mission are mutually exclusive — a task under an intent reaches ' +
+            'the mission through the intent. Provide only one (or set the mission on the intent).', options.json);
+        return;
+    }
     try {
         await confirmWriteTarget('create task', options);
         const client = await createAdapter(options.area);
-        // Every object reference below — the issue, the intent, the orbit, the agent — travels
-        // VERBATIM. `POST /tasks` validates `source_issue_id`, `intent_id`, `orbit_id` and
-        // `agent_id` with `App\Rules\EntityRef` (shape only) and resolves the uuid / display
-        // number / bare code / slug server-side (TS-av6332), answering 404 ISSUE_NOT_FOUND,
-        // INTENT_NOT_FOUND, ORBIT_NOT_FOUND or AGENT_NOT_FOUND when the reference is unknown.
+        // Every object reference below — the issue, the intent, the mission, the orbit, the
+        // agent — travels VERBATIM. `POST /tasks` validates `source_issue_id`, `intent_id`,
+        // `mission_id`, `orbit_id` and `agent_id` with `App\Rules\EntityRef` (shape only) and
+        // resolves the uuid / display number / bare code / slug server-side (TS-av6332),
+        // answering 404 ISSUE_NOT_FOUND, INTENT_NOT_FOUND, MISSION_NOT_FOUND, ORBIT_NOT_FOUND
+        // or AGENT_NOT_FOUND when the reference is unknown.
         // Resolving any of them here would duplicate server logic and cost an extra round trip —
         // which is exactly what `--from-issue` used to pay for a `GET /issues/{id_or_number}`.
         const response = (await client.createTask({
@@ -23,6 +33,7 @@ export async function createCommand(title, options) {
             agent_instructions: options.instructions,
             source_issue_id: options.fromIssue,
             intent_id: options.intent,
+            mission_id: options.mission,
             orbit_id: options.orbit,
         }));
         if (options.json) {

package/dist/commands/create.js.map

@@ -1 +1 @@
-{"version":3,"file":"create.js","sourceRoot":"","sources":["../../src/commands/create.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAoBtE,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,KAAa,EACb,OAcC;IAED,IAAI,CAAC;QACH,MAAM,kBAAkB,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QACjD,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAEjD,uFAAuF;QACvF,mFAAmF;QACnF,qFAAqF;QACrF,oFAAoF;QACpF,sFAAsF;QACtF,yFAAyF;QACzF,uFAAuF;QACvF,MAAM,QAAQ,GAAG,CAAC,MAAM,MAAM,CAAC,UAAU,CAAC;YACxC,KAAK;YACL,WAAW,EAAE,OAAO,CAAC,IAAI;YACzB,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,gBAAgB,EAAE,OAAO,CAAC,MAAM;YAChC,QAAQ,EAAE,OAAO,CAAC,OAAO;YACzB,WAAW,EAAE,OAAO,CAAC,MAAM;YAC3B,kBAAkB,EAAE,OAAO,CAAC,YAAY;YACxC,eAAe,EAAE,OAAO,CAAC,SAAS;YAClC,SAAS,EAAE,OAAO,CAAC,MAAM;YACzB,QAAQ,EAAE,OAAO,CAAC,KAAK;SACxB,CAAC,CAAmB,CAAC;QAEtB,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YACjB,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;YAC1C,OAAO;QACT,CAAC;QAED,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC;QACxB,IAAI,GAAG,GAAG,iBAAiB,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,cAAc,IAAI,CAAC,CAAC,WAAW,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,QAAQ,GAAG,CAAC;QACzG,yFAAyF;QACzF,wFAAwF;QACxF,yFAAyF;QACzF,qDAAqD;QACrD,IAAI,CAAC,CAAC,mBAAmB,EAAE,CAAC;YAC1B,GAAG,IAAI,qBAAqB,CAAC,CAAC,mBAAmB,IAAI,OAAO,CAAC,SAAS,sBAAsB,CAAC;QAC/F,CAAC;QACD,IAAI,CAAC,CAAC,oBAAoB,EAAE,CAAC;YAC3B,GAAG,IAAI,cAAc,CAAC,CAAC,oBAAoB,EAAE,CAAC;QAChD,CAAC;QACD,IAAI,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;YACxB,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,CAAC;gBAC5B,GAAG,IAAI,cAAc,CAAC,EAAE,CAAC;YAC3B,CAAC;QACH,CAAC;QACD,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QAChC,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}
+{"version":3,"file":"create.js","sourceRoot":"","sources":["../../src/commands/create.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAoB5F,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,KAAa,EACb,OAeC;IAED,+EAA+E;IAC/E,8EAA8E;IAC9E,iFAAiF;IACjF,yDAAyD;IACzD,IAAI,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACtC,oBAAoB,CAClB,iFAAiF;YAC/E,sFAAsF,EACxF,OAAO,CAAC,IAAI,CACb,CAAC;QACF,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,MAAM,kBAAkB,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QACjD,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAEjD,oFAAoF;QACpF,oFAAoF;QACpF,sFAAsF;QACtF,iFAAiF;QACjF,sFAAsF;QACtF,oDAAoD;QACpD,yFAAyF;QACzF,uFAAuF;QACvF,MAAM,QAAQ,GAAG,CAAC,MAAM,MAAM,CAAC,UAAU,CAAC;YACxC,KAAK;YACL,WAAW,EAAE,OAAO,CAAC,IAAI;YACzB,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,gBAAgB,EAAE,OAAO,CAAC,MAAM;YAChC,QAAQ,EAAE,OAAO,CAAC,OAAO;YACzB,WAAW,EAAE,OAAO,CAAC,MAAM;YAC3B,kBAAkB,EAAE,OAAO,CAAC,YAAY;YACxC,eAAe,EAAE,OAAO,CAAC,SAAS;YAClC,SAAS,EAAE,OAAO,CAAC,MAAM;YACzB,UAAU,EAAE,OAAO,CAAC,OAAO;YAC3B,QAAQ,EAAE,OAAO,CAAC,KAAK;SACxB,CAAC,CAAmB,CAAC;QAEtB,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YACjB,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;YAC1C,OAAO;QACT,CAAC;QAED,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC;QACxB,IAAI,GAAG,GAAG,iBAAiB,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,cAAc,IAAI,CAAC,CAAC,WAAW,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,QAAQ,GAAG,CAAC;QACzG,yFAAyF;QACzF,wFAAwF;QACxF,yFAAyF;QACzF,qDAAqD;QACrD,IAAI,CAAC,CAAC,mBAAmB,EAAE,CAAC;YAC1B,GAAG,IAAI,qBAAqB,CAAC,CAAC,mBAAmB,IAAI,OAAO,CAAC,SAAS,sBAAsB,CAAC;QAC/F,CAAC;QACD,IAAI,CAAC,CAAC,oBAAoB,EAAE,CAAC;YAC3B,GAAG,IAAI,cAAc,CAAC,CAAC,oBAAoB,EAAE,CAAC;QAChD,CAAC;QACD,IAAI,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;YACxB,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,CAAC;gBAC5B,GAAG,IAAI,cAAc,CAAC,EAAE,CAAC;YAC3B,CAAC;QACH,CAAC;QACD,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QAChC,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/commands/emit-instructions.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `orbitmap emit-instructions` — the hook relay (IN-pp967d, TS-9r98vv).
+ *
+ * Reads a Claude Code hook payload (JSON) on stdin, lifts an Instructions block out of
+ * `tool_response.stdout` (marker contract pinned by tests/intent-instructions.test.ts:
+ * header `/^Instructions \(/` at column 0, body lines indented two spaces, interior
+ * blank lines allowed) and re-emits it as hook `additionalContext` so it lands at
+ * instruction tier instead of data tier.
+ *
+ * Deliberately dumb: no OrbitMap semantics, no network, no adapter — a new producer of
+ * the marker (PreToolUse, SessionStart, another command) needs no change here, and the
+ * command runs on every matching Bash call, so it must do no work beyond parse → grep →
+ * print. On any problem (malformed JSON, missing fields, no block) it exits 0 silently:
+ * a hook that throws is worse than one that says nothing.
+ */
+/**
+ * Extracts the Instructions block from a tool's stdout, or null when there is none.
+ *
+ * Rule: the block starts at the first line matching /^Instructions \(/ and extends over
+ * every following line that begins with two spaces. A blank line is part of the block
+ * only when a later two-space-indented line follows it before the block ends (interior
+ * blank lines belong to the body); the block ends at the first line that is neither
+ * blank nor two-space-indented, and a trailing run of blank lines is excluded.
+ */
+export declare function extractInstructionsBlock(stdout: string): string | null;
+export declare function emitInstructionsCommand(input?: NodeJS.ReadableStream): Promise<void>;

package/dist/commands/emit-instructions.js

@@ -0,0 +1,68 @@
+/**
+ * `orbitmap emit-instructions` — the hook relay (IN-pp967d, TS-9r98vv).
+ *
+ * Reads a Claude Code hook payload (JSON) on stdin, lifts an Instructions block out of
+ * `tool_response.stdout` (marker contract pinned by tests/intent-instructions.test.ts:
+ * header `/^Instructions \(/` at column 0, body lines indented two spaces, interior
+ * blank lines allowed) and re-emits it as hook `additionalContext` so it lands at
+ * instruction tier instead of data tier.
+ *
+ * Deliberately dumb: no OrbitMap semantics, no network, no adapter — a new producer of
+ * the marker (PreToolUse, SessionStart, another command) needs no change here, and the
+ * command runs on every matching Bash call, so it must do no work beyond parse → grep →
+ * print. On any problem (malformed JSON, missing fields, no block) it exits 0 silently:
+ * a hook that throws is worse than one that says nothing.
+ */
+/**
+ * Extracts the Instructions block from a tool's stdout, or null when there is none.
+ *
+ * Rule: the block starts at the first line matching /^Instructions \(/ and extends over
+ * every following line that begins with two spaces. A blank line is part of the block
+ * only when a later two-space-indented line follows it before the block ends (interior
+ * blank lines belong to the body); the block ends at the first line that is neither
+ * blank nor two-space-indented, and a trailing run of blank lines is excluded.
+ */
+export function extractInstructionsBlock(stdout) {
+    const lines = stdout.split('\n');
+    const start = lines.findIndex((line) => /^Instructions \(/.test(line));
+    if (start === -1)
+        return null;
+    let end = start + 1; // exclusive index just past the last confirmed block line
+    for (let i = start + 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.startsWith('  ')) {
+            end = i + 1; // confirms this line and any blank run before it
+        }
+        else if (line !== '') {
+            break; // neither blank nor indented — the block is over
+        }
+        // blank line: tentatively skipped; included only if a later indented line confirms it
+    }
+    return lines.slice(start, end).join('\n');
+}
+async function readStream(input) {
+    const chunks = [];
+    for await (const chunk of input) {
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+export async function emitInstructionsCommand(input = process.stdin) {
+    try {
+        const payload = JSON.parse(await readStream(input));
+        const eventName = payload?.hook_event_name;
+        const stdout = payload?.tool_response?.stdout;
+        if (typeof eventName !== 'string' || typeof stdout !== 'string' || stdout === '')
+            return;
+        const block = extractInstructionsBlock(stdout);
+        if (block === null)
+            return;
+        console.log(JSON.stringify({
+            hookSpecificOutput: { hookEventName: eventName, additionalContext: block },
+        }));
+    }
+    catch {
+        // Silent by design — never break the hook chain. Exit code stays 0.
+    }
+}
+//# sourceMappingURL=emit-instructions.js.map