@k-l-lambda/portolan 0.0.0-stage → 0.1.0

package/dist/threads.d.ts

@@ -0,0 +1,93 @@
+export type ThreadEvent = {
+    type: "open";
+    thread: string;
+    target: string;
+    author: string;
+    text: string;
+    time: string;
+    id: string;
+} | {
+    type: "reply";
+    thread: string;
+    author: string;
+    text: string;
+    time: string;
+    id: string;
+    reply_to?: string;
+} | {
+    type: "resolve";
+    thread: string;
+    author: string;
+    time: string;
+} | {
+    type: "reopen";
+    thread: string;
+    author: string;
+    time: string;
+}
+/** Written when a node ID is renamed, so threads follow the node. */
+ | {
+    type: "retarget";
+    thread: string;
+    target: string;
+    time: string;
+};
+export interface Message {
+    id: string;
+    author: string;
+    text: string;
+    time: string;
+    reply_to: string | null;
+}
+export interface Thread {
+    id: string;
+    /** Node ID the thread is attached to. */
+    target: string;
+    status: "open" | "resolved";
+    messages: Message[];
+    updated: string;
+}
+export interface FoldResult {
+    threads: Thread[];
+    /** 1-based sidecar lines that could not be applied. */
+    problems: {
+        line: number;
+        message: string;
+    }[];
+}
+export declare function foldThreads(events: {
+    event: unknown;
+    line: number;
+}[]): FoldResult;
+/** Input accepted from clients; the store fills in IDs and timestamps. */
+export type ThreadAction = {
+    action: "open";
+    target: string;
+    author: string;
+    text: string;
+} | {
+    action: "reply";
+    thread: string;
+    author: string;
+    text: string;
+    reply_to?: string;
+} | {
+    action: "resolve";
+    thread: string;
+    author: string;
+} | {
+    action: "reopen";
+    thread: string;
+    author: string;
+};
+export declare class ThreadStore {
+    readonly path: string;
+    constructor(rhumbPath: string);
+    load(): FoldResult;
+    /** Validates a client action, appends the event and returns it. */
+    apply(input: ThreadAction): ThreadEvent;
+    /** Makes threads follow a renamed node. */
+    retarget(from: string, to: string): void;
+    private requireThread;
+    private append;
+}

package/dist/threads.js

