@codyswann/lisa 2.155.7 → 2.157.0

package/plugins/lisa-wiki-cursor/skills/lisa-wiki-query/SKILL.md

@@ -8,7 +8,13 @@ description: Answer a question from the LLM Wiki with citations. Reads the index
 Answer from the wiki, with citations, without changing it (by default).
 
 ## Workflow
-1. Read `wiki/index.md` to locate candidate pages; consult `wiki/start-here.md` for orientation.
+0. **Resolve the wiki root.** Run `node scripts/ensure-wiki.mjs --json` and use the returned
+   `wikiRoot` as the base for every read below — never assume `wiki/`. A local wiki resolves
+   instantly (no-op); a wiki whose `.lisa.config.json` declares `wiki.source.url` is mirrored and
+   refreshed transparently first. The script is offline-tolerant (it proceeds with the existing
+   mirror and warns rather than blocking), so freshness is guaranteed here and the caller never has
+   to think about it.
+1. Read `<wikiRoot>/index.md` to locate candidate pages; consult `<wikiRoot>/start-here.md` for orientation.
 2. Drill into the relevant synthesis pages and their cited source notes.
 3. Synthesize an answer. **Every claim cites its wiki page and/or source note.** If the wiki does not
    support an answer, say so plainly rather than inventing one; suggest an `/ingest` that would fill

package/plugins/src/base/rules/eager/wiki-knowledge-source.md

@@ -1,16 +1,18 @@
 # Wiki as Knowledge Source (load-bearing)
 
-If the project has an LLM Wiki (a `wiki/` directory with `index.md`), treat it as the canonical source of durable project knowledge.
+If the project has an LLM Wiki, treat it as the canonical source of durable project knowledge. A project has a wiki when **either** a local `wiki/` directory with `index.md` exists **or** `.lisa.config.json` declares a `wiki.source` pointer to a remote wiki repo. Documentation rolls UP into that wiki; individual repos are not expected to carry their own prose docs beyond inline code comments.
+
+You never have to fetch or freshness-check the wiki yourself: the query and ingest skills resolve the wiki root and guarantee it exists and is current (via `scripts/ensure-wiki.mjs`) as their own first step — a local wiki resolves instantly, a remote wiki is mirrored/refreshed transparently into a gitignored working copy. Just call the skill.
 
 Before researching background, conventions, ownership, architecture, glossary, or "how/why does X work here":
 
-1. **Consult the wiki first.** Start from `wiki/index.md` or use the wiki query skill (`/lisa-wiki-query`).
+1. **Consult the wiki first.** Use the wiki query skill (`/lisa-wiki-query`), which resolves the wiki root for you; for a local wiki you may also start from `wiki/index.md` directly.
 2. **Use what the wiki says** as the authoritative answer when it covers the question — do not re-derive it from raw sources.
 3. **Fall back to primary sources** (code, tickets, commit history, external docs) only when the wiki is silent, ambiguous, or contradicted by what you observe.
 4. **Surface gaps.** If the wiki is wrong, stale, or missing knowledge that belongs there, flag it — and where the workflow supports it, capture the correction via `/lisa-wiki-ingest`.
 
 The wiki documents knowledge; it does NOT override executable behavior. When wiki and running code disagree about what the system does, trust the code and treat the wiki as out of date.
 
-If the project has no `wiki/`, this rule does not apply.
+If the project has neither a local `wiki/` nor a `wiki.source` pointer, this rule does not apply.
 
 Full prose: [reference/wiki-knowledge-source.md](../reference/wiki-knowledge-source.md).

package/plugins/src/base/rules/reference/config-resolution.md

@@ -167,6 +167,38 @@ fi
 | `tracker` | **yes** | — | Destination for ticket writes. One of `"jira"`, `"github"`, `"linear"`. Missing → fail with instruction to run the matching `/lisa:setup:*` skill. |
 | `source` | no | — | Default PRD source for batch skills (`/lisa:intake`) and arg-less single-PRD skills. One of `"notion"`, `"confluence"`, `"linear"`, `"github"`, `"jira"`. Explicit URLs/keys passed to a skill always win over `source`; this is a default, not a lock. |
 | `usage` | no | — | Optional token/cost pricing metadata consumed by the `usage-accounting` rule. Missing pricing never blocks a lifecycle flow; Lisa records token counts with `estimated_cost: null` when no trustworthy price source is configured. |
