@kontourai/flow-agents 0.3.0 → 1.0.0

package/kits/knowledge/adapters/obsidian-store/README.md

@@ -0,0 +1,141 @@
+# Knowledge Kit — Obsidian Store Adapter
+
+Spike verdict: **RATIFY**
+
+The "file is the record" thesis holds. Each Knowledge Kit record maps to exactly
+one Obsidian-native markdown note. Frontmatter carries the full contract payload;
+the markdown body is human-readable Obsidian rendering. The adapter passes the
+full 48-test contract suite without modifications.
+
+---
+
+## The File-Is-the-Record Thesis
+
+A Knowledge Kit record has a canonical identity (`id`), a structured payload
+(type, category, provenance, links, mutation_log), and a human-facing body.
+The Obsidian store places ALL of this in a single `.md` file:
+
+- YAML frontmatter holds every contract field including `body`.
+- The markdown section below `---` is rendered for Obsidian readability only —
+  it is decorative and not read back on load.
+- The file IS the record. No separate database. No shadow index for content.
+
+This is the core claim of the spike: **a single Obsidian note can faithfully
+represent a Knowledge Kit record** with zero fidelity loss.
+
+---
+
+## File Shape
+
+```
+---
+id: <uuid>
+type: raw | compiled | concept | snapshot
+title: <string>
+category: eng.decisions
+tags: [tag-a, tag-b]
+status: active | implemented | retired
+created_at: <ISO8601>
+updated_at: <ISO8601>
+provenance:
+  agent: <string>
+  session_id: <optional>
+  source_ids: [<optional uuid list>]
+links:
+  - target_id: <uuid>
+    kind: related | source | proposes | supersedes | refines
+    label: <optional>
+mutation_log:
+  - op: update
+    at: <ISO8601>
+    agent: <string>
+    evidence:
+      fields: [title, body]
+body: "The full contract body text stored here for round-trip fidelity."
+---
+
+<!-- Obsidian-readable section below — decorative, not parsed on load -->
+
+> [!note]- Raw Notes          ← raw type: collapsed callout
+> Original capture text here.
+
+## Sources                     ← compiled/concept/snapshot: wikilinks to sources
+
+[[source-slug|Source Note]]
+
+## Related
+
+[[related-slug]]
+```
+
+---
+
+## Storage Layout
+
+```
+<storeRoot>/
+  <category/as/path>/<title-slug>.md     active records
+  archive/<category/as/path>/<slug>.md   superseded records (moved, not deleted)
+  graph-index.json                       link graph (suite §13 requirement)
+  .graph-index.json                      path index (id → {path, archived})
+```
+
+- Category dots map to directory segments: `eng.decisions` → `eng/decisions/`.
+- Title is slugified for the filename: `My Decision` → `my-decision.md`.
+- Filename collisions (same slug, different id) get a suffix: `my-decision-2.md`.
+- When a record is superseded, its file MOVES to `archive/` (supersede-not-delete
+  invariant). The record remains fully queryable via `get(id)`.
+
+---
+
+## Spike Gaps Found
+
+1. **Multi-file wikilink resolution**: Obsidian resolves `[[slug]]` links by
+   filename across the entire vault, regardless of folder. The adapter renders
+   wikilinks using the filename slug for human readability, but the canonical
+   link data (stored as UUIDs in frontmatter) is what the contract uses. If a
+   user clicks a wikilink in Obsidian, it navigates by slug — not by UUID —
+   which may not match if slugs collide across categories.
+
+2. **Vault-level wikilink display**: Obsidian flattens `[[slug]]` resolution.
+   Two records in different categories that happen to share a slug
+   (`eng/api/deploy.md` and `ops/api/deploy.md`) would cause Obsidian link
+   ambiguity. The contract itself is unaffected (UUIDs in frontmatter win),
+   but the human-readable `## Related` section would be ambiguous in Obsidian.
+   Mitigation: use category-prefixed slugs in the Obsidian body rendering.
+
+3. **Frontmatter `body` YAML quoting for complex content**: Bodies containing
+   Obsidian callout syntax (`> [!note]`) or multi-paragraph content serialize
+   correctly via the shared codec's `yamlScalar` quoting, but the result can be
+   a long single-line quoted string in frontmatter. Obsidian displays this fine,
+   but it is less human-editable than a literal block scalar. A future YAML block
+   scalar (`|`) serializer would improve ergonomics.
+
+4. **Obsidian sync conflicts**: If two agents write to the same record
+   concurrently, Obsidian Sync may create conflict copies. The adapter uses no
+   file locking. This is acceptable for a spike but would need attention in
+   production use with live sync.
+
+5. **Archive folder visibility**: The `archive/` subdirectory will appear in the
+   Obsidian vault file explorer. This is intentional (superseded records remain
+   inspectable) but users may want to exclude it via `.obsidianignore` or a
+   dedicated vault folder setting.
+
+---
+
+## Spike Verdict: RATIFY
+
+The adapter proves:
+
+- A single Obsidian note is a sufficient and non-lossy representation of a
+  Knowledge Kit record, including all Addendum A (snapshot/supersede) and
+  Addendum B (status/retire) contract extensions.
+- The category hierarchy maps naturally to Obsidian folder organization.
+- Supersede-not-delete is expressible as an archive move within the vault.
+- Human readability (callouts, Sources/Related wikilink sections) coexists with
+  machine-readable frontmatter without duplication errors.
+- The contract suite (48/48) passes without modification.
+
+**Recommendation**: Proceed with the Obsidian store adapter as a supported adapter
+alongside the default store. Address gap #2 (slug ambiguity) before marking the
+adapter production-ready for multi-category vaults.