@@ -0,0 +1,128 @@
+// Annotation threads, stored in an append-only sidecar `<name>.threads.jsonl` next to the
+// .rhumb file. One JSON event per line; state is rebuilt by folding events, so resolving
+// or retargeting never rewrites old lines and concurrent writers rarely conflict.
+//
+// Open interfaces (not implemented in 0.1):
+// - Delivering new human messages to an agent. The server emits a `threads` SSE event and
+//   `GET /api/threads?status=open` lists pending threads; a CLI poller, MCP tool or hook
+//   can be built on top of that.
+// - Targets other than nodes (edges, anchors) and @mentions.
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+export function foldThreads(events) {
+    const threads = new Map();
+    const problems = [];
+    for (const { event, line } of events) {
+        const e = event;
+        const t = threads.get(e?.thread);
+        if (e?.type === "open") {
+            if (t) {
+                problems.push({ line, message: `Thread ${e.thread} opened twice` });
+                continue;
+            }
+            threads.set(e.thread, {
+                id: e.thread, target: e.target, status: "open", updated: e.time,
+                messages: [{ id: e.id, author: e.author, text: e.text, time: e.time, reply_to: null }],
+            });
+            continue;
+        }
+        if (!t) {
+            problems.push({ line, message: "Event for an unknown thread" });
+            continue;
+        }
+        switch (e.type) {
+            case "reply":
+                t.messages.push({ id: e.id, author: e.author, text: e.text, time: e.time, reply_to: e.reply_to ?? null });
+                break;
+            case "resolve":
+                t.status = "resolved";
+                break;
+            case "reopen":
+                t.status = "open";
+                break;
+            case "retarget":
+                t.target = e.target;
+                break;
+            default:
+                problems.push({ line, message: "Unknown event type" });
+                continue;
+        }
+        t.updated = e.time;
+    }
+    return { threads: [...threads.values()], problems };
+}
+const MAX_TEXT = 20_000;
+const MAX_AUTHOR = 100;
+export class ThreadStore {
+    path;
+    constructor(rhumbPath) {
+        this.path = rhumbPath.replace(/\.rhumb$/, "") + ".threads.jsonl";
+    }
+    load() {
+        if (!existsSync(this.path))
+            return { threads: [], problems: [] };
+        const events = [];
+        const problems = [];
+        readFileSync(this.path, "utf8").split("\n").forEach((text, i) => {
+            if (text.trim() === "")
+                return;
+            try {
+                events.push({ event: JSON.parse(text), line: i + 1 });
+            }
+            catch {
+                problems.push({ line: i + 1, message: "Invalid JSON" });
+            }
+        });
+        const folded = foldThreads(events);
+        return { threads: folded.threads, problems: [...problems, ...folded.problems] };
+    }
+    /** Validates a client action, appends the event and returns it. */
+    apply(input) {
+        const a = input;
+        const str = (k, max) => {
+            const v = a[k];
+            if (typeof v !== "string" || v.trim() === "" || v.length > max)
+                throw new Error(`Invalid ${k}`);
+            return v;
+        };
+        const time = new Date().toISOString();
+        let event;
+        switch (a.action) {
+            case "open":
+                event = { type: "open", thread: randomUUID(), target: str("target", 100), author: str("author", MAX_AUTHOR),
+                    text: str("text", MAX_TEXT), time, id: randomUUID() };
+                break;
+            case "reply":
+                this.requireThread(str("thread", 100));
+                event = { type: "reply", thread: a.thread, author: str("author", MAX_AUTHOR),
+                    text: str("text", MAX_TEXT), time, id: randomUUID(),
+                    ...(typeof a.reply_to === "string" ? { reply_to: a.reply_to } : {}) };
+                break;
+            case "resolve":
+            case "reopen":
+                this.requireThread(str("thread", 100));
+                event = { type: a.action, thread: a.thread, author: str("author", MAX_AUTHOR), time };
+                break;
+            default:
+                throw new Error("Unknown action");
+        }
+        this.append(event);
+        return event;
+    }
+    /** Makes threads follow a renamed node. */
+    retarget(from, to) {
+        const time = new Date().toISOString();
+        for (const t of this.load().threads) {
+            if (t.target === from)
+                this.append({ type: "retarget", thread: t.id, target: to, time });
+        }
+    }
+    requireThread(id) {
+        if (!this.load().threads.some((t) => t.id === id))
+            throw new Error(`Unknown thread ${id}`);
+    }
+    append(event) {
+        appendFileSync(this.path, JSON.stringify(event) + "\n");
+    }
+}
+//# sourceMappingURL=threads.js.map

