@codyswann/lisa 2.350.0 → 2.352.0

package/plugins/src/base/skills/lisa-secrets-access/scripts/note-format.mjs

@@ -0,0 +1,179 @@
+/**
+ * Validate a credential's usage note against the format the contract documents.
+ *
+ * The contract states Rule A — "the note must exist and be well-formed",
+ * enforced statically by `verify` and by `doctor`. Only half of that was ever
+ * true. Both consumers tested the note for emptiness and nothing tested its
+ * shape, so a note that promised a scope and delivered a bare colon, or a
+ * `tool:` line naming a URL instead of a CLI, passed every check Lisa had. The
+ * prose described an enforcement that did not exist, which is worse than no
+ * rule: readers stopped checking because they believed something else was.
+ *
+ * This module is that missing half, and it lives in one place on purpose. The
+ * same argument the values file makes for keeping its writer and its parser
+ * together applies here: `tools-from-notes.mjs` decides what a `tool:` line
+ * *is*, and if this validator held a second copy of that pattern, a note could
+ * pass doctor and then be silently ignored at install time with nothing to
+ * reveal the disagreement. So the matcher is defined here once and imported
+ * there.
+ *
+ * Messages are written for the person who has to fix the vault, who is often
+ * not an engineer. Each one names the secret's defect and the edit that clears
+ * it, never only the rule that was broken.
+ * @module note-format
+ */
+
+/**
+ * A `key: value` metadata line.
+ *
+ * The key must be a single bare lowercase token. That is what separates
+ * `scope: read-write` from prose that happens to contain a colon, such as
+ * "Attio CRM: system of record for sales" — a sentence has spaces before its
+ * colon, and a capitalised word opening a sentence is prose, not a field. The
+ * discriminator is deliberately generous: mistaking a field for prose only
+ * loosens a check, while mistaking prose for a field would fail a good note.
+ */
+const FIELD_LINE = /^[ \t]*([a-z][a-z0-9_-]*)[ \t]*:[ \t]*(.*)$/;
+
+/** Matches `tool: name` or `tools: a, b`, case-insensitively, on one line. */
+const TOOL_LINE_SINGLE = /^[ \t]*tools?[ \t]*:[ \t]*(.*)$/i;
+
+/**
+ * The same matcher, global and multiline, for scanning a whole note.
+ *
+ * Derived from the single-line pattern rather than written out again, so the
+ * two can never disagree about what a tool line is.
+ */
+export const TOOL_LINE = new RegExp(TOOL_LINE_SINGLE.source, "gim");
+
+/**
+ * A bare CLI name: what a `tool:` entry is permitted to be.
+ *
+ * Names are matched against Lisa's catalogue and never executed, so this is not
+ * the security boundary — the catalogue is. It is the check that tells an
+ * operator their entry will be silently dropped, which is the failure mode
+ * worth catching: a note asking for `sonar (for CI)` installs nothing, and the
+ * session fails much later for a reason that looks unrelated.
+ */
+const TOOL_NAME = /^[a-z0-9][a-z0-9._+-]*$/;
+
+/**
+ * Whether a line is structured metadata rather than a sentence.
+ * @param {string} line One line of a note.
+ * @returns {boolean} True when the line is a field or a tool line.
+ */
+function isMetadataLine(line) {
+  return FIELD_LINE.test(line) || TOOL_LINE_SINGLE.test(line);
+}
+
+/**
+ * Check the entries on one `tool:` / `tools:` line.
+ * @param {string} value The text after the colon.
+ * @param {object[]} defects Collector to append to.
+ */
+function checkToolLine(value, defects) {
+  if (!value.trim()) {
+    defects.push({
+      level: "error",
+      code: "empty-tool-line",
+      message:
+        "has a `tool:` line that names no tool. Either name the command-line " +
+        "tool this credential is for (for example `tool: sonar`) or delete " +
+        "the line — as written it asks for a tool and supplies none, so " +
+        "nothing gets installed",
+    });
+    return;
+  }
+
+  for (const raw of value.split(",")) {
+    const entry = raw.trim();
+    if (!entry) {
+      // A trailing or doubled comma is sloppy punctuation, not a broken note:
+      // the reader drops the empty entry and installs the rest correctly.
+      // Blocking a vault over a comma would teach operators the check is noise.
+      defects.push({
+        level: "warn",
+        code: "stray-separator",
+        message:
+          "has a `tool:` line with a stray comma. Nothing breaks, but tidy it " +
+          "so the list reads as the tools it actually names",
+      });
+      continue;
+    }
+    if (!TOOL_NAME.test(entry.toLowerCase())) {
+      defects.push({
+        level: "error",
+        code: "bad-tool-name",
+        message:
+          `has a \`tool:\` entry that is not a tool name: "${entry}". Each ` +
+          "entry must be one plain name such as `sonar` or `gh`, separated by " +
+          "commas — no descriptions, links, versions, or punctuation. As " +
+          "written this entry is ignored, so the tool never gets installed",
+      });
+    }
+  }
+}
+
+/**
+ * Report every way a usage note departs from the documented format.
+ *
+ * Returns defects rather than throwing so a caller can list a whole vault's
+ * problems in one pass. An operator fixing a vault wants every edit at once,
+ * not one error per run.
+ * @param {unknown} note The note text stored beside the secret.
+ * @returns {{level: string, code: string, message: string}[]} Defects found.
+ */
+export function validateNote(note) {
+  if (typeof note !== "string" || !note.trim()) {
+    // One cause, one instruction. Also accusing an absent note of lacking a
+    // first line would leave the operator guessing which fix comes first.
+    return [
+      {
+        level: "error",
+        code: "missing-note",
+        message:
+          "has no usage note. Write one in the secret's own description field " +
+          "in the vault: a first line saying what this credential is for and " +
+          "what it can reach, then `key: value` lines such as `scope:`, " +
+          "`owner:`, and `tool:`. Guessing a credential's purpose from its " +
+          "name is exactly the guess that writes to the wrong system",
+      },
+    ];
+  }
+
+  const defects = [];
+  const lines = note.split(/\r?\n/);
+  const populated = lines.filter(line => line.trim());
+
+  if (!populated.some(line => !isMetadataLine(line))) {
+    defects.push({
+      level: "error",
+      code: "no-prose",
+      message:
+        "has no plain-language first line. Add a sentence at the top saying " +
+        "what this credential is for and what it can reach — the `key: value` " +
+        "lines below it list details, but they never say what the thing is",
+    });
+  }
+
+  for (const line of populated) {
+    const tool = TOOL_LINE_SINGLE.exec(line);
+    if (tool) {
+      checkToolLine(tool[1], defects);
+      continue;
+    }
+    const field = FIELD_LINE.exec(line);
+    if (field && !field[2].trim()) {
+      defects.push({
+        level: "error",
+        code: "empty-field",
+        message:
+          `has an empty \`${field[1]}:\` line. Either fill in the value or ` +
+          "delete the line — a field with nothing after the colon promises a " +
+          "fact the reader then cannot find anywhere",
+      });
+    }
+  }
+
+  return defects;
+}

