@codyswann/lisa 4.35.4 → 4.36.0

package/plugins/lisa-wiki/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "4.35.4",
+  "version": "4.36.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "4.35.4",
+  "version": "4.36.0",
   "description": "Distributable LLM Wiki kernel — ingest, query, lint, and maintain a git-native markdown knowledge base across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "4.35.4",
+  "version": "4.36.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "4.35.4",
+  "version": "4.36.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "4.35.4",
+  "version": "4.36.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/src/base/rules/reference/measurement-integrity.md

@@ -33,6 +33,16 @@ An entire corpus sits outside the query's scope and nothing says so. `gh search
 
 **Catch it:** validate the detector against known-true items before believing any count.
 
+#### A second domain, which is what makes this a category rather than a quirk
+
+The same mode, on a filesystem rather than a tracker. A survey of agent worktrees enumerating `.claude/worktrees/` and `.worktrees/` returns a well-formed list — and omits every worktree created outside the repository tree, under the per-user temporary directory. Four such worktrees existed, three of them with uncommitted changes; none appeared.
+
+Run it through the membership test and it qualifies on all three counts: the list is **well formed** (no error, no warning, no partial marker); the omission is **invisible from the list itself**, which looks exactly like a complete survey of a machine with fewer worktrees on it; and **a mechanical step would have caught it** — the same one A1 already prescribes, validating the enumeration against a worktree you know exists.
+
+This example is here rather than folded into the paragraph above because **a second domain tests whether the category is real or just a description of one tool's behaviour.** A mode observed only through `gh search` could be a fact about GitHub's search semantics; the same shape in a `find` over directories says the failure belongs to *enumeration with an unstated boundary*, whichever substrate is enumerating. When extending this document, a new domain for an existing mode is worth as much as a new mode.
+
+**The consequence in that instance was not academic.** Uncommitted work outside the repository tree is invisible to every query anyone would run before deciding what to clean up, and looks identical to abandoned scratch — so a survey feeding a deletion decision under-reports precisely the thing that must not be deleted. See the worktree-and-binding hazards for the separate question of a mitigation whose cost is invisibility; the measurement half is this mode.
+
 ### A2. Truncation — under, enumeration
 
 Real members past the first page are dropped with no truncation signal. `gh issue list` and `gh pr list` default to 30 and cap silently at whatever `--limit` is passed: one audit reported **37 items where the answer was 513**, a 14× undercount. A paging API returning **249 of 845 rows with `hasNextPage: false`** is the same mode on another substrate.

package/plugins/src/base/skills/lisa-jsdoc-best-practices/SKILL.md

