@codyswann/lisa 4.54.13 → 4.55.0

package/dist/core/ownership-header.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ownership-header.d.ts","sourceRoot":"","sources":["../../src/core/ownership-header.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,UAAU,CAAC;AAE1C;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,6DAA6D;AAC7D,MAAM,MAAM,eAAe;AACzB,wDAAwD;AACtD,cAAc;AAChB,sEAAsE;GACpE,iBAAiB;AACnB,oEAAoE;GAClE,gBAAgB,CAAC;AAErB;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CASzE"}

package/dist/core/ownership-header.js

@@ -0,0 +1,76 @@
+/**
+ * The ownership contract a Lisa template states about itself, in its own first
+ * lines, and the bounded read that recovers it from a file on disk.
+ *
+ * Every template Lisa ships carries one of exactly two headers, and which one
+ * is enforced repo-wide by `tests/unit/templates/template-ownership-header.test.ts`:
+ *
+ * - **`copy-overwrite`**: "This file is managed by Lisa and IS replaced on each
+ *   `lisa` run." Lisa asserts ownership of the bytes.
+ * - **`create-only`**: "Seeded by Lisa on first setup — this file is YOURS.
+ *   Lisa will not overwrite it." Lisa disclaims ownership at seed time.
+ *
+ * The headers are not decoration; they are opposite contracts, and more than
+ * one guard has to read them. `core/workflow-deletion-ownership` reads one to
+ * decide whether Lisa may delete a file, and `core/stale-managed-banner` reads
+ * the same one to decide whether the sentence is still TRUE. Both need the
+ * marker strings, the precedence between them, and the bound on how far into
+ * the file counts as "the header" — and a second copy of any of the three
+ * would drift silently, which is the failure mode both callers exist to end.
+ * So the reading lives here once and the callers ask it questions.
+ * @module core/ownership-header
+ */
+/**
+ * The sentence a `copy-overwrite` template carries, minus its comment prefix.
+ *
+ * Matched as a substring rather than a whole line because the prefix differs by
+ * file type (`#`, `//`, ` *`) and the wording has been revised once already —
+ * the retired header said "changes will be overwritten on the next `lisa` run".
+ * Both spellings contain this phrase, so a consumer still holding a years-old
+ * Lisa artifact is still correctly attributed.
+ */
+export const LISA_MANAGED_MARKER = "managed by Lisa";
+/**
+ * The word a `create-only` seed header shouts, minus its comment prefix.
+ *
+ * "YOURS" is the load-bearing token of that contract and the one the header
+ * test asserts. A file carrying it came out of Lisa's template tree AND was
+ * handed to the consumer.
+ */
+export const LISA_SEEDED_MARKER = "YOURS";
+/**
+ * How many leading lines of a file count as its ownership header.
+ *
+ * Bounded on purpose. A whole-file search would let any mention of Lisa
+ * anywhere in a consumer's file — a step name, a comment about a Lisa command —
+ * read as an ownership claim, which is the false-positive direction. Every
+ * shipped template puts its header on the first two lines; four covers a
+ * leading `---` document marker, a shebang, or a blank line above it and still
+ * stops short of any file body.
+ */
+export const OWNERSHIP_HEADER_LINES = 4;
+/**
+ * Read the ownership contract a file states about itself.
+ *
+ * Precedence is seed-before-managed. A `create-only` header mentions
+ * `copy-overwrite` in its own second line, so a naive managed-first check would
+ * read every seeded file as Lisa-managed — which, on the deletion path, deletes
+ * files Lisa promised to keep (CodySwannGT/lisa#3656) and, on the banner path,
+ * reports a truthful seed header as a false managed one. Ordering it this way
+ * means the strongest claim a file can make is the one that keeps it.
+ * @param contents - Raw text of the file, or a leading prefix of it long enough
+ *   to contain {@link OWNERSHIP_HEADER_LINES} lines
+ * @returns The contract its header states
+ */
+export function classifyOwnershipHeader(contents) {
+    const header = contents
+        .split("\n")
+        .slice(0, OWNERSHIP_HEADER_LINES)
+        .join("\n");
+    if (header.includes(LISA_SEEDED_MARKER))
+        return "host-owned-seed";
+    return header.includes(LISA_MANAGED_MARKER)
+        ? "lisa-managed"
+        : "unattributable";
+}
+//# sourceMappingURL=ownership-header.js.map

