@codyswann/lisa 3.33.5 → 3.33.7

package/all/copy-overwrite/scripts/check-state-classification.mjs

@@ -113,9 +113,25 @@ const PERSISTENCE_SIGNALS = Object.freeze([
   { kind: "schema-definition", pattern: /(^|\/)db\/schema\.[cm]?[jt]s$/iu },
 ]);
 
+// The `CREATE TABLE` grammar, one clause per name. Written as fragments rather
+// than one literal because the literal was unreadable — the alternations are
+// SQL's, and loosening any of them into a wildcard would make the subtraction
+// detector match statements that are not entity declarations.
+/** `CREATE [UNLOGGED|TEMPORARY|TEMP|GLOBAL|LOCAL] ...` modifier run. */
+const CREATE_MODIFIERS =
+  "(?:unlogged\\s+|temporary\\s+|temp\\s+|global\\s+|local\\s+)*";
+/** The object kinds that declare durable state. */
+const CREATE_OBJECT_KIND = "(?:materialized\\s+view|table|view)";
+/** Optional `IF NOT EXISTS` guard. */
+const OPTIONAL_IF_NOT_EXISTS = "(?:if\\s+not\\s+exists\\s+)?";
+/** A possibly schema-qualified, possibly quoted identifier. */
+const ENTITY_NAME = '([\\w."`[\\]]+)';
+
 /** `CREATE TABLE`-shaped declarations the subtraction detector recognizes. */