@@ -348,7 +348,66 @@ In `@example` blocks, use fenced code blocks and escape `@` as `\@`:
  */
 ```
 
-### Quick Reference for Escaping
+### Path Examples Must Not Contain the Block Terminator
+
+A path written as an example inside a doc comment **ends the comment** if it
+contains `*/` — a glob such as `sandbox-*/`, or any real directory whose
+name ends in an asterisk. Everything below that point is then parsed as source:
+path segments become identifiers, and the separator between them becomes
+division.
+
+**Write the wildcard as a placeholder, not a glob:**
+
+```typescript
+// WRONG — the comment ends inside the path, mid-line
+/**
+ * Debris lands at `.stryker-tmp/bite-guard-intact/sandbox-*/rails/scripts/foo.sh`
+ * and this line is no longer a comment.
+ */
+
+// RIGHT — a placeholder cannot terminate the block
+/**
+ * Debris lands at `.stryker-tmp/bite-guard-intact/sandbox-<id>/rails/scripts/foo.sh`
+ * and this line is still a comment.
+ */
+```
+
+`<id>`, `<name>`, `<n>` — the same placeholder convention used everywhere else
+in Lisa's docs. Escaping (`*\/`) also works but produces an example nobody can
+copy and paste, which defeats the point of writing one.
+
+### What it looks like when you get it wrong
+
+The build goes red immediately — `bun run typecheck`, `bun run lint` and the
+test run all fail — but **none of them mentions a comment**, and every line
+they report sits *below* the real cause. Measured, with the true cause on
+line 89:
+
+```text
+src/configs/repo-scan.ts(90,9):  error TS1005: ';' expected.
+src/configs/repo-scan.ts(90,20): error TS1443: Module declaration names may only use ' or " quoted strings.
+src/configs/repo-scan.ts(94,1):  error TS1160: Unterminated template literal.
+```
+
+Errors naming identifiers you never wrote — `Cannot find name 'mutation'`,
+`Cannot find name 'src'` — are the giveaway: those are backtick contents from
+inside the comment, now being read as code. **Look upward for a doc comment
+before looking for a missing import.**
+
+Lisa's gate runner says this for you. When a gate fails, it scans the files the
+failure named and reports the closed comment by name:
+
+```text
+a doc comment in src/configs/repo-scan.ts ends early, on line 89 — every error
+reported below that line is downstream of it, not a fault of its own
+  ↳ src/configs/repo-scan.ts:89 — the block opened on line 87 ends at the
+    terminator INSIDE this line, not on line 92
+```
+
+It is a text scan rather than a lint rule on purpose: the file does not parse,
+so ESLint reports `Parsing error` and runs zero rules on it.
+
+## Quick Reference for Escaping
 
 | Context | Approach | Example |
 |---------|----------|---------|

package/scripts/check-third-party-action-pins.mjs

@@ -69,16 +69,41 @@
  *   - the file list comes from `git ls-files`, so the gate sees exactly what a
  *     release would carry.
  *