package/dist/core/ownership-header.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ownership-header.js","sourceRoot":"","sources":["../../src/core/ownership-header.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAC;AAE1C;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAWxC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAAgB;IACtD,MAAM,MAAM,GAAG,QAAQ;SACpB,KAAK,CAAC,IAAI,CAAC;SACX,KAAK,CAAC,CAAC,EAAE,sBAAsB,CAAC;SAChC,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,IAAI,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAC;QAAE,OAAO,iBAAiB,CAAC;IAClE,OAAO,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAC;QACzC,CAAC,CAAC,cAAc;QAChB,CAAC,CAAC,gBAAgB,CAAC;AACvB,CAAC"}

package/dist/core/rails-deploy-production-intent.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The repository secret that has to exist before `- main` may be uncommented.
+ *
+ * Load-bearing, and the reason this is the marker of an actionable
+ * explanation rather than any prose at all: `noliran/branch-based-secrets`
+ * expands `AWS_ACCOUNT_ID` into `AWS_ACCOUNT_ID_<BRANCH IN UPPERCASE>`, so a
+ * `main` trigger without this secret resolves an empty account id and fails at
+ * the credentials step. A comment saying only "enable when ready" is the bare
+ * marker with more words.
+ */
+export declare const PRODUCTION_ACCOUNT_SECRET = "AWS_ACCOUNT_ID_MAIN";
+/**
+ * What a deploy workflow says about deploying production.
+ *
+ * `unstated` is the defect: production is off and the file gives no reason,
+ * so a reader cannot tell a decision from an accident. The other three are
+ * all fine, and are kept apart because they are different facts about the
+ * project, not different renderings of "nothing to report".
+ */
+export type ProductionDeployIntent = 
+/** A live `main` entry: production deploys, deliberately. */
+"triggers"
+/** Commented out, with the enabling precondition named. */
+ | "explained"
+/** Commented out, bare. */
+ | "unstated"
+/** No `main` entry at all, live or commented. */
+ | "unmentioned";
+/**
+ * Classify what a deploy workflow says about production deployment.
+ * @param workflowText - Full deploy workflow source
+ * @returns The intent the workflow states, or fails to
+ * @throws {Error} When the workflow cannot be parsed as YAML
+ */
+export declare function classifyProductionDeployIntent(workflowText: string): ProductionDeployIntent;
+//# sourceMappingURL=rails-deploy-production-intent.d.ts.map

package/dist/core/rails-deploy-production-intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rails-deploy-production-intent.d.ts","sourceRoot":"","sources":["../../src/core/rails-deploy-production-intent.ts"],"names":[],"mappings":"AA6BA;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,wBAAwB,CAAC;AAW/D;;;;;;;GAOG;AACH,MAAM,MAAM,sBAAsB;AAChC,6DAA6D;AAC3D,UAAU;AACZ,2DAA2D;GACzD,WAAW;AACb,2BAA2B;GACzB,UAAU;AACZ,iDAAiD;GAC/C,aAAa,CAAC;AAuBlB;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,YAAY,EAAE,MAAM,GACnB,sBAAsB,CAMxB"}

package/dist/core/rails-deploy-production-intent.js

