cans-spec 0.1.0

package/src/commands/init.ts

@@ -0,0 +1,184 @@
+import { basename, dirname, join, relative } from 'path';
+import type { InitResult } from '../types';
+import { resolveWorkspaceRoot, resolveInitTarget, mkdirp, exists, dirExists } from '../core/fs';
+import { parseArgs, type FlagSpec } from '../core/args';
+
+const TEMPLATES_DIR = join(import.meta.dir, '..', '..', 'templates');
+
+async function readTemplate(name: string): Promise<string> {
+  return await Bun.file(join(TEMPLATES_DIR, name)).text();
+}
+
+export interface InitArgs {
+  flat: boolean;
+  folders: boolean;
+  bare: boolean;
+  force: boolean;
+  json: boolean;
+  tool: string | null;
+  errors: string[];
+}
+
+const INIT_FLAGS: FlagSpec[] = [
+  { name: 'flat', boolean: true },
+  { name: 'folders', boolean: true },
+  { name: 'bare', boolean: true },
+  { name: 'force', boolean: true },
+  { name: 'json', boolean: true },
+  { name: 'tool', boolean: false },
+];
+
+/** §21: `--tool <name>` emits a tool-specific copy of AGENTS.md. */
+const KNOWN_TOOLS = ['claude', 'cursor'];
+
+export function parseInitArgs(args: string[]): InitArgs {
+  const parsed = parseArgs(args, INIT_FLAGS);
+  const folders = parsed.flags.has('folders');
+  const flat = parsed.flags.has('flat');
+  const tool = parsed.flags.get('tool');
+  return {
+    flat: flat || !folders,
+    folders,
+    bare: parsed.flags.has('bare'),
+    force: parsed.flags.has('force'),
+    json: parsed.flags.has('json'),
+    tool: typeof tool === 'string' ? tool : null,
+    errors: parsed.errors,
+  };
+}
+
+// Dense, clean spec stubs (parents have 2+ children, texts 3..120 chars, depth <= 5).
+const SPEC_STUBS: Array<{ name: string; content: string }> = [
+  { name: '00-overview.md', content: '- Overview\n  - Product: TBD\n  - Users: TBD\n  - Status: draft\n' },
+  { name: '01-architecture.md', content: '- Architecture\n  - Stack: TBD\n  - Layers: TBD\n  - Boundaries: TBD\n  - Principles: TBD\n' },
+  { name: '02-authentication.md', content: '- Authentication\n  - Sign up: TBD\n  - Sessions: TBD\n  - Passwords: TBD\n' },
+  { name: '03-data.md', content: '- Data\n  - Storage: TBD\n  - Schema: TBD\n  - Backups: TBD\n  - Retention: TBD\n' },
+  { name: '04-api.md', content: '- API\n  - Endpoints: TBD\n  - Auth: TBD\n  - Errors: TBD\n  - Rate limits: TBD\n' },
+  { name: '05-frontend.md', content: '- Frontend\n  - Framework: TBD\n  - Routes: TBD\n  - State: TBD\n' },
+  { name: '06-operations.md', content: '- Operations\n  - Deployment: TBD\n  - Environments: TBD\n  - Monitoring: TBD\n  - Runbooks: TBD\n' },
+];
+
+interface PlanEntry {
+  path: string;
+  dir: boolean;
+  content: string | null;
+}
+
+/** §21: "Refuses if already inside a `cans/` directory" — at any depth
+ *  (`<root>/cans` as well as `<root>/cans/_collab`). */
+function insideCansDirectory(): boolean {
+  let dir = process.cwd();
+  for (;;) {
+    if (basename(dir) === 'cans' && dirExists(dir)) return true;
+    const parent = dirname(dir);
+    if (parent === dir) return false;
+    dir = parent;
+  }
+}
+
+function initRefusal(error: string): InitResult {
+  return { ok: false, command: 'init', exitCode: 1, created: [], skipped: [], root: '', error };
+}
+
+export async function run(args: string[]): Promise<InitResult> {
+  const opts = parseInitArgs(args);
+
+  // §20/§37: unknown or malformed flags are never silently ignored.
+  if (opts.errors.length > 0) {
+    return initRefusal(opts.errors[0]);
+  }
+
+  // §21/§37: an unrecognized --tool value must be surfaced, not dropped.
+  if (opts.tool !== null && !KNOWN_TOOLS.includes(opts.tool)) {
+    return initRefusal(`unknown tool "${opts.tool}" — supported tools: ${KNOWN_TOOLS.join(', ')}`);
+  }
+
+  // §21: refuse when standing anywhere inside a cans/ directory.
+  if (insideCansDirectory()) {
+    return initRefusal('already inside a cans/ workspace — cd to the project root first');
+  }
+
+  // Idempotent: an existing workspace (walk-up `cans/` or scratch) is re-used —
+  // existing files are skipped unless --force. Architecture §21.
+  const existing = resolveWorkspaceRoot();
+  const workspace = existing ?? join(resolveInitTarget(), 'cans');
+  mkdirp(workspace);
+
+  const rulesContent = await readTemplate('_rules.yaml');
+  const agentsContent = await readTemplate('AGENTS.md');
+
+  const plan: PlanEntry[] = [
+    { path: '_rules.yaml', dir: false, content: rulesContent },
+    { path: 'AGENTS.md', dir: false, content: agentsContent },
+  ];
+
+  // Spec stubs: flat files by default; --folders keeps 00-overview.md flat
+  // and puts numbered specs into NN-name/index.md folders. §8: "Flat wins over
+  // folder" — when the flat file already exists, never manufacture a folder
+  // twin beside it (duplicate canonical home).
+  for (const stub of SPEC_STUBS) {
+    if (opts.bare && stub.name !== '00-overview.md') continue;
+    const folderMode = opts.folders && /^(?!00-)\d{2}-/.test(stub.name);
+    const path = folderMode && !exists(join(workspace, stub.name))
+      ? `${stub.name.slice(0, -3)}/index.md`
+      : stub.name;
+    plan.push({ path, dir: false, content: stub.content });
+  }
+
+  if (!opts.bare) {
+    plan.push({ path: '_adr', dir: true, content: null });
+    plan.push({ path: '_tasks', dir: true, content: null });
+    plan.push({ path: '_collab/handoffs.md', dir: false, content: '- handoffs\n' });
+    plan.push({ path: '_collab/conflicts.md', dir: false, content: '- conflicts\n' });
+    plan.push({ path: '_collab/decisions.md', dir: false, content: '- decisions\n' });
+  }
+  // --bare (§21 "minimal") keeps the workspace lean (_rules.yaml + AGENTS.md +
+  // 00-overview.md) but still emits cans/AGENTS.md — §36 help advertises
+  // "Agents: cans/AGENTS.md" and the bare skeleton must match it (QA-07
+  // QA-01 #10).
+
+  if (opts.tool === 'claude') {
+    plan.push({ path: 'CLAUDE.md', dir: false, content: agentsContent });
+  } else if (opts.tool === 'cursor') {
+    plan.push({ path: '.cursorrules', dir: false, content: agentsContent });
+  }
+
+  const created: string[] = [];
+  const skipped: string[] = [];
+  for (const entry of plan) {
+    const abs = join(workspace, entry.path);
+    if (entry.dir) {
+      const label = `${entry.path}/`;
+      if (dirExists(abs)) {
+        skipped.push(label);
+      } else {
+        mkdirp(abs);
+        created.push(label);
+      }
+      continue;
+    }
+    // §29: _collab/*.md carry append-only coordination state (decisions.md is
+    // the ADR index). --force regenerates the skeleton spec files but must
+    // never clobber existing _collab files — create only when missing (QA-09 E1).
+    if (opts.force && entry.path.startsWith('_collab/') && exists(abs)) {
+      skipped.push(entry.path);
+      continue;
+    }
+    if (exists(abs) && !opts.force) {
+      skipped.push(entry.path);
+      continue;
+    }
+    await Bun.write(abs, entry.content ?? '');
+    created.push(entry.path);
+  }
+
+  // §35 init.json fixture: `root` is the relative display form ("./cans").
+  // Programmatic (non-JSON) callers keep the absolute path for path joins.
+  let root = workspace;
+  if (opts.json) {
+    const relRoot = relative(process.cwd(), workspace) || '.';
+    root = relRoot.startsWith('.') ? relRoot : `./${relRoot}`;
+  }
+
+  return { ok: true, command: 'init', exitCode: 0, created, skipped, root };
+}