+ * ## `--warn`: how this arrives in a consumer without breaking it
+ *
+ * This file also ships to consumers through `all/copy-overwrite/scripts/`,
+ * which — unlike `create-only` — reaches every repository that already exists,
+ * on its next update. That reach is exactly why it must not arrive blocking.
+ *
+ * A consumer's seeded workflows carry mutable refs *today*: that is the defect
+ * #3588 exists to migrate away. A detector that hard-failed on arrival would
+ * redden the entire installed base at once, for a condition those repositories
+ * did not introduce and could not have fixed yet, since the migration that
+ * fixes it lands in the same update. That is not hypothetical — a guard added
+ * to a workflow consumed at `@main` failed closed on a pre-existing consumer
+ * misconfiguration and took four repositories' releases down for five hours;
+ * the repair was to keep it loud and stop it blocking (#3755, #3757).
+ *
+ * So `--warn` reports every finding and exits 0, and the shipped consumer
+ * script entry uses it. Tightening to blocking is a separate, deliberate
+ * decision for once the installed base has had a chance to migrate — one flag
+ * on one line — not something to "finish" while consumers are still mutable.
+ *
+ * `--warn` also softens the empty-scan usage error, because a consumer with no
+ * workflow files is an ordinary shape rather than a broken invocation. A
+ * misspelled flag stays a hard error in every mode: that one is the caller's.
+ *
  * CLI:
- *   node scripts/check-third-party-action-pins.mjs [--root <dir>] [--json]
+ *   node scripts/check-third-party-action-pins.mjs [--root <dir>] [--json] [--warn]
  *
  * Exit codes (mirroring the sibling gates in this directory):
- *   0 — every third-party reference is a 40-hex SHA carrying a version comment.
+ *   0 — every third-party reference is a 40-hex SHA carrying a version comment;
+ *       or `--warn` was passed and the findings are being reported, not enforced.
  *   1 — >=1 reference is mutable, or pinned without a version comment.
  *   2 — operational/usage error: unknown flag, a flag missing its value,
  *       `--root` absent or not a git repository, git unavailable, or zero
  *       workflow files discovered. Finding nothing to check is a broken
- *       invocation, not conformance.
+ *       invocation, not conformance — except under `--warn`, see above.
  *
  * @module scripts/check-third-party-action-pins
  */
@@ -134,14 +159,60 @@ const NO_VERSION = "missing-version-comment";
  * a trailing `# v1.2.3` can be read. Local (`./path`) and container
  * (`docker://`) references have no owner and never match.
  */
-const USES_RE =
-  /^\s*(?:-\s*)?uses:\s*(?<owner>[A-Za-z0-9][A-Za-z0-9-]*)\/(?<rest>[A-Za-z0-9_.][A-Za-z0-9_./-]*)@(?<ref>[^\s"'#]+)(?<trailer>.*)$/;
+const USES_RE = /^[ \t]*(?:-[ \t]*)?uses:[ \t]*(?<value>[^\s"'#]+)/;
+
+/** A well-formed action owner. Anchored, so matching is linear. */
+const OWNER_RE = /^[A-Za-z0-9][A-Za-z0-9-]*$/;
+
+/** A well-formed action path below the owner. Anchored, so linear. */
+const ACTION_PATH_RE = /^[A-Za-z0-9_.][A-Za-z0-9_./-]*$/;
+
+/**
+ * Split a `uses:` value into owner, action path, and ref.
+ *
+ * The shape is validated with anchored parts rather than described as one
+ * pattern. Spelling `owner/repo/path@ref` as adjacent character classes gives
+ * the engine several ways to divide the same text, which is super-linear on a
+ * long line; splitting first and validating each piece has one.
+ *
+ * @param {string} value - the raw value of a `uses:` line.
+ * @returns {{ owner: string, rest: string, ref: string } | null} parts, or null
+ *   when this is not an `owner/repo@ref` reference (a local `./path` or a
+ *   `docker://` image never is).
+ */
+function parseUsesValue(value) {
+  const at = value.lastIndexOf("@");
+  if (at <= 0) return null;
+  const action = value.slice(0, at);
+  const ref = value.slice(at + 1);
+  const slash = action.indexOf("/");
+  if (ref === "" || slash <= 0 || action.includes("://")) return null;
+  const owner = action.slice(0, slash);
+  const rest = action.slice(slash + 1);
+  if (!OWNER_RE.test(owner) || !ACTION_PATH_RE.test(rest)) return null;
+  return { owner, rest, ref };
+}
 
 /** A full commit SHA. Abbreviated SHAs are ambiguous and do not count. */
 const FULL_SHA_RE = /^[0-9a-f]{40}$/;
 
-/** A trailing `# <version>` comment with at least one non-space character. */
-const VERSION_COMMENT_RE = /#\s*(?<version>\S.*?)\s*$/;
+/**
+ * Read the version out of a line's trailing `# ...` comment.
+ *
+ * Deliberately not a regex. Every spelling of "text after a hash to end of
+ * line" is either a backtracking shape or an unanchored `.*$` the engine
+ * retries from each position, and neither is worth it for a one-character
+ * search.
+ *
+ * @param {string} trailer - everything on the line after the `uses:` value.
+ * @returns {string | null} the comment text, or null when there is none.
+ */
+function versionComment(trailer) {
+  const hash = trailer.indexOf("#");
+  if (hash < 0) return null;
+  const version = trailer.slice(hash + 1).trim();
+  return version === "" ? null : version;
+}
 
 /** Max bytes of `git ls-files` output (7k+ tracked paths is ~0.3 MB today). */
 const MAX_GIT_OUTPUT_BYTES = 64 * 1024 * 1024;
@@ -182,15 +253,19 @@ export function findActionRefs(content) {
   for (let index = 0; index < lines.length; index++) {
     const match = USES_RE.exec(lines[index]);
     if (match === null) continue;
-    const { owner, ref, rest, trailer } = match.groups;
-    const comment = VERSION_COMMENT_RE.exec(trailer);
+    const parsed = parseUsesValue(match.groups.value);
+    if (parsed === null) continue;
+    const { owner, ref, rest } = parsed;
     refs.push({
       action: `${owner}/${rest}`,
       kind: classifyOwner(owner),
       line: index + 1,
       owner,
       ref,
-      version: comment === null ? null : comment.groups.version,
+      // The rest of the line is sliced rather than captured: a trailing `.*`
+      // after the value's character class gives the engine two ways to divide
+      // the same text, which is the super-linear shape.
+      version: versionComment(lines[index].slice(match[0].length)),
     });
   }
   return refs;
@@ -350,10 +425,13 @@ function humanReport(report) {
 export function parseArgs(argv) {
   let root = null;
   let json = false;
+  let warn = false;
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "--json") {
       json = true;
+    } else if (arg === "--warn") {
+      warn = true;
     } else if (arg === "--root") {
       const next = argv[i + 1];
       if (next === undefined || next.startsWith("--")) {
@@ -365,7 +443,7 @@ export function parseArgs(argv) {
       throw new UsageError(`unknown argument: ${arg}`);
     }
   }
-  return { json, root: path.resolve(root ?? REPO_ROOT) };
+  return { json, warn, root: path.resolve(root ?? REPO_ROOT) };
 }
 
 /**
@@ -406,14 +484,22 @@ export function main(argv, io = {}) {
   const out = io.stdout ?? process.stdout;
   const err = io.stderr ?? process.stderr;
   let opts;
-  let scan;
   try {
     opts = parseArgs(argv);
-    scan = collectWorkflows(opts.root);
   } catch (error) {
+    // A misspelled flag is the caller's mistake and stays loud in every mode.
     err.write(`error: ${error.message}\n`);
     return 2;
   }
+  let scan;
+  try {
+    scan = collectWorkflows(opts.root);
+  } catch (error) {
+    // Under --warn this is a repository with nothing to scan, which for a
+    // consumer is an ordinary shape rather than a broken invocation.
+    err.write(`error: ${error.message}\n`);
+    return opts.warn ? 0 : 2;
+  }
 
   let checked = 0;
   let thirdParty = 0;
@@ -445,7 +531,18 @@ export function main(argv, io = {}) {
   out.write(
     `${opts.json ? JSON.stringify(report, null, 2) : humanReport(report)}\n`
   );
-  return report.findings.length === 0 ? 0 : 1;
+  if (report.findings.length === 0) {
+    return 0;
+  }
+  if (opts.warn) {
+    out.write(
+      "\nReporting only: this check is not blocking here. Nothing above stops " +
+        "a build.\nRun `npx @codyswann/lisa@latest .` to pin these " +
+        "references, then re-run.\n"
+    );
+    return 0;
+  }
+  return 1;
 }
 
 if (invokedAsScript(import.meta.url)) {

package/scripts/two-channel-couplings.json

@@ -7,7 +7,7 @@
     "workflows": 22,
     "steps": 716,
     "couplings": 34,
-    "inventory": 71
+    "inventory": 72
   },
   "counts": {
     "package-backed": 10,

package/typescript/copy-overwrite/.prettierignore

@@ -73,6 +73,7 @@ scripts/check-npm-publish-landed.mjs
 scripts/check-release-package-identity.mjs
 scripts/check-skipped-required-checks.mjs
 scripts/check-state-classification.mjs
+scripts/check-third-party-action-pins.mjs
 scripts/check-third-party-review-evidence.mjs
 scripts/check-threshold-ratchet.mjs
 scripts/check-verification-coverage.mjs

package/typescript/package-lisa/package.lisa.json

@@ -26,6 +26,7 @@
       "test:node": "LISA_TEST_SCRATCH_PREFIXES='[\"node-\"]' lisa-test-run --profile typescript --adapter direct -- node scripts/lisa-test-node.mjs",
       "check:work-item": "node scripts/lisa-work-item.mjs validate-pr",
       "check:conflict-markers": "node scripts/check-conflict-markers.mjs",
+      "check:third-party-action-pins": "node scripts/check-third-party-action-pins.mjs --warn",
       "check:work-item:push": "node scripts/lisa-work-item.mjs validate-push",
       "check:verification": "node scripts/check-verification-coverage.mjs"
     },