@@ -0,0 +1,79 @@
+/**
+ * Does a Rails deploy workflow SAY why it does not deploy production?
+ *
+ * The Rails deploy template shipped `# - main` commented out with nothing
+ * beside it, which reads exactly like a line someone forgot to restore. The
+ * seed was fixed, but that file is `create-only`: Lisa writes it once and
+ * never again, so every project seeded before the fix still carries the bare
+ * marker and nothing in the toolchain looks for it. The population is not
+ * merely unfixed, it is unknown — which is what this module exists to end
+ * (CodySwannGT/lisa#3743, CodySwannGT/lisa#3779).
+ *
+ * The classification lives here, apart from both callers, because two
+ * surfaces have to ask the identical question: the regression guard on the
+ * shipped template, and the `lisa doctor` check that lets an already-seeded
+ * project find itself. Two spellings of "bare" would drift, and the drift
+ * would be silent in the direction that matters — a doctor check quietly
+ * accepting a shape the seed guard rejects.
+ *
+ * Every answer here is derived from the workflow text alone, and the one
+ * answer it cannot derive — a document it cannot parse — is thrown rather
+ * than folded into "production is off". Guessing "no live `main`" out of
+ * unparsed YAML would report an ENABLED production deploy as withheld.
+ * @module core/rails-deploy-production-intent
+ */
+import { loadYaml } from "../utils/yaml.js";
+/** Branch this template deploys production from. */
+const PRODUCTION_BRANCH = "main";
+/**
+ * The repository secret that has to exist before `- main` may be uncommented.
+ *
+ * Load-bearing, and the reason this is the marker of an actionable
+ * explanation rather than any prose at all: `noliran/branch-based-secrets`
+ * expands `AWS_ACCOUNT_ID` into `AWS_ACCOUNT_ID_<BRANCH IN UPPERCASE>`, so a
+ * `main` trigger without this secret resolves an empty account id and fails at
+ * the credentials step. A comment saying only "enable when ready" is the bare
+ * marker with more words.
+ */
+export const PRODUCTION_ACCOUNT_SECRET = "AWS_ACCOUNT_ID_MAIN";
+/**
+ * A commented-out production entry in a `branches:` list, in the spellings a
+ * YAML sequence entry can take. Anchored end-to-end so a line that comments
+ * out `- main` AND says something is not matched here — that text is what
+ * `PRODUCTION_ACCOUNT_SECRET` is then asked about.
+ */
+const COMMENTED_PRODUCTION_ENTRY = /^[ \t]*#[ \t]*-[ \t]*(?:"main"|'main'|main)[ \t]*\r?$/mu;
+/**
+ * Branches the workflow pushes on, as YAML actually parses them.
+ *
+ * `on:` is YAML 1.1 truthy, so a parser may key the trigger block as `true`;
+ * both spellings are read. A scalar `branches:` is one branch.
+ * @param workflowText - Full deploy workflow source
+ * @returns Every push branch the workflow declares
+ * @throws {Error} When the document cannot be parsed
+ */
+function pushBranches(workflowText) {
+    const document = loadYaml(workflowText);
+    const branches = (document?.on ?? document?.true)?.push?.branches;
+    if (typeof branches === "string")
+        return [branches];
+    return Array.isArray(branches)
+        ? branches.filter((entry) => typeof entry === "string")
+        : [];
+}
+/**
+ * Classify what a deploy workflow says about production deployment.
+ * @param workflowText - Full deploy workflow source
+ * @returns The intent the workflow states, or fails to
+ * @throws {Error} When the workflow cannot be parsed as YAML
+ */
+export function classifyProductionDeployIntent(workflowText) {
+    if (pushBranches(workflowText).includes(PRODUCTION_BRANCH))
+        return "triggers";
+    if (!COMMENTED_PRODUCTION_ENTRY.test(workflowText))
+        return "unmentioned";
+    return workflowText.includes(PRODUCTION_ACCOUNT_SECRET)
+        ? "explained"
+        : "unstated";
+}
+//# sourceMappingURL=rails-deploy-production-intent.js.map

package/dist/core/rails-deploy-production-intent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rails-deploy-production-intent.js","sourceRoot":"","sources":["../../src/core/rails-deploy-production-intent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,oDAAoD;AACpD,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAEjC;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,qBAAqB,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,0BAA0B,GAC9B,yDAAyD,CAAC;AAoB5D;;;;;;;;GAQG;AACH,SAAS,YAAY,CAAC,YAAoB;IACxC,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAG9B,CAAC;IACT,MAAM,QAAQ,GAAG,CAAC,QAAQ,EAAE,EAAE,IAAI,QAAQ,EAAE,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC;IAClE,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpD,OAAO,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;QAC5B,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC;QACxE,CAAC,CAAC,EAAE,CAAC;AACT,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,8BAA8B,CAC5C,YAAoB;IAEpB,IAAI,YAAY,CAAC,YAAY,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAC;QAAE,OAAO,UAAU,CAAC;IAC9E,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,YAAY,CAAC;QAAE,OAAO,aAAa,CAAC;IACzE,OAAO,YAAY,CAAC,QAAQ,CAAC,yBAAyB,CAAC;QACrD,CAAC,CAAC,WAAW;QACb,CAAC,CAAC,UAAU,CAAC;AACjB,CAAC"}