package/dist/threads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"threads.js","sourceRoot":"","sources":["../src/threads.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,yFAAyF;AACzF,kFAAkF;AAClF,EAAE;AACF,4CAA4C;AAC5C,0FAA0F;AAC1F,yFAAyF;AACzF,iCAAiC;AACjC,6DAA6D;AAE7D,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAiCzC,MAAM,UAAU,WAAW,CAAC,MAA0C;IACpE,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,MAAM,QAAQ,GAA2B,EAAE,CAAC;IAC5C,KAAK,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,MAAM,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,KAAoB,CAAC;QAC/B,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;QACjC,IAAI,CAAC,EAAE,IAAI,KAAK,MAAM,EAAE,CAAC;YACvB,IAAI,CAAC,EAAE,CAAC;gBAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,MAAM,eAAe,EAAE,CAAC,CAAC;gBAAC,SAAS;YAAC,CAAC;YACzF,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE;gBACpB,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,IAAI;gBAC/D,QAAQ,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;aACvF,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,IAAI,CAAC,CAAC,EAAE,CAAC;YAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,6BAA6B,EAAE,CAAC,CAAC;YAAC,SAAS;QAAC,CAAC;QACtF,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;YACf,KAAK,OAAO;gBAAE,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,IAAI,IAAI,EAAE,CAAC,CAAC;gBAAC,MAAM;YAC/H,KAAK,SAAS;gBAAE,CAAC,CAAC,MAAM,GAAG,UAAU,CAAC;gBAAC,MAAM;YAC7C,KAAK,QAAQ;gBAAE,CAAC,CAAC,MAAM,GAAG,MAAM,CAAC;gBAAC,MAAM;YACxC,KAAK,UAAU;gBAAE,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;gBAAC,MAAM;YAC5C;gBAAS,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,oBAAoB,EAAE,CAAC,CAAC;gBAAC,SAAS;QAC5E,CAAC;QACD,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC;IACrB,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC;AACtD,CAAC;AASD,MAAM,QAAQ,GAAG,MAAM,CAAC;AACxB,MAAM,UAAU,GAAG,GAAG,CAAC;AAEvB,MAAM,OAAO,WAAW;IACb,IAAI,CAAS;IAEtB,YAAY,SAAiB;QAC3B,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,GAAG,gBAAgB,CAAC;IACnE,CAAC;IAED,IAAI;QACF,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;QACjE,MAAM,MAAM,GAAuC,EAAE,CAAC;QACtD,MAAM,QAAQ,GAA2B,EAAE,CAAC;QAC5C,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;YAC9D,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;gBAAE,OAAO;YAC/B,IAAI,CAAC;gBACH,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACxD,CAAC;YAAC,MAAM,CAAC;gBACP,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC,CAAC;YAC1D,CAAC;QACH,CAAC,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;QACnC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,QAAQ,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;IAClF,CAAC;IAED,mEAAmE;IACnE,KAAK,CAAC,KAAmB;QACvB,MAAM,CAAC,GAAG,KAAgC,CAAC;QAC3C,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,GAAW,EAAE,EAAE;YACrC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YACf,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,MAAM,GAAG,GAAG;gBAAE,MAAM,IAAI,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;YAChG,OAAO,CAAC,CAAC;QACX,CAAC,CAAC;QACF,MAAM,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACtC,IAAI,KAAkB,CAAC;QACvB,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC;YACjB,KAAK,MAAM;gBACT,KAAK,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,QAAQ,EAAE,UAAU,CAAC;oBACzG,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,CAAC;gBACxD,MAAM;YACR,KAAK,OAAO;gBACV,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC;gBACvC,KAAK,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,MAAgB,EAAE,MAAM,EAAE,GAAG,CAAC,QAAQ,EAAE,UAAU,CAAC;oBACpF,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,UAAU,EAAE;oBACnD,GAAG,CAAC,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;gBACxE,MAAM;YACR,KAAK,SAAS,CAAC;YACf,KAAK,QAAQ;gBACX,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC;gBACvC,KAAK,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,MAAgB,EAAE,MAAM,EAAE,GAAG,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE,IAAI,EAAE,CAAC;gBAChG,MAAM;YACR;gBACE,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAC;QACtC,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACnB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,2CAA2C;IAC3C,QAAQ,CAAC,IAAY,EAAE,EAAU;QAC/B,MAAM,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACtC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC;YACpC,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI;gBAAE,IAAI,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3F,CAAC;IACH,CAAC;IAEO,aAAa,CAAC,EAAU;QAC9B,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC;IAC7F,CAAC;IAEO,MAAM,CAAC,KAAkB;QAC/B,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;IAC1D,CAAC;CACF"}

package/dist/types.d.ts

