Task relations¶

A task can relate to any other task with an optional label, from Bob Mac Capture (~ / ~~) and from the Obsidian Task Card (l / ⇧L). The relation is authored once on the source's 🪢 **LINKS:** line, and a generated 🪢 **LINKED FROM:** line on the target always converges to it. Live chips render both ends correctly, and relations never block, promote, consume, schedule, stamp, or route anything.

This file is the contract every implementation cites. The Rust side is src/native/task_relations/ (LINKS and LINKED FROM parsers, label rules, formatters, canonical sort, slot rules, and edit planners) plus the reconcile_relation_lines pass in bob task reconcile. The JavaScript twins are the relation grammar in bob-navigation-hotkeys, the live relation index and chip model in bob-ledger-tools, and the small recognisers in task-status-cycler and block-id-prompt. Each implementation copies the vector tables it needs from this file into its tests, citing the vector id. If an implementation disagrees with a vector, fix this doc first in the same change.

1. Vocabulary¶

• Task relation (or relation): a directed, optionally labelled, inert edge from a source task S to a target task T. It is stored as one entry on S's LINKS line.
• LINKS line: the single managed direct-child line that holds a task's outgoing relations: 🪢 **LINKS:**.
• LINKED FROM line: the single generated direct-child line that mirrors the relations pointing at a task: 🪢 **LINKED FROM:**. Reconcile owns it; nothing reads it back as input.
• Relation label (or label): optional free text phrased from the source's side, such as follow-up of. Writers trim it, collapse inner whitespace, strip one trailing :, and keep the 1–40 character result.
• Relationship modifiers: capture's existing umbrella for task-to-task modifiers. It covers & (depends on), * (blocks), ~ (links to), and ~~ (linked from). The existing JSON names (picker.relationship, dependency_target, relationship_needs_text, mode task_dependency) keep their spelling and now cover all four.
• Task Link keeps its glossary meaning: a block link to an Obsidian task. Entries on a LINKS line are block links to tasks, but they are never Pomodoro Task Links.

Navigation has two symmetric writers: the Links stage (writes S's LINKS line) and the Linked-from stage (writes other tasks' LINKS lines so they point here). Neither reads a LINKED FROM line as input.

2. What relations never do¶

A relation write, a relation line, or a relation gesture never:

• blocks, unblocks, promotes, releases, or consumes anything; never flips a checkbox to [?], and never recovers one;
• counts as a Pomodoro Task Link, a plan-budget item, a completable sighting, a successor anchor, or a successor offer. Ctrl+Shift+Enter, !, and tree close never act on a relation line;
• changes a status, lane, [fresh::], [keeps::], [unblocked::], schedule, priority, [id::], or [dependsOn::]. The only task-line edit a relation write may make is appending a minted ^block-id;
• counts as a review answer, advances the ]s walk, becomes a walk tier, or triggers inbox routing;
• disappears because either end closes, is cancelled, reopens, or is archived. Relations are history.

A link that needs to block is a dependency (&, b).

3. Grammar¶

Example:

