@codyswann/lisa 2.116.2 → 2.118.0

package/plugins/src/base/rules/eager/repo-scope-split.md

@@ -0,0 +1,39 @@
+# Repo Scope & Work-Time Splitting (load-bearing)
+
+**Leaf work units are single-repo.** A leaf is an individually implementable ticket with no children — types **Bug, Task, Sub-task, Improvement**. Each names exactly one repo. **Epic, Story, Spike** are coordination containers and may span repos.
+
+Enforced at four points: gate **S10** (`*-validate-*`, write time), `task-decomposition` step 1.5 (PRD-decomposition time), claim-time repo scoping (`*-build-intake`), and the work-time split procedure (an existing ticket about to be implemented).
+
+## Choose the right strategy
+
+- **Decomposition-time (no tickets exist yet):** use `task-decomposition` step 1.5 — one work unit per repo under a parent Story.
+- **Work-time (a ticket already exists):** narrow the original to one repo, spin off a sibling per additional repo, link by dependency. Do NOT invent a new parent — siblings inherit the original's existing parent.
+
+## Work-time split (pre-flight gate, agent-performed)
+
+1. **Detect repos.** Parse description + AC + approach, confirm against actual code surfaces. If single-repo, no split.
+2. **Pick the keeper.** Default: the original keeps the consumer / user-facing repo.
+3. **Create one sibling per extra repo**, cloning metadata (re-prefix summary, scope AC, carry parent, env, sign-in).
+4. **Link by dependency.** Producer **blocks** consumer (`is blocked by` on consumer / `blocks` on producer). No clear direction → `relates to`.
+5. **Narrow the original.** Edit summary prefix, Repository section, AC; remove cross-repo references.
+6. **Comment** on the original noting the split, linking each sibling.
+7. **Re-validate.** Run `tracker-verify` (S10) on the original and every sibling. All must PASS single-repo.
+8. **Proceed in dependency order.** Producer siblings first.
+
+## When to BLOCK instead of split
+
+Fall back to the standard BLOCK + reassign-to-Reporter path when:
+
+- Repos cannot be determined confidently from ticket + code.
+- Splitting would strand stakeholder context only the reporter can re-scope.
+- Required clone metadata (parent, env, credentials) is itself missing.
+
+## Claim-time repo scoping (build-intake)
+
+A tracker can oversee multiple repos. Build-intake claims only current-repo tickets. Resolve current repo per `config-resolution` (config `repo` → `github.repo` → git remote basename). For each ready candidate:
+
+1. **Read `repo:<name>` label.** Wrong repo → skip. Current repo → leaf-only gate + claim. Unlabeled → determine + stamp + re-apply.
+2. **Multi-repo leaf → split, never claim.** Each split sibling is created build-ready and stamped with its own `repo:<name>`.
+3. **Wrong-repo single-repo leaf → skip** (label keeps it cheap next cycle).
+
+Vendor mechanics (JIRA/GitHub/Linear) and full procedure: [reference/repo-scope-split.md](../reference/repo-scope-split.md).

package/plugins/src/base/rules/eager/security-audit-handling.md

@@ -0,0 +1,29 @@
+# Security Audit Handling (load-bearing)
+
+If `git push` fails because the pre-push hook reports security vulnerabilities, follow the rules below. **Never use `--no-verify`** to bypass the security audit.
+
+## Core rule
+
+Override the actually-vulnerable **leaf package**, not its parent. The audit chain shows `parent › intermediate › vulnerable` — only the vulnerable leaf needs the override.
+
+**Never override a parent package to force a lower major version.** Other packages may depend on the newer major; a forced downgrade breaks them.
+
+Before adding any override, verify:
+- You are targeting the actually-vulnerable package, not a parent in the chain.
+- The override is compatible with all dependents (check via `bun why <pkg>` or `npm ls <pkg>`).
+- The override does not downgrade across a major version boundary other deps require.
+
+## Node.js (GHSA)
+
+1. Note GHSA ID, package, advisory URL.
+2. If a patched version exists: add a resolution AND override in `package.json` for the leaf package, regenerate the lockfile, commit, retry.
+3. If no patch but safe (transitive, no untrusted input, dev/build only): add an exclusion to `audit.ignore.local.json` with `{"id", "package", "reason"}`, commit, retry.
+
+## Rails (bundler-audit)
+
+1. Note advisory ID, gem, URL.
+2. If direct dep with patch: update Gemfile constraint, `bundle update <gem>`, commit, retry.
+3. If transitive with patch: `bundle update <gem>` to bump the lockfile only, commit, retry.
+4. If no patch but safe: document the exception, retry.
+
+Full procedure with examples: [reference/security-audit-handling.md](../reference/security-audit-handling.md).

