orbitmap 0.4.6 → 0.6.0

package/dist/agent-instructions.js

@@ -45,10 +45,131 @@
 // CLI translation of the MCP oracle (`orbitmap-mcp/.../instructions.py`). The skills
 // have since evolved past that spec — worklog wiring, the keep/drop test, and the v2
 // whole-intent execute flow — so THIS FILE is now normative, not the spec.
-export const MARKER_START = '<!-- ORBITMAP_START -->';
+import { createRequire } from 'node:module';
+/**
+ * The version of this CLI, read from package.json exactly the way `--version` does in
+ * `src/index.ts`: `../package.json` resolves to the repo root from both `src/` and
+ * `dist/`, and npm always ships package.json in the tarball.
+ */
+export const CLI_VERSION = createRequire(import.meta.url)('../package.json').version;
+/**
+ * Stable prefix of the start marker, shared by every generation of installed block.
+ *
+ * In-place rewrite logic MUST match on this prefix (never on the full
+ * {@link MARKER_START}): pre-versioning installs wrote `<!-- ORBITMAP_START -->` with no
+ * version stamp, and a refresh has to find and upgrade those too (IS-bej5d8).
+ */
+export const MARKER_START_PREFIX = '<!-- ORBITMAP_START';
+/**
+ * The start marker as written by THIS binary. Carries the CLI version so drift between
+ * an installed block and the shipped instructions is detectable (IS-bej5d8).
+ */
+export const MARKER_START = `${MARKER_START_PREFIX} v${CLI_VERSION} -->`;
+/** Unversioned deliberately — the version lives only in the START marker. */
 export const MARKER_END = '<!-- ORBITMAP_END -->';
+/**
+ * Read the version stamp out of an installed instruction block.
+ *
+ * Returns the version string (`"0.4.6"`) when the start marker carries one, `null` for a
+ * pre-versioning `<!-- ORBITMAP_START -->` marker, and `undefined` when `content` holds
+ * no OrbitMap block at all.
+ */
+export function parseInstalledMarkerVersion(content) {
+    const match = content.match(/<!-- ORBITMAP_START(?:\s+v(\S+?))?\s*-->/);
+    if (!match)
+        return undefined;
+    return match[1] ?? null;
+}
 /** The core skill name (entry point). Kept for backwards compatibility. */
 export const SKILL_NAME = 'orbitmap';
