@codyswann/lisa 2.116.1 → 2.117.0

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/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)."