@opum-ai/lore 0.1.0 → 0.1.1

package/src/core/scaffold.ts

@@ -1,255 +0,0 @@
-/**
- * scaffold.ts — the **pure** description of an empty, conformant OKF bundle.
- *
- * This module is the byte-source for `lore init` (lore-design §3.1): it computes,
- * with no filesystem access whatsoever, the exact directories and file contents a
- * fresh bundle needs — the `.lore/` state directory ([ADR-0013](../../docs/adr/0013-lore-state-directory.md)),
- * the Draft-7 JSON Schemas exported from the Zod source of truth
- * ([ADR-0006](../../docs/adr/0006-schema-types-templates.md)), and the reserved
- * root `docs/index.md` that carries `okf_version`
- * ([okf-conformance](../../docs/reference/okf-conformance.md)).
- *
- * Keeping it pure is what makes init testable and deterministic: {@link buildScaffold}
- * returns a {@link ScaffoldPlan} of intended bytes that golden tests pin exactly, and
- * `commands/init.ts` is the thin layer that applies the plan **idempotently** (writing
- * only absent files, never clobbering) — the side effects live there, the bytes live
- * here. The single non-deterministic input, the root index's `timestamp`, enters
- * through an injected option (lore-design §8), so the same options always yield the
- * same plan.
- *
- * Scope (confirmed for LORE-17): an empty bundle only. Full index/log *generation*
- * (`indexes.generateIndexes`, `log.ts` → `log.md`) is M3 / `lore sync` and is **not** done here —
- * init writes a *minimal* root index. Per-type template *content* is `lore new`'s
- * concern (LORE-18, which carries built-in fallbacks); init only ensures the
- * `.lore/templates/` directory exists.
- */
-
-import { CONFIG_REL_PATH } from "../config";
-import { type Concept, idFromPath, serializeConcept, serializeConceptWithModeline } from "./concept";
-import { defaultProfile, PROFILE_REL_PATH, type Profile } from "./profile";
-import { emitSchemaFiles, schemaModeline } from "./schema";
-
-/**
- * The bundle root — the directory every concept lives under, relative to the repo root.
- * The single source of truth for the `docs/` convention, shared by the scaffolder, the
- * bundle walk, and `lore new`'s output-path computation so they never spell it differently.
- */
-export const DOCS_DIR = "docs";
-
-/**
- * The reserved bundle-root index — the only file that carries `okf_version`. Exported so
- * `core/validate.ts` can recognize it as the one lore-owned reserved file whose frontmatter is
- * always a concept (every other `RESERVED_STEMS` file — sub-directory `index.md`s, `log.md` — is
- * frontmatter-free and so never reaches the profile-driven validator at all): `lore validate`
- * must judge it under the same {@link defaultProfile} `serializeStructuralConcept` wrote it
- * against, never the active project profile (LORE-144).
- */
-export const ROOT_INDEX_PATH = `${DOCS_DIR}/index.md`;
-
-/**
- * Reserved file stems that name machine-generated hubs (`index.md`, `log.md`): regenerated
- * wholesale by `lore sync`, never a rename/supersede/link/unlink principal. Shared by
- * `commands/rename.ts`, `commands/supersede.ts`, and `commands/link.ts` — each guards its own
- * concept-id argument(s) against it.
- */
-export const RESERVED_STEMS: ReadonlySet<string> = new Set(["index", "log"]);
-
-/** A single file the scaffold wants to exist, with the exact bytes to write when it is absent. */
-export interface ScaffoldFile {
-  /** Repo-relative POSIX path. */
-  readonly path: string;
-  /** The exact bytes to write — pinned by golden tests, applied verbatim by the command. */
-  readonly contents: string;
-}
-
-/**
- * The complete, filesystem-free description of an empty bundle. `dirs` are ensured to
- * exist (idempotent `mkdir -p`, in parent-first order); `files` are created only when
- * absent so a re-run never clobbers user edits (the AC#2 idempotency contract).
- */
-export interface ScaffoldPlan {
-  /** Directories to ensure exist, parents before children. */
-  readonly dirs: readonly string[];
-  /** Files to create if absent, in a stable order. */
-  readonly files: readonly ScaffoldFile[];
-}
-
-/** Options for {@link buildScaffold}; the timestamp is the one injected determinism seam. */
-export interface ScaffoldOptions {
-  /**
-   * ISO-8601 datetime (e.g. `2026-06-25T12:00:00Z`) stamped on the generated root
-   * index. Injected by the command from its clock so the plan is deterministic and
-   * golden-testable (lore-design §8).
-   */
-  readonly timestamp: string;
-  /**
-   * The active profile whose types drive the emitted JSON Schemas and whose `okfVersion` stamps
-   * the root index. Defaults to the built-in {@link defaultProfile}, so a zero-config `lore init`
-   * scaffolds the six story-convention schemas exactly as before.
-   */
-  readonly profile?: Profile;
-}
-
-/**
- * Build the {@link ScaffoldPlan} for an empty OKF bundle: the `.lore/` state tree, one exported
- * JSON Schema per profile type, and the reserved root `docs/index.md`. Pure — it touches no
- * filesystem and reads no clock; identical `options` always produce identical bytes.
- */
-export function buildScaffold(options: ScaffoldOptions): ScaffoldPlan {
-  const profile = options.profile ?? defaultProfile();
-  return {
-    dirs: [".lore", ".lore/schemas", ".lore/templates", ".lore/cache", DOCS_DIR],
-    files: [
-      { path: CONFIG_REL_PATH, contents: DEFAULT_CONFIG_TOML },
-      { path: PROFILE_REL_PATH, contents: DEFAULT_PROFILE_TOML },
-      { path: ".lore/.gitignore", contents: LORE_GITIGNORE },
-      ...schemaFiles(profile),
-      // Materialize the templates directory without committing to per-type content:
-      // `lore new` (LORE-18) owns the template bodies and their override-if-present
-      // logic, so init only keeps the directory tracked.
-      { path: ".lore/templates/.gitkeep", contents: "" },
-      { path: ROOT_INDEX_PATH, contents: rootIndexDocument(options.timestamp, profile) },
-    ],
-  };
-}
-
-/**
- * One {@link ScaffoldFile} per profile type, each the generated Draft-7 JSON Schema pretty-printed
- * with a trailing newline, in the profile's type-declaration order so the plan (and its golden) is
- * stable. Delegates to the shared {@link emitSchemaFiles} (the byte contract `lore schema export`
- * reuses), so a scaffolded schema and a re-exported one can never diverge.
- */
-function schemaFiles(profile: Profile): ScaffoldFile[] {
-  return emitSchemaFiles(profile);
-}
-
-/**
- * The minimal reserved root index: byte-stable frontmatter (a `Reference` carrying
- * `okf_version: "0.1"` — the sole carrier in the bundle), with the editor modeline
- * spliced in as the **first line inside** the `---` fence via
- * {@link serializeConceptWithModeline} (the shared placement seam in concept.ts).
- *
- * The modeline sits *inside* the frontmatter, not above it, because that is the only
- * placement that both (a) lets lore read the file back as a concept — `parseConcept`
- * needs `---` at byte 0, so an above-fence comment would make `loadBundle` skip the
- * index as a non-concept — and (b) matches every modeline-bearing doc already in this
- * bundle. (Trade-off: js-yaml drops the in-fence comment if the file is ever
- * re-serialized — a documented round-trip limitation in concept.ts that applies to all
- * such docs equally; `init` writes the index once and never rewrites it.)
- */
-function rootIndexDocument(timestamp: string, profile: Profile): string {
-  const concept: Concept = {
-    id: idFromPath(ROOT_INDEX_PATH),
-    path: ROOT_INDEX_PATH,
-    type: ROOT_INDEX_TYPE,
-    frontmatter: {
-      type: ROOT_INDEX_TYPE,
-      title: "Documentation",
-      summary: "Root index of this OKF documentation bundle, created by `lore init`.",
-      timestamp,
-      okf_version: profile.okfVersion,
-    },
-    body: ROOT_INDEX_BODY,
-  };
-  // Only `okf_version` above is profile-derived; the serialization choice itself (structural
-  // profile, conditional modeline) is shared with every other reserved structural file — see
-  // {@link serializeStructuralConcept}.
-  return serializeStructuralConcept(concept, profile);
-}
-
-/**
- * Serialize a lore-owned **reserved structural file** — one with a fixed shape that lore itself
- * generates (the root `docs/index.md` here, `docs/tags.md` in `core/consumer-scaffold.ts`) — never
- * a user concept. Always validated/serialized against the built-in {@link defaultProfile}, never the
- * *active* one, so a custom profile that retypes the concept's `type` (e.g. adds a required field to
- * `Reference`) can never make a scaffold command fail to write its own reserved file. The `$schema`
- * editor modeline is carried only when the *active* `profile` defines `concept.type` — so the schema
- * it points at was actually emitted under `.lore/schemas/` — via {@link serializeConceptWithModeline};
- * otherwise a plain {@link serializeConcept} against the structural profile.
- */
-export function serializeStructuralConcept(concept: Concept, profile: Profile): string {
-  const structural = defaultProfile();
-  return profile.types.has(concept.type)
-    ? serializeConceptWithModeline(concept, schemaModeline(concept.path, concept.type), { profile: structural })
-    : serializeConcept(concept, { profile: structural });
-}
-
-/** The reserved root index's `type` — lore's bundle entry point is conventionally a `Reference`. */
-const ROOT_INDEX_TYPE = "Reference";
-
-/** The body of the scaffolded root index (after the frontmatter fence). */
-const ROOT_INDEX_BODY = `
-# Documentation
-
-This is the root index of an OKF documentation bundle, created by \`lore init\`.
-Add concepts under \`docs/\` and link them from here. This file is the bundle's
-entry point and the only one that carries \`okf_version\`.
-`;
-
-/** The committed `.lore/.gitignore`: keep the transient cache out of git (ADR-0013). */
-const LORE_GITIGNORE = `# lore transient cache — recomputable, machine-local, never committed (ADR-0013).
-cache/
-`;
-
-/**
- * The default, fully-commented `.lore/config.toml`. Every setting is shown commented
- * because lore is zero-config: a missing file — or one with every line commented —
- * yields the documented defaults (ADR-0013), so a fresh `init` produces a file that
- * changes nothing until a team uncomments a knob. The committed-token guard in
- * config.ts still applies; the Confluence token is environment-only.
- */
-const DEFAULT_CONFIG_TOML = `# lore configuration — committed, team-shared knobs for \`lore sync\` / \`lore check\`.
-# Every setting is OPTIONAL: with this file absent, or every line below commented,
-# lore uses the documented defaults. See docs/adr/0013-lore-state-directory.md.
-
-# [reconcile]
-# Status roll-up policy applied by \`lore sync\` / \`lore check\`.
-# mode = "task-rollup"   # all tasks Done -> done; any In Progress -> in-progress; else todo
-
-# [validate]
-# external_links = false       # external-link liveness is opt-in only
-# promote_portability = false  # keep the portability lint a warning, not an error
-
-# [confluence]
-# Non-secret publish target settings (the one-way publish adapter is deferred to v2).
-# The API token is environment-only: set $LORE_CONFLUENCE_TOKEN, never store it here.
-# base_url       = "https://yourorg.atlassian.net/wiki"
-# space          = "ENG"
-# parent_page_id = "98765"
-# format         = "storage"   # or "adf"
-`;
-
-/**
- * The default, fully-commented `.lore/profile.toml`. The profile is the declarative source of
- * truth for the type vocabulary (ADR-0006): with this file absent — or every line below
- * commented — lore uses the built-in story-convention profile (Epic/Story/Spec/ADR/Runbook/
- * Reference), so a fresh `init` produces a file that changes nothing until a team defines its own
- * types. It is separate from `config.toml`: config carries operational knobs, the profile carries
- * the type system. See docs/adr/0006-schema-types-templates.md.
- */
-const DEFAULT_PROFILE_TOML = `# lore profile — committed, declarative type vocabulary for this bundle.
-# OPTIONAL: with this file absent, or every line below commented, lore uses the built-in
-# story-convention profile (Epic/Story/Spec/ADR/Runbook/Reference). Fill it in to define your
-# own types. lore generates its runtime validators + editor JSON Schemas from this file at load.
-
-# [profile]
-# name = "my-project"      # required once any line below is uncommented
-# okf_version = "0.1"      # required; asserted against the bundle-root index.md
-# case = "Title"           # type-name casing convention (advisory; powers the did-you-mean hint)
-# resource_base = ""       # prefix for the stamped \`resource\` link (empty = none)
-
-# [base.fields]
-# Fields every type carries. \`type\` MUST be required (OKF's one hard requirement).
-# type = { required = true }
-# title = {}
-# description = {}
-# tags = { kind = "list" }
-# summary = {}
-# timestamp = { kind = "datetime" }
-
-# [[types]]
-# name = "Spec"                       # the OKF \`type\` value
-# sections = ["Summary", "Design"]    # required body headings (## …)
-# template = "spec.md"                # template under .lore/templates/
-# fields = { feature = { required = true }, status = { enum = ["draft", "approved"] } }
-`;

