@codyswann/lisa 4.22.6 → 4.22.8

package/plugins/src/base/skills/lisa-tracker-sync/SKILL.md

@@ -21,7 +21,27 @@ See the `config-resolution` rule for configuration and dispatch table.
    - Anything else → stop and report `"Unknown tracker '<value>' in .lisa.config.json. Expected 'jira', 'github', or 'linear'."`
 3. Pass through the output.
 
-`$ARGUMENTS` is forwarded verbatim, including the optional `--rollup` flag (see "Parent status rollup" below), the vendor lane-write flag (`--update-label` on GitHub, `--update-state` on Linear), `pr_url=<url>`, and `merge_sha=<sha>`. The shim never interprets these — the vendor skill does.
+`$ARGUMENTS` is forwarded verbatim, including the optional `--rollup` flag (see "Parent status rollup" below), `pr_url=<url>`, and `merge_sha=<sha>`. The shim never interprets these — the vendor skill does.
+
+> **There is no per-milestone lane-write flag on any vendor.** This paragraph previously documented `--update-label` on GitHub and `--update-state` on Linear. `--update-label` was never implemented — `lisa-github-sync` says flatly *"This skill never relabels"* — so a caller passing it got a silent no-op on GitHub and a real write on Linear for the equivalent flag. Both are gone. `--rollup` is the only write path a sync skill has.
+
+## Tracker status vocabulary — binding on all three arms
+
+Every suggested or performed transition names **only a role the project configured**, never a status, state or label discovered from the tracker's live workflow (transition lists, board columns, `type`-derived matches, other tickets). This binds a lead performing tracker writes exactly as it binds a subagent.
+
+Two consequences the vendor arms must not restate differently:
+
+- **A milestone whose role is unset gets a comment, not a transition.** `review` and the `qa.*` roles are optional and carry **no default** — omitting one means the project does not run that step, and the lifecycle skips it. "Unset" must never resolve to a built-in name; that is the difference between "not customized" and "we deliberately don't do this".
+- **A fallback may inform a read; it may never supply a write target.** Where a vendor exposes one (Linear resolves states by `type`), it selects by board position rather than intent — so on a board carrying more than one plausible state it returns whichever sits earliest, which is exactly the human-only lane a project left out of its config on purpose.
+
+Resolve roles through the shared resolver rather than an inlined helper:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-lifecycle-role.mjs" \
+  --role <role> --vendor <jira|linear|github> --intent <read|write> [--env <env>]
+```
+
+Exit `0` with a value means configured; exit `0` with **empty** output means an optional role is unset — skip the transition; exit `2` means a required role is unset or a write was refused a fallback value.
 
 If `$ARGUMENTS` is empty, all vendor skills auto-detect a ticket reference from the active plan file (most recently modified `.md` in `plans/`).
 
@@ -65,6 +85,6 @@ This is the reverse half of `lisa-git-submit-pr`'s PR body linkage. A PR that me
 ## Rules
 
 - Idempotent updates — running sync at the same milestone twice should not produce duplicate comments. Vendor skills enforce this.
-- Never auto-transition a lane the caller did not ask for. On GitHub the canonical signal is the `status:*` label, written only with `--update-label`; on Linear it is the native workflow state, written only with `--update-state`. Without the flag, every vendor arm only suggests.
+- Never transition a leaf's lane from a sync milestone on any vendor. The canonical signal differs — the `status:*` label on GitHub, the workflow status on JIRA, the native workflow state on Linear — but the owner is the same everywhere: build-intake / the vendor agent. Every arm only suggests. `--rollup` (parent derivation) is the sole exception, and it derives the parent from its children rather than advancing a leaf.
 - Parent rollup derives state from children per the `leaf-only-lifecycle` rule; it never sets a parent to `ready` and never resolves a dev/staging `done` in this single-environment repo.
 - Pull request backlinks are mandatory when `pr_url=<url>` is present: native first, managed-comment fallback, never silently dropped.

package/scripts/check-release-package-identity.mjs

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+// This file is managed by Lisa and IS replaced on each `lisa` run.
+// Do not edit directly — durable changes belong upstream in Lisa.
+
+/**
+ * Fail closed when a release checkout or packed npm candidate does not bind to
+ * one immutable version and commit.
+ *
+ * Release workflows have two separate state transitions: standard-version
+ * writes and pushes the release commit, then npm builds and publishes a tagged
+ * checkout. A tag aimed at the pre-release merge let the second transition
+ * compile stale generated source and only afterwards rewrite package.json. This
+ * checker makes both boundaries executable: `checkout` proves tag/HEAD/commit
+ * identity before build, and `pack` proves the exact tarball passed to
+ * `npm publish` contains matching package metadata and generated certificate.
+ *
+ * Projects without Lisa's nightly certificate still receive the generic
+ * version/commit/tarball checks. When the source certificate exists, its built
+ * and packed counterpart becomes mandatory.
+ * @module scripts/check-release-package-identity
+ */
+import { createHash } from "node:crypto";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+} from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+import { boundedExecFileSync } from "./lib/bounded-spawn.mjs";
+import { invokedAsScript } from "./lib/invoked-as-script.mjs";
+
+const RELEASE_COMMIT_PATTERN = /^[a-f0-9]{40}$/u;
+const SOURCE_CERTIFICATE = "src/core/nightly-e2e-guard-behavior-certificate.ts";
+const PACKED_CERTIFICATE =
+  "package/dist/core/nightly-e2e-guard-behavior-certificate.js";
+
+/** Raise one consistently named fail-closed identity error. */
+function mismatch(message) {
+  throw new Error(`Release package identity mismatch: ${message}`);
+}
+
+/** Return a required CLI option. */
+function requiredOption(argv, name) {
+  const index = argv.indexOf(name);
+  const value = index >= 0 ? argv[index + 1] : undefined;
+  if (!value || value.startsWith("--")) mismatch(`missing required ${name}`);
+  return value;
+}
+
+/** Resolve one git revision to its immutable commit. */
+function gitCommit(root, revision) {
+  try {
+    return String(
+      boundedExecFileSync("git", ["rev-parse", `${revision}^{commit}`], {
+        cwd: root,
+        encoding: "utf8",
+      })
+    ).trim();
+  } catch {
+    mismatch(`could not resolve git revision ${revision}`);
+  }
+}
+
+/** Parse one JSON file with a release-specific diagnostic. */
+function readJson(filePath, label) {
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+  } catch {
+    mismatch(`${label} is missing or invalid JSON (${filePath})`);
+  }
+}
+
+/** SHA-256 for an immutable file or member. */
+function sha256(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+/** Read one tar member without extracting paths into the checkout. */
+function tarMember(tarballPath, member) {
+  try {
+    return Buffer.from(
+      boundedExecFileSync("tar", ["-xOf", tarballPath, member])
+    );
+  } catch {
+    mismatch(`packed candidate does not contain ${member}`);
+  }
+}
+
+/** Extract the one workspace package version certified by generated bytes. */
+function certificateVersion(bytes, label) {
+  const match = String(bytes).match(
+    /workspace package @codyswann\/lisa@([^\s"'()]+)\s*\(/u
+  );
+  if (!match?.[1]) mismatch(`${label} has no workspace package provenance`);
+  return match[1];
+}
+
+/** Require a valid immutable release commit spelling. */
+export function assertReleaseCommit(releaseCommit) {
+  if (!RELEASE_COMMIT_PATTERN.test(releaseCommit)) {
+    mismatch(
+      `release commit must be 40 lowercase hexadecimal characters; got ${JSON.stringify(releaseCommit)}`
+    );
+  }
+  return releaseCommit;
+}
+
+/**
+ * Prove that the checked-out tag and HEAD name the supplied release commit.
+ * @param {{root: string, releaseCommit: string, tag: string}} input Identity input
+ * @returns {{headCommit: string, tagCommit: string, releaseCommit: string}}
+ */
+export function assertCheckoutIdentity({ root, releaseCommit, tag }) {
+  assertReleaseCommit(releaseCommit);
+  const headCommit = gitCommit(root, "HEAD");
+  if (headCommit !== releaseCommit) {
+    mismatch(
+      `HEAD ${headCommit} does not match release commit ${releaseCommit}`
+    );
+  }
+  const tagCommit = gitCommit(root, tag);
+  if (tagCommit !== releaseCommit) {
+    mismatch(`tag ${tag} resolves ${tagCommit}, expected ${releaseCommit}`);
+  }
+  return Object.freeze({ headCommit, tagCommit, releaseCommit });
+}
+
+/**
+ * Pack and validate the exact candidate later passed to npm publish.
+ * @param {{root: string, version: string, releaseCommit: string, packDestination: string}} input Candidate input
+ * @returns {{version: string, releaseCommit: string, certificateVersion: string|null, tarballPath: string, tarballSha256: string, certificateMemberSha256: string|null}}
+ */
+export function packAndValidateReleaseCandidate({
+  root,
+  version,
+  releaseCommit,
+  packDestination,
+}) {
+  assertReleaseCommit(releaseCommit);
+  const packageJson = readJson(path.join(root, "package.json"), "package.json");
+  if (packageJson.version !== version) {
+    mismatch(
+      `package.json version ${JSON.stringify(packageJson.version)} expected ${version}`
+    );
+  }
+  if (packageJson.lisaReleaseCommit !== releaseCommit) {
+    mismatch(
+      `package.json lisaReleaseCommit ${JSON.stringify(packageJson.lisaReleaseCommit)} expected ${releaseCommit}`
+    );
+  }
+  if (packageJson.gitHead !== releaseCommit) {
+    mismatch(
+      `package.json gitHead ${JSON.stringify(packageJson.gitHead)} expected ${releaseCommit}`
+    );
+  }
+
+  const sourceCertificatePath = path.join(root, SOURCE_CERTIFICATE);
+  const hasCertificate = existsSync(sourceCertificatePath);
+  if (hasCertificate) {
+    const sourceVersion = certificateVersion(
+      readFileSync(sourceCertificatePath),
+      "source certificate"
+    );
+    if (sourceVersion !== version) {
+      mismatch(
+        `source certificate names ${sourceVersion}, expected ${version}`
+      );
+    }
+  }
+
+  mkdirSync(packDestination, { recursive: true });
+  if (readdirSync(packDestination).length !== 0) {
+    mismatch(`pack destination must be empty (${packDestination})`);
+  }
+  let packOutput;
+  try {
+    packOutput = String(
+      boundedExecFileSync(
+        "npm",
+        [
+          "pack",
+          "--ignore-scripts",
+          "--silent",
+          "--pack-destination",
+          packDestination,
+        ],
+        { cwd: root, encoding: "utf8", timeout: 120_000 }
+      )
+    );
+  } catch (error) {
+    mismatch(
+      `npm pack failed before publication (${error instanceof Error ? error.message : String(error)})`
+    );
+  }
+  const candidates = readdirSync(packDestination).filter(file =>
+    file.endsWith(".tgz")
+  );
+  if (candidates.length !== 1) {
+    mismatch("npm pack did not report exactly one candidate tarball");
+  }
+  const reportedCandidate = packOutput
+    .split(/\r?\n/u)
+    .map(line => line.trim())
+    .filter(Boolean)
+    .at(-1);
+  if (path.basename(reportedCandidate ?? "") !== candidates[0]) {
+    mismatch(
+      `npm pack reported ${JSON.stringify(reportedCandidate)}, wrote ${JSON.stringify(candidates[0])}`
+    );
+  }
+
+  const tarballPath = path.resolve(packDestination, candidates[0]);
+  const tarballBytes = readFileSync(tarballPath);
+  const packedPackage = JSON.parse(
+    String(tarMember(tarballPath, "package/package.json"))
+  );
+  if (packedPackage.version !== version) {
+    mismatch(
+      `packed package version ${JSON.stringify(packedPackage.version)} expected ${version}`
+    );
+  }
+  if (packedPackage.lisaReleaseCommit !== releaseCommit) {
+    mismatch(
+      `packed lisaReleaseCommit ${JSON.stringify(packedPackage.lisaReleaseCommit)} expected ${releaseCommit}`
+    );
+  }
+  if (packedPackage.gitHead !== releaseCommit) {
+    mismatch(
+      `packed gitHead ${JSON.stringify(packedPackage.gitHead)} expected ${releaseCommit}`
+    );
+  }
+
+  let packedCertificateVersion = null;
+  let certificateMemberSha256 = null;
+  if (hasCertificate) {
+    const member = tarMember(tarballPath, PACKED_CERTIFICATE);
+    packedCertificateVersion = certificateVersion(member, "packed certificate");
+    if (packedCertificateVersion !== version) {
+      mismatch(
+        `packed certificate names ${packedCertificateVersion}, expected ${version} at release commit ${releaseCommit} (${PACKED_CERTIFICATE})`
+      );
+    }
+    certificateMemberSha256 = sha256(member);
+  }
+
+  return Object.freeze({
+    version,
+    releaseCommit,
+    certificateVersion: packedCertificateVersion,
+    tarballPath,
+    tarballSha256: sha256(tarballBytes),
+    certificateMemberSha256,
+  });
+}
+
+/** Append validated tarball identity to a GitHub Actions step output. */
+function writeGithubOutput(result, outputPath) {
+  if (!outputPath) return;
+  if (result.tarballPath.includes("\n") || result.tarballPath.includes("\r")) {
+    mismatch("candidate tarball path contains a line break");
+  }
+  appendFileSync(
+    outputPath,
+    [
+      `tarball=${result.tarballPath}`,
+      `tarball_sha256=${result.tarballSha256}`,
+      `certificate_member_sha256=${result.certificateMemberSha256 ?? "not-applicable"}`,
+      "",
+    ].join("\n")
+  );
+}
+
+/** Execute the checkout or pack CLI boundary. */
+export function runReleasePackageIdentityCli(
+  argv,
+  { root = process.cwd(), githubOutput = process.env.GITHUB_OUTPUT } = {}
+) {
+  const [mode, ...options] = argv;
+  if (mode === "checkout") {
+    const result = assertCheckoutIdentity({
+      root,
+      releaseCommit: requiredOption(options, "--release-commit"),
+      tag: requiredOption(options, "--tag"),
+    });
+    process.stdout.write(
+      `RELEASE_CHECKOUT_IDENTITY_OK ${JSON.stringify(result)}\n`
+    );
+    return 0;
+  }
+  if (mode === "pack") {
+    const result = packAndValidateReleaseCandidate({
+      root,
+      version: requiredOption(options, "--version"),
+      releaseCommit: requiredOption(options, "--release-commit"),
+      packDestination: requiredOption(options, "--pack-destination"),
+    });
+    writeGithubOutput(result, githubOutput);
+    process.stdout.write(
+      `RELEASE_PACKAGE_IDENTITY_OK ${JSON.stringify(result)}\n`
+    );
+    return 0;
+  }
+  mismatch("expected mode checkout or pack");
+}
+
+if (invokedAsScript(import.meta.url)) {
+  try {
+    process.exitCode = runReleasePackageIdentityCli(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(
+      `${error instanceof Error ? error.message : String(error)}\n`
+    );
+    process.exitCode = 1;
+  }
+}

package/scripts/two-channel-couplings.json

@@ -5,13 +5,13 @@
   },
   "inspected": {
     "workflows": 23,
-    "steps": 636,
-    "couplings": 26,
-    "inventory": 56
+    "steps": 639,
+    "couplings": 27,
+    "inventory": 57
   },
   "counts": {
     "package-backed": 10,
-    "apply-lagged": 14,
+    "apply-lagged": 15,
     "never-delivered": 0,
     "undelivered": 2
   },
@@ -68,6 +68,19 @@
       ],
       "detail": "`nightly-e2e-report.yml` is delivered at `@main`, so this step is live in every consumer on their next run. It reads `scripts/check-nightly-e2e-health.mjs` from the CALLER's tree with no package-relative candidate, and Lisa delivers that path on the `lisa apply` channel (typescript/copy-overwrite). The two halves land in the wrong order: this step is live everywhere immediately, the file it needs is live only where somebody applied. The read is unguarded, so an absent path fails the job loudly. Visible, which makes it the better of the two failures."
     },
+    {
+      "key": "publish-to-npm.yml::scripts/check-release-package-identity.mjs",
+      "workflow": "publish-to-npm.yml",
+      "path": "scripts/check-release-package-identity.mjs",
+      "channel": "apply",
+      "verdict": "apply-lagged",
+      "remedy": "run-lisa-apply",
+      "guarded": false,
+      "lanes": [
+        "all/copy-overwrite"
+      ],
+      "detail": "`publish-to-npm.yml` is delivered at `@main`, so this step is live in every consumer on their next run. It reads `scripts/check-release-package-identity.mjs` from the CALLER's tree with no package-relative candidate, and Lisa delivers that path on the `lisa apply` channel (all/copy-overwrite). The two halves land in the wrong order: this step is live everywhere immediately, the file it needs is live only where somebody applied. The read is unguarded, so an absent path fails the job loudly. Visible, which makes it the better of the two failures."
+    },
     {
       "key": "quality-rails.yml::scripts/check-threshold-ratchet.mjs",
       "workflow": "quality-rails.yml",

package/typescript/copy-overwrite/.prettierignore

@@ -68,6 +68,7 @@ scripts/check-conflict-markers.mjs
 scripts/check-e2e-coverage.mjs
 scripts/check-lighthouse-details.mjs
 scripts/check-nightly-e2e-health.mjs
+scripts/check-release-package-identity.mjs
 scripts/check-skipped-required-checks.mjs
 scripts/check-state-classification.mjs
 scripts/check-threshold-ratchet.mjs