continuous-improvement 3.20.0 → 3.20.4

package/plugins/continuous-improvement/scripts/detect-deploy-target.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# scripts/detect-deploy-target.sh
+#
+# Detect the auto-deploy provider for the repo rooted at the current working
+# directory (or the first argument, if supplied). Composability primitive used
+# by skills and hooks that need to know "does this repo auto-deploy, and if so
+# from where?" without each restating the file-marker table.
+#
+# Output: one of
+#   railway | cloudflare | vercel | netlify | fly | appengine | apprunner |
+#   gha-deploy | none
+#
+# Resolution priority (first match wins):
+#   1. railway.toml | railway.json                              → railway
+#   2. wrangler.toml | wrangler.jsonc                           → cloudflare
+#   3. vercel.json | .vercel/                                   → vercel
+#   4. netlify.toml                                             → netlify
+#   5. fly.toml                                                 → fly
+#   6. app.yaml                                                 → appengine
+#   7. apprunner.yaml                                           → apprunner
+#   8. .github/workflows/*.{yml,yaml} containing "deploy:" job  → gha-deploy
+#   9. nothing matched                                          → none
+#
+# Always exits 0. `none` is a valid result, not an error condition.
+#
+# Cited by:
+#   - skills/verification-loop.md Phase 8 (deploy-receipt handoff trigger)
+#   - skills/deploy-receipt.md "When to Activate" gate
+
+set -u
+
+ROOT="${1:-$PWD}"
+
+emit() {
+  printf '%s\n' "$1"
+  exit 0
+}
+
+# Order is the contract — earlier rows shadow later ones when multiple
+# markers exist in the same repo.
+[ -f "$ROOT/railway.toml" ]    && emit railway
+[ -f "$ROOT/railway.json" ]    && emit railway
+[ -f "$ROOT/wrangler.toml" ]   && emit cloudflare
+[ -f "$ROOT/wrangler.jsonc" ]  && emit cloudflare
+[ -f "$ROOT/vercel.json" ]     && emit vercel
+[ -d "$ROOT/.vercel" ]         && emit vercel
+[ -f "$ROOT/netlify.toml" ]    && emit netlify
+[ -f "$ROOT/fly.toml" ]        && emit fly
+[ -f "$ROOT/app.yaml" ]        && emit appengine
+[ -f "$ROOT/apprunner.yaml" ]  && emit apprunner
+
+# GitHub Actions deploy workflow: scan .github/workflows/*.{yml,yaml} for a
+# job whose key is literally `deploy:`. Cheap and conservative — false
+# positives (a non-deploy job named "deploy") are unlikely; false negatives
+# (a deploy job named something else) require the repo to declare the
+# provider via one of the file markers above instead.
+if [ -d "$ROOT/.github/workflows" ]; then
+  if grep -lE '^[[:space:]]*deploy:[[:space:]]*$' \
+        "$ROOT/.github/workflows/"*.yml \
+        "$ROOT/.github/workflows/"*.yaml 2>/dev/null \
+      | head -n 1 | grep -q .; then
+    emit gha-deploy
+  fi
+fi
+
+emit none

