@opum-ai/lore 0.1.0

package/src/core/agent-bridge.ts

@@ -0,0 +1,287 @@
+/**
+ * core/agent-bridge.ts — the pure content + planning engine behind `lore agents` (LORE-36).
+ *
+ * `lore agents` generates the Claude Code "agent bridge" (docs/adr/0004-cli-first-skill-bridge):
+ * a `.claude/skills/lore/SKILL.md` that teaches an agent how to drive lore, and a tiny
+ * marker-delimited `CLAUDE.md` nudge that points at that skill and at `lore instructions`. Both
+ * are *generated*, not hand-maintained, so they stay in lockstep with the CLI surface.
+ *
+ * This module holds everything pure: the generated bytes ({@link buildSkillDoc},
+ * {@link buildNudgeBody}), the canonical command surface ({@link LORE_COMMANDS}), and the pure
+ * {@link planBridge planner} that — given each file's current bytes (or absence) and the `--force`
+ * flag — decides what each file's next state should be. All filesystem side effects live in the
+ * command layer (`commands/agents.ts`), per lore-design §2.1.
+ *
+ * ### Content is grounded in live source, not the runbook
+ *
+ * Every factual claim here (the command list, the `--json` envelope shape, the exit-code table, the
+ * canonical loop) is grounded in what the CLI *actually* does today — `src/cli.ts`, `src/output.ts`,
+ * `src/errors.ts`, and the shipped `core/instructions.ts` OVERVIEW — never in an aspirational
+ * runbook/ADR that also describes not-yet-shipped state. In particular the generated content names
+ * only **shipped** commands the real dispatcher handles (the LORE-37 phantom-command trap); the
+ * `agents.test.ts` lockstep guard re-checks {@link LORE_COMMANDS} against the real dispatcher.
+ */
+
+import { upsertManagedBlock } from "./managed-block";
+
+/** The repo-relative path of the generated skill bridge (pinned by ADR-0004 §3 and cli-surface §agents). */
+export const SKILL_REL_PATH = ".claude/skills/lore/SKILL.md";
+
+/** The repo-relative path of the project memory file the nudge block is upserted into. */
+export const CLAUDE_MD_REL_PATH = "CLAUDE.md";
+
+/**
+ * The label naming the `CLAUDE.md` nudge's managed block, consumed by
+ * {@link upsertManagedBlock} to build `<!-- lore:agents:begin -->` / `<!-- lore:agents:end -->`.
+ * Chosen to sit in lore's existing `lore:tasks` / `lore:index` marker namespace; kept stable
+ * because `--check` idempotency depends on the exact bytes.
+ */
+export const AGENT_BLOCK_LABEL = "lore:agents";
+
+/** One `lore` subcommand and its one-line summary, as advertised to an agent by the generated bridge. */
+export interface CommandSummary {
+  /** The subcommand token (`"sync"`), exactly as `src/cli.ts` dispatches it. */
+  readonly name: string;
+  /** A one-line description, distilled from the authoritative `cli.ts` USAGE text. */
+  readonly summary: string;
+}
+
+/**
+ * The canonical `lore` command surface the bridge advertises — the single source both
+ * {@link buildSkillDoc} and the `agents.test.ts` lockstep guard read. Names and order mirror
+ * `src/cli.ts`'s Commander handler registry / USAGE; the guard runs each name through the real CLI to prove
+ * none is a phantom (the exact LORE-37 failure mode: teaching an agent a command that does not exist).
+ */
+export const LORE_COMMANDS: readonly CommandSummary[] = [
+  {
+    name: "init",
+    summary: "Scaffold an OKF bundle; a bare TTY run also wizards the agent bridge/scaffolds/backlog check",
+  },
+  { name: "new", summary: "Scaffold a typed concept from a template" },
+  { name: "validate", summary: "Check concept files against OKF + the lore profile (per-file)" },
+  { name: "check", summary: "Validate links/anchors + reconciliation drift across the bundle (CI gate)" },
+  { name: "replace", summary: "Find-and-replace across the bundle, skipping managed regions" },
+  { name: "rename", summary: "Move a concept and repoint every inbound link + ref" },
+  { name: "supersede", summary: "Mark a concept superseded by another, wiring both ways" },
+  { name: "link", summary: "Add task ids to a concept's tasks: + the doc: back-ref" },
+  { name: "unlink", summary: "Remove task ids from a concept's tasks: + the doc: back-ref" },
+  { name: "sync", summary: "Reconcile status + managed task blocks, regen index/log, commit backlog/" },
+  { name: "tasks", summary: "Show the live status rollup for a concept's linked tasks" },
+  { name: "orphans", summary: "Report tasks with no owning doc + docs whose linked task vanished" },
+  { name: "schema", summary: "Export the profile's editor JSON Schemas to .lore/schemas/" },
+  { name: "scaffold", summary: "Generate a downstream docs consumer's config, additively outside docs/" },
+  { name: "graph", summary: "Emit the bundle's cross-link graph as json or dot" },
+  { name: "path", summary: "Find bounded paths across exact authored concept and task edges" },
+  { name: "impact", summary: "Expand bounded impact across exact authored concept and task edges" },
+  { name: "snapshot", summary: "Explicitly retain, list, or delete bounded projection snapshots" },
+  { name: "changed", summary: "Compare two retained snapshots with bounded authored-fact deltas" },
+  { name: "provenance", summary: "Trace one retained concept, task, or edge to exact source evidence" },
+  { name: "explorer", summary: "Build a deterministic self-contained local graph explorer" },
+  { name: "export", summary: "Emit a deterministic, consumer-neutral OKF projection as JSONL" },
+  { name: "query", summary: "Full-text search the bundle with frontmatter filters" },
+  { name: "context", summary: "Assemble a concept + neighbor summaries within a token budget" },
+  { name: "agent", summary: "List context profiles or compile bounded task-scoped evidence" },
+  { name: "instructions", summary: "Print task-scoped agent guidance on demand" },
+  { name: "agents", summary: "Regenerate this bridge (SKILL.md + the CLAUDE.md nudge)" },
+  { name: "help", summary: "Show help, or the machine-readable command manifest under --json" },
+];
+
+/** The four detail topics `lore instructions <topic>` serves, mirrored (not restated) by the bridge. */
+const INSTRUCTION_DETAIL_TOPICS: ReadonlyArray<{ key: string; blurb: string }> = [
+  { key: "linking", blurb: "Story <-> Task coupling (`lore link` / `lore unlink`)" },
+  { key: "sync", blurb: "reconcile status + managed blocks (`lore sync`)" },
+  { key: "check", blurb: "the CI gate: drift, links, anchors, portability (`lore check`)" },
+  { key: "validation", blurb: "per-file OKF/schema conformance (`lore validate`)" },
+];
+
+/**
+ * Render a left-aligned two-column list: a tight `` `left` `` code span, then padding *after* the
+ * backtick (never inside it, which would render as trailing whitespace in the code span) so the
+ * right column aligns in the raw text an agent reads.
+ */
+function twoColumn(rows: ReadonlyArray<{ left: string; right: string }>): string {
+  const width = Math.max(...rows.map((row) => row.left.length));
+  return rows.map((row) => `- \`${row.left}\`${" ".repeat(width - row.left.length + 2)}${row.right}`).join("\n");
+}
+
+/**
+ * Build the full `SKILL.md` bytes: YAML frontmatter (the `name` + when-to-use `description` Claude
+ * Code loads the skill by) followed by a small, live-source-grounded teacher body. Deterministic and
+ * timestamp-free, so regenerating with no change is byte-identical (AC#1). Kept a thin pointer:
+ * `lore instructions` is the source of truth, and this file directs the agent there (AC#2).
+ */
+export function buildSkillDoc(): string {
+  const description =
+    "Author and maintain this repo's OKF documentation bundle (docs/) with the lore CLI. " +
+    "Use whenever reading, writing, linking, moving, or checking docs, so Story/Task coupling, " +
+    "managed blocks, and cross-links stay coherent. Run `lore instructions` for the canonical " +
+    "agent loop and `lore instructions <topic>` for just-in-time detail.";
+
+  const topicList = twoColumn(INSTRUCTION_DETAIL_TOPICS.map((t) => ({ left: t.key, right: t.blurb })));
+  const commandList = twoColumn(LORE_COMMANDS.map((c) => ({ left: c.name, right: c.summary })));
+
+  return `---
+name: lore
+description: "${description}"
+---
+
+# lore — OKF documentation CLI
+
+\`lore\` is this repo's documentation engine: a deterministic, CLI-first tool (no LLM dependency)
+for authoring and maintaining the OKF bundle under \`docs/\`. This skill is a thin pointer —
+**\`lore instructions\` is the source of truth for how to drive lore.**
+
+## When to use it
+
+Reach for \`lore\` — not a plain editor — whenever you read, write, link, move, or verify docs in
+this repo, so Story <-> Task coupling, managed blocks, and cross-links stay coherent.
+
+## Start here
+
+Run \`lore instructions\` for the canonical agent loop and the topic index, then pull just-in-time
+detail with \`lore instructions <topic>\`:
+
+${topicList}
+
+## Commands
+
+${commandList}
+
+## Machine contract
+
+Every command supports \`--json\` (the \`{schemaVersion, kind, data}\` envelope) and \`--plain\`
+(ANSI-free, auto-selected off a TTY). Branch on the semantic exit code, never on prose:
+\`0\` ok · \`2\` usage · \`3\` not_found · \`4\` denied · \`5\` conflict · \`6\` validation/drift.
+
+## Optional task-scoped context
+
+When native Claude Code instructions name a committed Lore profile, use this stable opt-in line:
+
+> Lore profile: \`<name>\`. Before working, run \`lore agent context <name> --task "<assigned task>"\`
+> and ground decisions in the returned source IDs.
+
+Lore supplies evidence only. It does not create or patch native agents, prompts, tools, models,
+permissions, or execution settings.
+
+<!-- Generated by \`lore agents\`; do not hand-edit. Re-run \`lore agents --force\` to refresh. -->
+`;
+}
+
+/**
+ * Build the inner body of the `CLAUDE.md` nudge — the bytes {@link upsertManagedBlock} places
+ * between the `lore:agents` markers. Deliberately tiny (ADR-0004: "the SKILL.md bridge costs ~30–50
+ * idle tokens"; the nudge carries no substantive guidance itself): its only job is discoverability —
+ * "lore exists, here is the skill, here is where to pull just-in-time detail." No trailing newline.
+ */
+export function buildNudgeBody(): string {
+  return `This repo uses **lore** — an OKF-native documentation CLI — for the docs bundle under \`docs/\`.
+When working on documentation, drive it through \`lore\` (not a plain editor) so Story <-> Task
+coupling, managed blocks, and cross-links stay coherent.
+
+- **Skill:** \`${SKILL_REL_PATH}\` — how to drive lore.
+- **Just-in-time detail:** run \`lore instructions\` for the canonical agent loop, then
+  \`lore instructions <topic>\` (\`linking\`, \`sync\`, \`check\`, \`validation\`).`;
+}
+
+/** What {@link planBridge} decided a single bridge file's next state should be. */
+export type BridgeAction =
+  /** The file did not exist and will be created. */
+  | "created"
+  /** The file (or its managed block) differs and will be rewritten. */
+  | "updated"
+  /** The on-disk bytes already match — nothing to write. */
+  | "unchanged"
+  /**
+   * A whole lore-owned file (SKILL.md) differs but was left untouched: either it looks hand-edited
+   * and `--force` was not given, or this is a `--check` run — which never writes, so `--force`
+   * cannot actually take effect and must not be reported as if it had (LORE-129).
+   */
+  | "protected";
+
+/** One file's entry in a {@link BridgePlan}. */
+export interface BridgeFilePlan {
+  /** Repo-relative path (`.claude/skills/lore/SKILL.md` or `CLAUDE.md`). */
+  readonly path: string;
+  /** The decided next state. */
+  readonly action: BridgeAction;
+  /** The full bytes to write, or `null` when nothing should be written (`unchanged`/`protected`). */
+  readonly contents: string | null;
+}
+
+/** The planned next state of every bridge file, computed purely from the on-disk bytes + `--force`. */
+export interface BridgePlan {
+  readonly files: readonly BridgeFilePlan[];
+}
+
+/** The current on-disk bytes of each bridge file (LF-normalized), or `null` when the file is absent, plus `--force`/`--check`. */
+export interface PlanBridgeInput {
+  /** Current `SKILL.md` bytes, or `null` if it does not exist. */
+  readonly skillOnDisk: string | null;
+  /** Current `CLAUDE.md` bytes, or `null` if it does not exist. */
+  readonly claudeOnDisk: string | null;
+  /** Whether `--force` was given (permits overwriting a differing, possibly hand-edited SKILL.md). */
+  readonly force: boolean;
+  /**
+   * Whether this is a `--check` (report-only) run. `--check` never writes, so `force` must not be
+   * honored while planning: a `--check --force` run against a differing SKILL.md still reports
+   * `protected` (never `updated`, which would claim a write that never happens) — see
+   * {@link planSkill} (LORE-129).
+   */
+  readonly check: boolean;
+}
+
+/**
+ * Decide the next state of both bridge files, purely (no IO). The two files have deliberately
+ * different write disciplines:
+ *
+ * - **SKILL.md is a whole lore-owned file.** Absent → `created`. Byte-equal to the generated
+ *   content → `unchanged`. Differs → `updated` only under `--force` *and not* `--check` (a
+ *   `--check` run never writes, so `--force` cannot take effect and must not be reported as if it
+ *   had — LORE-129), else `protected` (left untouched — a differing generated file may be a
+ *   hand-edit, and lore never silently clobbers it; the command reports "run with --force"). This
+ *   is exactly the "overwrite hand-edited generated files" role cli-surface pins on `--force`.
+ * - **The CLAUDE.md nudge is a managed block**, so lore only ever rewrites the bytes between its own
+ *   markers. Refreshing that block is by-design and needs no `--force`: absent file → `created`;
+ *   block absent or stale → `updated` (the surrounding prose and any unrelated block, e.g.
+ *   Backlog.md's, are preserved by {@link upsertManagedBlock}); already current → `unchanged`.
+ *
+ * {@link upsertManagedBlock} throws a `validation` {@link LoreError} if CLAUDE.md carries a malformed
+ * `lore:agents` marker pair — a fail-loud propagation the command surfaces (exit 6), never a guess.
+ */
+export function planBridge(input: PlanBridgeInput): BridgePlan {
+  return { files: [planSkill(input), planNudge(input)] };
+}
+
+/**
+ * Plan the SKILL.md file (whole-file, `--force`-protected discipline). `--force` only ever permits
+ * an actual write, so it only ever yields `updated` on a real (non-`--check`) run: `--check` is
+ * read-only by contract, and `--check --force` against a differing file must still report
+ * `protected` — the check-safe, non-mutating label — never `updated`, which would falsely claim a
+ * write that this run never performs (LORE-129).
+ */
+function planSkill(input: PlanBridgeInput): BridgeFilePlan {
+  const desired = buildSkillDoc();
+  if (input.skillOnDisk === null) {
+    return { path: SKILL_REL_PATH, action: "created", contents: desired };
+  }
+  if (input.skillOnDisk === desired) {
+    return { path: SKILL_REL_PATH, action: "unchanged", contents: null };
+  }
+  if (input.force && !input.check) {
+    return { path: SKILL_REL_PATH, action: "updated", contents: desired };
+  }
+  return { path: SKILL_REL_PATH, action: "protected", contents: null };
+}
+
+/** Plan the CLAUDE.md nudge (managed-block, always-refresh discipline). */
+function planNudge(input: PlanBridgeInput): BridgeFilePlan {
+  const base = input.claudeOnDisk ?? "";
+  const desired = upsertManagedBlock(base, { label: AGENT_BLOCK_LABEL, body: buildNudgeBody() });
+  if (input.claudeOnDisk === null) {
+    return { path: CLAUDE_MD_REL_PATH, action: "created", contents: desired };
+  }
+  if (desired === input.claudeOnDisk) {
+    return { path: CLAUDE_MD_REL_PATH, action: "unchanged", contents: null };
+  }
+  return { path: CLAUDE_MD_REL_PATH, action: "updated", contents: desired };
+}