package/plugins/src/base/rules/eager/usage-accounting.md

@@ -0,0 +1,28 @@
+# Usage Accounting (load-bearing)
+
+Lisa attaches AI usage and cost telemetry to every artifact it creates/updates. The format is a single canonical managed section.
+
+## Managed section
+
+Every artifact with inline body content gets exactly one section:
+
+```markdown
+## Lisa Usage
+```
+
+**Canonical. Rewrite in place; never append a second usage section.** If the host can't safely edit body, write the same section in a comment and treat that comment as the managed artifact for future rewrites.
+
+## Required field semantics
+
+Each direct entry records ONE logical Lisa run on ONE artifact. `entry_id` is the stable dedupe key — rewriting the same logical run with the same `entry_id` updates in place; a different run gets a different `entry_id`.
+
+- **`source`**: `observed` (runtime supplied) / `estimated` (derived from trustworthy metadata + pricing contract) / `unavailable`.
+- **`pricing_status`**: same trinary plus `missing` (cost not known but should be).
+- **Absence ≠ zero.** `null` means unknown; `0` means explicitly zero. Always write the entry — never silently omit.
+- Do NOT replace observed counts with estimates.
+
+## Rollup
+
+Container artifacts (Epic, PRD, etc.) roll up usage from their direct children. Roll-up is recursive — a parent's `## Lisa Usage` aggregates its descendants' direct entries. Re-writes are idempotent: re-running an intake or lifecycle skill must not duplicate entries.
+
+Full schema (all 17 fields, pricing semantics, rollup math, idempotent-rewrite rules): [reference/usage-accounting.md](../reference/usage-accounting.md).

package/plugins/src/base/rules/eager/verification.md

@@ -0,0 +1,21 @@
+# Empirical Verification (load-bearing)
+
+**Verification is not linting, typechecking, or testing.** Those are *quality checks* — necessary prerequisites, but NOT verification.
+
+**Verification is using the resulting software the way a user would** — interacting with the UI, calling the API, running the CLI, observing behavior. Tests pass in isolation; verification proves the system works as a whole.
+
+## Mandatory
+
+- **Never claim success without runtime evidence.** "The code looks correct" is not evidence.
+- **If all you did was run tests, typecheck, and lint — you have NOT verified.**
+- **Before starting implementation, state your verification plan** — how you will USE the resulting software to prove it works. A plan that only lists `test`/`typecheck`/`lint` commands is not a plan. Do not begin until confirmed.
+- **After verifying empirically, codify it as a regression test** via the `codify-verification` skill — Playwright for UI, integration test for API/DB/auth, benchmark for performance. Codification is mandatory for every verification type except PR/Documentation/Deploy and Investigate-Only spikes.
+- **Every PR must include reviewer replay steps** — the exact human steps to use the software and confirm the change works. Not test commands. If a reviewer can't reproduce from the PR description alone, the PR is incomplete.
+
+## Roles
+
+- **Builder agent** — implements the change.
+- **Verifier agent** — acts as the end user / API client / operator. Independent from Builder when possible.
+- **Human overseer** — approves risky operations and anything agents cannot fully verify.
+
+Full operational contract (verification types, evidence formats, escalation protocol): [reference/verification.md](../reference/verification.md).

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