- [ ] #task Fix flaky capture retries ^fix-retries
  - 🪢 **LINKS:** follow-up of [[done/bob_done#^capture-star]] • [[sase#^retry-design]]

<indent>- 🪢 **LINKS:** <entry> • <entry> • …
<entry>        := [<label> ' ']<link>
<indent>- 🪢 **LINKED FROM:** <mirror-entry> • <mirror-entry> • …
<mirror-entry> := <link>[' (' <label> ')']
<link>         := [[#^id]] | [[basename#^id]] | [[dir/note#^id]]

3.1 Writer form¶

• Starts with 🪢 (U+1FAA2, one code point, no VS16), one space, the bold label, and one space. Entries are joined by • (U+2022, one space on each side).
• No aliases, embeds, strikes, or duplicate targets.
• A line that would hold no entries is deleted, with no placeholder.

3.2 Labels¶

A label reads "S ‹label› T". Writers trim it and collapse whitespace runs to one space, strip a trailing :, and require 1–40 characters.

• A label may not contain [, ], (, ), ", \, |, •, *, ~, or a control character.
• It may not start with · or ,.
• Case is preserved. Suggestions dedupe case-insensitively.
• Readers accept any length that obeys the character rules.

3.3 Parse algorithm¶

Run the shared block_link_spans scanner first and never split on separators, because an alias can contain one.

1. Find the block links first (the shared link scanner already handles aliases, !, and ~~), then check what surrounds them.
2. After each link, skip one separator (•, ·, or ,) and whitespace. The text up to the next link is that entry's label.
3. A struck (~~[[…]]~~) or embedded (![[…]]) link is accepted and canonicalised.
4. An aliased link's alias becomes the label only when no label precedes it.
5. On LINKED FROM, a (label) after a link is its label.

3.4 Reader tolerance¶

Writers canonicalise all of these:

• the glyph is missing, or is 🔗;
• the authored label is LINKS or LINKS TO; the mirror label is LINKED FROM or BACKLINKS. Labels must be bold and uppercase;
• the separator is ·, ,, or whitespace instead of •;
• the line is in any direct-child slot.

3.5 Not a line¶

• Non-bold LINKS: (the 660 ref/ note links are plain text);
• lowercase labels, and RELATED / SEE ALSO;
• anything that is not a direct child of a #task;
• fenced, nested, blockquoted, or marker-less lines.

3.6 Malformed¶

• Text after the last link;
• a label that breaks the character rules;
• a half-typed link, a bare note link, or a heading link;
• separators only.

A malformed line is left untouched and warned about (malformed_links_line / malformed_linked_from_line). Writers never insert a second line beside one. An authored write to a malformed LINKS line is refused with "its LINKS line is malformed".

3.7 Cross-parse¶

The Depends-On, BLOCKS, LINKS, and LINKED FROM parsers each return not-a-line for the others' lines (LK19, MC15).

4. Slot and order¶

- [ ] #task T ^t
  - ❌ **CANCEL LOG**        (first, if present)
  - ⛓️ **DEPENDS ON:** …     upstream
  - 🧱 **BLOCKS:** …         downstream
  - 🧩 **Sub-projects:** …   structure (^prj only)
  - 🪢 **LINKS:** …          what T relates to (authored)
  - 🪢 **LINKED FROM:** …    what relates to T (generated)
  - user children, 🗓️ SCHEDULE LOG, 🛠️ WORK LOG …

• Slots. LINKS goes after the last direct-child subtree of Cancel Log, Depends-On, BLOCKS, or Sub-projects. Otherwise it is the first direct child (the second after a first-child Cancel Log). LINKED FROM goes after the LINKS subtree when one exists, otherwise in the LINKS slot.
• Reuse the task's existing child indent, otherwise use the parent indent plus one tab.
• Preserve CRLF and the final-newline state.
• Existing lines are never moved. A Depends-On, BLOCKS, or Sub-projects line inserted later lands in its own earlier slot, so the order still reads upstream, downstream, structure, out, then in. bob projects sync's anchor rule (after Depends-On and BLOCKS) is unchanged.
• LINKS order is authored. New entries are appended. Re-linking an existing target with a different label relabels it in place; with the same label it is a no-op.
• LINKED FROM order is canonical. Sort by canonical link text after ASCII case-folding, comparing Unicode code points, with raw code-point order as the tie-break: exactly BK21. Same-note entries therefore come first. JS compares code points, never UTF-16 units.
• Duplicates. A writer that touches a task with two LINKS lines merges the later line's entries into the first (appended, first label wins) and deletes the later one. On duplicate targets within one line, the first entry wins. Reconcile keeps the first LINKED FROM line and deletes the rest.

5. Identity and minting¶

• Edge identity is (S, T), each resolved by vault-relative path plus block id. A source holds at most one entry per target. A → B and B → A are independent edges, and cycles are allowed. Self-relations and non-task targets are refused.
• The target needs a ^block-id. Pickers show ＋ id and run the existing new-block-ID step (nav showBlockIdStage; capture requires_block_id / block_id_suggestions plus capture-task-id). Completion, dry-run, and Escape mint nothing. An id-less archived target is disabled ("archived tasks can't get an id").
• The source needs a ^block-id only for the mirror. It is minted silently with mint_block_id(description, used) (§11.7 of the dependency contract), once, inside the same transaction or batch, exactly like BLOCKS dependents (§14.4).
• No [id::] is ever added.
• When relations.linked_from_lines is false, no source is minted.
• In ~~, the new task is the target, so it is always minted.
• Never emit a link to an id that will not be on disk after the write. Reconcile skips listing a source whose mint would land in a note that is quiet-deferred this run (BR5).
• Link form. Use canonical_link from the owning note: [[#^id]], then [[basename#^id]], then [[dir/note#^id]]. A done/ source or target always keeps the explicit [[done/…#^id]] form, the only form the hooks resolve into archives.
• A broken link is never rebound by title or by a reused id. Supported moves (bob task move, Ctrl+Shift+M, bob task archive, and Obsidian renames) already rewrite links on every line.

6. The LINKED FROM projection¶

sources   = #task lines with a LINKS line in: active notes (writable)
            ∪ the previous daily note (read-only) ∪ every .md under done/ (read-only)
edges     = { (S, T, label) : an entry on S's LINKS resolves to #task T ∧ T ≠ S }
            (unresolved, non-task, self, and malformed are warned and omitted; never pruned from LINKS)
mirror(T) = sort_canonical({ (S, label) : (S, T, label) ∈ edges })
T owns a LINKED FROM line ⇔ mirror(T) ≠ ∅ ∧ T is writable (not done/, not the previous daily note)

• Open or closed T gets a maintained mirror. Unlike BLOCKS, it never freezes.
• Never prune on uncertainty. If S's LINKS line is malformed, or S's note has duplicate block ids, existing LINKED FROM entries naming S are kept and S is never newly added.
• The done/ read is narrow. Byte-prefilter every done/**/*.md for LINKS, parse only those files, and never write there during reconcile. The explicit rename exception below changes label spans only. Document it beside the exact-done/-target exception in docs/task-status-hooks.md.
• Rename exception (LR7). bob relations rename rewrites matching label spans in LINKS and LINKED FROM, including done/ and the previous daily note. It preserves each edge and every other byte; no other relation writer can change those notes.

7. Reconciliation¶

Reconcile is the authority for LINKED FROM. Gestures and capture make early courtesy writes, and closes, vim edits, agent edits, moves, and failed follow-ups are repaired by reconcile.

1. New pass reconcile_relation_lines in task_status_hooks/relations.rs. It runs right after reconcile_blocks_lines, over the re-parsed text, with the same structure.
2. Owners to check: every T with mirror(T) ≠ ∅, plus every writable task that already has a LINKED FROM child. Byte-prefilter for LINKED FROM / BACKLINKS; never walk every task's children.
3. Steps for each owner: mint missing source ids, render against the post-mint state, then call the cli-core mirror planner with the desired entries:

1. Guarded output. The edits are structural. They join the reconciled set, so the 2 s quiet interval, preimage checks, recovery snapshots, and pre_reconcile originals all apply.
2. Reconcile never edits a LINKS line. It only reads, warns, and mints.

8. Immediate writers¶

All writers share one planner, implemented in Rust with a JS twin and pinned by the same LW vectors. Writers compare canonical output before writing, so a no-op writes nothing and adds no undo entry. Writes stamp nothing.

9. Gestures on relation lines¶

10. Chips¶

Chips render a live relation index (§11), never the stored mirror.

• Anatomy. Reuse the bob-dep-row / bob-dep-chip family: a mini status checkbox from --task-status-*, about 40 characters of description, ↗ note for cross-note entries, a hover preview, and click / Mod-click. The row accent stays neutral. Colour carries status, never direction. Closed and archived targets are dimmed and never struck. #hide tasks are muted. There is no new palette, and no frees / waiting on badges.
• Labels are a muted small-caps pill on the arrow side.
• LINKS: ‹label› → (chip).
• LINKED FROM: ‹inverse› (chip) for a known label (the inverse table below), otherwise (chip) · ‹label› → this.
• Rows with labels wrap one entry per visual row. Unlabelled rows wrap between chips. Chips never change line height.
• Stale and broken. A stored LINKED FROM entry that is no longer live is dashed, with the tooltip No longer links here · refreshes on the next reconcile. A live edge missing from the text is appended in canonical order. A LINKS entry whose target cannot be resolved is a dashed ⚠ ^id not found.
• Collapse. Three or more closed chips on a row collapse to ✓×N, which expands on click.
• Controls (only when nav api.relations?.version >= 1):
• a trailing ＋ on LINKS (aria "Link this task to another") opens the Links stage;
• a trailing ＋ on LINKED FROM (aria "Choose a task that links here") opens the Linked-from stage;
• a hover × on each live LINKS chip (aria "Unlink ‹name›") removes the link;
• a hover × on each live LINKED FROM chip (aria "Remove the link from ‹name›") calls removeLink(S, T). The notice names S's note.
• Toggle. toggle-dependency-chips covers both relation rows too.
• Without the plugin, both lines still read as English.

Inverse phrases (display only; case-insensitive match; never stored):

The nav Linked-from stage's CURRENT rows use the same table.

11. The live relation index¶

bob-ledger-tools keeps a raw-text relation index and publishes it as api.relationIndex v1:

• Startup scan. A chunked, generation-guarded scan with a cheap prefilter: skip files whose metadata cache has no #^ block links, then text-prefilter for 🪢, **LINKS, **LINKED FROM, or **BACKLINKS. The scan includes done/, as read-only sources.
• Updates. Reparse per file on metadataCache.changed, and handle vault delete and rename. Overlay the active editor's unsaved text, so a just-typed entry shows at the target before save.
• Publishing. Forward (S → [(T, label)]) and reverse (T → [(S, label)]) maps are published together under one generation, so a count and its rows never disagree. Targets resolve by getFirstLinkpathDest plus the file's cached block ids. Status and text come from the Tasks memo, falling back to the cached line for notes the memo omits (done/).
• API. api.relationIndex v1 exposes version, generation, ready(), outgoing(path, blockId|line), incoming(path, blockId), and labelSuggestions(prefix?) → [{label, count}] (case-insensitive dedupe, count order). Chips subscribe through onChange.

12. Kill switch, outputs, and warnings¶

relations:
  linked_from_lines: true # write 🪢 LINKED FROM mirrors (task-relations.md)

Rust and nav read it from ~/.config/bob/config.yml (BOB_CONFIG_FILE / XDG_CONFIG_HOME). An invalid value falls back to true and warns.

• With false, reconcile removes every LINKED FROM line on writable tasks, mints nothing, and leaves LINKS alone, so the switch is lossless.
• Gestures and capture write no mirror and mint no source.

bob task reconcile JSON gains linked_from_line_updates, minted_relation_source_block_ids, and relation_warnings[] ({kind, path, line, message}), where kind is one of malformed_links_line, malformed_linked_from_line, unresolved_relation_link, relation_target_not_task, self_relation, or duplicate_block_id. Human output gets a 🪢 group in the dependency style, and --dry-run previews all of it.

Capture JSON (every schema_version stays 1; additive only):

• capture-parse: span kinds relation_sigil, relation_note, relation_block_id, relation_label_separator (covering both pipes for ||), and relation_label; top-level and per-item relations[] ({raw, direction: "to"|"from", note, block_id, quoted, hidden, label, label_range, range}, with hidden only for the || spelling), omitted when empty; needs relation_target and relation_label (an empty || probe is the relation_label need); top-level relation_grammar: 1 whenever the draft contains a ~ byte. Drafts without ~ are byte-identical to today, as is every | spelling. Relations never appear in dependencies[] or blocked_tasks[]. ~note:id|||label is an invalid_relation teaching use || to hide a label, | to name one.
• capture-complete: contexts relation_to and relation_from (the DependencyCandidate shape, plus already_linked, existing_label, also_prerequisite, and disabled_reason); context relation_label with catalog-backed suggestions[] (visible rows {label, key, count, replacement, hide_replacement, inverse?} and a leading typed row {label, key, replacement, hide_replacement, typed: true, existing?, count?, hidden?, disabled_reason?}); hidden rows are omitted except for an exact typed match. A || probe keeps its pipe count in replacement and gains one_off: true, with hide_replacement always the || form. The response includes hidden_count in this context. Typed key matches use the catalog display spelling. Shell completion gains links to / linked from groups.
• capture-task-id: relation_to_replacement (~note:id) and relation_from_replacement (~~note:id).
• capture / --dry-run, per item: relation_updates[] ({direction, source, target, label, previous_label, action: added|relabeled|unchanged}), linked_from_line_updates[], minted_relation_block_ids[], mirror_skipped[] ({reason: archived_target|previous_daily_target|malformed_line|disabled}), and relation_label_hides[] ({label, key, existing_count, was_hidden, action: hide|already_hidden}), plus a hides_existing_relation_label warning object ({code, label, count, message}) when a one-off hides a visible existing label and a relation_label_hide_failed object ({code, message}) when the journal append fails.

13. Guarantees¶

1. Single source (LR11). Delete every LINKED FROM line and run reconcile once: the lines come back byte-identical, and a second run changes nothing.
2. Inertness (LR18, LX13, LG13). Adding, removing, or relabelling any relation leaves every status, lane, field, schedule, Pomodoro section, and Depends-On / BLOCKS line byte-identical, apart from a minted ^id.
3. Engine agreement (LW14, LK*). Rust and JS agree on every LK, LW, and LM vector, malformed cases included.
4. Live view (LC8). Chips render from the live index, never from the stored mirror.
5. Convergence (LR3). Canonical sorting makes two machines produce the same bytes, and the next reconcile heals any textual conflict.
6. Read-only respect (LR7). Relation writes leave done/ and the previous daily note alone, except bob relations rename, which rewrites relation-label spans only and preserves every other byte.

14. Lifecycle¶

• Close, cancel, reopen S or T. None. Relations are history; nothing changes.
• Archive S. Link repair rewrites T's mirror entry to the [[done/…#^s]] form; reconcile keeps it unchanged (LR22).
• Archive T. No mirror is written in done/; chips show the live view only.
• Move or rename S or T. Generic link rebasing applies on every line; reconcile re-sorts and repairs the mirrors (LR10).
• T deleted. The LINKS entry stays, warned as unresolved_relation_link, and chips show ⚠ ^id not found. It is never auto-removed.
• S deleted. Its edges vanish with its note; the next reconcile removes the orphaned mirror entries.
• Duplicate ids. A source whose note carries a duplicate ^s is not listed, with a duplicate_block_id warning (LR23).
• Raw cut-and-paste. A pasted LINKS line is authored data and is kept; a pasted LINKED FROM line is regenerated on the next reconcile.
• Adopting old idioms. Hand-written Merged into [[…]], See [[…]], and **RELATED:** bullets are not adopted; adopting them is an opt-in follow-up.

15. Conformance vectors¶

LK — parse¶

LW — planner writes (LINKS and LINKED FROM)¶

LR — reconcile (mirror)¶

LX — capture execution¶

LP — capture parse¶

LD — double-pipe one-off labels¶

The executable cases live in tests/fixtures/relation_labels/vectors.json (grammar, rust_only).

LG — Obsidian gestures¶

LC — chips¶

16. Label vocabulary¶

Rules RV1–RV4, the CLI and journal parts of RV7, and RV8 are shipped. RV5, RV6, and RV9 remain planned until their phases land.

RV1 Words¶

• Relation label (contracts, CLI, JSON, code) is the optional text on a LINKS entry. The UI mostly says relation. Never use "description" in code or contracts: bob already uses it for task text.
• Hide / Unhide / Show hidden. Never "disable": disabled_reason already means "cannot be inserted", and a hidden label can still be inserted.
• One-off: a label created hidden (||). Wording that is never suggested again, not an expiring link. Relations are history.
• Naming in code: relation_labels (Rust module), RelationLabel* (Swift), api.relationLabels (JS).

RV2 Key, catalog, and display spelling¶

• Key. relation_label_key(label) applies the writer normalization (trim, collapse whitespace runs, strip one trailing :) and then Unicode to_lowercase. This one function feeds the catalog, the typed-row match, the journal, rename, and, through vectors, the JS mirror. No NFC or other new equivalence.
• Catalog. One row per key, counting every accepted LINKS entry with that label: open, closed, done/, daily notes, nested projects, and references. The walk visits every .md in sorted path order (the dependency discover set, done/ included), byte-prefilters for **LINKS, then parses direct children of #task lines with task_relations::parse::links_children_of. Malformed lines are skipped with a bounded warning. Completion tolerates them; rename refuses them. Never calls capture_dependency_tasks::discover. Parsed note rows use the machine-local bob-cli cache and per-file modification-time and size fingerprints. The full snapshot is reused for up to 60 seconds; a cache miss checks changed, new, and deleted notes, and successful bob capture writes invalidate it immediately.
• Display spelling. The most-used spelling of the key, with ties going to the first seen. spellings[] lists every spelling with its count, so case drift is visible.
• Inverse. The §10 display-only table, matched case-insensitively and never stored (task_relations::label::inverse_phrase).
• Journal-only keys. A hidden key with zero uses stays listable (count 0) from the journal's stored name, so it can always be found and unhidden.

RV3 Preferences journal¶

• Location: .bob/relations/<host>.jsonl, one append-only file per host. The host label is the vault-sync host label.
• Events (v: 1): relation_label.hide (key, name), relation_label.unhide (key, name), and relation_label.rename (from, to, from_name, to_name), each with v, ts, host, and via.
• Fold: exactly the theme rule, over the shared pref_journal module: read every *.jsonl, skip malformed lines with a bounded warning, sort by (ts instant, host, path, line), last writer wins per key, and a rename moves the source key's explicit state unless the target already has state. Events after a rename on the old key apply to the old key.
• Writers: bob only. Appends happen under bob_sync.lock with a 3 s wait (busy gives lock_busy), one O_APPEND write per event, and the directory is created on first use.
• Vault allowlist: !/.bob/relations/*.jsonl in .gitignore, and .bob/relations/*.jsonl merge=union in .gitattributes.

RV4 What hiding means¶

• Hiding removes a label from suggestions only. Card rows, the Obsidian stage, relations list defaults, and shell completion. LINKS text, LINKED FROM mirrors, chips, counts, and typed use are unchanged. The twin of theme-hide-is-recent-only.
• Using a hidden label never unhides it. Typing its exact name still works and is flagged hidden.
• No silent state. Nothing auto-hides. A hide is always an explicit Ctrl+D, bob relations hide, or ||.

RV5 The relation card¶

planned (phase mac-chooser, phase mac-vocab, phase mac-rename). Ctrl+N/P navigate without touching the query, Tab accepts or completes the top match, selection is by key, Ctrl+D hides what Return would insert, Ctrl+H toggles the Hidden section, and Ctrl+R renames everywhere.

RV6 Capture grammar: ||¶

~note:id||label stores the plain label and, once the capture succeeds, hides it from suggestions. The || spelling covers ~~ targets and "multi word" labels; an empty || is an incomplete relation_label need; ||| is a teaching error. The stored Markdown is identical to the | form, and || glues the way | glues. Warn, never block: the hide lands only after the notes commit succeeds (a dry run or a failed capture leaves no trace), one event per key in a multi-item draft, counts from the pre-capture catalog, and a failed append warns with the retry command while the capture succeeds. Hiding a visible existing label carries an amber warning with the link count; an already-hidden label writes no event. Shell examples quote the draft, so the shell never sees ||.

RV7 Contracts¶

Every schema_version stays 1; JSON grows additively.

• bob relations: a group in Tasks and projects, between projects and task. Its membership rule is "the relation-label vocabulary" (the bob themes precedent: a catalog noun whose rename also rewrites notes). A bare group runs the read-only list. Hide and unhide do not rewrite task lines, so they stay out of bob task, and nothing goes under bob capture.

bob relations [list] [-a/--all] [-f/--format human|json] [-H/--hidden] [-n/--limit N] [-q/--query Q]
bob relations hide LABEL…   [-f/--format human|json] [--allow-unused]
bob relations rename OLD NEW [-d/--dry-run] [-f/--format human|json] [-m/--merge] [-o/--offline]
bob relations unhide LABEL… [-f/--format human|json]

Hidden internal arguments: --via CLIENT (default bob-cli) on every writer, and --allow-unused on hide. Clients that hide a label they just wrote, before bob can see it on disk, pass --allow-unused.

• Human list (mint relation accent on a TTY, dim counts; still readable with NO_COLOR):

RELATIONS  3 labels · 6 links · 1 hidden
  inspired by      3 links
  implements       2 links
  duplicate of     1 link     ⇄ duplicated by     ◌ hidden   (with -a)

• JSON list: {schema_version, ok, counts:{labels, links, hidden}, labels:[{key, name, count, hidden, inverse, spellings, replacement, hide_replacement}], renamed_reappeared, warnings}. renamed_reappeared reports an OLD label used again after its rename; it reports the row and never rewrites the new use.
• Writers emit {schema_version, ok, …}. Human hide output reads: 🪢 Hid “implements” from relation suggestions · 2 links keep their label · undo: bob relations unhide implements.
• Refusal codes: unknown_label, invalid_label, unchanged, label_exists, malformed_links_line, lock_busy, dirty_paths, not_a_worktree, sync_failed, verify_failed, and stale_note.
• capture-complete relation_label: rows come from the fast relation-label catalog, use canonical keys and display spelling, include inverse phrases and counts, omit hidden rows, expose exact typed matches (including hidden state), and return hidden_count. zsh describes each row as N links. Every row and the typed row carry hide_replacement (always the || form); a || probe keeps its pipe count in replacement and gains one_off: true; the response carries hidden_count (present, possibly 0) in this context.
• capture / --dry-run, per item: relation_label_hides[] ({label, key, existing_count, was_hidden, action: hide|already_hidden}; pre-capture counts; one entry per distinct hidden label key, omitted when empty). Hiding a visible existing label also adds a warnings[] object ({code: "hides_existing_relation_label", label, count, message}) with a bob-authored message that clients render without computing the count, and a human 🪢 hides "label" from suggestions (N links) line. A failed journal append adds {code: "relation_label_hide_failed", message} with the exact retry command; the capture still succeeds. A dry run previews all of this and writes nothing.

RV8 The rename transaction¶

bob relations rename OLD NEW uses one previewed transaction and one revertable commit (bob relations rename: OLD → NEW). It scans every .md note in the RV2 scope, including done/ and the previous daily note, and rewrites only matching label spans on accepted LINKS and LINKED FROM lines. A malformed matching line or unreadable note refuses the plan rather than under-covering it. Case-only renames unify spelling; an unchanged spelling refuses; an existing NEW key requires --merge. Merge keeps every edge and its order. The source hidden state moves to NEW unless NEW already has explicit state. The preview lists each file and changed line, link and mirror counts (including done/), state and inverse changes, and NEW's replacement and hide_replacement forms.

Undo a successful rename with git revert <rename-commit>; the commit contains the note-span rewrites and the journal event. No live-vault rename is part of acceptance.

RV9 Obsidian¶

planned (phase obsidian-vocab, phase obsidian-rename). One ranker and one key shared through byte-for-byte vectors, a read-only journal fold, api.relationLabels v1 with desktop-only hide/unhide/rename writes through bob, and the nav relation-label stage with the card's keys and copy.

Shared vectors¶

tests/fixtures/relation_labels/vectors.json is the single source. Its key, catalog, fold, rank, and grammar (rust_only, LD vectors) sections are consumed by Rust tests; rename (rust_only) arrives with its phase. bob-plugins copies the file byte-for-byte when planned (phase obsidian-vocab) lands.