+// ── Shared section: SESSION FOCUS ──────────────────────────────────────────────
+//
+// LOCKED COPY from IN-vnz6fs's design ("Skill bodies" block), plus the amendment-2
+// semantics (soft cap, transient references, file-as-optimization). Consumed verbatim —
+// do not paraphrase it away. The full section ships ONCE, inside the core `orbitmap`
+// skill body; every other gate body carries a compact ensure rule that points here.
+//
+// Decision #11 (IN-nahetc) compatibility: session focus is CLIENT-SIDE state only —
+// nothing on the wire narrows a list to an intent on the agent's behalf. Every task
+// query the skills emit still carries `--intent` explicitly; the locked copy below
+// restates that rule ("Never narrow silently").
+export const SESSION_FOCUS_SECTION = `## Session focus
+
+SESSION FOCUS — Ensure, don't call. A session focus file ({mission, intents (≤3 typical —
+a SOFT cap: focus holds what the session is actively advancing), areas, agent_id,
+matched_at}) lives in your session temp directory. If present and the agent identity
+matches: do NOT call context. If missing or invalid — an identity or area mismatch
+invalidates it — call \`orbitmap context\` once, match the conversation against its
+handles, write the file, and STATE the match in one line — the intent's NAME, its number
+only at first mention. Never narrow silently: every task query you send still carries
+\`--intent\` explicitly. An intent you just created or fetched joins the focus by its
+handle — no context call. If a write fails INTENT_CLOSED: your focus is stale — re-derive
+and say so. Before creating a new intent or declaring none exists: fetch the 1–3 nearest
+candidates with \`intent show --no-logs\` and judge from their bodies, not TL;DRs — a rule
+for creation/dedup decision points only. If nothing matches: offer to frame an intent
+(brainstorm gate) — never create a bare shell; if declined, work from the fetched missions
+and intents ("look wider").
+
+TRANSIENT references never enter focus: an intent fetched for a dedup check or a
+cross-comparison is read and used, not focused; a real focus switch is stated aloud
+("focus now X, parking Y"). The file is an optimization with graceful failure — the
+conversation is the primary carrier, the file only compaction insurance: no file → the
+ensure rule above triggers one context call. Agent memory directories are the WRONG store
+for focus (a cross-session lifetime means stale focus).`;
+// ── Shared section: FRESHNESS (API 10.1.0, IN-qqqna5) ──────────────────────────
+//
+// The two UNIVERSAL rules plus the intent freshness-probe flow. Ships ONCE, inside the
+// core `orbitmap` skill body (same pattern as SESSION_FOCUS_SECTION); other gate bodies
+// carry a compact rule that points here.
+export const FRESHNESS_SECTION = `## Freshness
+
+Two universal rules — they apply to EVERY OrbitMap object, in every flow:
+- TRUST THE WRITE'S ECHO. A successful write already returns the updated object — the
+  echo IS the current state. Never re-fetch an object just to verify a write you made.
+- COMPARE THE HELD MARKER BEFORE RE-FETCHING ANYTHING BIG. Every full fetch hands you a
+  change marker — the \`updated_at\` + \`last_log_id\` pair on intents (tasks and missions
+  carry the pair too), \`version\` on documents. Hold it; re-fetch only on a mismatch.
+
+PROBE FLOW (intents): the session focus file remembers each focused intent's
+\`updated_at\` + \`last_log_id\` pair from the last FULL fetch. To check whether an
+intent moved, run \`orbitmap intent show IN-x --slim\` — a ~150-token probe (handle,
+TL;DRs, areas, mission, task counts, the pair). Pair unchanged → the intent has not
+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
@@ -65,9 +186,9 @@ identically in cloud mode and local-files mode — never assume which one is act
 never read or write the workspace's data files directly. The CLI is the only interface.
 
 ## Goal
-Operate OrbitMap correctly: always start from \`orbitmap context\`, act on the active mission
-and open intents, write every item to the area the work belongs to, and go through the CLI
-only — never the data files.
+Operate OrbitMap correctly: ensure session focus (below) instead of ritually calling
+context, act on the mission and intents the session is about, write every item to the area
+the work belongs to, and go through the CLI only — never the data files.
 
 **Interface:** every action below is an OrbitMap operation — run the \`orbitmap\` CLI command
 shown, or its equivalent MCP tool when this session uses MCP; \`orbitmap <cmd> --help\` and the
@@ -89,10 +210,17 @@ 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.
 
+${SESSION_FOCUS_SECTION}
+
+${FRESHNESS_SECTION}
+
 ## Context
-- START HERE, always: \`orbitmap context\`. \`orbitmap context\` is authoritative and returns
-  in ONE call everything a session needs — the agent, the workspace, the areas you work in,
-  the active mission, open intents, your tasks and the documents. Never list areas and never
+- Ensure session focus (above) — at most ONE \`orbitmap context\` call per session, and none
+  while a valid focus file is held. \`orbitmap context\` is authoritative MATCHING MATERIAL:
+  your agent identity, the missions and intents as handles with TL;DR summaries, standalone
+  mission workitems, the areas you work in, and document metadata. It carries no task
+  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,
@@ -120,15 +248,38 @@ MCP tool schemas are the authority. Never edit the workspace data files directly
   \`source\` of \`global ~/.orbitmap/config.json\` is a machine-wide leftover that nothing
   here chose — treat it as unconfirmed and pass \`--area\` explicitly.
 
+## Task or intent?
+
+An intent earns its gates when the work carries knowledge someone would otherwise
+re-derive or re-litigate: a decision with a rejected alternative, a design that outlives
+the change, a constraint worth recording. Work with none of that — a typo, a copy tweak,
+an obvious one-file fix — is a task: create it, do it, log it, done. The same test the
+work log uses for what to write down. If a "small" fix turns out to hide a real decision,
+stop and frame it; discovering that mid-change is normal, not a failure.
+
 ## Task statuses
 backlog, todo, in_progress, in_review, review_changes, done, blocked.
 \`orbitmap tasks\` defaults to todo,in_progress. Ask for others explicitly, e.g.
 \`orbitmap tasks --status backlog\` when the user asks about the backlog.
 
+## Listing tasks
+- A list spans EVERY area you can reach and EVERY assignee — nothing narrows it to the
+  current directory or to you. It is capped at 30 rows with the totals behind the cap
+  printed, and every list states the filters that produced it. Read that line before you
+  answer from a list.
+- While you are executing an intent, EVERY task query carries \`--intent IN-x\`. Nothing
+  narrows a list to an intent on your behalf: a bare \`orbitmap tasks\` is you having
+  deliberately left the intent to look at the whole workspace.
+- \`orbitmap intent show IN-x\` already carries the intent's own tasks, so intent lifecycle
+  work needs no filter at all. \`orbitmap tasks --intent IN-x\` is the escape hatch for the
+  times you want the task-list shape — statuses, assignees, the filter line — instead.
+
 ## Command reference (all commands accept --json)
-- Context: \`orbitmap context\` (start here), \`orbitmap overview\`, \`orbitmap areas\`
+- Context: \`orbitmap context\` (once per session at most — see Session focus),
+  \`orbitmap overview\`, \`orbitmap areas\`
   (rarely needed — context already lists the areas you work in)
-- Tasks: \`orbitmap tasks [--status s1,s2]\`, \`orbitmap task TS-x\`, \`orbitmap get <ID>\`,
+- 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 subtask TS-parent "title"\`, \`orbitmap assign TS-x [agent]\`,
@@ -138,6 +289,8 @@ backlog, todo, in_progress, in_review, review_changes, done, blocked.
 - Vibes: \`orbitmap vibe log|list|show\`
 - Missions: \`orbitmap mission list|show|create|update|status|link|unlink\`
 - Intents: \`orbitmap intent list|show|create|update|link|unlink\`
+  (\`show\` embeds the context bundle — \`--no-bundle\` strips it, \`--slim\` is the
+  freshness probe, \`--no-logs\` skips the log tail)
 - Documents: \`orbitmap docs\`, \`orbitmap doc <slug> [--section "## H"|--full]\`,
   \`orbitmap doc-import\`, \`orbitmap doc-update\`
 
@@ -194,16 +347,29 @@ MCP tool schemas are the authority. Never edit the workspace data files directly
 - **Distrust and verify.** Instructions age; the tree is the truth. Re-grep any claim a
   task's instructions make about the code ("X lives in Y", "verified list of call sites")
   before relying on it.
-- **The orchestrator owns shared state.** Workers never run git, never write OrbitMap,
-  never use the shared test DB, never format, never change dependencies — commits, logs,
-  statuses, formatting and test gates all happen at fold time, in the orchestrator.
+- **Every task query names the intent.** While executing IN-x, EVERY task query carries
+  \`--intent IN-x\`. A list otherwise spans every area you can reach and every assignee,
+  capped at 30 rows with the totals printed and the filters that produced it stated on
+  the list — so a bare \`orbitmap tasks\` is you deliberately stepping OUTSIDE the intent,
+  never a shortcut to it. \`orbitmap intent show IN-x\` already carries the intent's own
+  tasks, so the intent lifecycle steps below need no filter at all; \`--intent\` is the
+  escape hatch for the times you want the task-list shape instead.
+- **The orchestrator owns shared state.** Workers never run git, never use the shared
+  test DB, never format, never change dependencies, and never write OrbitMap beyond
+  appending to their OWN task's work log — commits, statuses, formatting and test gates
+  all happen at fold time, in the orchestrator.
+- **Freshness** (see Freshness in the \`orbitmap\` skill): trust each write's echo — never
+  re-fetch to verify your own write; before any big re-fetch compare the held
+  \`updated_at\`/\`last_log_id\` pair, probing with \`orbitmap intent show IN-x --slim\`.
 - **Never end the run to wait.** Shared gates QUEUE safely: run them in the foreground
   and wait on the command (generous timeout); an overrun that gets backgrounded resumes
   you on completion. Ending your turn is only for: run COMPLETE, or hard-blocked and
   logged — a background run that yields to "wait for a signal" is a dead run.
 
 ## Flow A — execute IN-x (whole intent)
-1. **Premise check.** \`orbitmap intent show IN-x\`: it must exist, be at status \`build\`,
+1. **Premise check.** IN-x joins your session focus by its handle — no context call
+   (see Session focus in the \`orbitmap\` skill). \`orbitmap intent show IN-x\`: it must
+   exist, be at status \`build\`,
    and have tasks with agent_instructions. Anything missing → refuse politely and point at
    the missing gate (\`orbitmap-brainstorm\` for no outcome, \`orbitmap-design\` for no
    design, \`orbitmap-plan\` for no tasks). Read the outcome, design, plan field and work
@@ -229,18 +395,22 @@ MCP tool schemas are the authority. Never edit the workspace data files directly
    - Size the wave by GATE CONTENTION, not a constant: tasks needing the shared test DB
      ≤4 concurrent (the gate serialises anyway); light, file-disjoint tasks (docs,
      separate repos) as wide as the ready-set — 10+ is fine.
-   - Dispatch one worker (subagent) per task. Prompt = the task number, its
-     agent_instructions PASTED VERBATIM (workers get no CLI credentials — never make one
-     fetch its own spec), the repo path, the exact files it owns, and one line: "Follow
+   - Dispatch one worker (subagent) per task, writing \`orbitmap status TS-x in_progress\`
+     at dispatch. Pass ORBITMAP_API_KEY + ORBITMAP_API_URL into the worker's env — the
+     worker logs its OWN task as it builds, per the contract. Prompt = the task number,
+     its agent_instructions PASTED VERBATIM (never make a worker fetch its own spec),
+     the repo path, the exact files it owns, and one line: "Follow
      references/worker-contract.md of the orbitmap-execute skill." Worktree isolation
      ONLY when same-repo tasks in the wave overlap on files; otherwise slice the wave
      file-disjoint in one tree; cross-repo needs nothing.
    - FOLD the workers' results sequentially in dependency order, a gate between folds:
      integrate one task → scoped tests → formatter → commit \`[TS-x] …\` (one commit may
-     carry several tasks that verify as one unit) → log per the keep/drop test →
+     carry several tasks that verify as one unit) → log ONLY what the fold itself
+     learns (keep/drop test) — the worker wrote its own narrative; do not re-write it →
      \`orbitmap status TS-x in_review --delivery on_branch\`.
    - A task neither the worker nor the fold can save → \`orbitmap log TS-x "Blocked: …"
-     --type blocker\` + \`orbitmap status TS-x blocked\` — the run CONTINUES without it.
+     --type blocker\` + \`orbitmap status TS-x blocked\` THE MOMENT the worker reports it,
+     not at fold — the run CONTINUES without it.
      Its dependents leave the ready-set with their own logged blocker but KEEP their
      status (backlog): they are waiting, not failed.
    - Recompute the ready-set; next wave.
@@ -256,13 +426,15 @@ 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\`. 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.
@@ -284,7 +456,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"];
@@ -302,15 +474,18 @@ 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"];
 }
 \`\`\`
 
 ## Flow B — work on TS-x (single task)
-1. \`orbitmap context\` — workspace, areas, active mission, open intents and your tasks in
-   one call. Never ask which area; never list areas first.
-2. Unfinished work in context (or \`orbitmap tasks --status in_progress\`) →
-   \`orbitmap task TS-x\` → read the work log → resume from the resume point.
+1. Ensure session focus (see Session focus in the \`orbitmap\` skill): a valid focus file
+   means NO context call; missing or invalid → one \`orbitmap context\` call, match the
+   conversation against its handles, and state the match in one line. A directly named
+   TS-x needs no matching at all — fetch it. Never ask which area; never list areas first.
+2. Unfinished work (\`orbitmap tasks --status in_progress\`, with \`--intent IN-x\` while
+   focused on an intent) → \`orbitmap task TS-x\` → read the work log → resume from the
+   resume point.
 3. Otherwise pick work serving the active mission / open intents, or \`orbitmap start\` —
    auto-picks the first todo task, sets it in_progress and prints full context.
    \`orbitmap start TS-x\` begins a specific task; \`orbitmap task TS-x\` only inspects.
@@ -322,6 +497,13 @@ digraph orbitmap_execute {
 
 ## Logging (both flows)
 - \`orbitmap log TS-x "…" --type note|code_change|decision|blocker\` — work WITHIN a task.
+- CADENCE IS A TEST, not a schedule: log when knowledge arises that git cannot
+  reconstruct — a spec claim that failed verification, a decision with a rejected
+  alternative, a blocker the moment it blocks, a discovery or risk outside the task's
+  boundary, what a failing gate revealed. NOT file lists, test counts or progress
+  narration. 1–3 entries on a normal task — losing nothing is the goal, volume is not.
+  A long task whose whole log lands at the end is refused (WORK_LOG_RECONSTRUCTED) —
+  log during, not after.
 - \`orbitmap vibe log "…" --type discovery|exploration|fix\` — ad-hoc work outside a task.
 - \`orbitmap idea add\` — future possibilities, NOT problems (problems →
   \`orbitmap issue register\`).
@@ -329,18 +511,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:
@@ -358,7 +529,8 @@ digraph orbitmap_execute {
   --type blocker\` then \`orbitmap status TS-x blocked\`.
 - Session ending, task unfinished but NOT blocked → \`orbitmap log TS-x "Resume point: …"
   --type note\` — leave status in_progress.
-- NEVER leave a task without a final log entry.
+- NEVER leave a task without a final log entry — the final entry closes a record that
+  already exists; it is never the record.
 - Closing the intent (ONLY when the user explicitly asks — Flow A never does) → the
   transition must carry the build phase's entries (\`--log <type>:<content>\` is
   repeatable): \`orbitmap intent update IN-x --status done --log code_change:"<what was
@@ -385,22 +557,26 @@ 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.
 - Decide-and-log within the design; \`blocked\` + continue for a stuck task; interrupt the
   user only for intent-level risk. Never a silent skip.
-- Workers follow \`references/worker-contract.md\`: no git, no OrbitMap writes, no shared
-  test DB, no formatter, no dependency changes — the orchestrator owns all of those.
+- Workers follow \`references/worker-contract.md\`: no git, no shared test DB, no
+  formatter, no dependency changes, no OrbitMap writes beyond their own task's log —
+  the orchestrator owns all of those.
 - Flow B works on ONE task at a time.
 - Always read agent_instructions before implementing, then re-verify their claims against
   the tree (distrust-and-verify).
 - Agents with a plan mode: an implementation plan for a tracked task MUST include the
   lifecycle as explicit steps — first the task number/title, last the final \`orbitmap log\`
   + \`orbitmap status\` per the status decision guide.
-- NEVER leave a task without a final log entry; never author \`status_change\`; an intent
-  transition without \`--log\` entries is refused (422).`;
+- NEVER leave a task without a final log entry — it closes a record that already exists,
+  never IS the record; never author \`status_change\`; an intent transition without
+  \`--log\` entries is refused (422).`;
 // Reference files shipped WITH the orbitmap-execute skill (the worker contract that
 // dispatched subagents read instead of the whole skill). See SkillDef.references for
 // the shape the installer consumes.