@@ -0,0 +1,16 @@
+# 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.
+
+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`).
+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.
+
+Full prose: [reference/wiki-knowledge-source.md](../reference/wiki-knowledge-source.md).

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

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/**
+ * ensure-gitignore.mjs — merge the lisa-wiki gitignore block into the project's
+ * `.gitignore`, idempotently. Dependency-free.
+ *
+ * The block is delimited by `# BEGIN: AI GUARDRAILS WIKI` and
+ * `# END: AI GUARDRAILS WIKI` markers (see templates/wrapper-gitignore.txt).
+ * Behavior matches the base lisa plugin's copy-contents strategy
+ * (src/strategies/copy-contents.ts):
+ *
+ *   - If the file is missing, create it with just the block.
+ *   - If the block markers exist, replace the block in place.
+ *   - If the markers don't exist, append the block to the end (preserving a
+ *     trailing newline).
+ *
+ * Patterns outside the marker block are NEVER touched. Re-running produces no
+ * spurious diff once the file is in sync.
+ *
+ * Usage: node ensure-gitignore.mjs [--cwd <project-dir>] [--dry-run]
+ *   default cwd: process.cwd()
+ *   --dry-run    prints the proposed merge result to stdout instead of writing
+ *
+ * Exit code 0 = ok (file was created, updated, or already in sync).
+ * Exit code 1 = error (e.g. template missing).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const BEGIN_MARKER = "# BEGIN: AI GUARDRAILS WIKI";
+const END_MARKER = "# END: AI GUARDRAILS WIKI";
+
+function fail(msg) {
+  console.error(`✗ ${msg}`);
+  process.exit(1);
+}
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const pluginRoot = path.dirname(scriptDir);
+const templatePath = path.join(
+  pluginRoot,
+  "templates",
+  "wrapper-gitignore.txt"
+);
+
+const argv = process.argv.slice(2);
+const cwdIndex = argv.indexOf("--cwd");
+const projectDir =
+  cwdIndex !== -1 && argv[cwdIndex + 1]
+    ? path.resolve(argv[cwdIndex + 1])
+    : process.cwd();
+const dryRun = argv.includes("--dry-run");
+
+if (!fs.existsSync(templatePath)) {
+  fail(`template not found: ${templatePath}`);
+}
+
+const templateRaw = fs.readFileSync(templatePath, "utf8");
+const block = extractBlock(templateRaw);
+if (!block) {
+  fail(
+    `template at ${templatePath} does not contain the expected marker pair (${BEGIN_MARKER} / ${END_MARKER})`
+  );
+}
+
+const gitignorePath = path.join(projectDir, ".gitignore");
+const existing = fs.existsSync(gitignorePath)
+  ? fs.readFileSync(gitignorePath, "utf8")
+  : null;
+
+const merged = mergeBlock(existing, block);
+
+if (existing !== null && merged === existing) {
+  console.log(`✓ .gitignore already in sync (${gitignorePath})`);
+  process.exit(0);
+}
+
+if (dryRun) {
+  process.stdout.write(merged);
+  process.exit(0);
+}
+
+fs.writeFileSync(gitignorePath, merged);
+const verb = existing === null ? "created" : "updated";
+console.log(`✓ ${verb} ${gitignorePath}`);
+process.exit(0);
+
+/**
+ * Pull the block (markers included) out of arbitrary text. Returns null when
+ * the marker pair is missing or out of order.
+ */
+function extractBlock(text) {
+  const startIdx = text.indexOf(BEGIN_MARKER);
+  if (startIdx === -1) return null;
+  const endStart = text.indexOf(END_MARKER, startIdx + BEGIN_MARKER.length);
+  if (endStart === -1) return null;
+  const endIdx = endStart + END_MARKER.length;
+  return text.slice(startIdx, endIdx);
+}
+
+/**
+ * Merge a freshly-rendered block into the destination file content.
+ *   - existing === null → return the block alone (file will be created)
+ *   - existing has the markers → replace the block in place
+ *   - existing lacks the markers → append the block at the end
+ * Always normalizes to exactly one trailing newline.
+ */
+function mergeBlock(existing, freshBlock) {
+  if (existing === null) {
+    return `${freshBlock.trimEnd()}\n`;
+  }
+
+  const startIdx = existing.indexOf(BEGIN_MARKER);
+  if (startIdx !== -1) {
+    const endStart = existing.indexOf(
+      END_MARKER,
+      startIdx + BEGIN_MARKER.length
+    );
+    if (endStart !== -1) {
+      const endIdx = endStart + END_MARKER.length;
+      const before = existing.slice(0, startIdx);
+      const after = existing.slice(endIdx);
+      const trimmedAfter = after.startsWith("\n") ? after : `\n${after}`;
+      return `${before}${freshBlock.trimEnd()}${trimmedAfter}`;
+    }
+  }
+
+  // No marker pair in the destination — append.
+  const base = existing.endsWith("\n") ? existing : `${existing}\n`;
+  return `${base}\n${freshBlock.trimEnd()}\n`;
+}

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