+| `wiki` | no | — | Wiki location for the `wiki-knowledge-source` rule. Omit for a local in-repo wiki (`wiki/`). See **Wiki source** below. |
+
+### Wiki source (`wiki`)
+
+Declares **where this repo's LLM Wiki lives** so the query/ingest skills can resolve and (for a remote wiki) mirror it. `wiki.source` has two shapes — **local** (`path`) and **remote** (`url`) — and the block belongs in the **consumer** repo's `.lisa.config.json`, not in `wiki/lisa-wiki.config.json` (which describes a wiki from the inside and is unavailable until a remote wiki is mirrored — chicken-and-egg). The whole `wiki` block is optional; omit it and the resolver falls back to the in-repo `wiki/` convention.
+
+```json
+// local: an explicit path (optional — equivalent to the default convention)
+"wiki": { "source": { "path": "wiki" } }
+
+// remote: mirror a separate wiki repo
+"wiki": {
+  "source": {
+    "url": "git@github.com:org/wiki.git",
+    "ref": "main",
+    "mirrorPath": ".lisa/wiki",
+    "subdir": "wiki"
+  },
+  "ttlSeconds": 300
+}
+```
+
+| Field | Required | Default | Notes |
+|-------|----------|---------|-------|
+| `wiki.source.path` | no | `wiki` (via convention) | **Local** wiki root, relative to the repo. The explicit form of the in-repo default. Mutually exclusive with `url`. |
+| `wiki.source.url` | no | — | Clone URL of a separate wiki repo. **Its presence selects REMOTE mode.** Mutually exclusive with `path`. |
+| `wiki.source.ref` | no | remote HEAD | Branch/ref to mirror (remote only). |
+| `wiki.source.mirrorPath` | no | `.lisa/wiki` | Where the gitignored mirror is materialized (remote only). `ensure-wiki` keeps this path gitignored automatically. |
+| `wiki.source.subdir` | no | auto | Wiki root within the cloned repo (remote only). Auto-detected as `wiki/` if present, else the repo root. |
+| `wiki.ttlSeconds` | no | `300` | Skip the refresh fetch if the mirror was synced more recently than this (remote only). |
+
+`scripts/ensure-wiki.mjs` is the single resolver (`node scripts/ensure-wiki.mjs --json` → `{mode, wikiRoot, …}`). **LOCAL** mode (no `url`) is a no-op that resolves the wiki root in precedence order `wiki.source.path` → `wikiRoot` in `wiki/lisa-wiki.config.json` → `wiki`; **REMOTE** mode (`url` set) clones-if-missing, fast-forwards when stale, and is offline-tolerant (proceeds with the existing mirror and warns rather than blocking). Callers (`lisa-wiki-query`, `lisa-wiki-ingest`) invoke it as step 0 and never hardcode `wiki/`; the freshness guarantee is the tool's, not the caller's.
 
 ### Vendor sections
 

package/plugins/src/base/rules/reference/wiki-knowledge-source.md

@@ -1,14 +1,21 @@
 # Wiki as Knowledge Source
 
-If this project has an LLM Wiki (a `wiki/` directory with an `index.md`), treat it as the canonical source of durable project knowledge. The wiki is curated and current; ad-hoc scraping of code, tickets, chat history, or stale READMEs is not.
+If this project has an LLM Wiki, treat it as the canonical source of durable project knowledge. The wiki is curated and current; ad-hoc scraping of code, tickets, chat history, or stale READMEs is not.
+
+A project has a wiki in one of two shapes:
+
+- **Local** — a `wiki/` directory with an `index.md` lives in this repo (`wikiRoot` in `wiki/lisa-wiki.config.json`, default `wiki`).
+- **Remote** — `.lisa.config.json` declares a `wiki.source` pointer (`url`, optional `ref` / `mirrorPath` / `subdir`) at the canonical wiki repo. The wiki is **not** committed into this repo; instead the query/ingest skills maintain a gitignored mirror of it. This is the model for an organization whose documentation rolls up into one shared wiki that every repo reads: each repo carries only inline code comments locally, and the full cross-repo knowledge is the mirrored wiki.
+
+Either way, freshness is not your concern. The query and ingest skills run `scripts/ensure-wiki.mjs` as their own first step, which resolves the wiki root and — for a remote wiki — clones the mirror if missing and fast-forwards it when stale (subject to a short TTL, and tolerant of being offline: it proceeds with the existing mirror and warns rather than blocking). The freshness guarantee lives in the tool, not in the caller's discipline. Do **not** add a separate "make sure the wiki is current" step to your own workflow — calling the skill already does it.
 
 Before researching project background, conventions, ownership, architecture, glossary terms, or "how/why does X work here":
 