package/src/core/schema.ts

@@ -1,366 +0,0 @@
-/**
- * schema.ts — validate concept frontmatter against the **active profile**.
- *
- * Per [ADR-0006](../../docs/adr/0006-schema-types-templates.md) (inverted by LORE-46),
- * the type vocabulary is no longer hand-authored Zod here: it is **data**, loaded and
- * compiled by [profile.ts](./profile.ts) into a {@link Profile} whose per-type Zod
- * validators and editor JSON Schemas are *generated* from a declarative
- * `.lore/profile.toml`. This module is the **consumer** of that compiled profile: it runs
- * the per-type validator, classifies findings into OKF's tiers, and owns the editor
- * schema-file naming + modeline conventions. With no profile passed, every function
- * defaults to the built-in story-convention {@link defaultProfile} — so a caller that
- * does not opt into a custom profile sees exactly the behavior lore shipped before the
- * profile existed.
- *
- * The validation tiers mirror OKF §9 + the active profile
- * ([okf-conformance](../../docs/reference/okf-conformance.md) "How lore checks conformance"):
- *
- * - **ERROR** (throws a `validation` {@link LoreError}, exit 6): unparseable frontmatter
- *   (handled upstream in concept.ts), a missing/empty `type`, or a *known* field carrying
- *   the wrong type (e.g. `tags` that is not a list).
- * - **WARNING** (recorded on a {@link WarningCollector}, never fatal): an unknown `type`
- *   (validated on `type` alone), an extra key on a *known* type, or a missing/over-long
- *   `summary`.
- *
- * Two deliberate departures from a naive reading of ADR-0006 are preserved by the
- * generated profile (see [profile.ts](./profile.ts)): known schemas are **loose** (extra
- * keys pass validation and are warned separately, preserving OKF tolerance), and
- * validation **never rewrites** the data — {@link validateFrontmatter} only inspects the
- * frontmatter and returns the resolved `type`, so byte-stable round-tripping
- * ([ADR-0011](../../docs/adr/0011-frontmatter-serialization-stability.md)) is never
- * compromised by coercion, key-stripping, or reordering. Dates stay **ISO strings**, never
- * coerced to `Date` (ADR-0006 §2).
- */
-
-import { posix } from "node:path";
-import type { z } from "zod";
-import { LoreError, type WarningCollector } from "../errors";
-import { type CompiledType, defaultProfile, type Profile, slugForTypeName } from "./profile";
-
-/**
- * The bundle-root index's path, in the two conventions a caller of {@link validateFrontmatter} may
- * pass for the identical physical file: **bundle-root-relative** (`"index.md"` — every
- * {@link import("./bundle").loadBundle}-backed command (`sync`/`query`/`graph`/`link`/…) reaches
- * this module through {@link import("./concept").parseConcept}/`tryParseConcept`, fed
- * bundle-root-relative paths by `loadBundle`'s own walk) and **repo-relative**
- * (`"docs/index.md"` — `core/validate.ts`'s `validateConceptText` threads this form instead; see
- * its own `ROOT_INDEX_PATH`, LORE-144). Both name the one file `lore init` ever stamps
- * `okf_version` onto, so both must be recognized as "the root" here. This module cannot import
- * `scaffold.ts`'s `ROOT_INDEX_PATH` directly — `scaffold.ts` already imports from this module, and
- * doing so would be a circular import — so the two literal spellings are pinned locally instead.
- */
-const ROOT_INDEX_PATHS: ReadonlySet<string> = new Set(["index.md", "docs/index.md"]);
-
-/** Whether `path` names the bundle-root index, under either convention {@link ROOT_INDEX_PATHS} pins. */
-function isRootIndexPath(path: string | undefined): boolean {
-  return path !== undefined && ROOT_INDEX_PATHS.has(path);
-}
-
-/**
- * Whether `key` is an OKF-reserved key that passes the extra-key warning on a known type. Both
- * `resource` and `okf_version` are legitimate, lore-recognized fields — not stray producer
- * extensions — so flagging either as unknown (as the generic extra-key check otherwise would)
- * would be a false positive on lore's own conformant output, but each is reserved only in the
- * ONE position lore itself ever writes it:
- *
- * - `resource` is the OKF-recommended canonical link `lore new` stamps from the profile's
- *   `resource_base` (LORE-47) onto an ordinary concept. **Index files are the exception**: lore
- *   never stamps `resource` on an `index.md` (it is a structure page, not a cited concept —
- *   LORE-47 AC#4/#5), so a `resource:` hand-authored onto one (`isIndex`) is not lore's
- *   recognized output and is warned like any other extra key.
- * - `okf_version` is the bundle-root index's conformance marker (OKF §4) — a whole-bundle
- *   conformance property, not a per-concept one. Only the bundle-ROOT index
- *   ({@link isRootIndexPath}) — the one file `lore init`'s `serializeStructuralConcept` ever
- *   stamps it onto — is exempt. A hand-authored `okf_version` anywhere else (an ordinary
- *   concept, or a *sub*-index like `docs/adr/index.md`) is not lore's own output and is warned
- *   like any other extra key (LORE-168; previously this was unconditionally exempt everywhere,
- *   contradicting the conformance check `docs/reference/okf-conformance.md` documents).
- */
-function isReservedKey(key: string, isIndex: boolean, isRootIndex: boolean): boolean {
-  if (key === "resource") {
-    return !isIndex;
-  }
-  if (key === "okf_version") {
-    return isRootIndex;
-  }
-  return false;
-}
-
-/** The longest a `summary` should be before lore warns it is no longer a one-liner (ADR-0006 §5). */
-const SUMMARY_SOFT_LIMIT = 200;
-
-/** Options for {@link validateFrontmatter}. */
-export interface ValidateOptions {
-  /** Sink for advisory warnings (unknown type, extra keys, summary). Absent → warnings are dropped. */
-  warnings?: WarningCollector;
-  /** The concept's repo-relative path, woven into diagnostics so a finding names its file. */
-  path?: string;
-  /** The active profile to validate against; defaults to the built-in {@link defaultProfile}. */
-  profile?: Profile;
-}
-
-/** Narrow an arbitrary string to a type the `profile` (default: built-in) validates strictly-by-field. */
-export function isKnownType(type: string, profile: Profile = defaultProfile()): boolean {
-  return profile.types.has(type);
-}
-
-/**
- * Resolve a user-supplied `<type>` token to its canonical spelling in `profile`. `lore new`
- * accepts a type case-insensitively (`story`, `ADR`, `reference`), so a token whose lower-case
- * form names a profile type returns that type's canonical casing (`Story`, `ADR`, `Reference`) —
- * the value lore writes to `type:` and keys its schema by. An **unknown** type is a tolerated OKF
- * producer extension: it is returned **trimmed but otherwise verbatim** (the author's own casing
- * preserved), never folded or rejected.
- */
-export function canonicalType(input: string, profile: Profile = defaultProfile()): string {
-  const trimmed = input.trim();
-  return profile.byLowerName.get(trimmed.toLowerCase()) ?? trimmed;
-}
-
-/**
- * The **required body sections** (`##` headings) a concept of `type` must carry under `profile` —
- * the per-type tier-2 section contract `lore validate` enforces as an **error** (ADR-0007). An
- * unknown (producer-extension) type yields `[]` (OKF tolerance: lore never imposes a section shape
- * on a type it does not own). The single source the validator reads.
- */
-export function requiredSectionsFor(type: string, profile: Profile = defaultProfile()): readonly string[] {
-  return profile.types.get(type)?.requiredSections ?? [];
-}
-
-/**
- * The bundle sub-directory each story-convention type's concepts conventionally live under,
- * relative to the bundle root (`docs/`). These plural/acronym directory names are **not derivable**
- * from the type by any single rule (the bundle uses the acronym `adr`, the singular `reference`, and
- * the plurals `runbooks`/`specs`), so they are a lore built-in convenience map — independent of the
- * profile, which (by its finalized grammar) carries no per-type directory. A type outside this map
- * (a producer extension, or a custom-profile type) falls back to its LOWER-KEBAB slug.
- */
-const TYPE_DIRECTORIES: Readonly<Record<string, string>> = Object.freeze({
-  Epic: "epics",
-  Story: "stories",
-  Spec: "specs",
-  ADR: "adr",
-  Runbook: "runbooks",
-  Reference: "reference",
-});
-
-/**
- * The bundle sub-directory a concept of `type` is scaffolded into: the {@link TYPE_DIRECTORIES}
- * convention for a story-convention type, else the type's {@link slugForTypeName LOWER-KEBAB slug}
- * (so `lore new "QA Plan" …` lands under `docs/qa-plan/`, never `docs/qa plan/`). Using the slug —
- * not a bare lower-case — keeps a multi-word/space-containing profile type from yielding an invalid
- * path segment. Returns a path segment relative to the bundle root, never including `docs/` itself.
- * A caller may always override the computed path (`lore new … --out`).
- */
-export function typeDirectory(type: string): string {
-  return TYPE_DIRECTORIES[type] ?? slugForTypeName(type);
-}
-
-/**
- * Validate a frontmatter object against `options.profile` (default: built-in), **throwing** on an
- * error-tier problem and **recording** warning-tier ones on `options.warnings`. It never mutates
- * `fm` — the caller keeps the verbatim object so byte-stable round-tripping is preserved (ADR-0011).
- * It **returns the resolved type** (the `type` value, trimmed). Behavior by tier:
- *
- * - Missing/empty `type` → throw (`validation`). This is the OKF §9 floor.
- * - Unknown `type` → warn; the type-only floor already passed, so nothing else is checked and
- *   every key is preserved (OKF tolerance).
- * - Known `type` with a mistyped field → throw (`validation`) citing the field(s). A `type`
- *   carrying surrounding whitespace, or spelled in a different casing than the profile's
- *   canonical form (`story` for `Story`), classifies via {@link canonicalType} — so it is
- *   looked up and validated against that type's *real* schema — and then fails the schema's
- *   `type` literal check loudly here, rather than being silently demoted to an unvalidated
- *   unknown type. Only the lookup key is folded; `fm` itself is never rewritten (ADR-0011).
- * - Known `type` with extra keys → one warning per extra key.
- * - Missing or over-long (~{@link SUMMARY_SOFT_LIMIT}-char) `summary` → warn.
- */
-export function validateFrontmatter(fm: Record<string, unknown>, options: ValidateOptions = {}): string {
-  const profile = options.profile ?? defaultProfile();
-  const where = options.path ? ` in ${options.path}` : "";
-  const type = requireType(fm, where, options.path);
-
-  const compiled = profile.types.get(canonicalType(type, profile));
-  if (compiled === undefined) {
-    // Unknown type: the non-empty-`type` floor (OKF §9) is already satisfied, so this is a
-    // tolerated producer extension — warn, validate nothing further, leave every key untouched.
-    options.warnings?.add(`unknown type "${type}"${where}; validated on \`type\` only`);
-    return type;
-  }
-
-  const result = compiled.schema.safeParse(fm);
-  if (!result.success) {
-    throw new LoreError(
-      "validation",
-      `invalid ${type} frontmatter${where}: ${describeIssues(result.error)}`,
-      "fix the field(s) named above to match the type's schema, or run `lore validate`",
-      { path: options.path, type, issues: issueList(result.error) },
-    );
-  }
-
-  const isIndex = options.path !== undefined && posix.basename(options.path) === "index.md";
-  const isRootIndex = isRootIndexPath(options.path);
-  warnExtraKeys(fm, compiled, where, options.warnings, isIndex, isRootIndex);
-  warnSummary(fm.summary, where, options.warnings);
-  return type;
-}
-
-/**
- * Read a non-empty string `type` and return it **trimmed**, or throw the OKF §9 floor error.
- * Trimming the return means a `type` with accidental surrounding whitespace classifies on its real
- * value (so a known type is type-checked, not silently demoted to "unknown"); the frontmatter object
- * keeps the verbatim value. `path` is echoed on the error's `input.path` so a consumer gets a usable path.
- */
-function requireType(fm: Record<string, unknown>, where: string, path: string | undefined): string {
-  const type = fm.type;
-  if (type === undefined || type === null) {
-    throw new LoreError(
-      "validation",
-      `frontmatter${where} is missing a \`type\``,
-      "every concept needs a `type:` field (OKF §9); add one, e.g. `type: Reference`",
-      { path },
-    );
-  }
-  if (typeof type !== "string" || type.trim() === "") {
-    throw new LoreError(
-      "validation",
-      `frontmatter${where} has an invalid \`type\` (must be a non-empty string)`,
-      'set `type` to a non-empty string; quote it if it looks like a number or date, e.g. `type: "2026"`',
-      { path },
-    );
-  }
-  return type.trim();
-}
-
-/**
- * Warn for each key on a *known*-type concept that its profile type does not declare. Diffs the
- * frontmatter's own keys against the compiled type's {@link CompiledType.declaredFields} (the
- * generated schema is loose, so these extras validated fine) — the tier-3 OKF-tolerance warning,
- * not an error.
- */
-function warnExtraKeys(
-  fm: Record<string, unknown>,
-  compiled: CompiledType,
-  where: string,
-  warnings: WarningCollector | undefined,
-  isIndex: boolean,
-  isRootIndex: boolean,
-): void {
-  if (warnings === undefined) {
-    return;
-  }
-  for (const key of Object.getOwnPropertyNames(fm)) {
-    if (!compiled.declaredFields.has(key) && !isReservedKey(key, isIndex, isRootIndex)) {
-      warnings.add(`unknown key "${key}"${where}; preserved but not validated`);
-    }
-  }
-}
-
-/** Warn when `summary` is absent or runs well past the one-liner soft limit (ADR-0006 §5). */
-function warnSummary(summary: unknown, where: string, warnings: WarningCollector | undefined): void {
-  if (warnings === undefined) {
-    return;
-  }
-  if (summary === undefined || summary === null) {
-    warnings.add(`missing \`summary\`${where}; add a one-line summary for indexes and query snippets`);
-    return;
-  }
-  if (typeof summary === "string") {
-    const codePointLength = [...summary].length;
-    if (codePointLength > SUMMARY_SOFT_LIMIT) {
-      warnings.add(
-        `\`summary\`${where} is ${codePointLength} chars; keep it under ~${SUMMARY_SOFT_LIMIT} (one sentence)`,
-      );
-    }
-  }
-}
-
-/**
- * Project one Zod issue onto its `{ path, message }` pair — the single source of the dotted-path
- * rendering, so the human message and the JSON envelope's `input.issues` can never spell a nested
- * path two different ways if Zod's issue shape changes.
- */
-function projectIssue(issue: z.core.$ZodIssue): { path: string; message: string } {
-  return { path: issue.path.join("."), message: issue.message };
-}
-
-/** Flatten Zod issues to a single-line, human "field: reason; field: reason" string. */
-function describeIssues(error: z.ZodError): string {
-  return error.issues
-    .map((issue) => {
-      const { path, message } = projectIssue(issue);
-      return `${path || "(root)"}: ${message}`;
-    })
-    .join("; ");
-}
-
-/** Project Zod issues onto a plain, JSON-safe array for the error envelope's `input`. */
-function issueList(error: z.ZodError): Array<{ path: string; message: string }> {
-  return error.issues.map(projectIssue);
-}
-
-// ── JSON Schema emission + editor modeline (ADR-0006 §3) ───────────────────────
-//
-// The generated profile already carries each type's Draft-7 JSON Schema
-// ({@link CompiledType.jsonSchema}); `lore init` writes one per type under `.lore/schemas/`.
-// This module owns the **filename + modeline conventions** that bind a doc to its schema, kept
-// here beside the validator so the emitter, the modeline writer, and the runtime check can never
-// disagree about what a type's schema is called or where it lives.
-
-/** Where lore writes the emitted JSON Schemas, relative to the repo root (ADR-0013). */
-export const SCHEMAS_DIR = ".lore/schemas";
-
-/**
- * The on-disk filename for a type's JSON Schema: its LOWER-KEBAB slug plus `.schema.json`
- * (`Reference` → `reference.schema.json`, `QA Plan` → `qa-plan.schema.json` — AC#7). For the
- * single-word story-convention types the slug equals the lower-cased name, so the filenames are
- * unchanged from before the profile existed (the committed modelines in this bundle still resolve).
- * The single source of the convention, shared by the scaffolder and {@link schemaModeline}.
- */
-export function schemaFileName(type: string): string {
-  return `${slugForTypeName(type)}.schema.json`;
-}
-
-/**
- * The editor modeline for a concept at `docPath` of `type` — the comment
- * `# yaml-language-server: $schema=<relative path to .lore/schemas/<slug>.schema.json>` (ADR-0006 §3).
- * The `$schema` path is computed **relative to the document's own directory** with POSIX separators,
- * so it resolves identically on every consumer regardless of how deep the doc sits. Pure and
- * filesystem-free.
- */
-export function schemaModeline(docPath: string, type: string): string {
-  const relDir = posix.relative(posix.dirname(docPath), SCHEMAS_DIR);
-  return `# yaml-language-server: $schema=${posix.join(relDir, schemaFileName(type))}`;
-}
-
-/** A single emitted JSON Schema file: its `<dir>`-relative path and the exact bytes to write. */
-export interface SchemaFile {
-  /** `<dir>/<slug>.schema.json`, POSIX-joined (`.lore/schemas/reference.schema.json`). */
-  readonly path: string;
-  /** The type's Draft-7 JSON Schema, two-space pretty-printed with one trailing newline (the byte contract). */
-  readonly contents: string;
-}
-
-/** Options for {@link emitSchemaFiles}. */
-export interface EmitSchemaFilesOptions {
-  /** Directory the files are placed under (default {@link SCHEMAS_DIR}). */
-  readonly dir?: string;
-  /** Emit only this one compiled type; default: every type in the profile, in declaration order. */
-  readonly only?: CompiledType;
-}
-
-/**
- * The emitted JSON Schema files for a `profile` — one {@link SchemaFile} per type (or just
- * `options.only`), each the type's generated Draft-7 JSON Schema pretty-printed with a two-space
- * indent and a single trailing newline (the committed byte contract), placed under `options.dir`.
- * Pure and deterministic: the same profile always yields the same files in the same order. This is
- * the **single source** `lore init` ({@link import("./scaffold").buildScaffold}) and
- * `lore schema export` share, so a scaffolded schema file and a re-exported one are byte-identical.
- */
-export function emitSchemaFiles(profile: Profile, options: EmitSchemaFilesOptions = {}): SchemaFile[] {
-  const dir = options.dir ?? SCHEMAS_DIR;
-  const types = options.only ? [options.only] : [...profile.types.values()];
-  return types.map((type) => ({
-    path: posix.join(dir, schemaFileName(type.name)),
-    contents: `${JSON.stringify(type.jsonSchema, null, 2)}\n`,
-  }));
-}