@@ -423,8 +599,13 @@ state, formatting, the test gates. Your job is the code and an honest report.
 - Own ONLY the files named in your dispatch prompt. A change needed elsewhere is a
   finding to report, never an edit to make.
 - NEVER run git — no commit, branch, stash, checkout. The orchestrator commits.
-- NEVER write OrbitMap state — no \`orbitmap log\` / \`status\` / \`create\` / \`update\`.
-  Reading (\`orbitmap task\`, \`orbitmap doc\`) is fine.
+- OrbitMap writes — one carve-out. You MAY append work-log entries to YOUR ONE
+  dispatched task (\`orbitmap log TS-x "…" --type note|code_change|decision|blocker\`),
+  as knowledge arises, never batched at the end. This is safe because append-only
+  writes to a single task cannot collide between parallel workers. Everything else is
+  still NEVER — \`orbitmap status\` / \`create\` / \`update\`, and any write to any OTHER
+  task: those operations share state the orchestrator owns. Reading (\`orbitmap task\`,
+  \`orbitmap doc\`) is fine.
 - NEVER use the shared test DB or its Docker gate — parallel workers would collide on it.
   The orchestrator runs those tests at fold time.
 - NEVER run the repo formatter (it rewrites files you do not own) and NEVER change
@@ -437,6 +618,19 @@ state, formatting, the test gates. Your job is the code and an honest report.
 - Syntax-check everything you touch with cheap, isolated checks (\`php -l\`, \`tsc --noEmit\`,
   \`python -m py_compile\`, a scoped non-shared test run) — never the shared gates.
 
+## Log as you build — the cadence is a test
+Write a work-log entry when knowledge arises that git cannot reconstruct: a spec claim
+that failed verification, a decision with a rejected alternative, a blocker the moment
+it blocks, a discovery or risk outside your boundary, what a failing check revealed.
+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.
@@ -546,26 +740,22 @@ task/issue that has an intent; the CLI enforces this.
   edge — wire it even though the tasks live in different areas.
 
 ## Flow
-1. Gather context. Read the intent's \`outcome\` + \`design\` + \`plan\` field
+1. Gather context. Ensure session focus (see Session focus in the \`orbitmap\` skill) —
+   the intent you are planning joins the focus by its handle, no context call while the
+   focus file is valid. Read the intent's \`outcome\` + \`design\` + \`plan\` field
    (\`orbitmap intent show IN-x\`) — if the plan field holds seed notes, absorb them as
-   highest-priority input (see above); \`orbitmap context\`; the relevant doc BODIES (\`orbitmap doc <slug>\` — the design flagged
+   highest-priority input (see above); the relevant doc BODIES (\`orbitmap doc <slug>\` — the design flagged
    which); the neighbourhood (mission, sibling intents, and the intent's EXISTING tasks —
    do not re-decompose them). Verify against the repo before decomposing.
 2. Decompose the design into a FLAT list of concrete tasks, each placed in the CORRECT
    area — \`orbitmap create "title" --intent IN-x --area <slug> [--priority p]\`. No
    subtasks.
-   - 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.
+   - DECLARE THE INTENT'S AREAS as part of decomposition: your task placement decisions
+     ARE the intent's area list — write it with
+     \`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.
+${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.
@@ -664,7 +854,8 @@ digraph orbitmap_plan {
 - **Self-contained?** Every task's instructions carry summary + Orb context + doc pointers
   + acceptance + any depends-on line — runnable by a zero-context agent.
 - **No placeholders?** Self-review done; no vague/TBD instructions remain.
-- **Areas?** Each task in the right area.
+- **Areas?** Each task in the right area, and the intent's areas declared
+  (\`intent update --areas\`) to match the placements.
 - **Dependencies?** Orb dep edges wired AND named in the dependent tasks' instructions.
 - **Plan field?** Cross-task notes + a summary written to the intent \`plan\` field.
 - **Doc-update?** A doc-update-after-green task is in the plan.
@@ -702,6 +893,8 @@ triaging issues):
   Orb context + doc pointers + acceptance + any depends-on line). No placeholders.
 - Wire dependencies as Orb edges AND name them in the dependent tasks' instructions.
 - Place each task in the correct area; derive it from the work, not the current directory.
+- Declare the intent's areas during decomposition (\`orbitmap intent update IN-x --areas\`) —
+  task placement decisions are the area list.
 - Self-review the plan before presenting; fix placeholders/coverage/consistency inline.
 - Write cross-task notes + a summary to the intent \`plan\` field.
 - Log \`decision\` entries that pass the keep/drop test (Flow step 2) as they are agreed, never
@@ -753,9 +946,11 @@ you hand to \`orbitmap-design\` (and, through the plan field, to \`orbitmap-plan
   do not interrogate. The ONE thing you must reach is an AGREED OUTCOME; everything else
   useful gets captured for later, never blocked on.
 - **Gate before build.** No feature, component, or behavior change starts before the
-  outcome is agreed and written to OrbitMap. "Too simple to frame" is exactly where
-  unexamined assumptions cost the most — every idea gets an outcome, even a one-sentence
-  one.
+  outcome is agreed and written to OrbitMap. For anything that changes behaviour, "too
+  simple to frame" is exactly where unexamined assumptions cost the most — a one-sentence
+  outcome is still an outcome. Genuinely small self-contained work (a typo, a copy tweak,
+  an obvious one-file fix) is a task, not an intent; see the \`orbitmap\` skill's
+  task-or-intent test.
 - **The outcome is an agreement, not your guess.** It is the user's, in the user's words.
   Never advance on an assumed or half-agreed outcome.
 - **One question at a time.** Refine by dialogue, never a questionnaire dump.
@@ -793,9 +988,11 @@ you hand to \`orbitmap-design\` (and, through the plan field, to \`orbitmap-plan
 
 ## Flow
 1. Gather context.
-   - \`orbitmap context\` and \`orbitmap intent show IN-x\` already carry the workspace,
-     mission, recently-used and open intents, and the target intent; read any referenced
-     idea (ID-) too.
+   - Ensure session focus (see Session focus in the \`orbitmap\` skill): a valid focus
+     file means NO context call; missing or invalid → one \`orbitmap context\` call
+     supplies the matching material. The focus plus \`orbitmap intent show IN-x\` already
+     carry the workspace, mission, the nearby recently-used and open intents, and the
+     target intent; read any referenced idea (ID-) too.
    - Check the repo itself — relevant files, docs, recent commits — when the outcome
      touches existing code and to get all the context.
    - Skim the available knowledge — the doc lists (\`available_docs\` across areas,
@@ -806,7 +1003,9 @@ you hand to \`orbitmap-design\` (and, through the plan field, to \`orbitmap-plan
      intent serve a still-active mission?) and the SIBLING intents under that mission/orbit
      with their outcomes + statuses — from the intent context if present, else
      \`orbitmap mission show MS-x\` / \`orbitmap intents\`. Reconcile or link rather than frame
-     a duplicate/conflicting outcome; ignore siblings that are \`done\`/\`cancelled\`.
+     a duplicate/conflicting outcome — and never declare "no duplicate" from TL;DRs alone:
+     fetch the 1–3 nearest candidates' bodies (\`orbitmap intent show IN-x --no-logs\`)
+     first. Ignore siblings that are \`done\`/\`cancelled\`.
    - Verify the premise before framing: is this already built or partially shipped, is any
      prerequisite phase actually complete, do the named entities exist? Grep migrations /
      commits / the tracker — frame on what is true NOW, not on the plan doc's claim.
@@ -814,18 +1013,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
@@ -847,6 +1035,10 @@ you hand to \`orbitmap-design\` (and, through the plan field, to \`orbitmap-plan
    as the user's in both fields; you may add your own, kept separate. The design gate reads
    the design notes and the plan gate reads the plan notes, each as its highest-priority
    input.
+   - A freshly created intent joins your session focus by its handle — no context call.
+   - OPTIONALLY declare the intent's areas when the conversation already made the touched
+     repos obvious — \`orbitmap intent update IN-x --areas <slug>,<slug>\`; otherwise leave
+     the declaration to the design and plan gates, which own it.
    - If you promoted an OrbitMap idea, mark it used: \`orbitmap idea status ID-x used\`.
 5. Advance the lifecycle, carrying this gate's entries — \`--log <type>:<content>\` is
    REPEATABLE and \`new → design\` is decision-heavy (why this outcome, what is out of scope):
@@ -921,7 +1113,8 @@ Then write it (Flow step 4), advance \`new → design\`, and hand the baton to
 export const SKILL_DESIGN_FRONTMATTER = `---
 name: orbitmap-design
 description: >