-1. Consult the wiki first. Start from `wiki/index.md` and follow links, or use the wiki query skill (`/lisa-wiki-query`, or the runtime's wiki query skill) to find the relevant page.
+1. Consult the wiki first via the wiki query skill (`/lisa-wiki-query`, or the runtime's wiki query skill), which resolves the wiki root for you. For a local wiki you may also start from `wiki/index.md` and follow links.
 2. Use what the wiki says as the authoritative answer when it covers the question. Do not re-derive it from raw sources when the wiki already documents it.
 3. Fall back to primary sources (code, tickets, commit history, external docs) only when the wiki is silent, ambiguous, or contradicted by what you observe in the code.
 4. If you find the wiki is wrong, stale, or missing knowledge that belongs there, surface the gap — and where the project's workflow supports it, capture the correction back into the wiki via its ingestion path (`/lisa-wiki-ingest` or equivalent) rather than leaving the knowledge only in this session.
 
 The wiki documents knowledge; it does not override executable behavior. When the wiki and the running code disagree about what the system actually does, trust the code and treat the wiki as out of date. See the `documentation-source-paths` rule for how source-material directories relate to the wiki.
 
-If the project has no `wiki/`, this rule does not apply.
+If the project has neither a local `wiki/` nor a `wiki.source` pointer in `.lisa.config.json`, this rule does not apply.

package/plugins/src/wiki/scripts/ensure-wiki.mjs

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+/**
+ * ensure-wiki.mjs — resolve the project's wiki root, mirroring/refreshing a
+ * remote wiki when one is configured. Dependency-free (Node built-ins only),
+ * so it stays portable to any downstream repo that installs the plugin.
+ *
+ * This is the single resolver that `lisa-wiki-query` and `lisa-wiki-ingest`
+ * call as step 0 so they never hardcode `wiki/` and never have to know whether
+ * the wiki is local or remote. The mode decision lives HERE, not in the skills:
+ *
+ *   - LOCAL  — the wiki lives on the local filesystem (the common case). Resolve
+ *              the wiki root, in precedence order, from `wiki.source.path`, else
+ *              `wikiRoot` in `wiki/lisa-wiki.config.json`, else `wiki`. No
+ *              network, a no-op. `wiki.source.path` is just the explicit form of
+ *              what the convention resolves implicitly.
+ *   - REMOTE — `.lisa.config.json` declares `wiki.source.url`. Maintain a
+ *              gitignored mirror of that repo and return the wiki root inside
+ *              it. Clone-if-missing, fetch+fast-forward when stale (TTL), and
+ *              tolerate being offline (proceed with the existing mirror + warn).
+ *
+ * `url` (remote) and `path` (local) are the two shapes of `wiki.source`; `url`
+ * takes precedence if both are somehow present.
+ *
+ * Config (consumer repo `.lisa.config.json`, with `.lisa.config.local.json`
+ * overriding per the config-resolution rule):
+ *
+ *   "wiki": {
+ *     "source": {
+ *       // LOCAL shape — optional; defaults to the in-repo `wiki/` convention:
+ *       "path":       "wiki",            // local wiki root, relative to repo root
+ *       // REMOTE shape (instead of path):
+ *       "url":        "git@github.com:org/wiki.git",  // present => REMOTE mode
+ *       "ref":        "main",            // default: remote HEAD / "main"
+ *       "mirrorPath": ".lisa/wiki",      // default; always gitignored
+ *       "subdir":     "wiki"             // optional: wiki root within the repo
+ *     },
+ *     "ttlSeconds": 300                  // skip the fetch if synced more recently
+ *   }
+ *
+ * Usage: node ensure-wiki.mjs [--cwd <dir>] [--json] [--ttl <seconds>] [--offline]
+ *   --cwd      project dir to resolve config/mirror against (default cwd)
+ *   --json     emit {mode, wikiRoot, mirrored, fetched, stale, offline} on stdout
+ *   --ttl      override ttlSeconds (0 = always fetch)
+ *   --offline  never touch the network; use whatever is already on disk
+ *
+ * Output: the resolved absolute wiki root is the LAST line on stdout (so a
+ * caller can `WIKI_ROOT=$(node ensure-wiki.mjs | tail -1)`). All human-facing
+ * progress goes to stderr. Exit 0 = a usable wiki root was resolved; 1 = not.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+const GITIGNORE_BEGIN = "# BEGIN: AI GUARDRAILS WIKI MIRROR";
+const GITIGNORE_END = "# END: AI GUARDRAILS WIKI MIRROR";
+const DEFAULT_MIRROR = ".lisa/wiki";
+const DEFAULT_TTL_SECONDS = 300;
+
+function log(msg) {
+  process.stderr.write(`${msg}\n`);
+}
+function fail(msg) {
+  log(`✗ ${msg}`);
+  process.exit(1);
+}
+function readJsonSafe(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+function git(args, cwd) {
+  return execFileSync("git", args, {
+    cwd,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf8",
+  }).trim();
+}
+
+// ── args ────────────────────────────────────────────────────────────────────
+const argv = process.argv.slice(2);
+function flagValue(name) {
+  const i = argv.indexOf(name);
+  return i !== -1 && argv[i + 1] ? argv[i + 1] : undefined;
+}
+const projectDir = path.resolve(flagValue("--cwd") ?? process.cwd());
+const asJson = argv.includes("--json");
+const offline = argv.includes("--offline");
+const ttlOverride = flagValue("--ttl");
+
+// ── resolve the wiki source from .lisa.config.json (+ .local override) ────────
+const committed =
+  readJsonSafe(path.join(projectDir, ".lisa.config.json")) ?? {};
+const local =
+  readJsonSafe(path.join(projectDir, ".lisa.config.local.json")) ?? {};
+const wikiCfg = { ...(committed.wiki ?? {}), ...(local.wiki ?? {}) };
+const source = {
+  ...(committed.wiki?.source ?? {}),
+  ...(local.wiki?.source ?? {}),
+};
+const ttlSeconds = Number(
+  ttlOverride ?? wikiCfg.ttlSeconds ?? DEFAULT_TTL_SECONDS
+);
+
+if (source.url !== undefined && typeof source.url !== "string") {
+  fail("`wiki.source.url` in .lisa.config.json must be a string");
+}
+if (source.path !== undefined && typeof source.path !== "string") {
+  fail("`wiki.source.path` in .lisa.config.json must be a string");
+}
+
+function emit(result) {
+  if (asJson) process.stdout.write(`${JSON.stringify(result)}\n`);
+  else process.stdout.write(`${result.wikiRoot}\n`);
+  process.exit(0);
+}
+
+// ── LOCAL mode (no remote clone) ───────────────────────────────────────────────
+// The wiki lives on the local filesystem. Its root is, in precedence order:
+//   1. `wiki.source.path` — explicit override in .lisa.config.json
+//   2. `wikiRoot` from wiki/lisa-wiki.config.json — the in-repo convention
+//   3. `wiki` — the default
+// No network, a no-op resolve. `wiki.source.path` is just the explicit form of
+// the same thing the convention resolves implicitly.
+if (!source.url) {
+  const wikiRoot = path.resolve(
+    projectDir,
+    source.path ??
+      readJsonSafe(path.join(projectDir, "wiki", "lisa-wiki.config.json"))
+        ?.wikiRoot ??
+      "wiki"
+  );
+  if (!fs.existsSync(path.join(wikiRoot, "index.md"))) {
+    log(
+      `⚠ no index.md under ${wikiRoot} — check wiki.source.path, or run /lisa-wiki:setup if the wiki is not scaffolded yet`
+    );
+  }
+  log(`✓ local wiki: ${wikiRoot}`);
+  emit({
+    mode: "local",
+    wikiRoot,
+    mirrored: false,
+    fetched: false,
+    stale: false,
+    offline,
+  });
+}
+
+// ── REMOTE mode ───────────────────────────────────────────────────────────────
+const mirrorPath = path.resolve(
+  projectDir,
+  source.mirrorPath ?? DEFAULT_MIRROR
+);
+const ref = source.ref || "";
+ensureGitignored(projectDir, source.mirrorPath ?? DEFAULT_MIRROR);
+
+const isClone = fs.existsSync(path.join(mirrorPath, ".git"));
+let fetched = false;
+let stale = false;
+
+if (!isClone) {
+  if (offline) fail(`offline and no mirror present at ${mirrorPath}`);
+  log(`↧ cloning wiki ${source.url} → ${mirrorPath}`);
+  try {
+    fs.mkdirSync(path.dirname(mirrorPath), { recursive: true });
+    const cloneArgs = ["clone", "--depth", "1"];
+    if (ref) cloneArgs.push("--branch", ref);
+    cloneArgs.push(source.url, mirrorPath);
+    git(cloneArgs, projectDir);
+    fetched = true;
+    stampSync(mirrorPath);
+  } catch (e) {
+    fail(`clone failed: ${String(e.message ?? e).split("\n")[0]}`);
+  }
+} else if (offline) {
+  log("• offline — using existing mirror without fetching");
+  stale = true;
+} else if (isFresh(mirrorPath, ttlSeconds)) {
+  log(`• mirror synced < ${ttlSeconds}s ago — skipping fetch`);
+} else {
+  // Stale: fetch and hard-reset. The mirror is a read-only working copy of the
+  // canonical wiki — never edited in place — so resetting to the remote ref is
+  // safe and keeps it byte-identical to upstream.
+  try {
+    const branch =
+      ref || git(["rev-parse", "--abbrev-ref", "HEAD"], mirrorPath);
+    log(`↻ refreshing wiki mirror (${branch})`);
+    git(["fetch", "--depth", "1", "origin", branch], mirrorPath);
+    git(["reset", "--hard", `origin/${branch}`], mirrorPath);
+    fetched = true;
+    stampSync(mirrorPath);
+  } catch (e) {
+    // Offline-tolerant: a fetch failure must not block work when we already
+    // have a usable (if stale) copy on disk.
+    log(
+      `⚠ refresh failed (${String(e.message ?? e).split("\n")[0]}) — using stale mirror`
+    );
+    stale = true;
+  }
+}
+
+const wikiRoot = resolveWikiRootInMirror(mirrorPath, source.subdir);
+if (!fs.existsSync(path.join(wikiRoot, "index.md"))) {
+  log(
+    `⚠ no index.md under ${wikiRoot} — check wiki.source.subdir / the wiki repo layout`
+  );
+}
+log(`✓ remote wiki mirror: ${wikiRoot}`);
+emit({ mode: "remote", wikiRoot, mirrored: true, fetched, stale, offline });
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+/** Locate the wiki content root inside a cloned wiki repo. */
+function resolveWikiRootInMirror(mirror, subdir) {
+  if (subdir) return path.resolve(mirror, subdir);
+  if (fs.existsSync(path.join(mirror, "wiki", "index.md")))
+    return path.join(mirror, "wiki");
+  return mirror; // dedicated wiki repo with content at its root
+}
+
+/** TTL stamp lives under .git so it is never part of the wiki content. */
+function stampPath(mirror) {
+  return path.join(mirror, ".git", "lisa-wiki-sync");
+}
+function stampSync(mirror) {
+  try {
+    fs.writeFileSync(stampPath(mirror), String(Date.now()));
+  } catch {
+    /* best-effort */
+  }
+}
+function isFresh(mirror, ttl) {
+  if (ttl <= 0) return false;
+  let last = NaN;
+  try {
+    last = Number(fs.readFileSync(stampPath(mirror), "utf8"));
+  } catch {
+    return false;
+  }
+  if (!Number.isFinite(last)) return false;
+  return Date.now() - last < ttl * 1000;
+}
+
+/** Idempotently keep the mirror path out of version control. */
+function ensureGitignored(dir, relPath) {
+  const gitignorePath = path.join(dir, ".gitignore");
+  const line = `/${relPath.replace(/^\/+/, "").replace(/\/+$/, "")}/`;
+  const block = `${GITIGNORE_BEGIN}\n# Remote wiki mirror — gitignored working copy, managed by ensure-wiki.\n${line}\n${GITIGNORE_END}`;
+  const existing = fs.existsSync(gitignorePath)
+    ? fs.readFileSync(gitignorePath, "utf8")
+    : null;
+  if (existing && existing.includes(line)) return; // already ignored (any block)
+  const start = existing?.indexOf(GITIGNORE_BEGIN) ?? -1;
+  let merged;
+  if (existing === null) {
+    merged = `${block}\n`;
+  } else if (start !== -1) {
+    const end = existing.indexOf(GITIGNORE_END, start) + GITIGNORE_END.length;
+    merged = `${existing.slice(0, start)}${block}${existing.slice(end)}`;
+  } else {
+    const base = existing.endsWith("\n") ? existing : `${existing}\n`;
+    merged = `${base}\n${block}\n`;
+  }
+  fs.writeFileSync(gitignorePath, merged);
+  log(`✓ ensured ${line} is gitignored`);
+}

package/plugins/src/wiki/skills/lisa-wiki-ingest/SKILL.md

@@ -19,10 +19,23 @@ performs the shared, ordered pipeline.
   run includes explicit external-write intent**.
 - **Dry run:** `/ingest --dry-run` — list the sources a full ingest would run; perform no writes.
 
+## Step 0 — resolve the wiki root (once per run)
+
+Before anything else, run `node scripts/ensure-wiki.mjs --json` and use the returned `wikiRoot` as the
+base for the whole pipeline — never hardcode `wiki/`. This is mode-agnostic by design:
+
+- **Local wiki** (no `wiki.source` in `.lisa.config.json`) — resolves the in-repo wiki root instantly;
+  the branch sync below proceeds against **this** repo's remote, exactly as before.
+- **Remote wiki** (`wiki.source.url` set) — `ensure-wiki` mirrors/refreshes the gitignored working copy
+  of the canonical wiki repo and returns its path. In this mode the "sync the branch" step below, and
+  the Commit/PR step (7), operate against the **wiki repo's own remote** (the mirror), not the host
+  project's `origin`. The host project repo is never written to.
+
 ## Before ingesting — sync the branch (once per run)
 
 Run this **once per ingest invocation, before any source is processed** (skip for `--dry-run`, which
-writes nothing). The point is to ingest on top of fresh state, never stale state.
+writes nothing). The point is to ingest on top of fresh state, never stale state. Operate in the wiki
+root resolved in Step 0 — the host repo for a local wiki, the mirror for a remote one.
 
 1. **Resolve the default remote branch** — `gh repo view --json defaultBranchRef -q .defaultBranchRef.name`,
    or `git remote show origin | sed -n 's/.*HEAD branch: //p'`, or the `origin/HEAD` symbolic ref. If

package/plugins/src/wiki/skills/lisa-wiki-query/SKILL.md

@@ -8,7 +8,13 @@ description: Answer a question from the LLM Wiki with citations. Reads the index
 Answer from the wiki, with citations, without changing it (by default).
 
 ## Workflow
-1. Read `wiki/index.md` to locate candidate pages; consult `wiki/start-here.md` for orientation.
+0. **Resolve the wiki root.** Run `node scripts/ensure-wiki.mjs --json` and use the returned
+   `wikiRoot` as the base for every read below — never assume `wiki/`. A local wiki resolves
+   instantly (no-op); a wiki whose `.lisa.config.json` declares `wiki.source.url` is mirrored and
+   refreshed transparently first. The script is offline-tolerant (it proceeds with the existing
+   mirror and warns rather than blocking), so freshness is guaranteed here and the caller never has
+   to think about it.
+1. Read `<wikiRoot>/index.md` to locate candidate pages; consult `<wikiRoot>/start-here.md` for orientation.
 2. Drill into the relevant synthesis pages and their cited source notes.
 3. Synthesize an answer. **Every claim cites its wiki page and/or source note.** If the wiki does not
    support an answer, say so plainly rather than inventing one; suggest an `/ingest` that would fill