@@ -30,13 +30,22 @@ never overwrites human-authored content.
 3. **Contract.** Render `wiki/schema/llm-wiki-contract.md` from the plugin templates + config via
    `scripts/render-contract.mjs`, stamping the `kernelVersion`. This snapshot keeps the wiki
    self-describing without the plugin installed.
-4. **Pointers.** Ensure `AGENTS.md` / `CLAUDE.md` point at the contract + plugin (thin pointers only).
-5. **Staff.** For each `config.staff[]` entry (the standard roster by default), generate the role's
+4. **Gitignore.** Merge the lisa-wiki gitignore block into the project's `.gitignore` via
+   `scripts/ensure-gitignore.mjs`. The block (delimited by `# BEGIN: AI GUARDRAILS WIKI` /
+   `# END: AI GUARDRAILS WIKI`) covers transient per-session worktrees and Lisa backup snapshots
+   (`.claude/worktrees/`, `.codex/worktrees/`, `.lisabak/`). Idempotent: re-running produces no
+   diff once the block is present. The block coexists with the base lisa plugin's
+   `# BEGIN: AI GUARDRAILS` block — both can be installed without overwriting each other because
+   the copy-contents strategy keys on the marker suffix. Wiki-wrapper repos (mode `wrapper` /
+   `standalone`) typically don't enable the base lisa plugin, so this step is the only path by
+   which they get the worktree-ignore patterns.
+5. **Pointers.** Ensure `AGENTS.md` / `CLAUDE.md` point at the contract + plugin (thin pointers only).
+6. **Staff.** For each `config.staff[]` entry (the standard roster by default), generate the role's
    `wiki/staff/<role>.md` page and its dual-runtime subagents by delegating to `lisa-wiki-add-role`
    (running the subagents is out of scope).
