@opum-ai/lore 0.1.0

package/src/core/codex-bridge.ts

@@ -0,0 +1,100 @@
+import type { BridgeAction, BridgeFilePlan, BridgePlan } from "./agent-bridge";
+import { upsertManagedBlock } from "./managed-block";
+
+export const CODEX_SKILL_REL_PATH = ".codex/skills/lore/SKILL.md";
+export const AGENTS_MD_REL_PATH = "AGENTS.md";
+export const CODEX_AGENT_BLOCK_LABEL = "lore:agents";
+
+export function buildCodexSkillDoc(): string {
+  return `---
+name: lore
+description: Author and maintain this repository's OKF documentation bundle under docs/ with the Lore CLI. Use whenever Codex reads, writes, links, moves, synchronizes, validates, or checks documentation so Story/Task coupling, managed blocks, and cross-links remain coherent. Run \`lore instructions\` for the canonical agent loop and its topic subcommands for just-in-time details.
+---
+
+# Lore — OKF documentation CLI
+
+Use \`lore\` as this repository's deterministic, CLI-first documentation engine. Treat
+\`lore instructions\` as the source of truth; this skill is the Codex discovery bridge.
+
+## Start
+
+1. Run \`lore instructions\`.
+2. Read \`docs/index.md\`, follow the relevant Story, and inspect its coupled task status.
+3. Pull only the needed topic instructions: \`linking\`, \`sync\`, \`check\`, or \`validation\`.
+4. Author prose only outside Lore-managed regions.
+5. After documentation changes, run \`lore sync\`, \`lore validate --strict\`,
+   \`lore check --strict\`, and \`git diff --check\`.
+
+## Guardrails
+
+- Use \`lore new\` to create typed concepts.
+- Use \`lore link\` and \`lore unlink\` for Story/Task coupling.
+- Use \`lore rename\`, \`lore replace\`, and \`lore supersede\` instead of manually rewriting
+  managed references.
+- Do not hand-edit Lore-managed blocks, generated indexes, or generated logs.
+- Follow the repository's Backlog workflow independently; Lore does not replace Backlog task
+  lifecycle commands.
+- Prefer \`--json\` for machine-stable output and \`--plain\` for readable output. Branch on exit
+  codes: \`0\` success, \`2\` usage, \`3\` not found, \`4\` denied, \`5\` conflict, \`6\`
+  validation/drift.
+
+## Command map
+
+- Authoring: \`new\`, \`replace\`, \`rename\`, \`supersede\`
+- Coupling and reconciliation: \`link\`, \`unlink\`, \`sync\`, \`tasks\`, \`orphans\`
+- Verification: \`validate\`, \`check\`
+- Discovery and context: \`query\`, \`context\`, \`agent\`, \`graph\`, \`instructions\`
+- Interchange and setup: \`export\`, \`schema\`, \`scaffold\`, \`agents\`
+
+## Optional task-scoped context
+
+When native Codex developer 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 init --codex\`; do not hand-edit. -->
+`;
+}
+
+export function buildCodexNudgeBody(): 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:** \`${CODEX_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\`).`;
+}
+
+export interface PlanCodexBridgeInput {
+  readonly skillOnDisk: string | null;
+  readonly agentsOnDisk: string | null;
+  readonly force: boolean;
+  readonly check: boolean;
+}
+
+export function planCodexBridge(input: PlanCodexBridgeInput): BridgePlan {
+  return { files: [planSkill(input), planNudge(input)] };
+}
+
+function planSkill(input: PlanCodexBridgeInput): BridgeFilePlan {
+  const desired = buildCodexSkillDoc();
+  if (input.skillOnDisk === null) return { path: CODEX_SKILL_REL_PATH, action: "created", contents: desired };
+  if (input.skillOnDisk === desired) return { path: CODEX_SKILL_REL_PATH, action: "unchanged", contents: null };
+  const action: BridgeAction = input.force && !input.check ? "updated" : "protected";
+  return { path: CODEX_SKILL_REL_PATH, action, contents: action === "updated" ? desired : null };
+}
+
+function planNudge(input: PlanCodexBridgeInput): BridgeFilePlan {
+  const desired = upsertManagedBlock(input.agentsOnDisk ?? "", {
+    label: CODEX_AGENT_BLOCK_LABEL,
+    body: buildCodexNudgeBody(),
+  });
+  if (input.agentsOnDisk === null) return { path: AGENTS_MD_REL_PATH, action: "created", contents: desired };
+  if (input.agentsOnDisk === desired) return { path: AGENTS_MD_REL_PATH, action: "unchanged", contents: null };
+  return { path: AGENTS_MD_REL_PATH, action: "updated", contents: desired };
+}