package/dist/core/stale-managed-banner.d.ts

@@ -0,0 +1,78 @@
+/**
+ * How the installed package ships a destination path.
+ *
+ * Only the two ownership-header strategies are named. Every other strategy —
+ * `merge`, `tagged-merge`, `copy-contents`, `package-lisa` — collapses to
+ * `other` because the question those answer is the same one: Lisa still writes
+ * this path, so a banner saying so is not false. Distinguishing them further
+ * would add states no caller acts on.
+ */
+export type ShippedTemplateStrategy = "copy-overwrite" | "create-only" | "other";
+/** What a file's managed banner is worth, given what the package ships. */
+export type ManagedBannerVerdict = 
+/** The banner is true: Lisa still writes this path. */
+{
+    readonly kind: "accurate";
+}
+/**
+ * Lisa still ships this path, but as a `create-only` seed — so the file is
+ * the host's and the managed wording overstates Lisa's claim.
+ *
+ * Reported as its own verdict rather than folded into `retired` because the
+ * two have different remedies and different populations: this one is the
+ * template that MOVED (CodySwannGT/lisa#3582), and calling it retired would
+ * tell an operator that a template still in the package is gone.
+ */
+ | {
+    readonly kind: "overstated";
+}
+/** Lisa ships nothing at this path. The banner is false and the file is the host's. */
+ | {
+    readonly kind: "retired";
+}
+/** The file makes no managed claim, so there is nothing to be wrong about. */
+ | {
+    readonly kind: "not-managed";
+};
+/**
+ * How many stale paths to name inline before deferring to a count.
+ *
+ * Naming them is the point of the finding, so the cap is generous; a doctor
+ * line that runs to two hundred filenames is one an operator scrolls past.
+ */
+export declare const MAX_NAMED_STALE_BANNERS = 10;
+/**
+ * Judge one file's managed banner against what the installed package ships.
+ *
+ * `shippedDestinations` must be the destinations of EVERY lane the package
+ * ships, not the lanes this project detected as. A template that ships only
+ * under one stack is still shipped; scoping the index to detected stacks would
+ * report every stack-specific artifact in the repository as retired the moment
+ * detection shifted, which is the same false accusation with a different cause.
+ *
+ * An empty index is rejected rather than answered. "Ships nothing anywhere" is
+ * not a state a real package can be in, so it means the tree was unreadable or
+ * was never enumerated — and answering it would classify every managed file in
+ * the project as retired at once.
+ * @param relativePath - Repo-relative path of the file on disk
+ * @param header - The file's leading bytes, long enough to carry its header
+ * @param shippedDestinations - Every destination the installed package ships,
+ *   with the strategy that ships it
+ * @returns What the file's banner is worth
+ * @throws {Error} When the shipped index is empty, which is not an answer
+ */
+export declare function classifyManagedBanner(relativePath: string, header: string, shippedDestinations: ReadonlyMap<string, ShippedTemplateStrategy>): ManagedBannerVerdict;
+/**
+ * The operator-facing finding for files whose managed banner has gone false.
+ *
+ * Written for whoever is about to decide whether they may touch one of these
+ * files. It names them, states the provable fact rather than the causal story,
+ * and says what changes — the sentence, not the file. It deliberately does not
+ * suggest removing the file: whether the workflow or script should still exist
+ * is a separate question, and answering it here is how the original harm
+ * happened in reverse.
+ * @param relativePaths - Repo-relative paths carrying a false managed banner
+ * @returns One operator-readable detail line
+ */
+export declare function describeStaleManagedBanners(relativePaths: readonly string[]): string;
+//# sourceMappingURL=stale-managed-banner.d.ts.map