-6. **README.** Apply the chosen README mode (ingest the old README first; `rich` keeps install/usage +
+7. **README.** Apply the chosen README mode (ingest the old README first; `rich` keeps install/usage +
    adds the onboarding line; `stub` is the minimal pointer; `preserve` leaves it).
-7. **Verify.** Run `lisa-wiki-doctor` and report the verdict + any blocking items.
+8. **Verify.** Run `lisa-wiki-doctor` and report the verdict + any blocking items.
 
 ## Standard roster
 The default operating team seeded into `config.staff[]` for every new wiki (Chief of Staff plus six

package/plugins/src/wiki/templates/wrapper-gitignore.txt

@@ -0,0 +1,19 @@
+# BEGIN: AI GUARDRAILS WIKI
+# Managed by the lisa-wiki kernel. Do not edit between these markers — re-run
+# /lisa-wiki:setup (or the equivalent script) to update. Patterns outside the
+# block are preserved untouched. The "WIKI" suffix lets this block coexist
+# with the base lisa plugin's "# BEGIN: AI GUARDRAILS" block when both are
+# installed (the copy-contents strategy keys on the marker suffix).
+
+# Claude Code per-session git worktrees. Each Claude session that needs an
+# isolated working copy spawns one under .claude/worktrees/ (via
+# `git worktree add`). They are transient, large (often hundreds of MB each),
+# and per-developer; they must never be committed.
+/.claude/worktrees/
+
+# Codex CLI per-session worktrees (Codex equivalent of the above).
+/.codex/worktrees/
+
+# Lisa backup snapshots (created by `lisa` runs).
+/.lisabak/
+# END: AI GUARDRAILS WIKI

package/scripts/check-rules-pairing.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# Fails if any plugin's rules/eager/X.md is missing its rules/reference/X.md
+# pair (or vice versa). The eager/reference split documents the contract that
+# every eager head points at a reference body for the long-form detail; an
+# unpaired file means either a head without a body (broken breadcrumb) or a
+# body without a head (orphaned, never injected).
+#
+# Bootstrap files are exempt: rules/eager/00-bootstrap.md (and any other file
+# matching rules/eager/00-*.md) is allowed to have no reference pair. The
+# leading "00-" prefix marks files that are eager-only by design.
+#
+# Skip rule: a rule may opt out of pairing by listing its basename in
+# rules/.pair-exempt — one filename per line, comments start with `#`. Use
+# sparingly; the default expectation is that every eager file pairs.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+cd "$ROOT_DIR"
+
+failed=0
+
+check_plugin() {
+  local rules_dir="$1"
+  local eager_dir="$rules_dir/eager"
+  local reference_dir="$rules_dir/reference"
+
+  # Skip plugins that haven't adopted the split yet (no eager/ subdir).
+  [ -d "$eager_dir" ] || return 0
+
+  # Build the opt-out list, if present.
+  local exempt_file="$rules_dir/.pair-exempt"
+  local exempt_pattern=""
+  if [ -f "$exempt_file" ]; then
+    exempt_pattern="$(grep -v '^[[:space:]]*#' "$exempt_file" | grep -v '^[[:space:]]*$' || true)"
+  fi
+
+  # Every eager/X.md (except 00-bootstrap-style files and explicit exemptions)
+  # must have a reference/X.md pair.
+  while IFS= read -r eager_file; do
+    local base
+    base="$(basename "$eager_file")"
+    # Built-in exemption for bootstrap files.
+    case "$base" in
+      00-*) continue ;;
+    esac
+    # User-declared exemptions.
+    if [ -n "$exempt_pattern" ] && echo "$exempt_pattern" | grep -qxF "$base"; then
+      continue
+    fi
+    if [ ! -f "$reference_dir/$base" ]; then
+      echo "✗ Missing reference body for eager rule: $eager_file" >&2
+      echo "  Expected: $reference_dir/$base" >&2
+      failed=1
+    fi
+  done < <(find "$eager_dir" -maxdepth 1 -type f -name '*.md' | sort)
+
+  # Every reference/X.md must have an eager/X.md pair (catch orphans on the
+  # other side: a reference body with no breadcrumb pointing to it is dead).
+  if [ -d "$reference_dir" ]; then
+    while IFS= read -r ref_file; do
+      local base
+      base="$(basename "$ref_file")"
+      if [ -n "$exempt_pattern" ] && echo "$exempt_pattern" | grep -qxF "$base"; then
+        continue
+      fi
+      if [ ! -f "$eager_dir/$base" ]; then
+        echo "✗ Orphaned reference body (no eager head): $ref_file" >&2
+        echo "  Expected: $eager_dir/$base" >&2
+        failed=1
+      fi
+    done < <(find "$reference_dir" -maxdepth 1 -type f -name '*.md' | sort)
+  fi
+}
+
+# Check every plugins/*/rules and plugins/src/*/rules directory.
+while IFS= read -r rules_dir; do
+  check_plugin "$rules_dir"
+done < <(find "$ROOT_DIR/plugins" -type d -name rules | sort)
+
+if [ "$failed" -ne 0 ]; then
+  echo "" >&2
+  echo "  Every rules/eager/X.md must have a paired rules/reference/X.md" >&2
+  echo "  (and vice versa) so the eager head's breadcrumb to the full" >&2
+  echo "  reference body resolves. To exempt a file, either name it" >&2
+  echo "  00-*.md (bootstrap convention) or list its basename in" >&2
+  echo "  <plugin>/rules/.pair-exempt (one per line)." >&2
+  exit 1
+fi
+
+echo "✓ Every eager rule has its paired reference body (and vice versa)."