-const CREATE_ENTITY_PATTERN =
-  /create\s+(?:unlogged\s+|temporary\s+|temp\s+|global\s+|local\s+)*(?:materialized\s+view|table|view)\s+(?:if\s+not\s+exists\s+)?([\w."`[\]]+)/giu;
+const CREATE_ENTITY_PATTERN = new RegExp(
+  `create\\s+${CREATE_MODIFIERS}${CREATE_OBJECT_KIND}\\s+${OPTIONAL_IF_NOT_EXISTS}${ENTITY_NAME}`,
+  "giu"
+);
 
 /**
  * Read a JSON file, returning a discriminated result rather than throwing.
@@ -277,11 +293,9 @@ export function compareInventory({
 }) {
   const findings = [];
   const entities = contract.entities ?? [];
-  const byBareName = new Map();
   const classified = new Map();
   for (const entity of entities) {
     classified.set(entity.id, entity);
-    byBareName.set(bareName(entity.id), entity);
   }
   const waived = new Map(
     (contract.waivers ?? []).map(waiver => [waiver.id, waiver])

package/all/copy-overwrite/scripts/lisa-gates.mjs

@@ -71,17 +71,24 @@ export const LEVELS = ["required", "optional", "off"];
 /** What to do when a gate reports success without evidence of work. */
 export const HOLLOW_RESPONSES = ["report", "wait", "block"];
 
+// Moment names, named once. They appear in a dozen moment lists below; a
+// literal repeated that many times is one typo away from a gate that silently
+// never runs, and there is no test that can tell "gate not configured for this
+// moment" from "moment misspelled".
+const SESSION_START = "session-start";
+const PRE_TOOL = "pre-tool";
+const COMMIT = "commit";
+const PUSH = "push";
+const PULL_REQUEST = "pull-request";
+const PRE_DEPLOY = "pre-deploy";
+const POST_DEPLOY = "post-deploy";
+const CONTINUOUS = "continuous";
+
 /** Fixed moments. Two more families take an environment suffix. */
-export const MOMENTS = [
-  "session-start",
-  "pre-tool",
-  "commit",
-  "push",
-  "pull-request",
-];
+export const MOMENTS = [SESSION_START, PRE_TOOL, COMMIT, PUSH, PULL_REQUEST];
 
 /** Moment families that take an `:<environment>` suffix. */
-export const MOMENT_FAMILIES = ["pre-deploy", "post-deploy", "continuous"];
+export const MOMENT_FAMILIES = [PRE_DEPLOY, POST_DEPLOY, CONTINUOUS];
 
 /**
  * Moments that gate a *state* rather than a change.
@@ -99,7 +106,7 @@ export const MOMENT_FAMILIES = ["pre-deploy", "post-deploy", "continuous"];
  * new cases against a stable one. It applies equally to a CVE published today,
  * which makes yesterday's dependency scan wrong with no change at all.
  */
-export const STATE_FAMILIES = ["continuous"];
+export const STATE_FAMILIES = [CONTINUOUS];
 
 /** Keys on a gate entry that are settings rather than moments. */
 export const GATE_FIELDS = new Set(["run", "needs", "task"]);
@@ -130,19 +137,12 @@ export const GATE_FIELDS = new Set(["run", "needs", "task"]);
 /** Prefix marking a gate, or a config key, that this project invented. */
 export const CUSTOM_PREFIX = "x-";
 
-const COMMIT_ONWARD = [
-  "commit",
-  "push",
-  "pull-request",
-  "pre-deploy",
-  "post-deploy",
-];
-const PUSH_ONWARD = ["push", "pull-request", "pre-deploy", "post-deploy"];
-const PR_ONWARD = ["pull-request", "pre-deploy", "post-deploy"];
-const PR_ONLY = ["pull-request"];
-const DEPLOY_ONLY = ["pre-deploy", "post-deploy", "continuous"];
-const CONTINUOUS_ONLY = ["continuous"];
-const SESSION_ONWARD = ["session-start", ...COMMIT_ONWARD];
+const COMMIT_ONWARD = [COMMIT, PUSH, PULL_REQUEST, PRE_DEPLOY, POST_DEPLOY];
+const PUSH_ONWARD = [PUSH, PULL_REQUEST, PRE_DEPLOY, POST_DEPLOY];
+const PR_ONWARD = [PULL_REQUEST, PRE_DEPLOY, POST_DEPLOY];
+const PR_ONLY = [PULL_REQUEST];
+const DEPLOY_ONLY = [PRE_DEPLOY, POST_DEPLOY, CONTINUOUS];
+const SESSION_ONWARD = [SESSION_START, ...COMMIT_ONWARD];
 
 /**
  * Lisa's canonical gates.
@@ -231,14 +231,14 @@ export const REGISTRY = Object.freeze({
     label: "🎭 Playwright E2E Tests",
     summary: "Browser journeys pass end to end.",
     task: "test:e2e",
-    moments: [...PR_ONWARD, "continuous"],
+    moments: [...PR_ONWARD, CONTINUOUS],
     work: "specs run",
   },
   "e2e-native": {
     label: "📱 Maestro Native E2E",
     summary: "Native device journeys pass end to end.",
     task: "test:e2e:native",
-    moments: [...PR_ONWARD, "continuous"],
+    moments: [...PR_ONWARD, CONTINUOUS],
     work: "flows run",
   },
   // ---------------------------------------------------------------------
@@ -268,7 +268,7 @@ export const REGISTRY = Object.freeze({
     summary:
       "The environment reset exists, and its guard cannot be bypassed by calling it directly.",
     task: "environment:reset:verify",
-    moments: [...PR_ONWARD, "continuous"],
+    moments: [...PR_ONWARD, CONTINUOUS],
     work: "refusals proved",
   },
   "environment-reseed": {
@@ -276,7 +276,7 @@ export const REGISTRY = Object.freeze({
     summary:
       "The environment reseed exists, and its guard cannot be bypassed by calling it directly.",
     task: "environment:reseed:verify",
-    moments: [...PR_ONWARD, "continuous"],
+    moments: [...PR_ONWARD, CONTINUOUS],
     work: "refusals proved",
   },
   "generative-testing": {
@@ -288,7 +288,7 @@ export const REGISTRY = Object.freeze({
     // re-running one suite against every change explores far less of the input
     // space than generating new cases against a stable one." A property suite
     // pinned to the per-change gate re-walks the same ground forever.
-    moments: [...PR_ONWARD, "continuous"],
+    moments: [...PR_ONWARD, CONTINUOUS],
     work: "cases generated",
   },
   "structural-rules": {
@@ -322,14 +322,14 @@ export const REGISTRY = Object.freeze({
     task: "security:audit",
     // Continuous matters most here: a CVE published today makes yesterday's
     // green wrong with no change to trigger a re-scan.
-    moments: [...PUSH_ONWARD, "continuous"],
+    moments: [...PUSH_ONWARD, CONTINUOUS],
     work: "manifests scanned",
   },
   "static-security": {
     label: "🔍 Static Security Analysis",
     summary: "Static analysis finds no security defect.",
     task: "security:sast",
-    moments: [...PR_ONWARD, "continuous"],
+    moments: [...PR_ONWARD, CONTINUOUS],
     work: "files analysed",
   },
   "runtime-web-vulnerability": {
@@ -349,7 +349,7 @@ export const REGISTRY = Object.freeze({
     label: "👁️ Code Review",
     summary: "The change was reviewed by something that read it.",
     task: "review:local",
-    moments: ["push", "pull-request"],
+    moments: [PUSH, PULL_REQUEST],
   },
   "performance-budget": {
     label: "⚡ Performance Budget",
@@ -768,9 +768,9 @@ function validateGate(id, gate) {
       ...Object.keys(INTERCEPTORS),
     ]);
     return [
-      `gates."${id}" is not a gate Lisa knows` +
-        (near ? `. Did you mean "${near}"?` : "") +
-        ` Prefix a gate of your own with "${CUSTOM_PREFIX}" — Lisa will run ` +
+      `gates."${id}" is not a gate Lisa knows${
+        near ? `. Did you mean "${near}"?` : ""
+      } Prefix a gate of your own with "${CUSTOM_PREFIX}" — Lisa will run ` +
         `it without pretending to understand it.`,
     ];
   }
@@ -834,7 +834,7 @@ function validateMoment(id, moment, value, known, interceptor, gateRun) {
     );
   }
   if (entry.await) {
-    if (["commit", "push", "session-start", "pre-tool"].includes(moment)) {
+    if ([COMMIT, PUSH, SESSION_START, PRE_TOOL].includes(moment)) {
       problems.push(
         `gates."${id}"."${moment}" awaits "${entry.await}", but there is no ` +
           `pull request yet for a signal to post against. An awaited check ` +
@@ -953,8 +953,9 @@ export function validatePolicy(policy) {
     if (!Object.hasOwn(POLICY_SCHEMA, section)) {
       const near = nearest(section, Object.keys(POLICY_SCHEMA));
       problems.push(
-        `policy."${section}" is not a policy section Lisa knows` +
-          (near ? `. Did you mean "${near}"?` : "")
+        `policy."${section}" is not a policy section Lisa knows${
+          near ? `. Did you mean "${near}"?` : ""
+        }`
       );
       continue;
     }
@@ -967,8 +968,9 @@ export function validatePolicy(policy) {
       if (!expected) {
         const near = nearest(field, Object.keys(POLICY_SCHEMA[section]));
         problems.push(
-          `policy.${section}."${field}" is not a setting Lisa manages` +
-            (near ? `. Did you mean "${near}"?` : "")
+          `policy.${section}."${field}" is not a setting Lisa manages${
+            near ? `. Did you mean "${near}"?` : ""
+          }`
         );
         continue;
       }
@@ -1012,10 +1014,9 @@ export function auditConfigKeys(config) {
     findings.push({
       key,
       level: "warn",
-      message:
-        `${key} is not a key Lisa reads` +
-        (near ? `. Did you mean "${near}"?` : "") +
-        ` Nothing consumes it, so whatever it was meant to configure is unset.`,
+      message: `${key} is not a key Lisa reads${
+        near ? `. Did you mean "${near}"?` : ""
+      } Nothing consumes it, so whatever it was meant to configure is unset.`,
     });
   }
   return findings;
@@ -1050,7 +1051,7 @@ export function resolveMoment({
   // for a real moment; it is refused only for one that cannot exist.
   if (!isMoment(moment)) {
     throw new Error(
-      `"${moment}" ${unknownMomentMessage(moment)} ` + knownMomentsMessage()
+      `"${moment}" ${unknownMomentMessage(moment)} ${knownMomentsMessage()}`
     );
   }
   assertValidMomentKeys(gates);
@@ -1184,7 +1185,7 @@ export function needsAt({ gates, moment }) {
  */
 export function contextsFor(gates, options = {}) {
   const {
-    moment = "pull-request",
+    moment = PULL_REQUEST,
     workflowName = "🔍 Quality Checks",
     previousLabels = [],
   } = options;
@@ -1347,7 +1348,7 @@ function main() {
   }
 
   if (command === "needs") {
-    const moment = flag("moment") ?? "session-start";
+    const moment = flag("moment") ?? SESSION_START;
     console.log(JSON.stringify(needsAt({ gates, moment }), null, 2));
     return;
   }
@@ -1360,7 +1361,7 @@ function main() {
     console.log(
       JSON.stringify(
         contextsFor(gates, {
-          moment: flag("moment") ?? "pull-request",
+          moment: flag("moment") ?? PULL_REQUEST,
           workflowName: flag("workflow") ?? "🔍 Quality Checks",
           previousLabels,
         }),

package/all/copy-overwrite/scripts/lisa-run-gates.mjs

@@ -305,8 +305,9 @@ function summarise(result) {
     `(optional), ${result.skipped.length} not provable here`;
   lines.push(
     `${failedOptional.length ? "⚠️ " : "✅"} ${result.moment}: ${counts}, ` +
-      `of ${result.total} gate(s) declared.` +
-      (failedOptional.length ? " See the optional failure(s) above." : "")
+      `of ${result.total} gate(s) declared.${
+        failedOptional.length ? " See the optional failure(s) above." : ""
+      }`
   );
   return lines;
 }

package/all/copy-overwrite/scripts/lisa-work-item.mjs

@@ -25,6 +25,14 @@ const RELEASE_SUBJECT =
   /^chore\(release\): \d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)? \[skip ci\]$/;
 const ZERO_OID = /^0+$/;
 const MARKER = "[lisa-pr-link]";
+/**
+ * The command that establishes the ticket-side backlink.
+ *
+ * Named in every refusal that the backlink is missing. A validator that
+ * reports "no verified backlink" without the remedy sends the reader looking
+ * for a producer that, until this command existed, was prose in a SKILL.md.
+ */
+const BACKLINK_COMMAND = "node scripts/lisa-work-item.mjs backlink";
 /**
  * The prefix only — an anchored, fixed-length literal with no quantifier, so
  * it cannot backtrack. The ReDoS was never here; it was in the `\s*(.+?)\s*$`
@@ -1217,6 +1225,247 @@ export function textContainsBacklink(value, prUrl) {
   return false;
 }
 
+/**
+ * The managed backlink comment's body.
+ *
+ * One line, and the whole body — so establishing the backlink is a whole-body
+ * replace rather than an append, which is what makes a rerun converge instead
+ * of accumulating. Nothing else is carried here on purpose: the milestone and
+ * the merge SHA belong to the vendor sync skills' progress notes, and putting
+ * them in this body would make every rerun a content change.
+ * @param {string} prUrl Pull request URL.
+ * @returns {string} The comment body.
+ */
+function backlinkBody(prUrl) {
+  return `${MARKER} ${prUrl}`;
+}
+
+/**
+ * Whether a comment payload is Lisa's managed backlink comment.
+ *
+ * Shape-agnostic deliberately: GitHub and Linear return a plain string body,
+ * Jira returns an Atlassian Document Format tree. Serialising covers all three
+ * without a per-provider walker, and the marker is distinctive enough that a
+ * false positive would have to be a comment quoting it verbatim — which is
+ * still Lisa's comment to reuse rather than a second one to add.
+ * @param {unknown} body Comment body in whatever shape the provider returned.
+ * @returns {boolean} True when this is the managed comment.
+ */
+function carriesMarker(body) {
+  return JSON.stringify(body ?? "").includes(MARKER);
+}
+
+/**
+ * Establish the backlink on a GitHub issue.
+ * @param {string} ref Canonical `owner/repo#number` reference.
+ * @param {string} prUrl Pull request URL.
+ * @returns {string} What changed: created, updated, or unchanged.
+ */
+function githubBacklink(ref, prUrl) {
+  const [repository, number] = ref.split("#");
+  const listing = run(
+    "gh",
+    [
+      "api",
+      "--paginate",
+      `repos/${repository}/issues/${number}/comments?per_page=100`,
+    ],
+    { allowFailure: true }
+  );
+  if (listing.status !== 0) throw githubFailure(listing, ref);
+  const comments = safeJson(listing.stdout, `GitHub comments on ${ref}`);
+  const managed = (Array.isArray(comments) ? comments : []).find(comment =>
+    carriesMarker(comment?.body)
+  );
+  const body = backlinkBody(prUrl);
+  if (managed && managed.body === body) return "unchanged";
+  const [method, endpoint] = managed
+    ? ["PATCH", `repos/${repository}/issues/comments/${managed.id}`]
+    : ["POST", `repos/${repository}/issues/${number}/comments`];
+  run("gh", ["api", "--method", method, endpoint, "--field", `body=${body}`], {
+    error: `could not write the backlink comment on ${ref}`,
+  });
+  return managed ? "updated" : "created";
+}
+
+/**
+ * Send one Linear GraphQL document, refusing on either failure surface.
+ *
+ * GraphQL answers an invalid mutation with HTTP 200 and an `errors` array, so
+ * a status-only check reports success for a comment that was never written.
+ * @param {string} token Linear API key.
+ * @param {string} query The document.
+ * @param {object} variables Its variables.
+ * @param {string} context What the call was for, for the message.
+ * @returns {object} The `data` payload.
+ */
+function linearGraphql(token, query, variables, context) {
+  const result = secureCurl(
+    ["https://api.linear.app/graphql"],
+    [
+      ["request", "POST"],
+      ["header", "Content-Type: application/json"],
+      ["header", `Authorization: ${token}`],
+      ["data-binary", JSON.stringify({ query, variables })],
+    ],
+    { allowFailure: true }
+  );
+  if (result.status !== 0) throw new TrackingError(`${context} failed`);
+  const response = safeJson(result.stdout, context);
+  if (Array.isArray(response.errors) && response.errors.length > 0)
+    throw new TrackingError(
+      `${context} failed: ${response.errors[0]?.message}`
+    );
+  return response.data ?? {};
+}
+
+/**
+ * Establish the backlink on a Linear issue.
+ * @param {string} ref Canonical `KEY-123` identifier.
+ * @param {string} prUrl Pull request URL.
+ * @param {object} contract Resolved tracker contract.
+ * @returns {string} What changed: created, updated, or unchanged.
+ */
+function linearBacklink(ref, prUrl, contract) {
+  const token = readLinearKey(contract.workspace);
+  if (!token)
+    throw new TrackingError(
+      "writing a Linear backlink requires LINEAR_API_KEY or a lisa-linear keychain entry"
+    );
+  const issue = linearGraphql(
+    token,
+    "query($id:String!){issue(id:$id){id comments{nodes{id body}}}}",
+    { id: ref },
+    `Linear issue ${ref} lookup`
+  ).issue;
+  if (!issue?.id)
+    throw new TrackingError(
+      `Linear issue ${ref} does not exist or is inaccessible`
+    );
+  const managed = (issue.comments?.nodes ?? []).find(comment =>
+    carriesMarker(comment?.body)
+  );
+  const body = backlinkBody(prUrl);
+  if (managed && managed.body === body) return "unchanged";
+  if (managed) {
+    linearGraphql(
+      token,
+      "mutation($id:String!,$body:String!){commentUpdate(id:$id,input:{body:$body}){success}}",
+      { body, id: managed.id },
+      `Linear backlink update on ${ref}`
+    );
+    return "updated";
+  }
+  linearGraphql(
+    token,
+    "mutation($id:String!,$body:String!){commentCreate(input:{issueId:$id,body:$body}){success}}",
+    { body, id: issue.id },
+    `Linear backlink comment on ${ref}`
+  );
+  return "created";
+}
+
+/**
+ * The managed comment as an Atlassian Document Format tree.
+ *
+ * A single text node, so the marker and the URL land in one string — which is
+ * what `textContainsBacklink` walks the tree looking for. Splitting them across
+ * nodes would write a comment the reader accepts visually and the check
+ * rejects.
+ * @param {string} prUrl Pull request URL.
+ * @returns {object} The ADF document.
+ */
+function jiraCommentDocument(prUrl) {
+  return {
+    content: [
+      {
+        content: [{ text: backlinkBody(prUrl), type: "text" }],
+        type: "paragraph",
+      },
+    ],
+    type: "doc",
+    version: 1,
+  };
+}
+
+/**
+ * Establish the backlink on a Jira ticket.
+ *
+ * Requires API credentials rather than falling back to `acli`: the read path
+ * may degrade to whatever can answer, but a write that silently does not
+ * happen is exactly the failure this command exists to remove.
+ * @param {string} ref Canonical `KEY-123` reference.
+ * @param {string} prUrl Pull request URL.
+ * @param {object} contract Resolved tracker contract.
+ * @returns {string} What changed: created, updated, or unchanged.
+ */
+function jiraBacklink(ref, prUrl, contract) {
+  const credentials = jiraCredentials(contract);
+  if (!credentials)
+    throw new TrackingError(
+      "writing a Jira backlink requires ATLASSIAN_API_TOKEN/JIRA_API_TOKEN with JIRA_LOGIN and atlassian.cloudId/site"
+    );
+  const issueUrl = `${credentials.baseUrl}/rest/api/3/issue/${encodeURIComponent(ref)}/comment`;
+  const auth = [
+    ["user", `${credentials.login}:${credentials.token}`],
+    ["header", "Accept: application/json"],
+  ];
+  const listing = secureCurl([`${issueUrl}?maxResults=100`], auth, {
+    allowFailure: true,
+  });
+  if (listing.status !== 0)
+    throw new TrackingError(`Jira ticket ${ref} comments are inaccessible`);
+  const existing = safeJson(listing.stdout, `Jira comments on ${ref}`);
+  const managed = (existing.comments ?? []).find(comment =>
+    carriesMarker(comment?.body)
+  );
+  const document = jiraCommentDocument(prUrl);
+  const payload = JSON.stringify({ body: document });
+  if (managed && JSON.stringify(managed.body) === JSON.stringify(document))
+    return "unchanged";
+  secureCurl(
+    [managed ? `${issueUrl}/${encodeURIComponent(managed.id)}` : issueUrl],
+    [
+      ...auth,
+      ["request", managed ? "PUT" : "POST"],
+      ["header", "Content-Type: application/json"],
+      ["data-binary", payload],
+    ],
+    { error: `could not write the backlink comment on ${ref}` }
+  );
+  return managed ? "updated" : "created";
+}
+
+/**
+ * Establish the ticket-side backlink, whatever the tracker.
+ *
+ * This is the producer for the comment `assertBacklink` consumes, and it lives
+ * in this file for that reason: the requirement was documented in a SKILL.md
+ * and enforced here, so nothing executable ever wrote it and a required check
+ * failed on a step no command performed.
+ *
+ * Every provider `assertBacklink` reads is written here. A provider that is
+ * not refuses loudly rather than returning quietly, because a silent no-op
+ * here reproduces the original defect one layer down: the command reports
+ * success and the check still fails.
+ * @param {string} ref Canonical work-item reference.
+ * @param {string} prUrl Pull request URL.
+ * @param {object} contract Resolved tracker contract.
+ * @returns {string} What changed: created, updated, or unchanged.
+ */
+function postBacklink(ref, prUrl, contract) {
+  if (contract.provider === "github") return githubBacklink(ref, prUrl);
+  if (contract.provider === "linear")
+    return linearBacklink(ref, prUrl, contract);
+  if (contract.provider === "jira") return jiraBacklink(ref, prUrl, contract);
+  throw new TrackingError(
+    `no backlink writer for tracker '${contract.provider}'; ` +
+      `github, jira and linear are supported.\nThe Work-Item Traceability check ` +
+      `reads a managed ${MARKER} comment for this provider, so it cannot pass ` +
+      `until a writer exists here — add one rather than posting by hand.`
+  );
+}
+
 function assertBacklink(
   ref,
   prUrl,
@@ -1502,7 +1751,12 @@ function backlinkAdvice(ref, prUrl, contract) {
     contract.provider === "linear"
       ? `The tracker builds that link from the BRANCH NAME, so a branch carrying no ticket id can never acquire one: no edit to this pull request, its body, or its commits will do it. Fixing it that way needs a NEW branch named for ${ref} and a new pull request from it. `
       : "";
-  return `${branchDerived}The one remedy that needs no new branch is a comment on ${ref} containing: ${MARKER} ${prUrl}`;
+  return (
+    `${branchDerived}The one remedy that needs no new branch is the managed comment ` +
+    `\`${MARKER} ${prUrl}\` on ${ref}. Do not post it by hand — run:\n\n` +
+    `    ${BACKLINK_COMMAND} --ref ${ref} --pr-url ${prUrl}\n\n` +
+    `which creates that comment or updates the existing one, so running it twice is safe`
+  );
 }
 
 /**
@@ -1620,6 +1874,33 @@ function bind(args) {
   console.log(`work-item bound: ${ref} (${file})`);
 }
 
+/**
+ * Establish the ticket-side backlink for one work item and pull request.
+ *
+ * Idempotent by construction — the writer updates the managed comment it finds
+ * rather than adding a second — so this is safe to run on every push, and safe
+ * to rerun after a failure without inspecting what the last run managed to do.
+ * @param {string[]} args CLI arguments.
+ */
+function backlink(args) {
+  const contract = trackerContract();
+  const supplied = option(args, "--ref", "LISA_WORK_ITEM_REF");
+  const bound = readState(true)?.ref;
+  if (!supplied && !bound) {
+    throw new TrackingError(
+      `${BACKLINK_COMMAND} requires --ref <work-item>, or a worktree binding from \`lisa-work-item.mjs link\``
+    );
+  }
+  const ref = canonicalizeRef(supplied ?? bound, contract);
+  const prUrl =
+    option(args, "--pr-url", "LISA_PR_URL") ??
+    option(args, "--url", "LISA_PR_URL");
+  if (!prUrl)
+    throw new TrackingError(`${BACKLINK_COMMAND} requires --pr-url <url>`);
+  const outcome = postBacklink(ref, prUrl, contract);
+  console.log(`work-item backlink ${outcome} on ${ref}: ${MARKER} ${prUrl}`);
+}
+
 function prepareCommitMessage(args) {
   const [file, source = ""] = args;
   if (!file)
@@ -1755,12 +2036,13 @@ function main() {
     rmSync(statePath(), { force: true });
     return console.log("work-item binding cleared");
   }
+  if (command === "backlink") return backlink(args);
   if (command === "prepare-commit-msg") return prepareCommitMessage(args);
   if (command === "validate-commit") return validateCommit(args);
   if (command === "validate-push") return validatePush(args);
   if (command === "validate-pr") return validatePr(args);
   throw new TrackingError(
-    "Usage: lisa-work-item.mjs link|current|attach-branch|clear|prepare-commit-msg|validate-commit|validate-push|validate-pr" +
+    "Usage: lisa-work-item.mjs link|current|attach-branch|clear|backlink|prepare-commit-msg|validate-commit|validate-push|validate-pr" +
       "\n(`bind` is accepted as an alias for `link`, but some agent harnesses refuse the token `bind` in a command line.)"
   );
 }

package/dist/configs/eslint/base.d.ts

@@ -1409,6 +1409,27 @@ export declare const getJsFilesOverride: () => {
         "max-lines-per-function": string;
     };
 };
+/**
+ * Glob patterns covering the repository-maintenance script tree that Lisa
+ * installs into every consumer (`scripts/`), plus nested `scripts/` trees such
+ * as `projects/<name>/scripts/`. Exported so the coverage test can assert the
+ * shipped `.mjs` paths land inside the same set the override targets.
+ */
+export declare const scriptsFilePatterns: string[];
+/**
+ * Standalone-script override — the rule profile for the `scripts/` tree.
+ *
+ * These files are repository-maintenance CLIs invoked by a developer or a CI
+ * runner, not application source and not published library API. They were
+ * previously excluded from linting entirely; that is the defect this override
+ * exists to make survivable. Every rule turned off here is turned off because
+ * it encodes an assumption about application code that a CLI script does not
+ * meet — correctness and bug-finding rules (including the SonarJS rules an
+ * external scanner also runs, e.g. `sonarjs/no-alphabetical-sort`) stay ON,
+ * because those are precisely what the exclusion was hiding.
+ * @returns {object} ESLint flat config object for standalone scripts
+ */
+export declare const getScriptsFilesOverride: () => Linter.Config;
 /**
  * Shared hooks and components override - relaxes import restrictions.
  * @returns {object} ESLint flat config object for shared files

package/dist/configs/eslint/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/configs/eslint/base.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/configs/eslint/base.ts"],"names":[],"mappings":"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"}