package/dist/core/stale-managed-banner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-managed-banner.d.ts","sourceRoot":"","sources":["../../src/core/stale-managed-banner.ts"],"names":[],"mappings":"AA8CA;;;;;;;;GAQG;AACH,MAAM,MAAM,uBAAuB,GAC/B,gBAAgB,GAChB,aAAa,GACb,OAAO,CAAC;AAEZ,2EAA2E;AAC3E,MAAM,MAAM,oBAAoB;AAC9B,uDAAuD;AACrD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE;AAC/B;;;;;;;;GAQG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE;AACjC,uFAAuF;GACrF;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE;AAC9B,8EAA8E;GAC5E;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAErC;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAW1C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,mBAAmB,EAAE,WAAW,CAAC,MAAM,EAAE,uBAAuB,CAAC,GAChE,oBAAoB,CActB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CACzC,aAAa,EAAE,SAAS,MAAM,EAAE,GAC/B,MAAM,CAYR"}

package/dist/core/stale-managed-banner.js

@@ -0,0 +1,118 @@
+/**
+ * Is a "managed by Lisa" banner on a consumer's file still TRUE?
+ *
+ * The banner is not decoration and it is not a label — it is an instruction.
+ * "This file is managed by Lisa and IS replaced on each `lisa` run. Do not edit
+ * directly" tells an engineer, and every agent reading the repository, that a
+ * local fix to that file is pointless. When the template it came from has been
+ * removed upstream, the sentence is false in the most expensive direction
+ * available: it discourages exactly the edits the file now needs, and it
+ * inverts any "is this ours to change?" audit that trusts it. A consuming
+ * repository had a proposal to remove one such workflow declined on the stated
+ * grounds that it was "a Lisa-managed file". It was not one
+ * (CodySwannGT/lisa#3703).
+ *
+ * ## The claim this module makes, and the one it refuses to make
+ *
+ * It answers exactly one question: **does the installed package ship anything
+ * at this destination path?** That is provable from the package on disk. It
+ * does NOT claim to know why the answer is no — a template genuinely retired
+ * upstream and a file the consumer derived by copying a Lisa template to a new
+ * name are indistinguishable without a provenance record neither one carries.
+ * Both make the banner false, and both make the file the host's, so the
+ * finding is worded as the provable claim rather than the causal story.
+ *
+ * ## Report, never repair
+ *
+ * Nothing here edits, rewrites, or deletes anything. That is deliberate and it
+ * is the whole safety argument. The file under a stale banner may now be the
+ * host's only copy of that workflow or script, Lisa no longer has a template to
+ * reconcile it against, and an automatic "strip the banner" pass would be Lisa
+ * rewriting a file it has just finished proving it does not own. The remedy is
+ * a one-line edit a human makes with the context to make it.
+ *
+ * ## Three states, never two
+ *
+ * The caller must distinguish "ships a template here", "ships nothing here",
+ * and "could not establish what it ships". The last one is not a variant of the
+ * second: a probe run against an unreadable or absent template tree reports
+ * every file as unshipped, which would condemn a whole repository's banners at
+ * once. This module refuses to be handed an empty index — see
+ * {@link classifyManagedBanner} — and the caller carries the indeterminate case
+ * as its own reported outcome.
+ * @module core/stale-managed-banner
+ */
+import { classifyOwnershipHeader } from "./ownership-header.js";
+/**
+ * How many stale paths to name inline before deferring to a count.
+ *
+ * Naming them is the point of the finding, so the cap is generous; a doctor
+ * line that runs to two hundred filenames is one an operator scrolls past.
+ */
+export const MAX_NAMED_STALE_BANNERS = 10;
+/**
+ * Normalise a repo-relative path so Windows separators compare equal.
+ * @param relativePath - Repo-relative path as the caller spelled it
+ * @returns The same path with forward slashes
+ */
+function normalise(relativePath) {
+    return relativePath.replaceAll("\\", "/");
+}
+/**
+ * Judge one file's managed banner against what the installed package ships.
+ *
+ * `shippedDestinations` must be the destinations of EVERY lane the package
+ * ships, not the lanes this project detected as. A template that ships only
+ * under one stack is still shipped; scoping the index to detected stacks would
+ * report every stack-specific artifact in the repository as retired the moment
+ * detection shifted, which is the same false accusation with a different cause.
+ *
+ * An empty index is rejected rather than answered. "Ships nothing anywhere" is
+ * not a state a real package can be in, so it means the tree was unreadable or
+ * was never enumerated — and answering it would classify every managed file in
+ * the project as retired at once.
+ * @param relativePath - Repo-relative path of the file on disk
+ * @param header - The file's leading bytes, long enough to carry its header
+ * @param shippedDestinations - Every destination the installed package ships,
+ *   with the strategy that ships it
+ * @returns What the file's banner is worth
+ * @throws {Error} When the shipped index is empty, which is not an answer
+ */
+export function classifyManagedBanner(relativePath, header, shippedDestinations) {
+    if (shippedDestinations.size === 0) {
+        throw new Error("refusing to judge banners against an empty template index: an unreadable package ships nothing, which is not the same as removing everything");
+    }
+    if (classifyOwnershipHeader(header) !== "lisa-managed") {
+        return { kind: "not-managed" };
+    }
+    const shippedAs = shippedDestinations.get(normalise(relativePath));
+    if (shippedAs === undefined)
+        return { kind: "retired" };
+    return shippedAs === "create-only"
+        ? { kind: "overstated" }
+        : { kind: "accurate" };
+}
+/**
+ * The operator-facing finding for files whose managed banner has gone false.
+ *
+ * Written for whoever is about to decide whether they may touch one of these
+ * files. It names them, states the provable fact rather than the causal story,
+ * and says what changes — the sentence, not the file. It deliberately does not
+ * suggest removing the file: whether the workflow or script should still exist
+ * is a separate question, and answering it here is how the original harm
+ * happened in reverse.
+ * @param relativePaths - Repo-relative paths carrying a false managed banner
+ * @returns One operator-readable detail line
+ */
+export function describeStaleManagedBanners(relativePaths) {
+    const named = relativePaths.slice(0, MAX_NAMED_STALE_BANNERS);
+    const withheld = relativePaths.length - named.length;
+    const suffix = withheld > 0 ? `, and ${withheld} more` : "";
+    return (`These files say Lisa manages them and replaces them on each run, but the ` +
+        `installed Lisa ships no template at their paths, so nothing replaces ` +
+        `them and the banner is false: ${named.join(", ")}${suffix}. The files are ` +
+        `yours — edit them, and correct or remove the banner sentence so the next ` +
+        `reader is not told a local fix is pointless. Lisa will not rewrite or ` +
+        `remove these files; it no longer has a template for them`);
+}
+//# sourceMappingURL=stale-managed-banner.js.map

