@opum-ai/lore 0.1.0

package/src/core/scaffold.ts

@@ -0,0 +1,255 @@
+/**
+ * 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

@@ -0,0 +1,366 @@
+/**
+ * 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

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