package/plugins/src/base/skills/lisa-secrets-access/scripts/resolve-secret.mjs

@@ -30,6 +30,7 @@
 import { existsSync, readFileSync } from "node:fs";
 
 import { parseEnv } from "./envfile.mjs";
+import { validateNote } from "./note-format.mjs";
 import { ENV_KEY, fetchAll } from "./providers.mjs";
 import { materializedPaths, readConfig } from "./surfaces.mjs";
 
@@ -109,6 +110,19 @@ function sourceOf(name, provider, file) {
   return "         ";
 }
 
+/**
+ * Say what is wrong with a note, not merely that something is.
+ *
+ * "NO NOTE" against a note that exists but is malformed sends the operator
+ * looking for a missing field they already wrote.
+ * @param {object} [fault] The blocking defect, if any.
+ * @returns {string} A status label for the verify table.
+ */
+function noteStatus(fault) {
+  if (!fault) return "noted";
+  return fault.code === "missing-note" ? "NO NOTE" : `NOTE ${fault.code}`;
+}
+
 /**
  * Verify every declared secret, mirroring the ladder's own order.
  *
@@ -119,12 +133,20 @@ function sourceOf(name, provider, file) {
  * This command is read-only. Proving that a rotating credential can actually be
  * written back requires a write, so that check lives in the rotation path
  * rather than here.
+ *
+ * The two views are parameters so a test can supply them. Reaching for the
+ * provider CLI is the one thing in here that cannot run in a test, and a check
+ * nobody can test is how the note rule stayed unenforced for so long.
  * @param {object} cfg Resolved configuration.
+ * @param {Map<string, object>} [provider] Provider view.
+ * @param {Map<string, string>} [file] Materialized view.
  * @returns {number} Count of secrets that failed.
  */