package/src/core/snapshot-runtime.ts

@@ -1,52 +0,0 @@
-/** Source-loading boundary shared by snapshot/change/provenance commands. */
-
-import type { BacklogAdapter } from "../adapters/backlog";
-import type { WarningCollector } from "../errors";
-import { EXPECTED_LADYBUG_STORAGE_VERSION, EXPECTED_LADYBUG_VERSION } from "./ladybug-native";
-import { loadLadybugProjectionSource } from "./ladybug-source";
-import { buildRepositoryRetainedSnapshot, buildWorkspaceRetainedSnapshot, type RetainedSnapshot } from "./snapshot";
-import type { SnapshotScopeSelection } from "./snapshot-store";
-import { workspaceKeyForId } from "./workspace-contract";
-import { loadWorkspaceProjection } from "./workspace-source";
-
-export interface SnapshotRuntimeSelection {
-  readonly workspace?: string;
-  readonly workspaceId?: string;
-}
-
-export async function loadCurrentRetainedSnapshot(options: {
-  readonly root: string;
-  readonly selection: SnapshotRuntimeSelection;
-  readonly warnings?: WarningCollector;
-  readonly adapter?: BacklogAdapter;
-}): Promise<RetainedSnapshot> {
-  if (options.selection.workspace !== undefined) {
-    const loaded = await loadWorkspaceProjection({
-      root: options.root,
-      manifestPath: options.selection.workspace,
-      warnings: options.warnings,
-    });
-    return buildWorkspaceRetainedSnapshot(loaded.projection);
-  }
-  const source = await loadLadybugProjectionSource({
-    root: options.root,
-    ladybugVersion: EXPECTED_LADYBUG_VERSION,
-    ladybugStorageVersion: EXPECTED_LADYBUG_STORAGE_VERSION,
-    adapter: options.adapter,
-    warnings: options.warnings,
-  });
-  return buildRepositoryRetainedSnapshot(source);
-}
-
-export async function resolveSnapshotScope(options: {
-  readonly root: string;
-  readonly selection: SnapshotRuntimeSelection;
-  readonly warnings?: WarningCollector;
-  readonly adapter?: BacklogAdapter;
-}): Promise<SnapshotScopeSelection> {
-  if (options.selection.workspaceId !== undefined) {
-    return { kind: "workspace", scopeKey: workspaceKeyForId(options.selection.workspaceId) };
-  }
-  const current = await loadCurrentRetainedSnapshot(options);
-  return { kind: current.scopeKind, scopeKey: current.scopeKey };
-}