package/dist/core/stale-managed-banner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-managed-banner.js","sourceRoot":"","sources":["../../src/core/stale-managed-banner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAmChE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAE1C;;;;GAIG;AACH,SAAS,SAAS,CAAC,YAAoB;IACrC,OAAO,YAAY,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,qBAAqB,CACnC,YAAoB,EACpB,MAAc,EACd,mBAAiE;IAEjE,IAAI,mBAAmB,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CACb,8IAA8I,CAC/I,CAAC;IACJ,CAAC;IACD,IAAI,uBAAuB,CAAC,MAAM,CAAC,KAAK,cAAc,EAAE,CAAC;QACvD,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;IACjC,CAAC;IACD,MAAM,SAAS,GAAG,mBAAmB,CAAC,GAAG,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC;IACnE,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IACxD,OAAO,SAAS,KAAK,aAAa;QAChC,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE;QACxB,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,2BAA2B,CACzC,aAAgC;IAEhC,MAAM,KAAK,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC,EAAE,uBAAuB,CAAC,CAAC;IAC9D,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IACrD,MAAM,MAAM,GAAG,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,QAAQ,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5D,OAAO,CACL,2EAA2E;QAC3E,uEAAuE;QACvE,iCAAiC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,MAAM,kBAAkB;QAC5E,2EAA2E;QAC3E,wEAAwE;QACxE,0DAA0D,CAC3D,CAAC;AACJ,CAAC"}

