@codyswann/lisa 2.323.0 → 2.324.0

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

@@ -15,6 +15,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 
 const RELEASE_SUBJECT =
   /^chore\(release\): \d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)? \[skip ci\]$/;
@@ -27,6 +28,69 @@ const GUIDANCE = [
 
 class TrackingError extends Error {}
 
+/**
+ * Say which of three different failures a `gh` invocation actually hit.
+ *
+ * The three are indistinguishable from an exit status alone, and they send the
+ * reader to three different places: a missing binary is an environment to
+ * provision, a refused credential is an access grant to obtain, and only the
+ * third is anything to do with the ticket.
+ *
+ * Collapsing them cost a real round trip. On Claude Code web, where `gh` is not
+ * pre-installed, every commit was refused with "issue #2202 does not exist or
+ * is inaccessible" — about an issue that was open and correct. The message
+ * accused the ticket, so that is where the reader went.
+ * @param {{status: number|null, error?: Error, stderr?: string}} result Spawn result.
+ * @param {string} ref Work item reference, for the message.
+ * @param {string} noun What the reference names.
+ * @returns {string} A message naming the actual fault.
+ */
+export class TrackerUnreachableError extends TrackingError {}
+
+/**
+ * Turn a failed `gh` invocation into the right kind of refusal.
+ *
+ * The distinction is the whole point: a missing binary or a refused credential
+ * means the tracker could not be ASKED, while a "no" from the tracker is an
+ * answer. Absence of evidence is not evidence of absence, and only the first
+ * kind may be degraded — treating them alike would either strand finished work
+ * or wave through an item that genuinely is not committable.
+ * @param {{status: number|null, error?: Error, stderr?: string}} result Spawn result.
+ * @param {string} ref Work item reference.
+ * @returns {Error} The error to throw.
+ */
+export function githubFailure(result, ref) {
+  const reason = githubFailureReason(result, ref, "GitHub issue");
+  const unreachable =
+    result.error?.code === "ENOENT" || /cannot authenticate/.test(reason);
+  return unreachable
+    ? new TrackerUnreachableError(reason)
+    : new TrackingError(reason);
+}
+
+export function githubFailureReason(result, ref, noun) {
+  if (result.error?.code === "ENOENT") {
+    return (
+      `the GitHub CLI (gh) is not installed, so ${noun} ${ref} could not be ` +
+      `checked.\nThis is an environment gap, not a problem with the work item. ` +
+      `Pin gh in remoteEnv.tools.install for surfaces that lack it.`
+    );
+  }
+  const stderr = String(result.stderr ?? "");
+  if (
+    /not enabled for this session|gh auth login|HTTP 40[13]|Bad credentials|authentication/i.test(
+      stderr
+    )
+  ) {
+    return (
+      `the GitHub CLI cannot authenticate, so ${noun} ${ref} could not be ` +
+      `checked.\nThis is a credential gap, not a problem with the work item.` +
+      `\n${stderr.trim().slice(0, 300)}`
+    );
+  }
+  return `${noun} ${ref} does not exist or is inaccessible`;
+}
+
 function run(command, args, options = {}) {
   const result = spawnSync(command, args, {
     cwd: options.cwd ?? process.cwd(),
@@ -536,10 +600,7 @@ function githubIssue(ref, contract) {
       allowFailure: true,
     }
   );
-  if (result.status !== 0)
-    throw new TrackingError(
-      `GitHub issue ${ref} does not exist or is inaccessible`
-    );
+  if (result.status !== 0) throw githubFailure(result, ref);
   const issue = safeJson(result.stdout, `GitHub issue ${ref}`);
   if (String(issue.number) !== number)
     throw new TrackingError(`GitHub returned the wrong issue for ${ref}`);
@@ -775,10 +836,48 @@ function linearIssue(ref, contract) {
   return issue;
 }
 
+/**
+ * Ask the tracker whether this work item may be committed against.
+ *
+ * When the tracker cannot be REACHED, the live checks are reported as skipped
+ * rather than enforced or silently dropped. Everything checkable without a
+ * network — the trailer is present, well formed, and matches this branch's
+ * binding — has already run by the time this is called, and the semantic
+ * checks it cannot do here are re-run in CI by a REQUIRED status check
+ * ("Work-Item Traceability"), with credentials, before anything can merge.
+ *
+ * So the guarantee is not lost; it moves to a gate that cannot be bypassed.
+ * That is the whole justification, and it holds only while that check stays
+ * required — if it is ever made optional, this degradation becomes a hole.
+ *
+ * The alternative was worse in both directions. Refusing outright strands
+ * finished, green work on any surface without a GitHub credential — a cloud
+ * container, for one — and the agent's only remaining move is a bypass that
+ * skips the offline checks too. Enforcing nothing hides the difference between
+ * "could not ask" and "the tracker said no".
+ * @param {string} ref Work item reference.
+ * @param {object} [contract] Tracker contract.
+ * @returns {object|undefined} The live item, or undefined when unreachable.
+ */
 function validateLive(ref, contract = trackerContract()) {
-  if (contract.provider === "github") return githubIssue(ref, contract);
-  if (contract.provider === "jira") return jiraIssue(ref, contract);
-  return linearIssue(ref, contract);
+  try {
+    if (contract.provider === "github") return githubIssue(ref, contract);
+    if (contract.provider === "jira") return jiraIssue(ref, contract);
+    return linearIssue(ref, contract);
+  } catch (error) {
+    if (!(error instanceof TrackerUnreachableError)) throw error;
+    // Loud on stderr, never silent: a degradation nobody sees is the failure
+    // mode this exists to avoid, not a milder version of it.
+    console.error(
+      `\n⚠️  Work-item live validation SKIPPED for ${ref}.\n` +
+        `${error.message}\n\n` +
+        `The offline checks still ran: the trailer is present, well formed and ` +
+        `bound to this branch.\nWhat could not be checked here — that the item ` +
+        `is open, claimed and a leaf — is re-run\nwith credentials by the ` +
+        `required "Work-Item Traceability" check before this can merge.\n`
+    );
+    return undefined;
+  }
 }
 
 function textContainsBacklink(value, prUrl) {
@@ -797,6 +896,18 @@ function assertBacklink(
   contract,
   issue = validateLive(ref, contract)
 ) {
+  // The PR check never degrades, because it IS the re-check the local hooks
+  // degrade in favour of. A required status check that passes when it could
+  // not reach the tracker would make the whole arrangement circular: local
+  // defers to CI, CI defers to nothing.
+  if (!issue) {
+    throw new TrackingError(
+      `cannot verify ${ref} against the tracker, and this check is the one ` +
+        `that must.\nLocal hooks may skip live validation when the tracker ` +
+        `is unreachable; this check may not,\nbecause it is what they defer ` +
+        `to. Fix the tracker credential for this run.`
+    );
+  }
   if (contract.provider === "github") {
     const native = (issue.closedByPullRequestsReferences ?? []).some(
       pr => pr.url === prUrl
@@ -1165,12 +1276,40 @@ function main() {
   );
 }
 
-try {
-  main();
-} catch (error) {
-  const detail = error instanceof Error ? error.message : String(error);
-  console.error(
-    `\n❌ Work-item tracking blocked this operation: ${detail}\n\n${GUIDANCE}\n`
-  );
-  process.exitCode = 1;
+/**
+ * Run the CLI, reporting any refusal the way the Git hooks expect.
+ *
+ * Exported so the thin entrypoint at `scripts/lisa-work-item.mjs` can invoke it
+ * explicitly. That entrypoint re-exports this module rather than duplicating
+ * it, so inside here `import.meta.url` names THIS file while `argv[1]` names
+ * the entrypoint — the two never match, and a guard comparing them would leave
+ * Lisa's own hooks doing nothing at all, silently and with exit 0. An exported
+ * call is unambiguous where a path comparison is a guess.
+ */
+export function runCli() {
+  try {
+    main();
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    console.error(
+      `\n❌ Work-item tracking blocked this operation: ${detail}\n\n${GUIDANCE}\n`
+    );
+    process.exitCode = 1;
+  }
+}
+
+// Only when invoked as a program. Running on import made every function here
+// unreachable from a test: importing the module executed the CLI, so the only
+// way to exercise any of it was to spawn a process and drive it through the
+// filesystem and PATH. That is why a bug in the message above shipped — the
+// branch that produced it had no way to be asserted on.
+//
+// This branch covers a host project, where the file is copied to
+// `scripts/lisa-work-item.mjs` and invoked directly. Lisa's own checkout keeps
+// a re-exporting entrypoint instead, which calls runCli() itself.
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  runCli();
 }

package/dist/core/upstream-evidence-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upstream-evidence-manifest.d.ts","sourceRoot":"","sources":["../../src/core/upstream-evidence-manifest.ts"],"names":[],"mappings":"AACA,iFAAiF;AACjF,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgnEpE,CAAC;AAEL,4EAA4E;AAC5E,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAujNjE,CAAC;AAEL,sFAAsF;AACtF,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAk6I/D,CAAC"}
+{"version":3,"file":"upstream-evidence-manifest.d.ts","sourceRoot":"","sources":["../../src/core/upstream-evidence-manifest.ts"],"names":[],"mappings":"AACA,iFAAiF;AACjF,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAknEpE,CAAC;AAEL,4EAA4E;AAC5E,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CA4jNjE,CAAC;AAEL,sFAAsF;AACtF,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAk6I/D,CAAC"}

package/dist/core/upstream-evidence-manifest.js

@@ -3,7 +3,7 @@
 export const UPSTREAM_EVIDENCE_MANIFEST = Object.freeze({
     "all/copy-contents/.gitattributes": "9d3831007e681186a3673e1037ef3fc82980cab2fc04e27c0868e562912c9e9f",
     "all/copy-contents/gitignore": "2dbf7fd2f2020fc7824c432342002d9ca3ebb57b2872e761b14e942b23479a11",
-    "all/copy-overwrite/scripts/lisa-work-item.mjs": "5eb31c284e820a51312d4484f0669128007326af55ee515923fec33700d003a1",
+    "all/copy-overwrite/scripts/lisa-work-item.mjs": "6a8be8577242588f14ab52b25b2a22b6def53aefa9513b4d3d7c49f4d8027079",
     "all/create-only/.claude/rules/PROJECT_RULES.md": "6e1c7923ad2a15356babc60c97e7f97be728d790af285b6a7cd7d1b4d39cd97f",
     "all/create-only/.lisaignore": "3c9827e7e98daa46510b5357cd6dd9406da1821e64cc46d2eea9f311cd6d06b9",
     "all/create-only/scripts/remote-agent-aws-setup.sh": "7677908a345891810d2104ba8b2fd1a8318bb29c408fb5ce0110d57beef9b556",
@@ -559,11 +559,11 @@ export const UPSTREAM_EVIDENCE_MANIFEST = Object.freeze({
     "plugins/src/base/skills/lisa-setup-linear/SKILL.md": "ec76f832a6df6f58b163f7f5ba6826ed2fcbddc91e44a8372e874858e4d0c518",
     "plugins/src/base/skills/lisa-setup-notion/SKILL.md": "f5a1e9290789fd1c33675168d30461fb24a11c98a433ef777c1f536bc2f905ef",
     "plugins/src/base/skills/lisa-setup-remote-aws/SKILL.md": "80fbf157f9c562c033886c25a99b37356602edd9e61cd2d492f339769ddcf97e",
-    "plugins/src/base/skills/lisa-setup-remote-env/SKILL.md": "5627c45a4ce7d0f0d122791f699b6dd2841602adf873678c693ad08a48eab401",
-    "plugins/src/base/skills/lisa-setup-remote-env/assets/session-start.sh": "6e3871ec2f8d56b8ebb85376ebdd3956f3ed8fa4f7b278c2ed90ca9b8845897c",
+    "plugins/src/base/skills/lisa-setup-remote-env/SKILL.md": "821f9f7db39259c3aef24dc369c7cdcfb55a85d61742b32ac2a961e1b3e263a4",
+    "plugins/src/base/skills/lisa-setup-remote-env/assets/session-start.sh": "cb63d08b14ab7aa2d405e6770e0cf7db5d6588ae1dcb924ea6224b026fcff496",
     "plugins/src/base/skills/lisa-setup-remote-env/assets/setup.sh": "c04afb1cf8e14a2713645228e679fa7772559488330a240ec0297cae6afd03e2",
-    "plugins/src/base/skills/lisa-setup-remote-env/scripts/setup-remote-env.mjs": "68339117f7d2fe1fdb9f05c8039ffe719f24da7cf700bc3c940bfccbf82cded2",
-    "plugins/src/base/skills/lisa-setup-remote-env/scripts/toolchain.mjs": "ff66d33ba41a068d09be18f81ac68988238c2afa1d4e3733ae906b73eea74324",
+    "plugins/src/base/skills/lisa-setup-remote-env/scripts/setup-remote-env.mjs": "1f451881342364d086640b59914a3b07286a3734caa63f01efe64531d3bde7e4",
+    "plugins/src/base/skills/lisa-setup-remote-env/scripts/toolchain.mjs": "8822af39d0251a2e4fb0eac9157ba9e63ea813d914240ca0cacacd6cb7cbb5bb",
     "plugins/src/base/skills/lisa-setup-remote-env/scripts/verify-remote-env.mjs": "82bc2a27a0a5afb2ff413a88365c619fd7f0eaada5de3ccabf2000938f0607a4",
     "plugins/src/base/skills/lisa-setup-sonar/SKILL.md": "53fbd8acce4b5e47e88195a7b90d5be424fa6ef7ad872f52c50467c690664c3b",
     "plugins/src/base/skills/lisa-sonarcloud-access/SKILL.md": "031acb01195ae59010a65335da98d46a1d6080e749823d6f6d157938d9e96648",
@@ -985,14 +985,15 @@ export const UPSTREAM_EVIDENCE_MANIFEST = Object.freeze({
     "scripts/lib/reusable-workflow-contract.d.mts": "791f01b55dd7a6b5d9a5f4cb9c44167caa146c2fc3c31a2ae4c2d8a350adc2f1",
     "scripts/lib/reusable-workflow-contract.mjs": "134ee2a327290f066f1eb318b5ed53c711557c3e10ed462c00ff5c97cfb20863",
     "scripts/lisa-commit-and-pr-local.sh": "605409c3ce6ec38ad3275604291a1ceae98f7807a605654263bc14f811c03903",
+    "scripts/lisa-enforcement-fallback.sh": "8dc942ac4edc2017d6b8277296c8f80542e7c024eef1bb65de609979d0ca9a0e",
     "scripts/lisa-github-environments.sh": "0a76e92f108519abaf3e29991299ec3b0db20ea533e69e6d2a53d802dba9c370",
     "scripts/lisa-github-repo-settings.sh": "4afbccdfb08c62ba13afee42ec8561a28facf87c61f6f4b80000115328364d54",
     "scripts/lisa-github-repo-setup.sh": "dc2f1c9d718aa34ba57161120d9319b5f78fe6b0b496d8e3c77226a08795aa36",
     "scripts/lisa-github-rulesets.sh": "920a43ba268421b6fe55096062bd85850468bee9389f6006ad7c671010e7cccb",
-    "scripts/lisa-remote-env/session-start.sh": "6e3871ec2f8d56b8ebb85376ebdd3956f3ed8fa4f7b278c2ed90ca9b8845897c",
+    "scripts/lisa-remote-env/session-start.sh": "cb63d08b14ab7aa2d405e6770e0cf7db5d6588ae1dcb924ea6224b026fcff496",
     "scripts/lisa-remote-env/setup.sh": "c04afb1cf8e14a2713645228e679fa7772559488330a240ec0297cae6afd03e2",
     "scripts/lisa-update-local.sh": "c811f9e10dbcb38499a9791c1ae9051460b347051d04a1d2046925bab9a53c96",
-    "scripts/lisa-work-item.mjs": "acb359ed7a39150fd5e1e68f4c95144045e75d9d53b735da4a7a9271f063044e",
+    "scripts/lisa-work-item.mjs": "51081847e980f314a764c2e50a7a121b1ced9ef4b980f33898057de4c7b852e6",
     "scripts/migrate-deploy-order.sh": "77d909b4cbbfc05169a79168d7868600ea7f56f846feefb7d5121618c54800c3",
     "scripts/plugin-parity-drift.mjs": "34235c4c75c8735aaca96e3e0a52073ba1dee8bad54c85af01c3cf9912d0ea57",
     "scripts/plugin-routing-validate.mjs": "eb38cf139eb04a27dd6493ff6f766945060d5bf73a35856bd3da4c8e4110e2ba",
@@ -6543,6 +6544,7 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "scripts/lib/reusable-workflow-contract.d.mts": true,
     "scripts/lib/reusable-workflow-contract.mjs": true,
     "scripts/lisa-commit-and-pr-local.sh": true,
+    "scripts/lisa-enforcement-fallback.sh": true,
     "scripts/lisa-github-environments.sh": true,
     "scripts/lisa-github-repo-settings.sh": true,
     "scripts/lisa-github-repo-setup.sh": true,
@@ -7174,6 +7176,7 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "tests/unit/hooks/enforce-verification-gate-preserve.test.ts": true,
     "tests/unit/hooks/enforce-verification-gate-v1.test.ts": true,
     "tests/unit/hooks/enforce-verification-gate-v2.test.ts": true,
+    "tests/unit/hooks/enforcement-fallback.test.ts": true,
     "tests/unit/hooks/enforcement-gates-e2e.test.ts": true,
     "tests/unit/hooks/inject-rules.test.ts": true,
     "tests/unit/hooks/install-pkgs-worktree-node-modules.test.ts": true,
@@ -7252,6 +7255,8 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "tests/unit/scripts/threshold-ratchet.test.ts": true,
     "tests/unit/scripts/upstream-evidence-manifest.test.ts": true,
     "tests/unit/scripts/verification-coverage.test.ts": true,
+    "tests/unit/scripts/work-item-github-failure-diagnosis.test.ts": true,
+    "tests/unit/scripts/work-item-tracker-unreachable.test.ts": true,
     "tests/unit/secrets/automation-workflow.test.ts": true,
     "tests/unit/secrets/bootstrap-key-naming.test.ts": true,
     "tests/unit/secrets/doctor-secrets.test.ts": true,
@@ -7260,6 +7265,7 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "tests/unit/secrets/remote-env-bindir-path.test.ts": true,
     "tests/unit/secrets/remote-env-installed-copy.test.ts": true,
     "tests/unit/secrets/remote-env-phases.test.ts": true,
+    "tests/unit/secrets/remote-env-session-start-hook.test.ts": true,
     "tests/unit/secrets/remote-env-setup-field.test.ts": true,
     "tests/unit/secrets/remote-env-skill-resolution.test.ts": true,
     "tests/unit/secrets/remote-env-toolchain.test.ts": true,