package/kits/knowledge/adapters/obsidian-store/demo.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * Knowledge Kit — Obsidian Store Demo
+ *
+ * Generates a small set of realistic sample notes in a temporary vault,
+ * then prints the snapshot note verbatim to demonstrate the file-is-the-record
+ * thesis.
+ *
+ * Run:
+ *   node kits/knowledge/adapters/obsidian-store/demo.js
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const adapterPath = path.join(__dirname, "index.js");
+const { ObsidianKnowledgeStore } = await import(adapterPath);
+
+// ---------------------------------------------------------------------------
+// Setup: ephemeral vault
+// ---------------------------------------------------------------------------
+
+const vaultRoot = fs.mkdtempSync(path.join(os.tmpdir(), "obsidian-demo-"));
+const store = new ObsidianKnowledgeStore({ storeRoot: vaultRoot });
+
+console.log(`\nDemo vault: ${vaultRoot}\n`);
+console.log("─".repeat(70));
+
+// ---------------------------------------------------------------------------
+// 1. Raw capture: meeting transcript
+// ---------------------------------------------------------------------------
+
+const rawId = await store.create({
+  type: "raw",
+  title: "Q2 Planning Meeting — Transcript",
+  body: `Discussed moving deploy pipeline to GitHub Actions.
+Ben: we should retire the Jenkins instance, it's costing us $300/mo.
+Alice: agreed, but we need the secrets migration plan first.
+Action items: Alice to draft secrets migration doc by Friday.`,
+  category: "eng.decisions",
+  tags: ["meeting", "infra", "q2"],
+  provenance: {
+    agent: "demo-agent",
+    session_id: "demo-sess-001",
+    note: "Captured from Zoom transcript",
+  },
+});
+
+console.log(`\n[1/4] Created raw capture: ${rawId}`);
+
+// ---------------------------------------------------------------------------
+// 2. Compiled: distilled from the raw
+// ---------------------------------------------------------------------------
+
+const compiledId = await store.create({
+  type: "compiled",
+  title: "Jenkins Retirement Decision",
+  body: `Team agreed to retire the Jenkins CI instance in Q2.
+Prerequisite: secrets migration plan must be completed first (owner: Alice).
+Cost savings: ~$300/month after retirement.`,
+  category: "eng.decisions",
+  tags: ["infra", "ci", "cost"],
+  links: [{ target_id: rawId, kind: "source" }],
+  provenance: {
+    agent: "demo-agent",
+    source_ids: [rawId],
+    note: "Compiled from Q2 planning meeting transcript",
+  },
+});
+
+console.log(`[2/4] Created compiled note: ${compiledId}`);
+
+// ---------------------------------------------------------------------------
+// 3. Placeholder snapshot (to be superseded)
+// ---------------------------------------------------------------------------
+
+const placeholderSnapshotId = await store.create({
+  type: "snapshot",
+  title: "CI Strategy Snapshot — Draft",
+  body: "Placeholder: CI strategy under discussion. No final decision yet.",
+  category: "eng.decisions",
+  tags: ["ci", "strategy", "draft"],
+  provenance: {
+    agent: "demo-agent",
+    note: "Placeholder snapshot pending planning meeting outcome",
+  },
+});
+
+console.log(`[3/4] Created placeholder snapshot: ${placeholderSnapshotId}`);
+
+// ---------------------------------------------------------------------------
+// 4. Final snapshot that supersedes the placeholder
+// ---------------------------------------------------------------------------
+
+const finalSnapshotId = await store.create({
+  type: "snapshot",
+  title: "CI Strategy Snapshot — Q2 2026",
+  body: `Decision: Migrate from Jenkins to GitHub Actions in Q2 2026.
+
+Key constraints:
+- Secrets migration must complete before Jenkins decommission.
+- Target: Jenkins instance retired by end of June 2026.
+- Owner: Platform team (Alice lead).
+
+Cost impact: -$300/month after retirement.`,
+  category: "eng.decisions",
+  tags: ["ci", "strategy", "q2-2026"],
+  links: [
+    { target_id: compiledId, kind: "source" },
+  ],
+  provenance: {
+    agent: "demo-agent",
+    source_ids: [compiledId],
+    note: "Final Q2 snapshot after planning meeting",
+  },
+});
+
+// Supersede the placeholder
+await store.supersede(finalSnapshotId, [placeholderSnapshotId], {
+  agent: "demo-agent",
+  rationale: "Q2 planning meeting resolved the CI strategy; placeholder superseded by final snapshot.",
+});
+
+console.log(`[4/4] Created final snapshot ${finalSnapshotId} (supersedes ${placeholderSnapshotId})\n`);
+console.log("─".repeat(70));
+
+// ---------------------------------------------------------------------------
+// Print the final snapshot note verbatim
+// ---------------------------------------------------------------------------
+
+// Find the file via the path index
+const pathIndexRaw = fs.readFileSync(path.join(vaultRoot, ".graph-index.json"), "utf8");
+const pathIndex = JSON.parse(pathIndexRaw);
+const snapshotEntry = pathIndex.by_id[finalSnapshotId];
+const snapshotPath = path.join(vaultRoot, snapshotEntry.path);
+
+console.log(`\nFinal snapshot note on disk: ${snapshotPath}\n`);
+console.log("═".repeat(70));
+console.log(fs.readFileSync(snapshotPath, "utf8"));
+console.log("═".repeat(70));
+
+// ---------------------------------------------------------------------------
+// Show the archived placeholder
+// ---------------------------------------------------------------------------
+
+const archivedEntry = pathIndex.by_id[placeholderSnapshotId];
+console.log(`\nSuperseded placeholder archived at: ${archivedEntry.path}`);
+console.log(`(archived: ${archivedEntry.archived})`);
+
+// Confirm it's still queryable
+const archived = await store.get(placeholderSnapshotId);
+console.log(`\nArchived record still queryable via get(): title = "${archived.title}"`);
+console.log(`Mutation log has ${archived.mutation_log.length} entr${archived.mutation_log.length === 1 ? "y" : "ies"}.`);
+const sbEntry = archived.mutation_log.find((e) => e.op === "superseded-by");
+if (sbEntry) {
+  console.log(`  - superseded-by: new_id = ${sbEntry.new_id}`);
+}
+
+// ---------------------------------------------------------------------------
+// Vault structure
+// ---------------------------------------------------------------------------
+
+console.log("\nVault layout:");
+function printTree(dir, prefix = "") {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const isLast = entry === entries[entries.length - 1];
+    console.log(`${prefix}${isLast ? "└── " : "├── "}${entry.name}`);
+    if (entry.isDirectory()) {
+      printTree(path.join(dir, entry.name), prefix + (isLast ? "    " : "│   "));
+    }
+  }
+}
+printTree(vaultRoot);
+
+// Cleanup
+fs.rmSync(vaultRoot, { recursive: true, force: true });
+console.log(`\nDemo vault cleaned up.\n`);