package/plugins/continuous-improvement/scripts/get-deployed-sha.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# scripts/get-deployed-sha.sh
+#
+# Print the currently-deployed commit SHA for an auto-deploy provider, or
+# print the CLI command shape (with `--show-command`) without executing it.
+# Composability primitive that owns the per-provider CLI knowledge so skills
+# can cite one path instead of restating the 5-provider extraction table.
+#
+# Usage:
+#   bash scripts/get-deployed-sha.sh <provider>
+#   bash scripts/get-deployed-sha.sh --show-command <provider>
+#
+# Providers: railway | cloudflare | vercel | netlify | fly
+#
+# Default mode: runs the provider CLI, pipes through jq, prints the SHA on
+# stdout. Requires the CLI to be installed and authenticated; exits 3 with a
+# clear error if the CLI is missing.
+#
+# --show-command mode: prints the command pipeline that would run, without
+# executing it. Useful for skill citations, dry-runs, and tests that should
+# not require live CLI auth.
+#
+# Exit codes:
+#   0 — SHA printed (default mode) or command printed (--show-command mode)
+#   2 — missing or unknown provider (usage error)
+#   3 — required CLI not installed (default mode only)
+#   non-zero — CLI failure (passed through)
+#
+# Cited by:
+#   - skills/verification-loop.md Phase 8 (deploy-receipt handoff trigger)
+#   - skills/deploy-receipt.md Route A (provider CLI extraction)
+
+set -u
+
+SHOW_COMMAND=false
+PROVIDER=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --show-command)
+      SHOW_COMMAND=true
+      shift
+      ;;
+    -h|--help)
+      sed -n '2,/^$/p' "$0" >&2
+      exit 0
+      ;;
+    *)
+      if [ -z "$PROVIDER" ]; then
+        PROVIDER="$1"
+      else
+        printf 'usage: get-deployed-sha.sh [--show-command] <provider>\n' >&2
+        exit 2
+      fi
+      shift
+      ;;
+  esac
+done
+
+if [ -z "$PROVIDER" ]; then
+  printf 'usage: get-deployed-sha.sh [--show-command] <provider>\n' >&2
+  exit 2
+fi
+
+# Single source of truth for the per-provider command pipeline. Each value is
+# the literal pipeline that would run; the jq filter extracts the SHA.
+case "$PROVIDER" in
+  railway)
+    CMD='railway status --json | jq -r .deployments[0].meta.commitHash'
+    CLI=railway
+    ;;
+  cloudflare)
+    CMD='wrangler deployments list --json | jq -r .[0].metadata.deployment_trigger.metadata.commit_hash'
+    CLI=wrangler
+    ;;
+  vercel)
+    CMD='vercel inspect "$(vercel ls --json | jq -r .[0].url)" --json | jq -r .gitSource.sha'
+    CLI=vercel
+    ;;
+  netlify)
+    CMD='netlify api listSiteDeploys --data="{\"site_id\":\"$NETLIFY_SITE_ID\"}" | jq -r .[0].commit_ref'
+    CLI=netlify
+    ;;
+  fly)
+    CMD='fly releases --json | jq -r .[0].commit_sha'
+    CLI=fly
+    ;;
+  *)
+    printf 'unknown or unsupported provider: %s\n' "$PROVIDER" >&2
+    printf 'supported: railway | cloudflare | vercel | netlify | fly\n' >&2
+    exit 2
+    ;;
+esac
+
+if [ "$SHOW_COMMAND" = "true" ]; then
+  printf '%s\n' "$CMD"
+  exit 0
+fi
+
+if ! command -v "$CLI" >/dev/null 2>&1; then
+  printf 'required CLI "%s" not installed for provider "%s"\n' "$CLI" "$PROVIDER" >&2
+  exit 3
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+  printf 'required CLI "jq" not installed\n' >&2
+  exit 3
+fi
+
+# Execute the pipeline. eval is intentional — the per-provider CMD contains
+# pipes and command substitution that need shell interpretation. CMDs are
+# sourced from the literal table above, not user input.
+eval "$CMD"

package/plugins/continuous-improvement/scripts/git-state-snapshot.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# scripts/git-state-snapshot.sh
+#
+# Emit a single-line JSON envelope describing the current git working-tree
+# state. Composability primitive used by skills that need to baseline or check
+# git state without each restating the same 3-command triple.
+#
+# Fields:
+#   - head:     short SHA returned by `git rev-parse --short HEAD`
+#   - upstream: short SHA of `@{u}` if the branch tracks an upstream, else "none"
+#   - dirty:    integer count of lines from `git status --porcelain` (0 == clean)
+#   - root:     absolute path from `git rev-parse --show-toplevel`
+#   - branch:   `git symbolic-ref --short HEAD`, else "detached"
+#
+# Outside a git repository the script prints `{"error":"not-a-git-repo"}` and
+# exits 1. All other failures are treated as a non-git-repo condition rather
+# than emitting a partial envelope.
+#
+# Cited by:
+#   - skills/gateguard.md            (Parallel-Actor Gate baseline + divergence)
+#   - skills/worktree-safety.md      (Root + branch alignment)
+#   - skills/workspace-surface-audit.md (Environment Grain — parallel-actor row)
+
+set -u
+
+head=$(git rev-parse --short HEAD 2>/dev/null) || {
+  printf '{"error":"not-a-git-repo"}\n'
+  exit 1
+}
+
+if upstream=$(git rev-parse --short '@{u}' 2>/dev/null); then
+  upstream_field=$(printf '"%s"' "$upstream")
+else
+  upstream_field='"none"'
+fi
+
+dirty=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+
+root=$(git rev-parse --show-toplevel 2>/dev/null || printf 'unknown')
+
+if branch=$(git symbolic-ref --short HEAD 2>/dev/null); then
+  branch_field=$(printf '"%s"' "$branch")
+else
+  branch_field='"detached"'
+fi
+
+printf '{"head":"%s","upstream":%s,"dirty":%s,"root":"%s","branch":%s}\n' \
+  "$head" "$upstream_field" "$dirty" "$root" "$branch_field"

