@opum-ai/lore 0.1.0

package/src/core/instructions.ts

@@ -0,0 +1,209 @@
+/**
+ * core/instructions.ts — the static guidance `lore instructions` serves.
+ *
+ * `lore instructions [<topic>]` is the just-in-time channel described in
+ * docs/runbooks/agent-onboarding.md §2.3: instead of carrying lore's guidance
+ * resident in an agent's context, it prints exactly the topic needed for the
+ * current step of the canonical loop, mirroring the `backlog instructions
+ * <topic>` idiom this project itself uses.
+ *
+ * Every topic here is a condensed restatement of guidance that already lives
+ * elsewhere (the runbook, the ADRs, the CLI contract) — this module invents no
+ * new policy, it only makes existing policy pullable on demand. Content is
+ * static and root-independent: no bundle load, no config read, so the command
+ * layer needs no `root`.
+ */
+
+/** One guidance topic `lore instructions` can print. */
+export interface InstructionTopic {
+  /** The key passed as `lore instructions <key>` (`overview` is the no-arg default). */
+  readonly key: string;
+  /** A one-line description — the pretty-mode heading and the topic-index entry. */
+  readonly title: string;
+  /** The full guidance body: plain prose, no ANSI, no trailing newline. */
+  readonly body: string;
+}
+
+const LINKING: InstructionTopic = {
+  key: "linking",
+  title: "Story <-> Task coupling (`lore link` / `lore unlink`)",
+  body: `A Story concept's frontmatter \`tasks:\` list is the source of coupling to
+Backlog.md -- those are the task ids the Story owns. Roll up their current live
+status with \`lore tasks <conceptId>\` (pass the Story, not a task id -- the
+read-only rollup \`lore sync\` writes into the managed block); to inspect one
+task, use \`backlog task view <taskId> --plain\`. Never trust the Story's own
+written \`status\`, which only refreshes when \`lore sync\` runs.
+
+To couple a new task to a Story, create it in Backlog (\`backlog task create
+...\`) then run \`lore link <story> <taskId...>\` -- this updates both the
+Story's frontmatter \`tasks:\` list and the task's \`doc:<conceptId>\`
+back-reference label in one step, validating every given id exists first
+and failing the whole command loud (not_found, exit 3) before writing
+anything if one doesn't. \`lore unlink <story> <taskId...>\` removes the
+coupling the same way, but is more forgiving: a task id no longer present
+in Backlog is simply skipped (exit 0), not an error.
+
+\`lore link\`/\`lore unlink\` edit \`backlog/tasks/*.md\` directly and commit
+those edits themselves -- each calls \`commitBacklogFiles\`, scoped to
+exactly the files it touched, right after writing them, so nothing is left
+pending for \`lore sync\` on their account. \`lore sync\`'s own commit step
+is now a catch-all sweep: it still commits anything left dirty under
+\`backlog/\` from another source (a human's direct \`backlog task edit\`, or
+a prior run's commit that failed). Never hand-edit or \`git add\` files
+under \`backlog/tasks/\` yourself; whichever command touches them commits
+them.
+
+See ADR-0009 (Story <-> Task coupling & reconciliation) and ADR-0012
+(Backlog coexistence & git ownership).`,
+};
+
+const SYNC: InstructionTopic = {
+  key: "sync",
+  title: "Reconciling status and managed blocks (`lore sync`)",
+  body: `\`lore sync [paths...]\` is the write step that makes the bundle coherent:
+it recomputes each Story's \`status\` from its coupled tasks' live Backlog
+state (ADR-0009's reconciliation rules), rewrites the
+\`<!-- lore:tasks:begin -->\` ... \`<!-- lore:tasks:end -->\` managed blocks from
+that live data, regenerates the bundle's index/log, and commits \`backlog/\`
+if \`lore link\`/\`lore unlink\` left it dirty.
+
+It is idempotent: run it again with no upstream change and it produces
+byte-identical output -- a clean, empty diff. The \`--json\` payload is
+\`kind: sync.result\` and reports exactly what changed (status rewrites,
+managed-block diffs, regenerated files), plus \`orphanedIndexes\`:
+repo-relative paths of on-disk \`index.md\` files whose directory no longer
+holds any concept (e.g. after a manual \`rm\`/\`mv\` outside \`lore rename\`) --
+reported so they're never silently unmentioned, but left untouched on disk,
+not auto-written or removed.
+
+Never hand-edit inside a managed block: the next \`lore sync\` silently
+overwrites it, and \`lore replace\` silently skips any match inside one --
+neither errors. (Malformed markers themselves -- missing, duplicated,
+crossed, or a collapsed same-line begin/end pair -- are a \`validation\`
+error, exit 6; that's a different failure than an ordinary hand-edit.)
+Author prose only outside the markers.
+
+Run \`lore sync\` after any task status change or after linking/unlinking a
+task, before \`lore check\` -- check is read-only and will only tell you sync
+is needed, not fix it for you.`,
+};
+
+const CHECK: InstructionTopic = {
+  key: "check",
+  title: "The CI gate: drift, links, anchors, portability (`lore check`)",
+  body: `\`lore check [paths...]\` is lore's read-only CI gate. It always emits the
+full \`check.report\` on stdout (\`kind: check.report\` under \`--json\`) --
+findings for broken internal links, rotted heading anchors, reconciliation
+drift (a Story's written status or managed block gone stale), and, under
+\`--strict\`, portability-lint warnings. It then *returns* exit 6 when any of
+those is error-tier (or any warning exists under \`--strict\`) -- a plain
+exit code, not a thrown error: nothing throws on this path, so there is no
+\`--json\` error envelope for a failing report (the report itself, already on
+stdout, is the payload). cli-contract.md's exit table labels this condition
+\`drift\` for documentation purposes only, to distinguish it from
+\`validation\` -- \`lore validate\`'s own error_type for a different command;
+check has no error_type split of its own to branch on.
+
+check's throws (each carries a \`--json\` error envelope) are \`usage\`
+(exit 2, a bad flag, or a bundle-root path argument that exists but isn't a
+directory), \`not_found\` (exit 3, a given bundle-root path that doesn't
+exist, or, when a discovered concept links a Backlog task, that task's id no
+longer existing), \`denied\` (exit 4, a bundle-root path that exists but
+can't be read), and \`validation\` (exit 6; its causes include a malformed
+status flow or override in the reconcile config, validated up front before
+any task resolution; malformed frontmatter on a \`tasks:\`-linked concept,
+caught per-file while scanning for reconciliation eligibility -- before any
+task resolution runs, but not re-thrown until after the report has already
+emitted; a resolved task whose live status is in neither the configured
+status flow nor its \`[reconcile.overrides]\`, discovered only once that
+task's own detail has already been resolved; and corrupted managed-block
+markers, hit per-concept while regenerating that concept's
+\`<!-- lore:tasks -->\` region during drift detection -- i.e. *after* that
+concept's own tasks are already resolved). \`validation\`'s exit code
+coincides with the drift-tier report's exit 6 above, but the two are
+distinct: \`validation\` is a thrown error with a \`--json\` envelope; the
+report's exit 6 is a plain returned code with no throw.
+
+Because check writes nothing and lore's core has no LLM dependency, it is
+deterministic: a clean \`lore check\` locally means a clean \`lore check\` in
+CI, with no flakiness to chase. A typical loop: run check; exit 0 means
+done; exit 6 means read the report and run \`lore sync\` for any drift
+finding, then re-check; exit 3 means fix the path argument; an uncaught 1
+needs investigation, not a blind sync.
+
+Treat \`lore check\` exiting 0 as the actual definition of "done" for any
+docs-touching change -- not typecheck or lint alone.`,
+};
+
+const VALIDATION: InstructionTopic = {
+  key: "validation",
+  title: "Per-file OKF/schema conformance (`lore validate`)",
+  body: `\`lore validate [paths...]\` is a tiered, per-file conformance reporter,
+distinct from \`check\`'s cross-file drift/link/portability pass. It
+validates: OKF §9 conformance (frontmatter parses, \`type\` is present and
+non-empty) as an error if violated; per-type frontmatter shape and required
+sections against a Zod schema generated from the declarative
+\`.lore/profile.toml\` (the source of truth per ADR-0006's LORE-46 amendment)
+as an error if violated for known types; an unknown \`type\` or extra
+frontmatter keys as a warning only (OKF tolerates unknown fields -- custom
+frontmatter passes through untouched); a stale \`resource:\` value that no
+longer matches what the profile computes for the concept's current path as
+a warning (rule "resource"); and frontmatter values that would serialize
+ambiguously as quote-safety findings -- mostly errors (an unquoted YAML
+indicator char, a YAML-1.1 boolean like bare \`no\`/\`yes\`, or a colon
+followed by a space, which YAML would otherwise misread as a nested
+mapping), with only a bare \`YYYY-MM-DD\` date downgraded to a warning. A
+colon with no trailing space is not flagged -- a URL like \`https://...\`
+or an ISO timestamp like \`2024-01-01T00:00:00\` is accepted even though
+it contains a colon.
+
+With no path arguments it walks the whole bundle; pass explicit \`[paths...]\`
+to scope it (e.g. from a pre-commit hook checking only staged files).
+\`--type <T>\` narrows the report to one concept type; \`--strict\` treats any
+warning as a failure for the exit code.
+
+It emits the full \`validate.report\` on stdout regardless of outcome, then
+returns exit 6 when any error-tier finding exists (or any warning under
+\`--strict\`) -- the report is the payload, the exit code is the gate signal.`,
+};
+
+/** The detailed, task-scoped topics (everything except `overview`). */
+const DETAIL_TOPICS: readonly InstructionTopic[] = [LINKING, SYNC, CHECK, VALIDATION];
+
+/** Render the `key   title` topic-index lines shared by the overview body and (indirectly) its JSON `topics` field. */
+function topicIndexLines(topics: readonly InstructionTopic[]): string {
+  const width = Math.max(...topics.map((topic) => topic.key.length));
+  return topics.map((topic) => `  ${topic.key.padEnd(width)}  ${topic.title}`).join("\n");
+}
+
+const OVERVIEW: InstructionTopic = {
+  key: "overview",
+  title: "The canonical agent loop and topic index",
+  body: `lore's canonical agent loop: read docs/index.md (the bundle's entry point)
+-> follow a Story concept -> check its coupled tasks' live status (see the
+\`linking\` topic) -> do the work (author prose outside lore-managed regions)
+-> \`lore sync\` to reconcile status and regenerate managed blocks -> \`lore
+check\` as the CI gate (exit 6 on a failing report -- see the \`check\`
+topic).
+
+lore is CLI-first and deterministic: no LLM dependency, so the same inputs
+against an unchanged bundle always produce the same output and exit code.
+Every command supports \`--json\` (the \`{schemaVersion, kind, data}\`
+envelope) and \`--plain\` (ANSI-free text, auto-selected when stdout isn't a
+TTY); branch on the semantic exit code (0 ok, 2 usage, 3 not_found, 4 denied,
+5 conflict, 6 validation/drift) rather than parsing prose.
+
+Topics:
+${topicIndexLines(DETAIL_TOPICS)}
+
+Run \`lore instructions <topic>\` for detail on any of these. Full reference:
+docs/runbooks/agent-onboarding.md.`,
+};
+
+/** Every topic `lore instructions` can serve, `overview` first — the order the topic index/JSON `topics` field lists them in. */
+export const INSTRUCTION_TOPICS: readonly InstructionTopic[] = [OVERVIEW, ...DETAIL_TOPICS];
+
+/** Look up a topic by its exact key (case-sensitive, no fuzzy match), or `undefined` if unknown. */
+export function findInstructionTopic(key: string): InstructionTopic | undefined {
+  return INSTRUCTION_TOPICS.find((topic) => topic.key === key);
+}