package/src/commands/new.ts

@@ -0,0 +1,138 @@
+import { join, basename } from 'path';
+import type { NewResult } from '../types';
+import { resolveWorkspaceRoot, resolveWorkspaceOrCreate, mkdirp, discoverAdrs, dirExists, isFile } from '../core/fs';
+import { parseArgs, type FlagSpec } from '../core/args';
+
+const TEMPLATES_DIR = join(import.meta.dir, '..', '..', 'templates');
+
+async function readTemplate(name: string): Promise<string> {
+  return await Bun.file(join(TEMPLATES_DIR, name)).text();
+}
+
+/** lowercase → strip double quotes → non-alphanumeric runs → hyphens → trim hyphens.
+ *  Apostrophes become hyphens ("What's Next?" → "what-s-next").
+ *  §23/§37: the slug is capped at 80 chars (truncating cleanly, without
+ *  trailing dashes) so the derived `_adr/NNN-<slug>.md` / `_tasks/<slug>.md`
+ *  filename is always filesystem-safe — a 300-char title is user input to
+ *  normalize, never an ENAMETOOLONG internal error (QA-08 A5). */
+export const MAX_SLUG_LENGTH = 80;
+
+export function slugify(input: string): string {
+  const full = input
+    .trim()
+    .toLowerCase()
+    .replace(/["“”]/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  if (full.length <= MAX_SLUG_LENGTH) return full;
+  return full.slice(0, MAX_SLUG_LENGTH).replace(/-+$/g, '');
+}
+
+/** Next ADR number: max existing NNN in _adr + 1 (starts at 1). */
+export function nextAdrNumber(root: string): number {
+  let max = 0;
+  if (dirExists(join(root, '_adr'))) {
+    for (const rel of discoverAdrs(root)) {
+      const m = basename(rel).match(/^(\d{3})-/);
+      if (m !== null) max = Math.max(max, Number(m[1]));
+    }
+  }
+  return max + 1;
+}
+
+const NEW_FLAGS: FlagSpec[] = [
+  { name: 'json', boolean: true },
+];
+
+function today(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+/** §21/§37: `new` never silently resets an existing artifact. If the target
+ *  file already exists, refuse unless the content would be byte-identical
+ *  (idempotent no-op). */
+async function existingContentGuard(
+  abs: string,
+  file: string,
+  content: string,
+  change: string,
+): Promise<NewResult | null> {
+  if (!isFile(abs)) return null;
+  const existing = await Bun.file(abs).text();
+  if (existing === content) {
+    return { ok: true, command: 'new', exitCode: 0, change, file };
+  }
+  return {
+    ok: false, command: 'new', exitCode: 1, change, file,
+    error: `refusing to overwrite existing ${file} — it already has content; delete it or use a different name`,
+  };
+}
+
+export async function run(args: string[]): Promise<NewResult> {
+  const parsed = parseArgs(args, NEW_FLAGS);
+
+  if (parsed.errors.length > 0) {
+    return { ok: false, command: 'new', exitCode: 1, change: '', file: '', error: parsed.errors[0] };
+  }
+
+  const kind = parsed.positional[0] ?? '';
+  const rawName = parsed.positional.slice(1).join(' ');
+  const slug = slugify(rawName);
+
+  if (kind !== 'task' && kind !== 'adr') {
+    return {
+      ok: false, command: 'new', exitCode: 1, change: rawName, file: '',
+      error: kind === '' ? 'usage: cans new <adr|task> <name>' : `unknown kind "${kind}" — use "adr" or "task"`,
+    };
+  }
+
+  if (slug === '') {
+    return {
+      ok: false, command: 'new', exitCode: 1, change: rawName, file: '',
+      error: `empty slug from "${rawName}" — provide a non-empty title`,
+    };
+  }
+
+  // §21 (QA-06 6c): only `init` may create cans/. `new` operates on an existing
+  // workspace (walk-up `cans/`, CANS_ROOT, or a scratch dir under <cwd>/.tmp)
+  // and must REFUSE — never auto-vivify a partial cans/ skeleton — when no
+  // workspace directory exists. Every resolver result except the
+  // `<cwd>/cans` last-resort points at a directory that already exists on
+  // disk, so requiring an existing directory is exactly the no-vivify guard.
+  let workspace = resolveWorkspaceRoot();
+  if (workspace === null) workspace = resolveWorkspaceOrCreate();
+  if (!dirExists(workspace)) {
+    return {
+      ok: false, command: 'new', exitCode: 1, change: slug, file: '',
+      error: 'no cans workspace found — run `cans init` first',
+    };
+  }
+
+  if (kind === 'task') {
+    const tasksDir = join(workspace, '_tasks');
+    mkdirp(tasksDir);
+    const template = await readTemplate('task-template.md');
+    const content = template.replaceAll('{slug}', slug);
+    const file = join('_tasks', `${slug}.md`);
+    const guard = await existingContentGuard(join(workspace, file), file, content, slug);
+    if (guard !== null) return guard;
+    await Bun.write(join(workspace, file), content);
+    return { ok: true, command: 'new', exitCode: 0, change: slug, file };
+  }
+
+  // adr
+  const adrDir = join(workspace, '_adr');
+  mkdirp(adrDir);
+  const n = nextAdrNumber(workspace);
+  const NNN = String(n).padStart(3, '0');
+  const template = await readTemplate('adr-template.md');
+  const content = template
+    .replaceAll('{NNN}', NNN)
+    .replaceAll('{Title}', rawName)
+    .replaceAll('{YYYY-MM-DD}', today());
+  const file = join('_adr', `${NNN}-${slug}.md`);
+  const guard = await existingContentGuard(join(workspace, file), file, content, slug);
+  if (guard !== null) return guard;
+  await Bun.write(join(workspace, file), content);
+  return { ok: true, command: 'new', exitCode: 0, change: slug, file };
+}

package/src/commands/status.ts

@@ -0,0 +1,152 @@
+import { join, basename } from 'path';
+import { readFileSync } from 'fs';
+import type { StatusResult, OutlineNode } from '../types';
+import {
+  resolveWorkspaceRoot, discoverSpecFiles, discoverActiveTasks,
+  discoverArchivedTasks, discoverAdrs, dirExists,
+} from '../core/fs';
+import { parseOutline, flattenNodes } from '../core/outline';
+import { parseArgs, type FlagSpec } from '../core/args';
+
+export interface StatusArgs {
+  unclaimed: boolean;
+  blocked: boolean;
+  owners: boolean;
+  json: boolean;
+  errors: string[];
+}
+
+const STATUS_FLAGS: FlagSpec[] = [
+  { name: 'unclaimed', boolean: true },
+  { name: 'blocked', boolean: true },
+  { name: 'owners', boolean: true },
+  { name: 'json', boolean: true },
+];
+
+export function parseStatusArgs(args: string[]): StatusArgs {
+  const parsed = parseArgs(args, STATUS_FLAGS);
+  return {
+    unclaimed: parsed.flags.has('unclaimed'),
+    blocked: parsed.flags.has('blocked'),
+    owners: parsed.flags.has('owners'),
+    json: parsed.flags.has('json'),
+    errors: parsed.errors,
+  };
+}
+
+// globFiles throws ENOENT on missing dirs — guard the optional ones.
+function safeActiveTasks(root: string): string[] {
+  return dirExists(join(root, '_tasks')) ? discoverActiveTasks(root) : [];
+}
+
+function safeArchivedTasks(root: string): string[] {
+  return dirExists(join(root, '_tasks', '_archive')) ? discoverArchivedTasks(root) : [];
+}
+
+function safeAdrs(root: string): string[] {
+  return dirExists(join(root, '_adr')) ? discoverAdrs(root) : [];
+}
+
+function countConflicts(conflictsPath: string): number {
+  try {
+    return readFileSync(conflictsPath, 'utf-8')
+      .split('\n')
+      .filter(line => /status:\s*unresolved/i.test(line)).length;
+  } catch {
+    return 0;
+  }
+}
+
+export async function run(args: string[]): Promise<StatusResult> {
+  const opts = parseStatusArgs(args);
+
+  if (opts.errors.length > 0) {
+    return {
+      ok: false, command: 'status', exitCode: 1,
+      specFiles: 0, activeTasks: 0, archivedTasks: 0, adrCount: 0,
+      tasks: { total: 0, done: 0, unclaimed: 0, blocked: 0 },
+      owners: {},
+      taskFiles: [],
+      conflicts: 0,
+      error: opts.errors[0],
+    };
+  }
+
+  const workspace = resolveWorkspaceRoot();
+  if (workspace === null) {
+    return {
+      ok: false, command: 'status', exitCode: 1,
+      specFiles: 0, activeTasks: 0, archivedTasks: 0, adrCount: 0,
+      tasks: { total: 0, done: 0, unclaimed: 0, blocked: 0 },
+      owners: {},
+      taskFiles: [],
+      conflicts: 0,
+      error: 'no cans workspace found — run `cans init` first',
+    };
+  }
+
+  const specFiles = discoverSpecFiles(workspace);
+  const activeTasks = safeActiveTasks(workspace);
+  const archivedTasks = safeArchivedTasks(workspace);
+  const adrs = safeAdrs(workspace);
+
+  let tasksTotal = 0;
+  let tasksDone = 0;
+  let tasksUnclaimed = 0;
+  let blockedFiles = 0;
+  const owners: Record<string, { tasks: number; done: number }> = {};
+  const taskFiles: StatusResult['taskFiles'] = [];
+
+  for (const rel of activeTasks) {
+    let flat: OutlineNode[] = [];
+    try {
+      flat = flattenNodes(parseOutline(await Bun.file(join(workspace, rel)).text(), rel));
+    } catch {
+      // unparsable task file: contributes nothing but its existence
+    }
+
+    const tasks = flat.filter(n => n.isTask && !n.isHumanGate);
+    const gates = flat.filter(n => n.isTask && n.isHumanGate);
+    const tasksDoneCount = tasks.filter(n => n.isDone).length;
+    const gatesDoneCount = gates.filter(n => n.isDone).length;
+    const isBlocked = gates.some(n => !n.isDone) || tasks.some(n => !n.isDone);
+    const unclaimedCount = tasks.filter(n => n.owner === null).length;
+
+    taskFiles.push({
+      name: basename(rel, '.md'),
+      tasksDone: tasksDoneCount,
+      tasksTotal: tasks.length,
+      gatesDone: gatesDoneCount,
+      gatesTotal: gates.length,
+      blocked: isBlocked,
+      unclaimed: unclaimedCount,
+    });
+
+    if (isBlocked) blockedFiles++;
+    tasksTotal += tasks.length;
+    tasksDone += tasksDoneCount;
+    tasksUnclaimed += unclaimedCount;
+
+    for (const n of flat) {
+      if (!n.isTask) continue;
+      if (n.owner === null || n.owner === '@human') continue;
+      const entry = owners[n.owner] ?? { tasks: 0, done: 0 };
+      entry.tasks++;
+      if (n.isDone) entry.done++;
+      owners[n.owner] = entry;
+    }
+  }
+
+  return {
+    ok: true, command: 'status', exitCode: 0,
+    specFiles: specFiles.length,
+    activeTasks: activeTasks.length,
+    archivedTasks: archivedTasks.length,
+    adrCount: adrs.length,
+    tasks: { total: tasksTotal, done: tasksDone, unclaimed: tasksUnclaimed, blocked: blockedFiles },
+    owners,
+    taskFiles,
+    conflicts: countConflicts(join(workspace, '_collab', 'conflicts.md')),
+    filter: opts.unclaimed ? 'unclaimed' : opts.blocked ? 'blocked' : opts.owners ? 'owners' : undefined,
+  };
+}

package/src/converters/index.ts

@@ -0,0 +1,4 @@
+export * from './shared';
+export * from './opml';
+export * from './logseq';
+export * from './obsidian';

package/src/converters/logseq.ts

@@ -0,0 +1,42 @@
+import type { ExternalNode } from '../types';
+import {
+  convertOwnerMarkers, convertWikiLinks, logseqSlashLinks, parseCheckbox,
+  parseIndent, reverseWikiLinks, stripMetadata,
+} from './shared';
+
+/** Logseq page → flat ExternalNode list (document order; hierarchy via `indent`).
+ *  Drops pure `key:: value` property lines (keys may contain spaces — only `::`
+ *  marks the property, QA-08 E11), strips `((block-refs))`, `[[wiki]]` → `see:`
+ *  (with `[[X/Y]]` → `see: X.md#Y` per §28, QA-09 D8), TODO/DONE → isTask/isDone,
+ *  `⏳ Human` → `← @human` (QA-09 D5). */
+export function parseLogseq(source: string): ExternalNode[] {
+  const nodes: ExternalNode[] = [];
+  for (const raw of source.split(/\r?\n/)) {
+    if (!/^\s*-\s/.test(raw)) continue; // logseq pages are bullets only
+    const { isTask, isDone, clean } = parseCheckbox(raw);
+    if (/^[\w\s-]+::/.test(clean)) continue; // pure property line → drop
+    const text = stripMetadata(
+      convertWikiLinks(
+        convertOwnerMarkers(logseqSlashLinks(clean.replace(/\(\([\w-]+\)\)/g, '')), 'logseq'),
+      ),
+      'logseq',
+    );
+    if (!text) continue;
+    nodes.push({ text, indent: parseIndent(raw), isTask, isDone, children: [], metadata: {} });
+  }
+  return nodes;
+}
+
+/** CANS → Logseq: `- [ ] t` → `- TODO t`, `- [x] t` → `- DONE t`, `see: X#Y` → `[[X#Y]]`. */
+export function serializeLogseq(nodes: ExternalNode[]): string {
+  const lines: string[] = [];
+  const walk = (list: ExternalNode[]): void => {
+    for (const n of list) {
+      const marker = n.isTask ? (n.isDone ? 'DONE ' : 'TODO ') : '';
+      lines.push('  '.repeat(n.indent) + '- ' + marker + reverseWikiLinks(n.text));
+      walk(n.children);
+    }
+  };
+  walk(nodes);
+  return lines.length > 0 ? lines.join('\n') + '\n' : '';
+}

package/src/converters/obsidian.ts

@@ -0,0 +1,95 @@
+import type { ExternalNode } from '../types';
+import {
+  convertOwnerMarkers, convertWikiLinks, parseCheckbox, parseIndent,
+  reverseWikiLinks, stripMetadata,
+} from './shared';
+
+/** Remove a leading YAML frontmatter block (`---` fences at very top), fences included. */
+export function stripFrontmatter(source: string): string {
+  const m = source.match(/^[ \t]*---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/);
+  return m ? source.slice(m[0].length) : source;
+}
+
+/** Obsidian callout line classifier (§31 "Handles callout markers").
+ *  `> [!type] Title` → { kind: 'header', type, title }
+ *  `> body text`     → { kind: 'body', text }
+ *  null for non-callout lines and empty `>` lines. */
+function parseCalloutLine(
+  line: string,
+): { kind: 'header'; type: string; title: string } | { kind: 'body'; text: string } | null {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith('>')) return null;
+  const content = trimmed.replace(/^>\s*/, '');
+  const headerMatch = content.match(/^\[!(\w+)\]\s*(.*)/);
+  if (headerMatch) {
+    return { kind: 'header', type: headerMatch[1], title: headerMatch[2].trim() };
+  }
+  if (content.trim() !== '') {
+    return { kind: 'body', text: content.trim() };
+  }
+  return null; // empty `>` line — skip
+}
+
+/** Obsidian note → flat ExternalNode list (document order; hierarchy via `indent`).
+ *  Frontmatter stripped, `[[wiki]]`/`![[embeds]]` → `see:`, `#tags` stripped,
+ *  callouts (`> [!type]` + body) preserved as nodes (QA-05 F4 — no silent drop),
+ *  native `- [ ]` checkboxes preserved. */
+export function parseObsidian(source: string): ExternalNode[] {
+  const nodes: ExternalNode[] = [];
+  let calloutIndent = 0; // callout content attaches at the last bullet's level
+
+  for (const raw of stripFrontmatter(source).split(/\r?\n/)) {
+    // Callout lines (`> …`) become nodes instead of vanishing
+    const callout = parseCalloutLine(raw);
+    if (callout !== null) {
+      if (callout.kind === 'header') {
+        // `> [!note] Decision` → node "Decision" (the callout type is metadata, not content)
+        const text = callout.title !== '' ? callout.title : callout.type;
+        if (text !== '') {
+          nodes.push({
+            text, indent: calloutIndent, isTask: false, isDone: false,
+            children: [], metadata: { callout: callout.type },
+          });
+        }
+      } else {
+        // `> body text` → child node under the callout header
+        const text = convertWikiLinks(
+          stripMetadata(convertOwnerMarkers(callout.text, 'obsidian'), 'obsidian'),
+        );
+        if (text !== '') {
+          nodes.push({
+            text, indent: calloutIndent + 1, isTask: false, isDone: false,
+            children: [], metadata: {},
+          });
+        }
+      }
+      continue;
+    }
+
+    if (!/^\s*-\s/.test(raw)) continue; // bullets only
+    const { isTask, isDone, clean } = parseCheckbox(raw);
+    // strip #tags before link conversion so anchors (`X#Y`) are never eaten; `![[embed]]` → plain link.
+    // §28 inverse: `🤖 agent-1` / `⏳ Human` come back as owner/gate arrows (QA-09 D5).
+    const text = convertWikiLinks(
+      stripMetadata(convertOwnerMarkers(clean.replace(/!\[\[/g, '[['), 'obsidian'), 'obsidian'),
+    );
+    if (!text) continue;
+    calloutIndent = parseIndent(raw); // track last bullet indent for callout attachment
+    nodes.push({ text, indent: parseIndent(raw), isTask, isDone, children: [], metadata: {} });
+  }
+  return nodes;
+}
+
+/** CANS → Obsidian: `see: X#Y` → `[[X#Y]]`, native `- [ ]`/`- [x]` checkboxes kept as-is. */
+export function serializeObsidian(nodes: ExternalNode[]): string {
+  const lines: string[] = [];
+  const walk = (list: ExternalNode[]): void => {
+    for (const n of list) {
+      const box = n.isTask ? (n.isDone ? '[x] ' : '[ ] ') : '';
+      lines.push('  '.repeat(n.indent) + '- ' + box + reverseWikiLinks(n.text));
+      walk(n.children);
+    }
+  };
+  walk(nodes);
+  return lines.length > 0 ? lines.join('\n') + '\n' : '';
+}