package/dist/core/two-channel-delivery-scan.d.ts

@@ -34,9 +34,39 @@
  * will fail. `guarded` runs the other way and is true if ANY occurrence is
  * guarded, because one silent-skip path is enough to make the absence silent.
  * Both directions point at reporting more rather than less.
+ *
+ * ## Why the handling signals are literal, and stay literal
+ *
+ * `guarded` says the step can TELL the path is missing. It has never said what
+ * the step then does, and a narrative that inferred the consequence from it
+ * asserted control flow nothing had read (CodySwannGT/lisa#3860). Deciding what
+ * an absent branch does needs a shell parser, and the answer would still be a
+ * guess. So this module reports the other checkable thing: which literal
+ * absence-handling tokens the step's own text contains. `else-branch` does not
+ * mean the else covers this read — it means the characters are there, so a
+ * reader who was about to conclude "this skips silently" is told, in the same
+ * sentence, that the step has a branch they have not read.
+ *
+ * ## Why the staleness probe is reported at two scopes
+ *
+ * The second dimension — can this coupling tell an OLD artifact from a current
+ * one — needs the same treatment, with one wrinkle the handling signals do not
+ * have. A read can reach the step it is used in through a `workflow_call`
+ * input default: `nightly-e2e-health.yml` defaults `guard_script` to
+ * `scripts/check-nightly-e2e-health.mjs`, and the step that compares contract
+ * versions names `$GUARD` and never the path. A step-scoped signal would
+ * therefore MISS a handshake that exists — a false negative on the one arm
+ * where a false negative reads as "this cannot detect staleness".
+ *
+ * So both scopes are reported, under names that say which is which:
+ * `step-requests-version` is exact for the step that reads the path, and
+ * `workflow-requests-version` says only that some step of this workflow asks.
+ * Neither is allowed to conclude anything alone — the artifact half, which the
+ * caller supplies and which IS exact for the path, is what bounds them.
  * @module core/two-channel-delivery-scan
  */
-import type { CouplingInput } from "./two-channel-delivery.js";
+import { type CouplingInput } from "./two-channel-delivery.js";
+import { type StalenessSignal } from "./two-channel-staleness.js";
 /** One step of a workflow, reduced to the text a scan needs. */
 export interface WorkflowStep {
     /** The step's `name:`, or an empty string when it has none. */
@@ -61,12 +91,14 @@ export declare function extractSteps(text: string): readonly WorkflowStep[];
  * @param options.workflow - Workflow file name, as a consumer spells it after `@main`
  * @param options.text - Raw workflow YAML
  * @param options.lanesFor - Delivery lanes shipping a caller path
+ * @param options.artifactSignalsFor - Staleness tokens the delivered artifact carries, or null when nothing is delivered there
  * @returns One coupling per distinct caller path, sorted by path
  */
 export declare function scanWorkflow(options: {
     workflow: string;
     text: string;
     lanesFor: (callerPath: string) => readonly string[];
+    artifactSignalsFor: (callerPath: string) => readonly StalenessSignal[] | null;
 }): readonly CouplingInput[];
 /**
  * Whether a workflow can be called by another repository at all.

package/dist/core/two-channel-delivery-scan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"two-channel-delivery-scan.d.ts","sourceRoot":"","sources":["../../src/core/two-channel-delivery-scan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AA6B/D,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,YAAY,EAAE,CAgBlE;AAgKD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,CAAC;CACrD,GAAG,SAAS,aAAa,EAAE,CAO3B;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIhD"}
+{"version":3,"file":"two-channel-delivery-scan.d.ts","sourceRoot":"","sources":["../../src/core/two-channel-delivery-scan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,OAAO,EAEL,KAAK,aAAa,EAEnB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AA6BpC,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,YAAY,EAAE,CAgBlE;AA+OD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,CAAC;IACpD,kBAAkB,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,SAAS,eAAe,EAAE,GAAG,IAAI,CAAC;CAC/E,GAAG,SAAS,aAAa,EAAE,CAW3B;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIhD"}