@@ -0,0 +1,62 @@
+export type Status = "todo" | "doing" | "done" | "dropped" | "blocked" | "idea";
+export type EdgeKind = "needs" | "blocks" | "relates" | "replaces" | "from";
+export type Level = "error" | "warning" | "info";
+export interface Diagnostic {
+    code: string;
+    level: Level;
+    line: number;
+    message: string;
+}
+export interface Anchor {
+    text: string;
+    target: string;
+    line: number;
+    /** `prefix`: `diary:…` resolved via front matter `links`; `relative`: path from the .rhumb file; `url`: absolute URL. */
+    kind: "prefix" | "relative" | "url";
+    prefix: string | null;
+    path: string | null;
+    /** Heading slug (or unique slug prefix) the fragment starts from. */
+    fragment: string | null;
+    text_fragment: string | null;
+    /** `^=prefix`: first line in the section (or file) that starts with this text, ignoring indentation. */
+    line_prefix: string | null;
+    /** `+L3` / `-L2`: lines below / above the matched line or the heading. */
+    line_offset: number | null;
+    /** `#L42` or `#L42-L50`: absolute 1-based line range. */
+    lines: [number, number] | null;
+    /** Why the fragment could not be parsed; the resolver reports it as W003. */
+    fragment_error: string | null;
+}
+export interface Note {
+    text: string;
+    line: number;
+    /** Nesting depth below the owning node; 0 = direct note. */
+    depth: number;
+}
+export interface RhumbNode {
+    id: string | null;
+    generated_id: boolean;
+    /** null only when the checkbox symbol is unknown (E002). */
+    status: Status | null;
+    title: string;
+    attrs: Record<string, unknown>;
+    notes: Note[];
+    anchors: Anchor[];
+    children: RhumbNode[];
+    line: number;
+}
+export interface Edge {
+    kind: EdgeKind;
+    from: string;
+    to: string;
+    label: string | null;
+    line: number;
+}
+export interface RhumbDocument {
+    rhumb: string;
+    title: string | null;
+    links: Record<string, string>;
+    nodes: RhumbNode[];
+    edges: Edge[];
+    diagnostics: Diagnostic[];
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/docs/rhumb-spec.md

@@ -0,0 +1,289 @@
+# Rhumb 0.1 Syntax Specification (draft)
+
+Rhumb is Portolan's graph DSL. It describes the hierarchy, status and relations of work items. Each project has one `.rhumb` file. Details live in the diary, and Rhumb only links to them.
+
+Design principle: every syntax element reuses a notation that LLMs and people already know. Rhumb only adds syntax for what those notations cannot express, namely edges.
+
+| Element | Notation | Borrowed from |
+| --- | --- | --- |
+| File metadata | YAML front matter | Markdown / Jekyll / Mermaid |
+| Node | nested `- [ ] title` list | GFM task list |
+| Extended statuses | `[/]` `[-]` `[!]` `[?]` | Obsidian Tasks / alternate checkboxes |
+| Node ID | trailing `^id` | Obsidian block ID |
+| Attributes | trailing `{key: value}` | YAML flow mapping |
+| Anchor | `[text](target#heading)` | Markdown link, GitHub heading slug |
+| Entry locator | `#heading:~:text=snippet` | URL Text Fragments |
+| Comment | `%% ...` | Mermaid / Obsidian |
+| Edge | `a needs b` | plain English verb sentence, see section 5 |
+
+## 1. Example
+
+```rhumb
+---
+rhumb: 0.1
+title: Portolan
+links:
+  diary: ../diary-job/{path}.md
+---
+
+- [/] Portolan project ^portolan
+  - [x] Prior-art survey ^survey
+    - [survey notes](diary:2026/1008#portolan)
+  - [/] Rhumb DSL design {owner: claude} ^dsl
+    - [/] Syntax spec ^dsl-spec
+    - [ ] Parser + formatter ^dsl-parser
+  - [ ] Visual frontend ^ui
+  - [?] Node annotations and threads ^threads
+
+%% relations
+dsl-parser needs dsl-spec
+ui needs dsl-parser
+threads relates ui
+```
+
+## 2. File structure
+
+- Encoding is UTF-8, the extension is `.rhumb`, and line endings are LF. The parser accepts CRLF, and `fmt` writes LF.
+- A file has optional front matter followed by a body. The body is parsed line by line, and each line has one of these types:
+
+| Line type | Recognized by |
+| --- | --- |
+| Blank | whitespace only |
+| Comment | starts with `%%` after indentation |
+| Node | list item whose marker is followed by a `[S]` checkbox |
+| Note | list item without a checkbox |
+| Edge | starts at column 0, shaped `ref kind ref…` |
+
+Any other line is error `E001`.
+
+### 2.1 Front matter
+
+If the first line is `---`, everything up to the next `---` is parsed as YAML. The block is optional.
+
+| Key | Meaning | Default |
+| --- | --- | --- |
+| `rhumb` | syntax version | current version |
+| `title` | graph title | file name |
+| `links` | link prefix table, `prefix: template`, with a `{path}` placeholder in the template | empty |
+
+Unknown keys are kept and reported as `I001`. A version newer than the parser supports is error `E013`. A missing closing `---`, invalid YAML, or a `links` value that is not a string map is error `E012`; an unterminated block makes the whole file unusable.
+
+## 3. Nodes
+
+```
+node-line = indent ("-" | "*") SP "[" S "]" SP title [SP attrs] [SP "^" ID]
+```
+
+### 3.1 Statuses
+
+| Symbol | Status | Meaning |
+| --- | --- | --- |
+| `[ ]` | todo | not started |
+| `[/]` | doing | in progress |
+| `[x]` | done | finished |
+| `[-]` | dropped | abandoned |
+| `[!]` | blocked | explicitly blocked; put the reason in a note |
+| `[?]` | idea | proposed, not yet committed |
+
+For tolerance the parser also accepts `[X]` and `[~]`, which `fmt` normalizes to `[x]` and `[/]`. Any other symbol is error `E002`.
+
+### 3.2 IDs
+
+- An ID goes at the end of the line as `^` plus the ID. Hand-written IDs match `[a-z0-9][a-z0-9-]{0,47}`.
+- A readable ID is the default, and agents must always write one. If the ID is omitted, `fmt` or any write command generates `^_` plus 6 random base32 characters (for example `^_k3f7q2`) and writes it back. The ID never changes after that. IDs starting with `_` are reserved for generated IDs, so hand-written IDs cannot start with `_`.
+- Generated IDs are random, not derived from the title, so renaming a node does not change its ID.
+- IDs are unique within the file. A duplicate is error `E003`; the first occurrence is the one edges resolve to.
+- A trailing `^token` that is not a valid ID (for example `^Not_Valid`) stays in the title and is warning `W009`.
+- A node with an empty title (`- [ ] ^id`, `- [ ]`) is error `E011`.
+- Edges can only reference IDs, so a node without an ID cannot be the target of an edge.
+
+### 3.3 Title and attributes
+
+The parser strips suffixes from the end of the line, in this order:
+
+1. If the last token matches `^ID`, it is stripped as the ID.
+2. If what remains ends with one complete `{…}` that parses as a YAML flow mapping, it is stripped as the attributes.
+3. The rest is the title, which is parsed as inline Markdown (links, code, emphasis).
+
+- `^` and `{` in the middle of a title need no escaping. Only a title that itself ends in `^word` or `{…}` must write `\^` or `\{`.
+- Reserved attribute keys are `owner`, `due` (ISO date), `tags` (list), `priority` (`high` / `normal` / `low`) and `star` (boolean). Unknown keys are kept and reported as `I002`.
+- `star: true` marks a node as a favorite of the project; it is shared like any other attribute and is independent of status. To unstar, remove the key. Any value other than `true`/`false` is warning `W010` and the node counts as not starred.
+- Markdown links in a title are anchors, see section 4.
+
+### 3.4 Hierarchy
+
+Nesting follows Markdown nested lists:
+
+- A list item's parent is the nearest preceding node with smaller indentation.
+- Siblings must have the same indentation. A dedent must return to an existing level, otherwise it is error `E004`.
+- A tab counts as 4 columns, as in CommonMark. `fmt` always writes 2 spaces per level.
+
+### 3.5 Notes
+
+A list item without a checkbox is a note that belongs to its parent node. A note is not a child node: the UI shows it as part of the node's description, not as a new branch.
+
+```rhumb
+- [!] K3 hidden-state capture ^capture
+  - Wait for the current 4-GPU training job to finish; TP8 needs the whole machine
+  - [record](diary:2026/1008#camelot-exp73)
+```
+
+- A note at the top level has no parent. It is ignored and reported as `W001`.
+- A node indented under a note is attached to the node that owns the note, and reported as `W002`.
+
+## 4. Anchors (links)
+
+Every Markdown link in a node's title or in its notes is an anchor of that node. A node can have any number of anchors.
+
+```
+[text](target)       [text](<target with spaces>)       <https://…>
+```
+
+Targets are resolved as follows:
+
+| Form | Resolution |
+| --- | --- |
+| `diary:2026/1008#frag` | look up prefix `diary` in the front matter `links`, replace `{path}` with `2026/1008`; the path is relative to the `.rhumb` file |
+| `../notes/x.md#frag` | path relative to the `.rhumb` file |
+| `https://…` | used as is |
+
+The fragment (after `#`) is matched like this:
+
+- Heading slugs follow GitHub rules: lowercase, punctuation removed, spaces replaced with `-`.
+- A unique prefix of the slug is enough: `#portolan` matches `## Portolan: agent-human shared mind map …`.
+- To point at a specific entry under a heading, append a Text Fragment: `#portolan:~:text=Backlog.md`. The resolver picks the first list entry under that heading that contains the text. If the text has spaces, wrap the whole target in angle brackets.
+
+### 4.1 Lines inside a target
+
+A fragment narrows left to right: a heading, then a line selector, then a line offset. An absolute line needs no heading and works in any text file.
+
+```
+fragment = slug [":~:text=" text]                    ; existing form, text runs to the end
+         | [slug] "^=" prefix [offset]               ; line that starts with prefix
+         | slug offset                               ; lines from the heading
+         | "L" n ["-L" m]                            ; absolute line or range
+prefix   = "`" chars "`" | chars                     ; backticks for spaces or + # : ~
+offset   = ("+" | "-") "L" n
+```
+
+| Form | Points at |
+| --- | --- |
+| `#heading^=foo` | first line in the heading's section that starts with `foo`, ignoring indentation |
+| ``#heading^=`* \> [host] Make` `` | same; backticks when the prefix has spaces or `+ # : ~` |
+| `#^=export function parse` | first such line in the whole file (any text file) |
+| `#heading+L3` / `#heading-L2` | 3 lines below / 2 lines above the heading line |
+| `#heading^=foo+L2` | 2 lines below the matched line |
+| `#L42`, `#L42-L50` | line 42, lines 42 to 50 (as on GitHub) |
+
+- These separators never clash with slugs: GitHub slugs are lowercase and drop `+ ^ = \` : ~`, so `L` is always uppercase in an offset or line.
+- Lines are counted as in an editor, blank lines included. The first match wins. An offset may not leave the heading's section (or the file).
+- Prefer a `^=` or text match to a bare offset: inserting a line above shifts an offset to another line, and `check` cannot notice.
+- Inside `<…>` a backslash escapes ASCII punctuation (CommonMark), so a diary entry line `* > [host] …` is written ``^=`* \> [host] …` ``. A prefix is percent-decoded after quoting, so a backtick inside it is written `%60`: a line `` * `src/edit.ts`: … `` is ``^=`* %60src/edit.ts%60` ``. An unescaped `>` ends the target early; the link is then not recognized and the line gets warning `W011`.
+- The `:~:text=` form keeps its existing meaning and cannot take an offset (its text runs to the end of the fragment).
+
+`rhumb check` resolves anchors against the actual files. An undefined prefix is error `E005`. A missing file, a missing heading, an ambiguous prefix, a text fragment or `^=` prefix that is not found, an offset that leaves its section, a line past the end of the file, or a fragment that cannot be parsed (such as `#L9-L3` or an unterminated backtick) is warning `W003`. The diary lives in another repository and may not always be present, so these are warnings, not errors.
+
+## 5. Edges
+
+```
+edge-line = ref SP kind SP ref ("," [SP] ref)* [[SP] ":" [SP] label]
+```
+
+An edge line starts at column 0 and can appear anywhere in the body. `fmt` does not reorder edges.
+
+| kind | Meaning | Affects readiness |
+| --- | --- | --- |
+| `needs` | a depends on b; a becomes ready once b is done | yes |
+| `blocks` | a blocks b, same as `b needs a` | yes |
+| `relates` | related; undirected without a label, directed with one (see 5.1) | no |
+| `replaces` | a supersedes b | no |
+| `from` | a was derived from b (split, follow-up, spin-off) | no |
+
+- A `ref` in an edge is a node ID, with or without the `^` prefix (`^a needs ^b`). `fmt` removes the `^`.
+- The label is optional free text: `ui needs dsl-parser: needs a stable AST`. With several targets, the label applies to each resulting edge.
+- A line shaped like an edge with an unknown kind is `E008` only when its first word is a known ID; otherwise it is plain prose and `E001`. An indented edge line is also `E001`.
+- Cross-file references are not supported in 0.1. The form `other.rhumb^id` is reserved and is error `E006` for now.
+
+### 5.1 Domain relations go in labels
+
+The five kinds are kept because each is general across domains and the tools treat it differently: `needs`/`blocks` drive readiness and cycle checks, `replaces` and `from` record supersession and provenance. A relation that only appears in some kinds of work (an experiment compared against a control, a task that uses a dataset, an investigation that tests a hypothesis) is written as a labeled `relates`, not as a new keyword:
+
+```rhumb
+a1 relates a0: compared against
+train relates dataset: uses
+probe relates lr-hypothesis: tests
+```
+
+- The label is a verb phrase. The edge reads as one sentence, source + label + target: "a1 compared against a0".
+- A labeled `relates` keeps the direction it is written in. An unlabeled `relates` stays undirected.
+- Duplicates (`W004`): an unlabeled `relates` matches either direction; labeled edges match on direction and label, so `a relates b: uses` and `a relates b: tests` are two edges.
+- Use `needs` only for execution order. A treatment that is compared against a control does not need the control to finish first; write `relates … : compared against`, otherwise readiness and progress become wrong.
+- A label is promoted to a keyword only when it recurs across unrelated domains and a tool needs to treat it differently from `relates`.
+
+Edges do not use Mermaid's `-->` because an arrow is ambiguous for dependencies: `a --> b` can be read as "a depends on b" or as "a comes before b". A plain English verb sentence leaves no room for an LLM to read the direction wrong.
+
+| Problem | Code |
+| --- | --- |
+| reference to an unknown ID | `E007` |
+| unknown kind | `E008` |
+| cycle through `needs` / `blocks` | `E009` |
+| self-edge | `E010` |
+| duplicate edge | `W004` (`fmt` removes it) |
+| `needs` / `blocks` between a parent and its descendant | `W005` (the hierarchy already expresses containment) |
+
+## 6. Derived semantics
+
+These values are computed by tools and never written to the file.
+
+- **Progress**: done leaves in the subtree divided by (all leaves minus dropped and idea leaves). If the denominator is 0, no progress is shown.
+- **Readiness**: a node is ready when its status is todo and every `needs` target (including reversed `blocks`) is done. A dependency on a dropped node is warning `W006` and does not block readiness.
+- **Consistency checks**:
+  - a done parent whose subtree still has todo, doing or blocked nodes: `W007`
+  - a doing or done node with a `needs` target that is not done: `W008`
+  - a todo parent with a doing or done child: `I003` (suggests changing the parent to doing)
+- **Parent status** is always written explicitly. 0.1 does not derive it, so the file never disagrees with what the UI shows.
+
+## 7. Formatting (`rhumb fmt`)
+
+Goal: when an agent edits one node, the diff touches only that line.
+
+- 2 spaces per indent level, `-` as the list marker, status aliases normalized.
+- One space between title, attributes and `^id`, with no column alignment. Alignment would rewrite every line in a sibling group whenever one sibling's title changes length.
+- Attributes are written as `{k: v, k: v}` and keep their original key order.
+- Missing IDs are generated.
+- Edges lose the `^` prefix, duplicates are removed, and there is one space after each `,`.
+- Runs of blank lines collapse to one. Comments and their positions are kept.
+- Idempotent: `fmt(fmt(x)) == fmt(x)`.
+
+UI write-back also goes through AST → `fmt`, never by splicing into the original text.
+
+Implementation status (0.1 tooling): `rhumb fmt` currently only assigns missing IDs and normalizes status aliases. Programmatic changes go through the edit operations in `src/edit.ts`, which rewrite only the affected lines and reject edits that add new errors. The rest of this section needs a full CST printer and is not implemented yet.
+
+## 8. AST (JSON)
+
+```json
+{
+  "rhumb": "0.1",
+  "title": "Portolan",
+  "links": {"diary": "../diary-job/{path}.md"},
+  "nodes": [
+    {
+      "id": "survey", "generated_id": false,
+      "status": "done", "title": "Prior-art survey",
+      "attrs": {}, "notes": [{"text": "[survey notes](diary:2026/1008#portolan)", "line": 9}],
+      "anchors": [{"text": "survey notes", "target": "diary:2026/1008#portolan", "line": 9}],
+      "children": [], "line": 8
+    }
+  ],
+  "edges": [{"kind": "needs", "from": "dsl-parser", "to": "dsl-spec", "label": null, "line": 17}],
+  "diagnostics": [{"code": "W003", "level": "warning", "line": 9, "message": "…"}]
+}
+```
+
+`blocks` is kept as written in the AST, and the derivation layer converts it to `needs`. Comments exist only in the CST (used by `fmt`) and are not part of the AST.
+
+## 9. Open items
+
+- Reference-style links `[text][ref]` with definition lines are not supported in 0.1.
+- Cross-file references `other.rhumb^id`.
+- The sidecar format for node annotations and threads will get its own spec. The 0.1 implementation (`src/threads.ts`) is an append-only `<name>.threads.jsonl` with `open / reply / resolve / reopen / retarget` events.