@elmundi/ship-cli 0.14.2 → 0.15.4

package/lib/commands/trigger.mjs

@@ -1,7 +1,7 @@
 import { readConfig } from "../config/io.mjs";
 import { dueLanesFromRoutines, dueRoutines } from "../runtime/routines.mjs";
 
-const VERSION = "v2";
+const VERSION = "v3";
 
 export async function triggerCommand(ctx, rest) {
   const opts = parseArgs(rest);
@@ -12,10 +12,23 @@ export async function triggerCommand(ctx, rest) {
   const baseUrl = resolveBaseUrl(opts.baseUrl || explicitGlobalBaseUrl(ctx));
   const token = process.env.SHIP_API_TOKEN || "";
   let claimStatus = "skipped:no-token";
-  if (token && due.length > 0 && !opts.noClaim) {
-    let workspaceId = opts.workspace;
+  let workspaceId = null;
+  let repoId = null;
+  if (token && (due.length > 0 || opts.pipelineFallback) && !opts.noClaim) {
+    // ``SHIP_WORKSPACE_ID`` env var matches what ``shipctl run`` already
+    // honours (run.mjs reads it directly). Without this fallback the
+    // CLI burned a ``GET /v1/workspaces`` round-trip every tick and
+    // — if the token's user happened to have zero memberships at that
+    // moment — printed "No workspaces visible to this token" and
+    // failed the entire schedule, even though the workflow file had
+    // the workspace ID right there in env. Honour the env var so the
+    // common case skips the discovery call entirely.
+    workspaceId =
+      opts.workspace || (process.env.SHIP_WORKSPACE_ID || "").trim() || "";
     if (!workspaceId) workspaceId = await resolveSoleWorkspace(baseUrl, token);
-    const repoId = await resolveRepoId(baseUrl, token, workspaceId, opts.repo);
+    repoId = await resolveRepoId(baseUrl, token, workspaceId, opts.repo);
+  }
+  if (token && due.length > 0 && !opts.noClaim) {
     const claimed = [];
     for (const routine of due) {
       const claim = await claimRoutine(baseUrl, token, workspaceId, repoId, opts.event, routine);
@@ -27,6 +40,26 @@ export async function triggerCommand(ctx, rest) {
     claimStatus = "attempted";
   }
 
+  // One-action-per-tick: if any routine is due, the workflow runs the
+  // first one and exits. The pipeline-pick fallback only fires when
+  // *no* cron routine is due AND the caller asked for it (the trigger
+  // workflow does; ad-hoc CLI invocations don't, so they keep the old
+  // behaviour).
+  let nextAction = { kind: "noop" };
+  if (due.length > 0) {
+    const first = due[0];
+    nextAction = {
+      kind: "routine",
+      routine_id: first.routine_id,
+      window_key: first.window_key,
+    };
+  } else if (opts.pipelineFallback && token) {
+    const pick = await fetchPipelinePick(baseUrl, token, workspaceId, repoId, opts.event);
+    if (pick && pick.action === "pipeline_pick" && pick.specialist) {
+      nextAction = { kind: "pipeline_pick", specialist: pick.specialist };
+    }
+  }
+
   const result = {
     event: opts.event,
     status: due.length ? "due" : "noop",
@@ -34,18 +67,22 @@ export async function triggerCommand(ctx, rest) {
     due_lanes: dueLanesFromRoutines(due),
     skipped_routines: local.skipped,
     claim_status: claimStatus,
+    next_action: nextAction,
   };
 
   if (ctx.json || opts.json) {
     console.log(JSON.stringify(result, null, 2));
     return;
   }
-  if (!due.length) {
-    console.log(`Ship trigger ${opts.event}: no routines due.`);
+  if (nextAction.kind === "noop") {
+    console.log(`Ship trigger ${opts.event}: no action this tick.`);
+    return;
+  }
+  if (nextAction.kind === "routine") {
+    console.log(`Ship trigger ${opts.event}: routine ${nextAction.routine_id}`);
     return;
   }
-  console.log(`Ship trigger ${opts.event}: ${due.length} routine(s) due`);
-  for (const routine of due) console.log(`  - ${routine.routine_id}`);
+  console.log(`Ship trigger ${opts.event}: pipeline pick → ${nextAction.specialist}`);
 }
 
 function explicitGlobalBaseUrl(ctx) {
@@ -53,13 +90,30 @@ function explicitGlobalBaseUrl(ctx) {
 }
 
 function printHelp() {
-  console.log(`shipctl trigger — compute which routines are due (${VERSION})
+  console.log(`shipctl trigger — compute the single next Ship action for this tick (${VERSION})
 
 USAGE
-  shipctl trigger --event schedule [--repo <id|owner/name>] [--workspace <id>] [--json]
+  shipctl trigger --event schedule [--repo <id|owner/name>] [--workspace <id>]
+                  [--pipeline-fallback] [--json]
+
+OUTPUT
+  'next_action' carries the chosen work for this tick:
+    {"kind": "routine", "routine_id": ...}      — a cron routine fired this tick
+    {"kind": "pipeline_pick", "specialist": ...} — no routine due; pipeline-pick chose a specialist
+    {"kind": "noop"}                            — nothing to do (and no fallback, or fallback empty)
+
+  'due_routines' keeps the legacy multi-item shape for callers that
+  parse it directly; the trigger workflow only consumes 'next_action'.
+
+FLAGS
+  --pipeline-fallback   When no routine is due, call /pipeline-pick to
+                        get a specialist to run instead. Default: off
+                        (so ad-hoc CLI invocations don't write audit
+                        log noise).
 
 ENV
   SHIP_API_TOKEN             Optional. When set, due routines are claimed in Ship.
+  SHIP_WORKSPACE_ID          Optional. Skips the /v1/workspaces lookup if set.
   SHIP_WORKSPACE_API_BASE    Optional API base override.
   SHIP_API_BASE              Fallback API base override.
 `);
@@ -74,6 +128,7 @@ function parseArgs(args) {
     cwd: null,
     now: null,
     noClaim: false,
+    pipelineFallback: false,
     json: false,
   };
   const copy = [...args];
@@ -107,6 +162,11 @@ function parseArgs(args) {
       copy.shift();
       continue;
     }
+    if (copy[0] === "--pipeline-fallback") {
+      out.pipelineFallback = true;
+      copy.shift();
+      continue;
+    }
     if (copy[0] === "--json") {
       out.json = true;
       copy.shift();
@@ -176,6 +236,31 @@ async function apiPostJson(baseUrl, path, body, token) {
   return apiRequest(baseUrl, path, "POST", token, body);
 }
 
+async function fetchPipelinePick(baseUrl, token, workspaceId, repoId, event) {
+  try {
+    return await apiPostJson(
+      baseUrl,
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/repos/${encodeURIComponent(repoId)}/pipeline-pick`,
+      {
+        event,
+        github: {
+          event_name: process.env.SHIP_EVENT_NAME || process.env.GITHUB_EVENT_NAME || "",
+          ref: process.env.SHIP_REF || process.env.GITHUB_REF || "",
+          sha: process.env.SHIP_SHA || process.env.GITHUB_SHA || "",
+          run_id: process.env.GITHUB_RUN_ID || "",
+        },
+      },
+      token,
+    );
+  } catch (err) {
+    console.error(
+      `warn: pipeline-pick failed, no fallback this tick: ${err instanceof Error ? err.message : err}`,
+    );
+    return null;
+  }
+}
+
+
 async function claimRoutine(baseUrl, token, workspaceId, repoId, event, routine) {
   try {
     return await apiPostJson(

package/lib/config/schema.mjs

@@ -1,14 +1,14 @@
 import { KNOWN_AGENTS } from "../detect.mjs";
 
 /* Historical schema used by every released shipctl through 0.11.x. We
- * keep validating it in parallel with v2 so customers who haven't run
- * `shipctl migrate` see clear warnings instead of silent failures. */
+ * keep validating it in parallel with v2 so legacy configs surface a
+ * deprecation warning instead of failing silently. */
 export const LEGACY_CONFIG_SCHEMA_VERSION = 1;
 
 /* RFC-0007 lanes-as-config. Introduced alongside `shipctl run`. Clients
  * that understand only v1 will refuse to read v2 and print a shipctl
  * upgrade hint; clients that understand v2 accept v1 with a deprecation
- * warning and suggest `shipctl migrate`. */
+ * warning. */
 export const CONFIG_SCHEMA_VERSION = 2;
 
 export const SUPPORTED_CONFIG_VERSIONS = Object.freeze([
@@ -65,6 +65,12 @@ export const PROCESS_TRIGGER_TYPES = Object.freeze(["manual", "event", "schedule
  * file names (`.github/workflows/ship-<lane>.yml`), and env vars, so
  * restrict them conservatively: ASCII lowercase, digits, dash, underscore. */
 export const LANE_ID_REGEX = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+
+/* Agent role slug — kebab-case only (Phase 2.4). Mirrors the
+ * server's ``backend/app/services/agent_roles.is_valid_slug`` regex
+ * so an invalid slug fails locally before the runtime resolver
+ * round-trips to the workspace API. Used for ``routine.specialist``. */
+export const AGENT_ROLE_SLUG_REGEX = /^[a-z0-9][a-z0-9-]{0,63}$/;
 export const IDEMPOTENCY_KEY_REGEX = /^[a-z0-9][a-z0-9_.-]{0,127}$/;
 /* Coarse sanity check for 5-field crons: we're not a cron parser, but
  * anything that isn't whitespace-separated 5 tokens is almost certainly
@@ -115,11 +121,11 @@ export const PRESETS = Object.freeze([
 
 export const CHANNELS = Object.freeze(["stable", "edge"]);
 
-export const KINDS = Object.freeze(["pattern", "tool", "collection", "doc"]);
+export const KINDS = Object.freeze(["collection"]);
 
 export const AGENT_IDS = Object.freeze(Object.keys(KNOWN_AGENTS));
 
-export const PIN_KEY_REGEX = /^(pattern|tool|collection|doc)\/[a-zA-Z0-9_\-\.\/]+$/;
+export const PIN_KEY_REGEX = /^collection\/[a-zA-Z0-9_\-\.\/]+$/;
 
 export const UUID_V4_REGEX =
   /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
@@ -330,7 +336,16 @@ function validateV2Process(obj, errors, warnings) {
   }
   pushUnknownKeyWarnings(
     process,
-    new Set(["id", "name", "primary", "states", "transitions", "routines"]),
+    new Set([
+      "id",
+      "name",
+      "primary",
+      "states",
+      "transitions",
+      "routines",
+      "schedule",
+      "gates",
+    ]),
     "process",
     warnings,
   );
@@ -343,6 +358,19 @@ function validateV2Process(obj, errors, warnings) {
   if (process.primary !== undefined && typeof process.primary !== "boolean") {
     errors.push("process.primary: must be boolean when set");
   }
+  // Where the operator wants to interject (Phase 3). ``after_pr``
+  // (default) is fully autonomous through the agent reviewer;
+  // ``after_arch`` pauses for human approval after architects;
+  // ``after_ba`` pauses earlier, after BA writes the spec.
+  // Enforcement (FSM "needs review" routing) lands in Phase 3.5.
+  if (process.gates !== undefined) {
+    const allowed = new Set(["after_ba", "after_arch", "after_pr"]);
+    if (typeof process.gates !== "string" || !allowed.has(process.gates)) {
+      errors.push(
+        `process.gates: must be one of ${[...allowed].join(" | ")} when set`,
+      );
+    }
+  }
 
   if (!Array.isArray(process.states) || process.states.length < 1) {
     errors.push("process.states: must contain at least one state");
@@ -530,6 +558,10 @@ function validateProcessRoutines(value, errors, warnings) {
         "schedule",
         "window",
         "event",
+        // ``fsm_stage`` overrides the role's default stage so one role
+        // can drive multiple processes (BA serves both
+        // ``ba_requirements`` for SDLC and ``wbs`` for decomposition).
+        "fsm_stage",
       ]),
       prefix,
       warnings,
@@ -558,7 +590,37 @@ function validateProcessRoutines(value, errors, warnings) {
     }
     requireOptionalString(routine.specialist_id, `${prefix}.specialist_id`, errors, { required: false });
     requireOptionalString(routine.specialist_name, `${prefix}.specialist_name`, errors, { required: false });
+    /* ``routine.specialist`` is the canonical Phase 2.4 form — an
+     * agent role slug ``shipctl run`` resolves through
+     * ``GET /v1/.../agent-roles/{slug}/resolve``. Two shapes are
+     * accepted: a bare string (the slug) for the new spec, and an
+     * object (with ``id`` / ``name``) for the legacy process-state
+     * specialist record. Object form is validated elsewhere; here we
+     * only police the string form's slug grammar. */
+    if (typeof routine.specialist === "string") {
+      if (!AGENT_ROLE_SLUG_REGEX.test(routine.specialist)) {
+        errors.push(
+          `${prefix}.specialist: must be an agent-role slug (kebab-case [a-z0-9-]{1,64})`,
+        );
+      }
+    }
+    /* Legacy ``pattern: <slug>`` keeps working but nudges authors
+     * toward the new vocabulary. ``specialist: <slug>`` wins when
+     * both are set. */
+    if (
+      typeof routine.pattern === "string" &&
+      routine.pattern.trim() &&
+      typeof routine.specialist !== "string"
+    ) {
+      const suggested = routine.pattern.startsWith("role-")
+        ? routine.pattern.slice("role-".length)
+        : routine.pattern;
+      warnings.push(
+        `${prefix}.pattern: deprecated alias — use \`specialist: ${suggested}\` instead`,
+      );
+    }
     validateProcessAgentProfile(routine.agent_profile, `${prefix}.agent_profile`, errors);
+    requireOptionalString(routine.fsm_stage, `${prefix}.fsm_stage`, errors, { required: false });
     validateRoutineTrigger(routine.trigger, `${prefix}.trigger`, errors);
     if (routine.schedule !== undefined && routine.schedule !== null) {
       if (typeof routine.schedule !== "string" && !isPlainObject(routine.schedule)) {
@@ -639,9 +701,9 @@ function validateV2Lanes(obj, errors, warnings) {
 
   const lanes = obj.lanes;
   if (lanes === undefined) {
-    /* An empty lanes map is legal — a fresh repo that has only gone
-     * through `shipctl migrate` has no automation wired yet, and that's
-     * the right default for onboarding. */
+    /* An empty lanes map is legal — a fresh repo seeded by the wizard
+     * declares automation under `process.routines:` instead, and the
+     * top-level `lanes:` key is left out. */
     return;
   }
   if (!isPlainObject(lanes)) {
@@ -863,7 +925,7 @@ export function validateConfig(obj) {
 
   if (!isV2) {
     warnings.push(
-      `version: config is at v${obj.version}; run \`shipctl migrate\` to upgrade to v${CONFIG_SCHEMA_VERSION}`,
+      `version: config is at v${obj.version}; v${CONFIG_SCHEMA_VERSION} is the current schema. Re-seed the repo from the workspace wizard to upgrade.`,
     );
   }
 
@@ -944,7 +1006,7 @@ export function validateConfig(obj) {
           for (const [k, v] of Object.entries(artifacts.pins)) {
             if (!PIN_KEY_REGEX.test(k)) {
               errors.push(
-                `artifacts.pins[${JSON.stringify(k)}]: invalid key; expected <kind>/<id> where kind∈{pattern,tool,collection,doc}`,
+                `artifacts.pins[${JSON.stringify(k)}]: invalid key; expected collection/<id>`,
               );
             }
             if (typeof v !== "string" || !SEMVER_OR_RANGE_REGEX.test(v.trim())) {

package/lib/http.mjs

@@ -93,8 +93,6 @@ export async function apiGet(baseUrl, path) {
  */
 export async function fetchManifest(baseUrl, { channel } = {}) {
   const KINDS = [
-    { plural: "patterns", singular: "pattern" },
-    { plural: "tools", singular: "tool" },
     { plural: "collections", singular: "collection" },
   ];
   const responses = await Promise.all(

package/lib/runtime/routines.mjs

@@ -47,11 +47,16 @@ export function executableIds(config) {
 
 export function routineToExecutable(id, routine) {
   const trigger = normalizeRoutineTrigger(routine);
+  // Phase 2.4: ``specialist:`` is the canonical agent-role slug;
+  // ``pattern:`` is kept as a back-compat alias and translated to a
+  // slug below (drop the ``role-`` prefix the legacy catalog used).
+  const specialist = pickSpecialistSlug(routine);
   return {
     id,
     type: "routine",
     kind: trigger.kind,
     trigger,
+    specialist,
     pattern: stringOrNull(routine.pattern),
     patterns: Array.isArray(routine.patterns) ? routine.patterns : undefined,
     pattern_version: stringOrNull(routine.pattern_version),
@@ -59,9 +64,43 @@ export function routineToExecutable(id, routine) {
     idempotency: routine.idempotency || null,
     prompt: stringOrNull(routine.prompt) || stringOrNull(routine.instructions),
     agent_profile: stringOrNull(routine.agent_profile) || stringOrNull(routine.specialist?.agent_profile),
+    // Per-routine FSM stage override. When set, ``shipctl run`` uses
+    // it instead of the role's default ``fsm_stage`` — that's how a
+    // single role (e.g. ``ba``) serves both SDLC (``ba_requirements``)
+    // and decomposition (``wbs``) without per-process role clones.
+    fsm_stage: stringOrNull(routine.fsm_stage),
   };
 }
 
+/**
+ * Pull the agent-role slug out of a routine, preferring the new
+ * ``specialist:`` key but falling back to the legacy ``pattern:`` and
+ * stripping the historical ``role-`` prefix when present.
+ *
+ * Object-form ``specialist`` (the process-state record with ``id`` /
+ * ``name``) is treated as a slug source via ``specialist.id`` for
+ * configs that mirror the process-stage shape into routines.
+ */
+function pickSpecialistSlug(routine) {
+  if (typeof routine.specialist === "string") {
+    const v = routine.specialist.trim();
+    if (v) return v;
+  }
+  if (
+    routine.specialist &&
+    typeof routine.specialist === "object" &&
+    typeof routine.specialist.id === "string"
+  ) {
+    const v = routine.specialist.id.trim();
+    if (v) return v;
+  }
+  if (typeof routine.pattern === "string" && routine.pattern.trim()) {
+    const p = routine.pattern.trim();
+    return p.startsWith("role-") ? p.slice("role-".length) : p;
+  }
+  return null;
+}
+
 export function laneToExecutable(id, lane) {
   return {
     id,

package/lib/templates.mjs

@@ -33,8 +33,8 @@ shipctl pattern list
 shipctl pattern show role-developer              # resolves latest or pin
 shipctl pattern fetch role-developer --version 1.4.2
 shipctl search "release gates and qa split" --top-k 8
-shipctl docs fetch documentation/adoption/delivery-quality-and-release-process.md
-shipctl sync                                       # reconcile .ship/cache/
+shipctl knowledge fetch repository-context           # workspace bucket
+shipctl sync                                         # reconcile .ship/cache/
 \`\`\`
 
 ## HTTP (curl, no CLI)

package/lib/verify/checks/agents-on-disk.mjs

@@ -1,7 +1,4 @@
-import fs from "node:fs";
-import path from "node:path";
 import { detectAgentTargets } from "../../detect.mjs";
-import { readCachedArtifact } from "../../cache/store.mjs";
 
 export const id = "agents-on-disk";
 export const category = "config";
@@ -17,32 +14,12 @@ export async function run(ctx) {
   if (!declared.length) {
     return { status: "skip", detail: "stack.agents is empty" };
   }
+  // Phase 2.5 retired the local artifact cache; agent-rule install
+  // paths are no longer available via cached frontmatter. Fall back
+  // to the heuristic detector only — it covers the common targets
+  // (CLAUDE.md, AGENTS.md, .cursor/rules/...) the seed PR writes.
   const detected = new Set(detectAgentTargets(ctx.cwd).map((t) => t.id));
-  const missing = [];
-  for (const agent of declared) {
-    if (detected.has(agent)) continue;
-    // Second chance: the cached agent-rules artifact may declare a custom
-    // install_target (e.g. codex -> AGENTS.md) that the heuristic detector
-    // doesn't recognise. Treat a present install_target file as "signal".
-    let fm = null;
-    try {
-      fm = readCachedArtifact(ctx.cwd, "collection", `agent-rules-${agent}`);
-    } catch {
-      fm = null;
-    }
-    const topLevel = fm && fm.fm && typeof fm.fm.install_target === "string"
-      ? fm.fm.install_target.trim()
-      : "";
-    const nested = fm && fm.spec && typeof fm.spec.install_target === "string"
-      ? fm.spec.install_target.trim()
-      : "";
-    const target = topLevel || nested;
-    if (target && fs.existsSync(path.join(ctx.cwd, target))) {
-      detected.add(agent);
-      continue;
-    }
-    missing.push(agent);
-  }
+  const missing = declared.filter((agent) => !detected.has(agent));
   if (missing.length) {
     return {
       status: "warn",

package/lib/verify/registry.mjs

@@ -23,32 +23,31 @@
  */
 
 import * as configPresent from "./checks/config-present.mjs";
-import * as gitignoreCache from "./checks/gitignore-cache.mjs";
-import * as rulesMarkers from "./checks/rules-markers.mjs";
-import * as cacheIntegrity from "./checks/cache-integrity.mjs";
 import * as bootstrapFiles from "./checks/bootstrap-files.mjs";
 import * as stackEnums from "./checks/stack-enums.mjs";
 import * as agentsOnDisk from "./checks/agents-on-disk.mjs";
 import * as apiReachable from "./checks/api-reachable.mjs";
-import * as artifactsUpToDate from "./checks/artifacts-up-to-date.mjs";
 import * as trackerLabels from "./checks/tracker-labels.mjs";
 import * as ciSecrets from "./checks/ci-secrets.mjs";
 
 /**
  * Ordered list of checks. Order governs how they appear in `shipctl verify`
  * output; within a category we keep a stable human-friendly grouping.
+ *
+ * Phase 2.5 retired four cache-coupled checks (``gitignore-cache``,
+ * ``rules-markers``, ``cache-integrity``, ``artifacts-up-to-date``)
+ * along with the ``shipctl sync`` flow that filled the cache. Agent
+ * rule files now live in the seed PR — there's nothing left in
+ * ``.ship/cache`` for ``verify`` to validate.
+ *
  * @type {Check[]}
  */
 const CHECKS = [
   configPresent,
-  gitignoreCache,
   stackEnums,
-  rulesMarkers,
-  cacheIntegrity,
   bootstrapFiles,
   agentsOnDisk,
   apiReachable,
-  artifactsUpToDate,
   trackerLabels,
   ciSecrets,
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elmundi/ship-cli",
-  "version": "0.14.2",
+  "version": "0.15.4",
   "type": "module",
   "description": "Ship CLI: bootstrap a repo, sync the catalog, run process routines, report outcomes.",
   "license": "Apache-2.0",