package/plugins/continuous-improvement/scripts/resolve-verify-ladder.mjs

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+// scripts/resolve-verify-ladder.mjs
+//
+// Resolve the per-project verification ladder for `verification-loop` Phase 0.
+// Encodes the four-step resolution priority — manifest > package.json sniff >
+// per-language toolchain > ask-operator — so the skill body cites this script
+// instead of restating the 80+ lines of priority prose inline.
+//
+// Usage:
+//   node scripts/resolve-verify-ladder.mjs              # pretty fenced block, cwd
+//   node scripts/resolve-verify-ladder.mjs <repo-root>  # pretty, explicit root
+//   node scripts/resolve-verify-ladder.mjs --json       # JSON for machines
+//   node scripts/resolve-verify-ladder.mjs --json <repo-root>
+//
+// Output (default — pretty fenced block):
+//
+//   verify-ladder (resolved):
+//     build:            npm run build  (sniff:package.json:scripts.build)
+//     typecheck:        npx tsc --noEmit  (manifest)
+//     ...
+//
+// Output (--json — single JSON object on stdout):
+//
+//   { "build": { "command": "npm run build", "source": "sniff:..." }, ... }
+//
+// Phases: build, typecheck, lint, test, security, deploy_receipt, synthetic_checks.
+// Sources: "manifest", "manifest:null" (explicitly skipped), "sniff:package.json:<key>",
+//          "sniff:Cargo.toml" | "sniff:go.mod" | "sniff:pyproject.toml" | "sniff:Gemfile",
+//          "ask-operator" (nothing matched).
+//
+// Cited by:
+//   - skills/verification-loop.md Phase 0
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { argv, cwd, exit, stdout } from "node:process";
+
+const PHASES = [
+  "build",
+  "typecheck",
+  "lint",
+  "test",
+  "security",
+  "deploy_receipt",
+  "synthetic_checks",
+];
+
+function parseArgs() {
+  const args = argv.slice(2);
+  let json = false;
+  let root = cwd();
+  for (const a of args) {
+    if (a === "--json") {
+      json = true;
+    } else if (a === "-h" || a === "--help") {
+      stdout.write(
+        "usage: resolve-verify-ladder.mjs [--json] [<repo-root>]\n",
+      );
+      exit(0);
+    } else {
+      root = a;
+    }
+  }
+  return { json, root };
+}
+
+function safeReadJson(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function readManifest(root) {
+  return safeReadJson(join(root, ".claude", "verify-ladder.json"));
+}
+
+function readPackageJson(root) {
+  return safeReadJson(join(root, "package.json"));
+}
+
+function sniffPackageJsonScript(pkg, phase) {
+  if (!pkg || !pkg.scripts) return null;
+  const scripts = pkg.scripts;
+  // Priority: verify:<phase> > <phase> > <phase>:* (wildcard tail).
+  // Phase aliases:
+  //   typecheck also matches `tsc` (common in repos that just use `tsc`).
+  //   security also matches `audit` (common in npm projects).
+  const candidates = [`verify:${phase}`, phase];
+  if (phase === "typecheck") candidates.push("tsc");
+  if (phase === "security") candidates.push("audit");
+
+  for (const name of candidates) {
+    if (typeof scripts[name] === "string") {
+      const cmd = name === "test" ? "npm test" : `npm run ${name}`;
+      return {
+        command: cmd,
+        source: `sniff:package.json:scripts.${name}`,
+      };
+    }
+  }
+
+  // Last resort: <phase>:* wildcard tail.
+  const wildcardKey = Object.keys(scripts).find((k) => k.startsWith(`${phase}:`));
+  if (wildcardKey) {
+    return {
+      command: `npm run ${wildcardKey}`,
+      source: `sniff:package.json:scripts.${wildcardKey}`,
+    };
+  }
+
+  return null;
+}
+
+const PER_LANGUAGE = [
+  {
+    marker: "Cargo.toml",
+    commands: {
+      build: "cargo build",
+      typecheck: "cargo check --all-targets",
+      lint: "cargo clippy --all-targets -- -D warnings",
+      test: "cargo test",
+      security: "cargo audit",
+    },
+  },
+  {
+    marker: "go.mod",
+    commands: {
+      build: "go build ./...",
+      typecheck: "go vet ./...",
+      lint: "go vet ./...",
+      test: "go test ./...",
+    },
+  },
+  {
+    marker: "pyproject.toml",
+    commands: {
+      typecheck: "pyright",
+      lint: "ruff check .",
+      test: "pytest",
+    },
+  },
+  {
+    marker: "Gemfile",
+    commands: {
+      lint: "bundle exec rubocop",
+      test: "bundle exec rspec",
+    },
+  },
+];
+
+function sniffPerLanguage(root, phase) {
+  for (const lang of PER_LANGUAGE) {
+    if (!existsSync(join(root, lang.marker))) continue;
+    if (lang.commands[phase]) {
+      return { command: lang.commands[phase], source: `sniff:${lang.marker}` };
+    }
+  }
+  return null;
+}
+
+function resolve(root) {
+  const manifest = readManifest(root);
+  const pkg = readPackageJson(root);
+  const ladder = {};
+
+  for (const phase of PHASES) {
+    // 1. Manifest layer. Underscore-prefixed keys in the manifest are
+    //    documentation/examples — verify-ladder.example.json uses keys like
+    //    "_doc", "_node_example" — so PHASES never starts with "_" and we
+    //    can rely on hasOwn for an exact phase match.
+    if (
+      manifest &&
+      Object.prototype.hasOwnProperty.call(manifest, phase) &&
+      !phase.startsWith("_")
+    ) {
+      const value = manifest[phase];
+      if (value === null) {
+        ladder[phase] = { command: null, source: "manifest:null" };
+      } else if (typeof value === "string") {
+        ladder[phase] = { command: value, source: "manifest" };
+      } else {
+        ladder[phase] = { command: null, source: "manifest:invalid" };
+      }
+      continue;
+    }
+
+    // 2. package.json scripts sniff.
+    const pkgHit = sniffPackageJsonScript(pkg, phase);
+    if (pkgHit) {
+      ladder[phase] = pkgHit;
+      continue;
+    }
+
+    // 3. Per-language toolchain sniff.
+    const langHit = sniffPerLanguage(root, phase);
+    if (langHit) {
+      ladder[phase] = langHit;
+      continue;
+    }
+
+    // 4. Nothing matched — operator must declare or set to null.
+    ladder[phase] = { command: null, source: "ask-operator" };
+  }
+
+  return ladder;
+}
+
+function pretty(ladder) {
+  const widest = Math.max(...Object.keys(ladder).map((k) => k.length));
+  const lines = ["verify-ladder (resolved):"];
+  for (const [phase, entry] of Object.entries(ladder)) {
+    const label = `${phase}:`.padEnd(widest + 2);
+    let line;
+    if (entry.command === null && entry.source === "ask-operator") {
+      line = `  ${label} (ask operator — no marker found)`;
+    } else if (entry.command === null && entry.source === "manifest:null") {
+      line = `  ${label} (skipped — manifest set this field to null)`;
+    } else if (entry.command === null) {
+      line = `  ${label} (skipped — ${entry.source})`;
+    } else {
+      line = `  ${label} ${entry.command}  (${entry.source})`;
+    }
+    lines.push(line);
+  }
+  return lines.join("\n") + "\n";
+}
+
+function main() {
+  const { json, root } = parseArgs();
+  const ladder = resolve(root);
+  if (json) {
+    stdout.write(JSON.stringify(ladder, null, 2) + "\n");
+  } else {
+    stdout.write(pretty(ladder));
+  }
+}
+
+main();

package/plugins/continuous-improvement/scripts/route-recommendation.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+// scripts/route-recommendation.mjs
+//
+// Route a single recommendation item to its preferred-skill chain + inline
+// fallback, using the data-driven routing table in
+// `scripts/route-recommendation.routes.json`.
+//
+// Replaces the 26-row Phase 3 routing table that `proceed-with-the-recommendation`
+// would otherwise re-derive every list walk. The skill body cites this script
+// once instead of restating the table inline; the routes.json file is the
+// programmatic source of truth.
+//
+// Usage:
+//   node scripts/route-recommendation.mjs "<recommendation item>"
+//   node scripts/route-recommendation.mjs --json "<recommendation item>"
+//   node scripts/route-recommendation.mjs --list           # all rows
+//   node scripts/route-recommendation.mjs --list --json    # all rows as JSON
+//
+// Output (default):
+//   Match: <row name>
+//   Preferred: <skill1> → <skill2>
+//   Fallback: <inline-fallback text>
+//   Marker: (Reference behavior — does not require <plugin>.)
+//
+// Output (--json):
+//   { "input": "...", "match": { name, preferred, fallback, marker }, "candidates": [...] }
+//
+// Cited by:
+//   - skills/proceed-with-the-recommendation.md Phase 3 routing table
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { argv, exit, stderr, stdout } from "node:process";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const ROUTES_PATH = join(SCRIPT_DIR, "route-recommendation.routes.json");
+
+function loadRoutes() {
+  if (!existsSync(ROUTES_PATH)) {
+    stderr.write(`routes file not found: ${ROUTES_PATH}\n`);
+    exit(3);
+  }
+  const raw = readFileSync(ROUTES_PATH, "utf8");
+  const parsed = JSON.parse(raw);
+  if (!parsed || !Array.isArray(parsed.rows)) {
+    stderr.write(`routes file is malformed (expected { rows: [...] })\n`);
+    exit(3);
+  }
+  return parsed.rows;
+}
+
+function parseArgs() {
+  const args = argv.slice(2);
+  const out = { json: false, list: false, input: null };
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--json") out.json = true;
+    else if (a === "--list") out.list = true;
+    else if (a === "-h" || a === "--help") {
+      stdout.write(
+        "usage: route-recommendation.mjs [--json] <recommendation item>\n" +
+          "       route-recommendation.mjs --list [--json]\n",
+      );
+      exit(0);
+    } else {
+      positional.push(a);
+    }
+  }
+  if (!out.list) {
+    if (positional.length === 0) {
+      stderr.write("usage: route-recommendation.mjs [--json] <recommendation item>\n");
+      stderr.write("input required: pass the recommendation text as the positional arg\n");
+      exit(2);
+    }
+    out.input = positional.join(" ").trim();
+  }
+  return out;
+}
+
+function compileRow(row) {
+  const patterns = Array.isArray(row.patterns) ? row.patterns : [];
+  const compiled = [];
+  for (const p of patterns) {
+    try {
+      compiled.push(new RegExp(p, "i"));
+    } catch {
+      // skip malformed pattern — surface via warning, don't crash
+      stderr.write(`warning: bad regex in routes.json (${row.name}): ${p}\n`);
+    }
+  }
+  return { ...row, _compiled: compiled };
+}
+
+function matchRow(row, input) {
+  for (const re of row._compiled) {
+    if (re.test(input)) return true;
+  }
+  return false;
+}
+
+function asciiArrow(preferred) {
+  return preferred.join(" -> ");
+}
+
+function pretty(matchResult) {
+  if (!matchResult.match) {
+    return [
+      `No routing match for input: "${matchResult.input}"`,
+      `ask-operator: this recommendation doesn't fit any known routing row.`,
+      `Either pick a row from --list manually, or surface to the operator.`,
+      "",
+    ].join("\n");
+  }
+  const m = matchResult.match;
+  const lines = [
+    `Match: ${m.name}`,
+    `Preferred: ${asciiArrow(m.preferred)}`,
+    `Fallback: ${m.fallback}`,
+  ];
+  if (m.marker) {
+    lines.push(`Marker: (Reference behavior — does not require ${m.marker}.)`);
+  }
+  if (matchResult.candidates.length > 1) {
+    lines.push("");
+    lines.push(`Other candidates (top match wins):`);
+    for (const c of matchResult.candidates.slice(1, 4)) {
+      lines.push(`  - ${c.name}`);
+    }
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+function main() {
+  const args = parseArgs();
+  const rawRows = loadRoutes();
+  const rows = rawRows.map(compileRow);
+
+  if (args.list) {
+    if (args.json) {
+      const stripped = rows.map(({ _compiled, ...row }) => row);
+      stdout.write(JSON.stringify({ rows: stripped }, null, 2) + "\n");
+      return;
+    }
+    for (const row of rows) {
+      stdout.write(`- ${row.name}\n`);
+      stdout.write(`    preferred: ${asciiArrow(row.preferred)}\n`);
+    }
+    return;
+  }
+
+  const candidates = rows.filter((r) => matchRow(r, args.input));
+  const result = {
+    input: args.input,
+    match: candidates.length > 0 ? stripCompiled(candidates[0]) : null,
+    candidates: candidates.map(stripCompiled),
+  };
+
+  if (args.json) {
+    stdout.write(JSON.stringify(result, null, 2) + "\n");
+  } else {
+    stdout.write(pretty(result));
+  }
+  // Surface the ask-operator hint on stderr regardless of mode, so callers
+  // that read stderr can detect no-match without re-parsing stdout.
+  if (!result.match) {
+    stderr.write("ask-operator: no routing row matched the input\n");
+  }
+}
+
+function stripCompiled(row) {
+  const { _compiled, ...rest } = row;
+  return rest;
+}
+
+main();