@opum-ai/lore 0.1.0 → 0.2.0

package/src/core/agent-bridge.ts

@@ -1,287 +0,0 @@
-/**
- * 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 };
-}