-function verify(cfg) {
-  const provider = fetchAll(cfg);
-  const file = readMaterialized(cfg);
+export function verify(
+  cfg,
+  provider = fetchAll(cfg),
+  file = readMaterialized(cfg)
+) {
   const names = cfg.require ?? [
     ...new Set([...provider.keys(), ...file.keys()]),
   ];
@@ -139,13 +161,17 @@ function verify(cfg) {
       provider.get(name)?.value
     );
     const named = ENV_KEY.test(name);
-    const noted = Boolean(provider.get(name)?.note);
-    if (!resolves || !named || !noted) bad += 1;
+    // Presence is not well-formedness. Testing `Boolean(note)` passed a note
+    // that was a single stray character, which is exactly the note an agent
+    // learns nothing from. Same validator doctor uses, so the two agree.
+    const defects = validateNote(provider.get(name)?.note);
+    const noteFault = defects.find(d => d.level === "error");
+    if (!resolves || !named || noteFault) bad += 1;
     console.log(
       `  ${name.padEnd(30)} ${resolves ? "resolves" : "MISSING "} ` +
         `${sourceOf(name, provider, file)} ` +
         `${named ? "name ok" : "NAME NOT UPPER_SNAKE"}  ` +
-        `${noted ? "noted" : "NO NOTE"}` +
+        `${noteStatus(noteFault)}` +
         `${rotating.has(name) ? "  rotating" : ""}`
     );
   }

package/plugins/src/base/skills/lisa-secrets-access/scripts/tools-from-notes.mjs

@@ -21,11 +21,15 @@
  * its note. Selecting from a known set means the worst a hostile note can do is
  * ask for a CLI Lisa already ships a pinned, checksummed entry for — it can
  * never introduce a URL, a version, or a command.
+ * The matcher itself lives in `note-format.mjs` alongside the validator that
+ * checks these lines, for the same reason the values file keeps its writer and
+ * its parser in one module: two copies of the pattern would let a note pass
+ * `doctor` and then be silently ignored here, with nothing to reveal the
+ * disagreement.
  * @module tools-from-notes
  */
 
-/** Matches `tool: name` or `tools: a, b`, case-insensitively, one per line. */
-const TOOL_LINE = /^[ \t]*tools?[ \t]*:[ \t]*(.+)$/gim;
+import { TOOL_LINE } from "./note-format.mjs";
 
 /**
  * Collect the tool names a set of notes asks for.

package/plugins/src/base/skills/lisa-setup-atlassian/SKILL.md

@@ -77,6 +77,23 @@ read_token() {
   local slug=$(echo "$email" | tr '[:upper:]@.' '[:lower:]__')
   local varname="ATLASSIAN_API_TOKEN_${slug}"
   [ -n "${!varname}" ] && { echo "${!varname}"; return; }
+  # Preferred path: the single secrets chokepoint. It owns the one-store rule
+  # and the surface ladder, so anything it can answer must not be read out of an
+  # OS keychain here — a second reader is how the same credential ends up living
+  # in two places and drifting. Keep this identical to `atlassian-access`.
+  local resolver
+  for resolver in .claude/skills/lisa-secrets-access/scripts/resolve-secret.mjs \
+                  .agents/skills/lisa-secrets-access/scripts/resolve-secret.mjs; do
+    if [ -f "$resolver" ]; then
+      local via_lisa
+      via_lisa=$(node "$resolver" get ATLASSIAN_API_TOKEN 2>/dev/null) \
+        && [ -n "$via_lisa" ] && { echo "$via_lisa"; return; }
+      break
+    fi
+  done
+  # Legacy fallback: the OS keychain written by the guided flow below, for
+  # projects that have not adopted a credentials provider. Reached only when the
+  # chokepoint is absent or has no entry.
   case "$(uname -s)" in
     Darwin)  security find-generic-password -s lisa-atlassian -a "$email" -w 2>/dev/null ;;
     Linux)   command -v secret-tool >/dev/null && secret-tool lookup service lisa-atlassian account "$email" 2>/dev/null ;;

package/plugins/src/base/skills/lisa-setup-linear/SKILL.md

@@ -89,6 +89,23 @@ read_linear_key() {  # $1=workspace slug
   local slug; slug=$(echo "$ws" | tr '[:upper:]-' '[:lower:]_')
   local varname="LINEAR_API_KEY_${slug}"
   [ -n "${!varname}" ] && { echo "${!varname}"; return; }
+  # Preferred path: the single secrets chokepoint. It owns the one-store rule
+  # and the surface ladder, so anything it can answer must not be read out of an
+  # OS keychain here — a second reader is how the same credential ends up living
+  # in two places and drifting. Keep this identical to `linear-access`.
+  local resolver
+  for resolver in .claude/skills/lisa-secrets-access/scripts/resolve-secret.mjs \
+                  .agents/skills/lisa-secrets-access/scripts/resolve-secret.mjs; do
+    if [ -f "$resolver" ]; then
+      local via_lisa
+      via_lisa=$(node "$resolver" get LINEAR_API_KEY 2>/dev/null) \
+        && [ -n "$via_lisa" ] && { echo "$via_lisa"; return; }
+      break
+    fi
+  done
+  # Legacy fallback: the OS keychain written by the guided flow below, for
+  # projects that have not adopted a credentials provider. Reached only when the
+  # chokepoint is absent or has no entry.
   case "$(uname -s)" in
     Darwin)  security find-generic-password -s lisa-linear -a "$ws" -w 2>/dev/null ;;
     Linux)   command -v secret-tool >/dev/null && secret-tool lookup service lisa-linear account "$ws" 2>/dev/null ;;

package/plugins/src/base/skills/lisa-setup-notion/SKILL.md

@@ -164,6 +164,23 @@ read_notion_token() {
   local slug=$(echo "$workspace" | tr '[:upper:]-' '[:lower:]_')
   local varname="NOTION_API_TOKEN_${slug}"
   [ -n "${!varname}" ] && { echo "${!varname}"; return; }
+  # Preferred path: the single secrets chokepoint. It owns the one-store rule
+  # and the surface ladder, so anything it can answer must not be read out of an
+  # OS keychain here — a second reader is how the same credential ends up living
+  # in two places and drifting. Keep this identical to `notion-access`.
+  local resolver
+  for resolver in .claude/skills/lisa-secrets-access/scripts/resolve-secret.mjs \
+                  .agents/skills/lisa-secrets-access/scripts/resolve-secret.mjs; do
+    if [ -f "$resolver" ]; then
+      local via_lisa
+      via_lisa=$(node "$resolver" get NOTION_API_TOKEN 2>/dev/null) \
+        && [ -n "$via_lisa" ] && { echo "$via_lisa"; return; }
+      break
+    fi
+  done
+  # Legacy fallback: the OS keychain written by the guided flow below, for
+  # projects that have not adopted a credentials provider. Reached only when the
+  # chokepoint is absent or has no entry.
   case "$(uname -s)" in
     Darwin)  security find-generic-password -s lisa-notion -a "$workspace" -w 2>/dev/null ;;
     Linux)   command -v secret-tool >/dev/null && secret-tool lookup service lisa-notion account "$workspace" 2>/dev/null ;;

package/plugins/src/typescript/hooks/block-suppress-directives.sh

@@ -16,7 +16,7 @@
 
 JSON_INPUT=$(cat)
 
-# Project rule (.claude/rules/PROJECT_RULES.md): never parse JSON in shell with
+# Project rule (host rules, .agents/rules/): never parse JSON in shell with
 # grep/sed/cut/awk — always use jq. Fail open without jq so we never hard-block
 # the agent on missing tooling.
 command -v jq >/dev/null 2>&1 || exit 0

package/scripts/github-status-check.sh

@@ -24,16 +24,31 @@
 
 set -euo pipefail
 
-# Auto-load .env.local if it exists (look in script dir and current dir)
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
 
-if [[ -f "$PROJECT_ROOT/.env.local" ]]; then
-  # shellcheck source=/dev/null
-  source "$PROJECT_ROOT/.env.local"
-elif [[ -f ".env.local" ]]; then
-  # shellcheck source=/dev/null
-  source ".env.local"
+# Read one setting from .env.local, and only that one.
+#
+# This used to `source` the file. Sourcing is unbounded: it imports every
+# variable the file happens to contain, including whatever tokens an operator
+# has parked there, which quietly made this script a second reader of
+# credentials that belong behind lisa-secrets-access. That is the exact drift
+# the one-store rule exists to prevent.
+#
+# LISA_GITHUB_REPOS is a list of repository names, not a credential, so reading
+# it here is fine. Authentication is `gh`'s own, and any credential this script
+# ever needs must come from the environment or resolve-secret.mjs.
+if [[ -z "${LISA_GITHUB_REPOS:-}" ]]; then
+  for env_file in "$PROJECT_ROOT/.env.local" ".env.local"; do
+    [[ -f "$env_file" ]] || continue
+    repos_line="$(grep -m1 -E '^[[:space:]]*(export[[:space:]]+)?LISA_GITHUB_REPOS=' "$env_file" || true)"
+    [[ -n "$repos_line" ]] || continue
+    repos_value="${repos_line#*=}"
+    repos_value="${repos_value%\"}" && repos_value="${repos_value#\"}"
+    repos_value="${repos_value%\'}" && repos_value="${repos_value#\'}"
+    export LISA_GITHUB_REPOS="$repos_value"
+    break
+  done
 fi
 
 # Colors for output

package/all/create-only/.claude/rules/PROJECT_RULES.md

@@ -1,17 +0,0 @@
-# Project Rules
-
-Project-specific rules and guidelines that apply to this codebase.
-
-Rules in `.claude/rules/` are automatically loaded by Claude Code at session start.
-Add project-specific patterns, conventions, and requirements below.
-
-This file is **human-authored only** — the humans' decree surface. Automated
-flows never append to it: machine-captured learnings land in the learnings
-ledger (default `.lisa/PROJECT_LEARNINGS.md`) via the executable contract, and
-the gardener (`/lisa:learnings:audit`) proposes promotions, demotions, and
-retirements as human-gated tracker tickets. Existing sections of this file are
-first-run gardener candidates like any other knowledge — expect prose that
-restates what a lint or hook already enforces to earn a promote-and-delete
-ticket over time, so this file shrinks instead of growing.
-
----