@multipliers-dev/renovate-workflow 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Truong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,173 @@
-# Temporary Holding Version
+# renovate-workflow
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Governed Renovate merge ladder with an Agent Plugins 1.0 portable core and Cursor-specific integration: classify dependency PRs, investigate high-risk changes, and merge only when repo-local policy and human gates allow.
+
+Renovate opens many dependency PRs. This product turns that queue into a repeatable **classify → route → (investigate) → maintainer** path with explicit policy, instead of ad-hoc merges.
+
+**Background:** [Upgrades don't have to be a blind trust exercise](https://dev.to/michaeltruong/upgrades-dont-have-to-be-a-blind-trust-exercise-13mj) (DEV Community) — the problem framing, four-step evidence checklist, and review path that led to this repository.
+
+```
+classify (/renovate-classifier)
+    → route by packet
+        → low risk → maintainer (auto path)
+        → high-touch / unlisted → investigator → human audit → maintainer --approved
+    → optional loop (/renovate-loop) for repeated cycles
+```
+
+**Ownership split**
+
+| Layer | Where it lives |
+| --- | --- |
+| Skills, agents, runbook, portable rubric | This repo (Cursor plugin + [Agent Plugins 1.0](https://agent-plugins.org/specification) `skills/`) |
+| Executable scripts (freshness poll, guardrails) | This repo (npm/git devDependency) |
+| Policy facts, Renovate bot config, CI workflow | Your repo |
+
+Portable vs Cursor manifest layers: [docs/adopt.md#portable-vs-cursor-layers-this-repo](docs/adopt.md#portable-vs-cursor-layers-this-repo).
+
+---
+
+## Install (Cursor plugin)
+
+Cursor imports this GitHub repository as a **local marketplace**, then installs the listed plugin.
+
+**Step 1 — import marketplace**
+
+Customize → **Plugins** → **+ Add** → **From GitHub Repository** → `https://github.com/multipliers-dev/renovate-workflow`
+
+Or in Agent chat:
+
+```text
+/add-plugin https://github.com/multipliers-dev/renovate-workflow
+```
+
+**Step 2 — install plugin**
+
+Customize → **Plugins** → open the imported **renovate-workflow** marketplace → install the **renovate-workflow** plugin.
+
+Full adoption guide: [docs/adopt.md](docs/adopt.md)
+
+---
+
+## Quick start (classifier only)
+
+Minimum path to evaluate the ladder — **no `package.json` changes required**.
+
+1. Import marketplace (step 1 above)
+2. Install the **renovate-workflow** plugin (step 2 above)
+3. Confirm `/renovate-classifier` appears under Customize → Plugins
+4. Copy [.agents/renovate-policy.template.yml](.agents/renovate-policy.template.yml) to `.agents/renovate-policy.yml` in your repo and customize package lists, checks, and paths — see [docs/policy-setup.md](docs/policy-setup.md) and [examples/example-repo/](examples/example-repo/)
+5. Ensure GitHub access (`gh` CLI or GitHub MCP)
+6. Run `/renovate-classifier`
+
+Success is `queue_empty` or a classification packet. The classifier **never merges**.
+
+---
+
+## Enable loop / babysit helpers
+
+Required for `/renovate-loop --babysit` and the freshness poll CLI. Not required to try the classifier.
+
+Add a git devDependency and script in your consumer `package.json`:
+
+```json
+{
+  "devDependencies": {
+    "renovate-workflow": "github:multipliers-dev/renovate-workflow",
+    "tsx": "^4.23.12"
+  },
+  "scripts": {
+    "renovate:freshness-poll": "tsx node_modules/renovate-workflow/scripts/renovate-freshness-poll.ts"
+  }
+}
+```
+
+The `scripts/` tree in the installable package is a **temporary legacy surface** for git consumers running `tsx` on TypeScript sources. The stable npm API is the compiled `renovate-workflow` CLI (`renovate-workflow freshness-poll`); see [`.cursor/plans/2026-10-07-npm-package-distribution.plan.md`](.cursor/plans/2026-10-07-npm-package-distribution.plan.md).
+
+See [examples/adopt-stub/package.json](examples/adopt-stub/package.json) and [docs/adopt.md](docs/adopt.md).
+
+---
+
+## What this does not do
+
+- Fully autonomous merging — human gates remain for high-risk and investigation paths
+- Scheduled or webhook-driven automation — manual invocation only
+- Classifier or investigator merge authority — only maintainer may merge, and only with a valid packet
+- Loop with `--approved` — investigation-approved merges require a separate maintainer step
+- Replace the Renovate bot — you still configure `renovate.json` and a Renovate workflow in your repo
+- Cursor public marketplace or org Team Marketplace catalog — install via GitHub import of this repo
+
+---
+
+## Documentation
+
+Primary adopter path:
+
+1. [docs/adopt.md](docs/adopt.md) — plugin install + npm helpers + consumer layout
+2. [docs/policy-setup.md](docs/policy-setup.md) — consumer policy sync model
+3. [docs/renovate-workflow.md](docs/renovate-workflow.md) — operator runbook
+
+Also:
+
+- [Upgrades don't have to be a blind trust exercise](https://dev.to/michaeltruong/upgrades-dont-have-to-be-a-blind-trust-exercise-13mj) — background essay (DEV Community)
+- [docs/versioning.md](docs/versioning.md) — version alignment and git dependency pinning
+- [docs/distribution-discovery.md](docs/distribution-discovery.md) — architecture rationale (maintainer deep-dive)
+- [AGENTS.md](AGENTS.md) — agent command reference
+
+---
+
+## Publishing (maintainers)
+
+This repository uses a **two-step release** — version bump in a reviewed PR, then manual publish. Merging to `main` never publishes.
+
+| Step | Who | What |
+| --- | --- | --- |
+| **A — Version bump** | Reviewed PR | Bump aligned manifests (`package.json`, `plugin.json`, `.cursor-plugin/plugin.json`). For `0.3.0`, also scope-rename to `@multipliers-dev/renovate-workflow` and remove `private`. |
+| **B — Publish** | Maintainer | Dispatch [`.github/workflows/release.yml`](.github/workflows/release.yml) on `main` with confirmation `publish X.Y.Z`. |
+
+**Before first release:**
+
+1. `version-bump-0.3.0` merged on `main` (scoped name, `0.3.0`, not private).
+2. **npm CLI preflight** — `sh scripts/npm-stage-cli-preflight.sh` (staged publishing requires npm **≥ 11.15.0**; Node version alone does not guarantee `npm stage` exists).
+3. **One-time registry bootstrap** — validate `0.3.0` in the checkout (`npm ci`, `npm test`, `npm run typecheck`, `npm run build`, `npm pack`), then `npm run bootstrap:tarball` to build/preflight a **disposable `0.0.1` tarball** (npm pack in an isolated temp dir — not manual `tar -czf`; canonical checkout stays at `0.3.0`), then `npm stage publish` that tarball. **Do not** stage `0.3.0` and leave it pending. See [docs/versioning.md § Trusted Publishing bootstrap](docs/versioning.md#trusted-publishing-bootstrap).
+4. Configure npm **Trusted Publisher** for workflow `release.yml` (`multipliers-dev/renovate-workflow`). See [docs/versioning.md § npm Trusted Publisher settings](docs/versioning.md#npm-trusted-publisher-settings).
+5. Dispatch **Release** within **48 hours** of creating the Trusted Publisher configuration; after successful OIDC `0.3.0`, reject the pending bootstrap stage with `npm stage reject <stage-id>` (2FA).
+
+Publishing uses **OIDC** (no `NPM_TOKEN`). Provenance is automatic for public packages from this public repo.
+
+The release workflow reads **name and version from the checked-out `package.json` only** (`npm publish --access public` with no CLI coordinate override). It does not bump versions or commit to `main`. npm and plugin always share version *V* at the same commit. Only one release dispatch runs at a time (`concurrency: release`).
+
+If `npm publish` succeeds but tag/GitHub Release creation fails, **do not republish** — verify the registry version matches the intended commit, then create the missing tag and GitHub Release manually. See [docs/versioning.md § Partial release recovery](docs/versioning.md#partial-release-recovery).
+
+Full policy: [docs/versioning.md](docs/versioning.md)
+
+---
+
+## Development
+
+```bash
+npm install
+npm test
+npm run typecheck
+npm run build
+```
+
+---
+
+## Layout
+
+```
+plugin.json            Agent Plugins 1.0 portable manifest (metadata only)
+skills/                Five renovate skills + verification assets (fixed discovery path)
+.cursor-plugin/        Cursor marketplace + extension manifest (agents, skill paths)
+.agents/               Agent prompts, rubric base, policy template, report templates
+.cursor/               Repo-local Cursor dev (hooks, Cloud VM) — not plugin-distributed
+docs/                  Adoption guides and runbook
+scripts/               Guardrails, freshness poll, tests/fixtures
+examples/example-repo/ Synthetic consumer stubs for policy schema tests
+```
+
+---
+
+## License
+
+[MIT](LICENSE)

package/dist/cli.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { runRenovateFreshnessPollCli } from "./renovate-freshness-poll.js";
+function printRootUsage() {
+    console.error(`Usage: renovate-workflow <command>
+
+Commands:
+  freshness-poll    Run the Renovate post-update babysit helper
+
+Options:
+  -h, --help        Show this help
+
+Run \`renovate-workflow freshness-poll --help\` for freshness-poll options.
+`);
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        printRootUsage();
+        process.exit(0);
+    }
+    const [command, ...rest] = args;
+    switch (command) {
+        case "freshness-poll":
+            await runRenovateFreshnessPollCli(rest);
+            return;
+        default:
+            console.error(`unknown command: ${command}`);
+            printRootUsage();
+            process.exit(2);
+    }
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist/lib/agent-plugins-spec.js

@@ -0,0 +1,100 @@
+export const AGENT_PLUGINS_SCHEMA_BASE = "https://agent-plugins.org/schemas";
+export const PUBLISHED_SPEC_MD_URL = "https://agent-plugins.org/specification.md";
+const DECLARED_SCHEMA_PATTERN = /^https:\/\/agent-plugins\.org\/schemas\/(\d+\.\d+\.\d+)\/plugin\.schema\.json$/;
+const PUBLISHED_SPEC_VERSION_PATTERN = /^\*\*Spec Version:\s*(\d+\.\d+\.\d+)\s*\*\*$/m;
+const PUBLISHED_STATUS_PATTERN = /^\*\*Status:\s*Published\s*\*\*$/m;
+export function buildPublishedSchemaUrl(version) {
+    return `${AGENT_PLUGINS_SCHEMA_BASE}/${version}/plugin.schema.json`;
+}
+export function parseAgentPluginsSchemaUrl(schemaUrl) {
+    const match = DECLARED_SCHEMA_PATTERN.exec(schemaUrl);
+    if (!match) {
+        throw new Error(`malformed Agent Plugins schema URL: expected https://agent-plugins.org/schemas/X.Y.Z/plugin.schema.json`);
+    }
+    return match[1];
+}
+export function parseDeclaredSpecVersion($schema) {
+    try {
+        return parseAgentPluginsSchemaUrl($schema);
+    }
+    catch {
+        throw new Error(`malformed $schema URL: expected https://agent-plugins.org/schemas/X.Y.Z/plugin.schema.json`);
+    }
+}
+export function parsePublishedSchemaDocumentVersion(schemaDocument) {
+    let parsed;
+    try {
+        parsed = JSON.parse(schemaDocument);
+    }
+    catch {
+        throw new Error("published schema document is not valid JSON");
+    }
+    if (typeof parsed !== "object" || parsed === null || !("$id" in parsed)) {
+        throw new Error("published schema document is missing $id");
+    }
+    const schemaId = parsed.$id;
+    if (typeof schemaId !== "string") {
+        throw new Error("published schema document has invalid $id");
+    }
+    return parseAgentPluginsSchemaUrl(schemaId);
+}
+export function parsePublishedSpecVersion(specMarkdown) {
+    if (!PUBLISHED_STATUS_PATTERN.test(specMarkdown)) {
+        throw new Error("upstream specification.md is missing Status: Published");
+    }
+    const versionMatch = PUBLISHED_SPEC_VERSION_PATTERN.exec(specMarkdown);
+    if (!versionMatch) {
+        throw new Error("upstream specification.md is missing Spec Version");
+    }
+    return versionMatch[1];
+}
+export function compareSemver(a, b) {
+    const aParts = a.split(".").map((part) => Number(part));
+    const bParts = b.split(".").map((part) => Number(part));
+    if (aParts.length !== 3 || bParts.length !== 3) {
+        throw new Error(`invalid semver: ${a} or ${b}`);
+    }
+    for (let index = 0; index < 3; index += 1) {
+        const aPart = aParts[index];
+        const bPart = bParts[index];
+        if (!Number.isInteger(aPart) || !Number.isInteger(bPart)) {
+            throw new Error(`invalid semver: ${a} or ${b}`);
+        }
+        if (aPart < bPart) {
+            return -1;
+        }
+        if (aPart > bPart) {
+            return 1;
+        }
+    }
+    return 0;
+}
+export function confirmPublishedUpstreamVersion(signals) {
+    const { markdownVersion, schemaVersion, schemaHttpStatus } = signals;
+    if (schemaHttpStatus !== 200) {
+        throw new Error(`published schema URL returned HTTP ${schemaHttpStatus} for version ${schemaVersion}`);
+    }
+    if (markdownVersion !== schemaVersion) {
+        throw new Error(`published signal mismatch: specification.md reports ${markdownVersion} but published schema document $id reports ${schemaVersion}`);
+    }
+    return markdownVersion;
+}
+export function evaluateSpecRelationship(options) {
+    const comparison = compareSemver(options.declared, options.published);
+    let relationship;
+    if (comparison < 0) {
+        relationship = "behind";
+    }
+    else if (comparison > 0) {
+        relationship = "ahead";
+    }
+    else {
+        relationship = "current";
+    }
+    return {
+        declaredVersion: options.declared,
+        latestPublishedVersion: options.published,
+        relationship,
+        driftDetected: relationship === "behind",
+    };
+}

package/dist/lib/bootstrap-tarball.js

@@ -0,0 +1,175 @@
+import { execSync } from "node:child_process";
+import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+export const BOOTSTRAP_VERSION = "0.0.1";
+const FORBIDDEN_ENTRY_PATTERNS = [
+    {
+        label: "directory entry package/ (trailing slash)",
+        test: (entry) => entry === "package/" || entry === "package",
+    },
+    {
+        label: "AppleDouble (._*)",
+        test: (entry) => /(^|\/)\._[^/]+/.test(entry),
+    },
+    {
+        label: ".git",
+        test: (entry) => entry.includes(".git"),
+    },
+    {
+        label: "test files",
+        test: (entry) => entry.endsWith(".test.ts") || entry.endsWith(".test.js"),
+    },
+    {
+        label: "fixtures",
+        test: (entry) => entry.includes("/fixtures/"),
+    },
+    {
+        label: "credentials",
+        test: (entry) => /(^|\/)\.env($|\.)/.test(entry) ||
+            entry.includes("credentials.json") ||
+            entry.includes("id_rsa"),
+    },
+];
+export function listTarballEntries(tarballPath) {
+    const listing = execSync(`tar -tzf "${tarballPath}"`, { encoding: "utf8" });
+    return listing
+        .trim()
+        .split("\n")
+        .filter(Boolean);
+}
+export function readPackedManifest(tarballPath) {
+    const raw = execSync(`tar -xOf "${tarballPath}" package/package.json`, { encoding: "utf8" });
+    return JSON.parse(raw);
+}
+export function parsePackTarballName(packOutput) {
+    const tarballName = packOutput
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.endsWith(".tgz"))
+        .at(-1);
+    if (!tarballName) {
+        throw new Error(`npm pack did not report a .tgz filename:\n${packOutput}`);
+    }
+    return tarballName;
+}
+export function assertBootstrapTarballEntries(entries) {
+    const violations = [];
+    for (const entry of entries) {
+        for (const pattern of FORBIDDEN_ENTRY_PATTERNS) {
+            if (pattern.test(entry)) {
+                violations.push(`${entry} (${pattern.label})`);
+                break;
+            }
+        }
+    }
+    if (violations.length > 0) {
+        throw new Error(`bootstrap tarball failed preflight:\n${violations.map((v) => `  - ${v}`).join("\n")}`);
+    }
+    const normalized = entries.map((entry) => entry.replace(/^package\//, ""));
+    if (!normalized.some((entry) => entry.startsWith("dist/"))) {
+        throw new Error("bootstrap tarball missing dist/ publish surface");
+    }
+    if (!normalized.includes("package.json")) {
+        throw new Error("bootstrap tarball missing package/package.json");
+    }
+    if (!normalized.includes("README.md")) {
+        throw new Error("bootstrap tarball missing package/README.md");
+    }
+}
+/** Lifecycle hooks that reference dev-only paths excluded from the packed `files` list. */
+const ISOLATED_PACK_SCRIPT_KEYS = ["prepare", "prepack"];
+function stripIsolatedPackLifecycleScripts(packageDir) {
+    const packageJsonPath = join(packageDir, "package.json");
+    const manifest = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+    if (!manifest.scripts) {
+        return;
+    }
+    for (const key of ISOLATED_PACK_SCRIPT_KEYS) {
+        delete manifest.scripts[key];
+    }
+    writeFileSync(packageJsonPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+function packDirectoryToDestination(packageDir, packDestination) {
+    mkdirSync(packDestination, { recursive: true });
+    const packOutput = execSync(`npm pack --ignore-scripts --loglevel error --pack-destination "${packDestination}"`, {
+        cwd: packageDir,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    const packedName = parsePackTarballName(packOutput);
+    return join(packDestination, packedName);
+}
+/**
+ * Build a disposable bootstrap tarball from an already-validated `npm pack` artifact.
+ *
+ * Uses `npm pack --ignore-scripts` in an isolated temp directory so the tarball
+ * matches libnpmpack layout (file entries only under package/..., no bare package/
+ * directory entry). Manual `tar -czf` is rejected by the npm registry (E415 invalid
+ * path: package/) because BSD tar emits a trailing-slash directory entry.
+ */
+export function createBootstrapTarballFromValidatedPack(validatedTarballPath, options = {}) {
+    const absoluteValidated = resolve(validatedTarballPath);
+    if (!existsSync(absoluteValidated)) {
+        throw new Error(`validated pack tarball not found: ${absoluteValidated}`);
+    }
+    const workRoot = mkdtempSync(join(tmpdir(), "renovate-workflow-bootstrap-work-"));
+    const extractDir = join(workRoot, "extract");
+    const isolatedPackageDir = join(workRoot, "isolated-package");
+    // Default: durable artifact dir outside workRoot so the returned .tgz survives work cleanup.
+    const artifactDir = options.outputDir
+        ? resolve(options.outputDir)
+        : mkdtempSync(join(tmpdir(), "renovate-workflow-bootstrap-artifact-"));
+    try {
+        mkdirSync(extractDir, { recursive: true });
+        cpSync(absoluteValidated, join(workRoot, "validated.tgz"));
+        execSync(`tar -xzf "${join(workRoot, "validated.tgz")}" -C "${extractDir}"`, {
+            stdio: "pipe",
+        });
+        const extractedPackageDir = join(extractDir, "package");
+        if (!existsSync(join(extractedPackageDir, "package.json"))) {
+            throw new Error("validated pack tarball missing package/package.json");
+        }
+        cpSync(extractedPackageDir, isolatedPackageDir, { recursive: true });
+        execSync(`npm pkg set version=${BOOTSTRAP_VERSION}`, {
+            cwd: isolatedPackageDir,
+            stdio: "pipe",
+        });
+        // Packed artifact omits scripts/*.sh; npm pack may still run `prepare` unless removed.
+        stripIsolatedPackLifecycleScripts(isolatedPackageDir);
+        const packDir = join(workRoot, "packed");
+        const packedPath = packDirectoryToDestination(isolatedPackageDir, packDir);
+        const packedName = basename(packedPath);
+        const finalPath = join(artifactDir, packedName);
+        copyFileSync(packedPath, finalPath);
+        const entries = listTarballEntries(finalPath);
+        assertBootstrapTarballEntries(entries);
+        const manifest = readPackedManifest(finalPath);
+        if (manifest.version !== BOOTSTRAP_VERSION) {
+            throw new Error(`bootstrap tarball version must be ${BOOTSTRAP_VERSION}, got ${manifest.version}`);
+        }
+        return { tarballPath: finalPath, entries, manifest };
+    }
+    finally {
+        if (!options.keepWorkdirs) {
+            rmSync(workRoot, { recursive: true, force: true });
+        }
+    }
+}
+export function packValidatedReleaseArtifact(repoRoot) {
+    const packDir = mkdtempSync(join(tmpdir(), "renovate-workflow-validated-pack-"));
+    return packDirectoryToDestination(repoRoot, packDir);
+}
+export function removePackedArtifactTree(tarballPath) {
+    rmSync(dirname(tarballPath), { recursive: true, force: true });
+}
+/** Remove the temp directory that owns a default-path bootstrap tarball. */
+export function removeBootstrapArtifactTree(tarballPath) {
+    rmSync(dirname(tarballPath), { recursive: true, force: true });
+}
+export function assertCheckoutVersion(repoRoot, expectedVersion) {
+    const manifest = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8"));
+    if (manifest.version !== expectedVersion) {
+        throw new Error(`Expected package version ${expectedVersion}, got ${manifest.version}`);
+    }
+}

package/dist/lib/derive-stop-causes.js

@@ -0,0 +1,85 @@
+/**
+ * Single derivation table for classifier emission and guardrails evaluation.
+ * Keys must match the reference table in the renovate investigation lane plan.
+ */
+export const TRIGGER_WATCH_KEYS = [
+    "implementation_changes_required",
+    "lockfile_threshold_exceeded",
+    "ci_failure_unexplained",
+    "runtime_behavior_affected",
+];
+export const KNOWN_STOP_CAUSES = [
+    "decision_human_required",
+    "stop_flag_expected_human_required",
+    "triggered_implementation_changes_required",
+    "triggered_lockfile_threshold_exceeded",
+    "triggered_ci_failure_unexplained",
+    "triggered_runtime_behavior_affected",
+    "triggered_runtime_behavior_affected_sole",
+    "triggered_human_required_unmapped",
+    "decision_defer",
+];
+const KNOWN_STOP_CAUSE_SET = new Set(KNOWN_STOP_CAUSES);
+const TRIGGER_WATCH_KEY_SET = new Set(TRIGGER_WATCH_KEYS);
+export function isKnownStopCause(value) {
+    return KNOWN_STOP_CAUSE_SET.has(value);
+}
+function deriveTriggerStopCauses(triggered) {
+    const causes = [];
+    if (triggered.some((key) => !TRIGGER_WATCH_KEY_SET.has(key))) {
+        causes.push("triggered_human_required_unmapped");
+    }
+    if (triggered.includes("implementation_changes_required")) {
+        causes.push("triggered_implementation_changes_required");
+    }
+    if (triggered.includes("lockfile_threshold_exceeded")) {
+        causes.push("triggered_lockfile_threshold_exceeded");
+    }
+    if (triggered.includes("ci_failure_unexplained")) {
+        causes.push("triggered_ci_failure_unexplained");
+    }
+    if (triggered.includes("runtime_behavior_affected")) {
+        if (triggered.length === 1) {
+            causes.push("triggered_runtime_behavior_affected_sole");
+        }
+        else {
+            causes.push("triggered_runtime_behavior_affected");
+        }
+    }
+    return causes;
+}
+export function deriveStopCauses(packet) {
+    const causes = [];
+    const decision = packet.classification?.decision;
+    const triggered = packet.triggered_human_required ?? [];
+    if (decision === "defer") {
+        causes.push("decision_defer");
+    }
+    if (decision === "human_required") {
+        causes.push("decision_human_required");
+    }
+    if (packet.stop === true && decision === "human_required") {
+        causes.push("stop_flag_expected_human_required");
+    }
+    causes.push(...deriveTriggerStopCauses(triggered));
+    return causes;
+}
+export function stopCausesMatchDerivation(packet) {
+    const expectedCauses = deriveStopCauses(packet);
+    const packetCauses = packet.stop_causes ?? [];
+    if (packetCauses.length !== expectedCauses.length) {
+        return false;
+    }
+    const sortedPacketCauses = [...packetCauses].sort();
+    const sortedExpectedCauses = [...expectedCauses].sort();
+    return sortedPacketCauses.every((cause, index) => cause === sortedExpectedCauses[index]);
+}
+export function validateStopCausesDerivation(packet) {
+    if (packet.stop !== true) {
+        return null;
+    }
+    if (!stopCausesMatchDerivation(packet)) {
+        return "packet stop_causes do not match deriveStopCauses derivation";
+    }
+    return null;
+}