-  Designing an intent's solution in OrbitMap: turns an agreed outcome into an approach,
+  Designing an intent's solution in OrbitMap — the second gate of the product-building
+  flow (after brainstorm): turns an agreed outcome into an approach,
   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
@@ -1001,9 +1194,10 @@ well-bounded units are easier to build, review, and reason about.
 
 ## Flow
 1. Gather context.
-   - \`orbitmap intent show IN-x\` → the outcome and the design field; \`orbitmap context\`
-     for the workspace and mission. If the design field holds framing notes, absorb them
-     as highest-priority input (see above).
+   - Ensure session focus (see Session focus in the \`orbitmap\` skill) — the intent you
+     are designing joins the focus by its handle; no context call while the focus file is
+     valid. \`orbitmap intent show IN-x\` → the outcome and the design field. If the design
+     field holds framing notes, absorb them as highest-priority input (see above).
    - Check the repo — relevant files, existing patterns, docs, recent commits. You design
      against real code, so read it before proposing.
    - Pull the relevant OrbitMap docs: from the doc lists (\`available_docs\` /
@@ -1023,18 +1217,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.
@@ -1066,7 +1249,9 @@ well-bounded units are easier to build, review, and reason about.
    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
-   notes that were in the field — you have already absorbed them into the doc.
+   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.
 7. Advance the lifecycle, carrying this gate's entries — \`--log <type>:<content>\` is
    REPEATABLE and \`design → plan\` is decision-heavy (technical choices, rejected
    alternatives):
@@ -1166,7 +1351,9 @@ description: >
 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 \`orbitmap context\` already lists them.
+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).
 
 ## Goal
 Read and update OrbitMap documents efficiently: pull only the context you need (TOC →
@@ -1196,7 +1383,19 @@ conversation.
 - 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
-  inside the OrbitMap workspace/cache directories directly.`;
+  inside the OrbitMap workspace/cache directories directly.
+
+## Editing safely — documents have NO revert (known server defects: IS-8wwkb9)
+- Prefer section ops (\`doc-patch --replace-section/--insert-section\`); use line-based
+  ops only when no section op can express the change — line coordinates are shifted
+  server-side assuming ASCENDING order, and blank edges of op content get trimmed.
+- The section parser is not fence-aware: a line-start \`#\` INSIDE a code block is taken
+  for a heading and becomes a section boundary. Keep code-block comments inline
+  (\`cmd  # comment\`), and check target sections for this hazard BEFORE replacing them.
+- Never read a document between a \`doc-update\` upload and its confirm — a cached read
+  makes the confirm silently re-save the OLD content while still bumping the version.
+- After ANY write, re-read the changed section (or TOC for structure) and verify the
+  result actually matches what you sent. A bumped version number is not proof.`;
 export const SKILLS = [
     {
         name: 'orbitmap',
@@ -1231,35 +1430,37 @@ 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
 
-This project tracks work in OrbitMap via the \`orbitmap\` CLI (cloud or local files alike).
-You work in a WORKSPACE: run \`orbitmap context\` first — one call gives the workspace, your
-areas, the active mission, open intents, tasks and documents. Never ask which area — it
-follows from the directory (map in \`.orbitmap/config.json\`); missions, intents and docs
-need none. When the user mentions tasks, backlog, missions, intents, ideas, issues, vibes,
-or design, load the matching skill: \`orbitmap\` (core), \`orbitmap-execute\` (tasks),
-\`orbitmap-plan\` (missions/intents/ideas/issues), \`orbitmap-brainstorm\` (idea → outcome),
-\`orbitmap-design\` (intent solutions), \`orbitmap-docs\` (documents).
-Golden rules: ONE task at a time per worker — the execute skill orchestrates intents; NEVER
-finish without a final \`orbitmap log\` entry and \`orbitmap status\` update — finished work
-defaults to \`in_review\`, not \`done\`. NEVER edit workspace files directly — always use \`orbitmap\`.`;
+Work is tracked in OrbitMap via the \`orbitmap\` CLI. You work in a WORKSPACE, which can span
+several repositories: each repo is an AREA, while missions, intents and documents belong to
+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).
+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\`.
+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
 
-This project tracks work in OrbitMap via the \`orbitmap\` CLI (cloud or local files alike).
-You work in a WORKSPACE: run \`orbitmap context\` first — one call gives the workspace, your
-areas, the active mission, open intents, tasks and documents. Never ask which area — it
-follows from the directory (map in \`.orbitmap/config.json\`); missions, intents and docs
-need none. When the user mentions tasks, backlog, missions, intents, ideas, issues, vibes,
-or design, follow the sections below: core (context & commands), working on tasks,
-planning (missions/intents/ideas/issues), framing an idea into an outcome, designing an
-intent's solution, and documents.
-Golden rules: ONE task at a time per worker — intent execution orchestrates its tasks; NEVER
-finish a task session without a final \`orbitmap log\` entry and an \`orbitmap status\` update;
-finished work defaults to \`in_review\`, not \`done\`. NEVER edit workspace files directly — always use \`orbitmap\`.`;
+Work is tracked in OrbitMap via the \`orbitmap\` CLI. You work in a WORKSPACE, which can span
+several repositories: each repo is an AREA, while missions, intents and documents belong to
+the workspace itself, not to any one repo.
+Follow the sections below whenever the user wants to build, add, change or fix something, in
+whatever words they use — do not wait for OrbitMap vocabulary. Follow them too when they talk
+about tracking work (backlog, tasks, missions, intents, ideas, issues, documents, planning).
+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\`.
+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) {
@@ -1282,7 +1483,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}`;
 }