@ritualai/cli 0.36.37 → 0.36.39

package/dist/lib/telemetry.js

@@ -0,0 +1,234 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isFirstRun = isFirstRun;
+exports.isEnabled = isEnabled;
+exports.setOptOut = setOptOut;
+exports.describeStatus = describeStatus;
+exports.capture = capture;
+exports.identify = identify;
+exports.maybeShowFirstRunNotice = maybeShowFirstRunNotice;
+exports.flush = flush;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const node_crypto_1 = require("node:crypto");
+const config_1 = require("./config");
+const credentials_backup_1 = require("./credentials-backup");
+const package_info_1 = require("./package-info");
+/**
+ * Anonymous, opt-out usage analytics for the Ritual CLI.
+ *
+ * Design goals:
+ *   - Never blocks a command. Every send is fire-and-forget with a hard
+ *     timeout; failures are swallowed. This is load-bearing for `login`,
+ *     whose browser-loopback must not wait on a telemetry POST.
+ *   - Anonymous until you sign in. A random install id (in
+ *     ~/.config/ritual/telemetry.json) is the distinct_id pre-login; on
+ *     login we $identify it to the Keycloak `sub` so the pre-login funnel
+ *     stitches to the account (and to the marketing-site signup, which
+ *     uses the same PostHog project).
+ *   - Easy to turn off: DO_NOT_TRACK, RITUAL_TELEMETRY=0, or
+ *     `ritual telemetry off`. Always skipped in CI.
+ *
+ * Same PostHog project as ritual.work so the web + CLI funnels are one
+ * graph. Key + host are overridable for self-hosters / tests.
+ */
+const POSTHOG_HOST = (process.env.RITUAL_POSTHOG_HOST || 'https://us.i.posthog.com').replace(/\/$/, '');
+const POSTHOG_KEY = process.env.RITUAL_POSTHOG_KEY || 'phc_nNH8wifJVxDrCfAUabmwni44genZggRTT52CBdtQS4w4';
+// Hard cap on how long a single send can hang. Reachable PostHog answers in
+// ~100-300ms; this only bites when the host is firewalled/black-holed, and it
+// bounds the worst-case latency a telemetry POST can add to a command's exit.
+const SEND_TIMEOUT_MS = 800;
+function statePath() {
+    return (0, node_path_1.join)((0, config_1.configDir)(), 'telemetry.json');
+}
+let cachedState = null;
+const pending = [];
+function isCI() {
+    const e = process.env;
+    return !!(e.CI ||
+        e.CONTINUOUS_INTEGRATION ||
+        e.GITHUB_ACTIONS ||
+        e.GITLAB_CI ||
+        e.CIRCLECI ||
+        e.TRAVIS ||
+        e.BUILDKITE ||
+        e.TF_BUILD ||
+        e.JENKINS_URL);
+}
+function envDisabled() {
+    const e = process.env;
+    if (e.DO_NOT_TRACK === '1' || e.DO_NOT_TRACK === 'true')
+        return true;
+    const t = (e.RITUAL_TELEMETRY || '').toLowerCase();
+    if (t === '0' || t === 'false' || t === 'off' || t === 'no')
+        return true;
+    return false;
+}
+/** True only the very first time the CLI runs on this machine. */
+function isFirstRun() {
+    return !(0, node_fs_1.existsSync)(statePath());
+}
+function readStateRaw() {
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(statePath(), 'utf-8'));
+        if (parsed && typeof parsed.installId === 'string')
+            return parsed;
+    }
+    catch {
+        /* missing / corrupt — caller decides */
+    }
+    return null;
+}
+/** Load (and create on first ever call) the telemetry state. */
+function loadState() {
+    if (cachedState)
+        return cachedState;
+    const existing = readStateRaw();
+    if (existing) {
+        cachedState = existing;
+        return existing;
+    }
+    const fresh = {
+        installId: (0, node_crypto_1.randomUUID)(),
+        firstRunAt: new Date().toISOString(),
+    };
+    saveState(fresh);
+    return fresh;
+}
+function saveState(state) {
+    cachedState = state;
+    try {
+        (0, node_fs_1.mkdirSync)((0, config_1.configDir)(), { recursive: true });
+        // Same 0600 create-with-mode helper the credentials store uses —
+        // the install id is low-sensitivity, but keep it owner-only anyway.
+        (0, credentials_backup_1.writeFileMode0600)(statePath(), JSON.stringify(state, null, 2));
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/**
+ * Is telemetry on? Env / CI checks come first so opted-out and CI users
+ * never even get an install id written to disk.
+ */
+function isEnabled() {
+    if (envDisabled() || isCI())
+        return false;
+    return !loadState().optedOut;
+}
+/** Persist an explicit opt-in/opt-out (for `ritual telemetry on|off`). */
+function setOptOut(optedOut) {
+    saveState({ ...loadState(), optedOut });
+}
+/** Current opt-out posture for `ritual telemetry status`. */
+function describeStatus() {
+    if (envDisabled())
+        return { enabled: false, reason: 'disabled via DO_NOT_TRACK / RITUAL_TELEMETRY', installId: '—' };
+    if (isCI())
+        return { enabled: false, reason: 'CI environment detected', installId: '—' };
+    const s = loadState();
+    return {
+        enabled: !s.optedOut,
+        reason: s.optedOut ? 'disabled via `ritual telemetry off`' : 'enabled',
+        installId: s.installId,
+    };
+}
+function baseProps() {
+    return {
+        $lib: 'ritual-cli',
+        cli_version: (0, package_info_1.readPackageVersionSafe)(),
+        os: (0, node_os_1.platform)(),
+        arch: process.arch,
+        node_version: process.version,
+        is_ci: isCI(),
+    };
+}
+/** sub once signed in (stitched on $identify), else the anonymous install id. */
+function distinctId() {
+    try {
+        const creds = (0, config_1.loadCredentials)();
+        if (creds?.user?.sub)
+            return creds.user.sub;
+    }
+    catch {
+        /* ignore */
+    }
+    return loadState().installId;
+}
+async function send(body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), SEND_TIMEOUT_MS);
+    try {
+        await fetch(`${POSTHOG_HOST}/capture/`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+    }
+    catch {
+        /* network down / aborted / blocked — never surface to the user */
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Fire-and-forget event. No-op when disabled. */
+function capture(event, properties = {}) {
+    if (!isEnabled())
+        return;
+    pending.push(send({
+        api_key: POSTHOG_KEY,
+        event,
+        distinct_id: distinctId(),
+        properties: { ...baseProps(), ...properties },
+        timestamp: new Date().toISOString(),
+    }));
+}
+/**
+ * Link the anonymous install id to the signed-in user (Keycloak sub) and
+ * set durable person properties. Call once, right after a successful login.
+ */
+function identify(sub, person = {}) {
+    if (!isEnabled())
+        return;
+    const installId = loadState().installId;
+    if (!sub || sub === installId)
+        return;
+    pending.push(send({
+        api_key: POSTHOG_KEY,
+        event: '$identify',
+        distinct_id: sub,
+        properties: {
+            $anon_distinct_id: installId, // merges prior anonymous events into the person
+            $set: { ...baseProps(), ...person },
+        },
+        timestamp: new Date().toISOString(),
+    }));
+}
+/**
+ * One-time disclosure. Printed to stderr so it never pollutes stdout that
+ * a script might parse. No-op in CI / when disabled / after first shown.
+ */
+function maybeShowFirstRunNotice() {
+    if (envDisabled() || isCI())
+        return;
+    const s = loadState();
+    if (s.noticeShownAt || s.optedOut)
+        return;
+    saveState({ ...s, noticeShownAt: new Date().toISOString() });
+    process.stderr.write('\n  Ritual CLI collects anonymous usage analytics to help improve the product.\n' +
+        '  Opt out anytime: `ritual telemetry off` (or set RITUAL_TELEMETRY=0).\n\n');
+}
+/** Await in-flight sends (bounded) so events leave before the process exits. */
+async function flush(timeoutMs = SEND_TIMEOUT_MS + 250) {
+    if (pending.length === 0)
+        return;
+    const inFlight = pending.splice(0);
+    await Promise.race([
+        Promise.allSettled(inFlight),
+        new Promise((resolve) => setTimeout(resolve, timeoutMs)),
+    ]);
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/lib/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../../src/lib/telemetry.ts"],"names":[],"mappings":";;AA0EA,gCAEC;AA4CD,8BAGC;AAGD,8BAEC;AAGD,wCASC;AA0CD,0BAWC;AAMD,4BAgBC;AAMD,0DASC;AAGD,sBAOC;AAhPD,qCAA8D;AAC9D,qCAAmC;AACnC,yCAAiC;AACjC,6CAAyC;AACzC,qCAAsD;AACtD,6DAAyD;AACzD,iDAAwD;AAExD;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,YAAY,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,0BAA0B,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AACxG,MAAM,WAAW,GAChB,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,kDAAkD,CAAC;AAEtF,4EAA4E;AAC5E,8EAA8E;AAC9E,8EAA8E;AAC9E,MAAM,eAAe,GAAG,GAAG,CAAC;AAS5B,SAAS,SAAS;IACjB,OAAO,IAAA,gBAAI,EAAC,IAAA,kBAAS,GAAE,EAAE,gBAAgB,CAAC,CAAC;AAC5C,CAAC;AAED,IAAI,WAAW,GAA0B,IAAI,CAAC;AAC9C,MAAM,OAAO,GAAuB,EAAE,CAAC;AAEvC,SAAS,IAAI;IACZ,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC;IACtB,OAAO,CAAC,CAAC,CACR,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,sBAAsB;QACxB,CAAC,CAAC,cAAc;QAChB,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,WAAW,CACb,CAAC;AACH,CAAC;AAED,SAAS,WAAW;IACnB,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC;IACtB,IAAI,CAAC,CAAC,YAAY,KAAK,GAAG,IAAI,CAAC,CAAC,YAAY,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACrE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,gBAAgB,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IACnD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACzE,OAAO,KAAK,CAAC;AACd,CAAC;AAED,kEAAkE;AAClE,SAAgB,UAAU;IACzB,OAAO,CAAC,IAAA,oBAAU,EAAC,SAAS,EAAE,CAAC,CAAC;AACjC,CAAC;AAED,SAAS,YAAY;IACpB,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAA,sBAAY,EAAC,SAAS,EAAE,EAAE,OAAO,CAAC,CAAmB,CAAC;QAChF,IAAI,MAAM,IAAI,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ;YAAE,OAAO,MAAM,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACR,wCAAwC;IACzC,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC;AAED,gEAAgE;AAChE,SAAS,SAAS;IACjB,IAAI,WAAW;QAAE,OAAO,WAAW,CAAC;IACpC,MAAM,QAAQ,GAAG,YAAY,EAAE,CAAC;IAChC,IAAI,QAAQ,EAAE,CAAC;QACd,WAAW,GAAG,QAAQ,CAAC;QACvB,OAAO,QAAQ,CAAC;IACjB,CAAC;IACD,MAAM,KAAK,GAAmB;QAC7B,SAAS,EAAE,IAAA,wBAAU,GAAE;QACvB,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;IACF,SAAS,CAAC,KAAK,CAAC,CAAC;IACjB,OAAO,KAAK,CAAC;AACd,CAAC;AAED,SAAS,SAAS,CAAC,KAAqB;IACvC,WAAW,GAAG,KAAK,CAAC;IACpB,IAAI,CAAC;QACJ,IAAA,mBAAS,EAAC,IAAA,kBAAS,GAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5C,iEAAiE;QACjE,oEAAoE;QACpE,IAAA,sCAAiB,EAAC,SAAS,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACR,iBAAiB;IAClB,CAAC;AACF,CAAC;AAED;;;GAGG;AACH,SAAgB,SAAS;IACxB,IAAI,WAAW,EAAE,IAAI,IAAI,EAAE;QAAE,OAAO,KAAK,CAAC;IAC1C,OAAO,CAAC,SAAS,EAAE,CAAC,QAAQ,CAAC;AAC9B,CAAC;AAED,0EAA0E;AAC1E,SAAgB,SAAS,CAAC,QAAiB;IAC1C,SAAS,CAAC,EAAE,GAAG,SAAS,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;AACzC,CAAC;AAED,6DAA6D;AAC7D,SAAgB,cAAc;IAC7B,IAAI,WAAW,EAAE;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,8CAA8C,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC;IACrH,IAAI,IAAI,EAAE;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,yBAAyB,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC;IACzF,MAAM,CAAC,GAAG,SAAS,EAAE,CAAC;IACtB,OAAO;QACN,OAAO,EAAE,CAAC,CAAC,CAAC,QAAQ;QACpB,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,qCAAqC,CAAC,CAAC,CAAC,SAAS;QACtE,SAAS,EAAE,CAAC,CAAC,SAAS;KACtB,CAAC;AACH,CAAC;AAED,SAAS,SAAS;IACjB,OAAO;QACN,IAAI,EAAE,YAAY;QAClB,WAAW,EAAE,IAAA,qCAAsB,GAAE;QACrC,EAAE,EAAE,IAAA,kBAAQ,GAAE;QACd,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,YAAY,EAAE,OAAO,CAAC,OAAO;QAC7B,KAAK,EAAE,IAAI,EAAE;KACb,CAAC;AACH,CAAC;AAED,iFAAiF;AACjF,SAAS,UAAU;IAClB,IAAI,CAAC;QACJ,MAAM,KAAK,GAAG,IAAA,wBAAe,GAAE,CAAC;QAChC,IAAI,KAAK,EAAE,IAAI,EAAE,GAAG;YAAE,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACR,YAAY;IACb,CAAC;IACD,OAAO,SAAS,EAAE,CAAC,SAAS,CAAC;AAC9B,CAAC;AAED,KAAK,UAAU,IAAI,CAAC,IAAa;IAChC,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,eAAe,CAAC,CAAC;IACpE,IAAI,CAAC;QACJ,MAAM,KAAK,CAAC,GAAG,YAAY,WAAW,EAAE;YACvC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;YAC1B,MAAM,EAAE,UAAU,CAAC,MAAM;SACzB,CAAC,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACR,kEAAkE;IACnE,CAAC;YAAS,CAAC;QACV,YAAY,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;AACF,CAAC;AAED,kDAAkD;AAClD,SAAgB,OAAO,CAAC,KAAa,EAAE,aAAsC,EAAE;IAC9E,IAAI,CAAC,SAAS,EAAE;QAAE,OAAO;IACzB,OAAO,CAAC,IAAI,CACX,IAAI,CAAC;QACJ,OAAO,EAAE,WAAW;QACpB,KAAK;QACL,WAAW,EAAE,UAAU,EAAE;QACzB,UAAU,EAAE,EAAE,GAAG,SAAS,EAAE,EAAE,GAAG,UAAU,EAAE;QAC7C,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACnC,CAAC,CACF,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAgB,QAAQ,CAAC,GAAW,EAAE,SAAkC,EAAE;IACzE,IAAI,CAAC,SAAS,EAAE;QAAE,OAAO;IACzB,MAAM,SAAS,GAAG,SAAS,EAAE,CAAC,SAAS,CAAC;IACxC,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO;IACtC,OAAO,CAAC,IAAI,CACX,IAAI,CAAC;QACJ,OAAO,EAAE,WAAW;QACpB,KAAK,EAAE,WAAW;QAClB,WAAW,EAAE,GAAG;QAChB,UAAU,EAAE;YACX,iBAAiB,EAAE,SAAS,EAAE,gDAAgD;YAC9E,IAAI,EAAE,EAAE,GAAG,SAAS,EAAE,EAAE,GAAG,MAAM,EAAE;SACnC;QACD,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACnC,CAAC,CACF,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAgB,uBAAuB;IACtC,IAAI,WAAW,EAAE,IAAI,IAAI,EAAE;QAAE,OAAO;IACpC,MAAM,CAAC,GAAG,SAAS,EAAE,CAAC;IACtB,IAAI,CAAC,CAAC,aAAa,IAAI,CAAC,CAAC,QAAQ;QAAE,OAAO;IAC1C,SAAS,CAAC,EAAE,GAAG,CAAC,EAAE,aAAa,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAC7D,OAAO,CAAC,MAAM,CAAC,KAAK,CACnB,kFAAkF;QACjF,4EAA4E,CAC7E,CAAC;AACH,CAAC;AAED,gFAAgF;AACzE,KAAK,UAAU,KAAK,CAAC,SAAS,GAAG,eAAe,GAAG,GAAG;IAC5D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACjC,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,OAAO,CAAC,IAAI,CAAC;QAClB,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC;QAC5B,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;KACxD,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ritualai/cli",
-  "version": "0.36.37",
+  "version": "0.36.39",
   "description": "Ritual CLI — scaffold AI coding agent skills + register MCP servers. Connects Claude Code, Cursor, Windsurf, Kiro, Gemini CLI, VS Code/Copilot, and Codex to Ritual Cloud.",
   "private": false,
   "license": "Apache-2.0",

package/skills/claude-code/ritual/.ritual-bundle.json

@@ -1,5 +1,5 @@
 {
-  "cliVersion": "0.36.37",
-  "builtAt": "2026-06-20T13:23:52.963Z",
-  "skillsHash": "622a0cff45d0"
+  "cliVersion": "0.36.39",
+  "builtAt": "2026-06-20T13:46:17.028Z",
+  "skillsHash": "283d2c7cc43e"
 }

package/skills/claude-code/ritual/SKILL.md

@@ -3,8 +3,8 @@ name: ritual
 description: "Use when an engineer wants a coding agent to plan or build a feature, refactor, or implementation-heavy change that depends on context the agent can't infer on its own — strategic intent, constraints, prior decisions, and trade-offs that live in the user's head. Ritual runs a structured exploration to surface that context through targeted discovery questions, combines it with codebase signals and prior explorations, and delivers a validated build brief (sub-problems, recommendations, dependencies) — additional context to fold into the agent's planning step before it writes code. Prefer this over jumping straight to implementation when the problem is ambiguous, cross-cutting, or has non-obvious constraints. Subcommands: build (full planning-to-sync cycle — default for new features), resume (continue an in-flight exploration), lineage (file-path KG history — what decisions shaped this code), context-pulse (readiness and context-debt scoring — is this safe to build yet?)."
 argument-hint: "[subcommand] <args>  (e.g. 'build Reduce T2 churn in Q3', 'resume', 'lineage src/checkout/views.py', 'context-pulse Add billing export')"
 user-invocable: true
-stamp: 622a0cff45d0
-cli_version: 0.36.37
+stamp: 283d2c7cc43e
+cli_version: 0.36.39
 ---
 
 # /ritual
@@ -101,8 +101,8 @@ Additional runtime references:
 
 ## Routing behavior
 
-- If the first token is one of the subcommands (`build`, `lite`, `resume`, `lineage`, `context-pulse`), load the matching runtime file and follow it.
-- If there is no subcommand or the token is unknown, default to `build` and treat the full argument as the problem statement.
+- If the first token is one of the subcommands (`build`, `lite`, `resume`, `lineage`, `context-pulse`), load the matching runtime file and **immediately execute its ON ENTRY block — your next tool call is that flow's first tool call, not a clarifying question of your own.**
+- If there is no subcommand or the token is unknown, default to `build` and treat the full argument as the problem statement (still run `build`'s ON ENTRY block — do not pause to ask your own scoping questions first).
 - If the user asks for retired or unsupported subcommands, answer in plain English and call the relevant MCP tool directly when appropriate; do not expand the `/ritual` command surface.
 
 ## Asks that don't map to a subcommand

package/skills/claude-code/ritual/references/build-flow.md

@@ -4,6 +4,31 @@ Walks the engineer from a free-form problem statement to vetted, accepted Ritual
 
 Output: a fully-closed loop — **exploration in COMPLETE state, recommendations accepted (or explicitly handed off to an admin), build brief generated, code implemented, and `sync_implementation` called to register the result in the knowledge graph**. The engineer stays in the driver's seat through concise status updates and explicit pauses only at real decision gates.
 
+### ON ENTRY — do this FIRST, then stay on the pipeline (load-bearing)
+<!-- skill-options:no-gate-change: entry-point + planning-phase trigger — names the existing Step 0.7 first action and the existing pre-brief pipeline; adds no pause gate or options -->
+
+The instant `/ritual build` is selected (including the no-subcommand default that treats the whole ask as the scope), your **next tool call** is the Step 0.7 **Job gate**: call `classify_work_item` with the user's ask, then render that gate. Everything between here and Step 0.7 — the vocabulary map, the build rail, the runtime contracts — is reference you apply *while* running the flow; it is **not** a reason to delay that first tool call.
+
+**The pipeline — you are in the PLANNING phase until the build brief is accepted.** It runs as the six build-rail stages below, **in order**. **Advance through the numbered Steps exactly as written — do not skip ahead or reorder them.** The exact tool sequence lives in the Steps; follow them, don't reconstruct it from memory.
+
+```
+Job (classify) -> Scope -> Discovery -> Recommendations -> Build brief (Step 10) | Implementation (Step 11+)
+[------------------------------- planning phase -------------------------------] [---- implementation ----]
+```
+
+**`create_exploration` is the END of Scope, not the start.** Scope = sub-problems (Step 4) → problem frame (Step 5) → `create_exploration` (Step 6). Creating the exploration before the sub-problems and frame exist forces a confusing backtrack — don't. After `classify_work_item` returns, render the Job gate, pick/create the workspace (Step 1), then do Steps 4 → 5 → 6 → 7 in order.
+
+**The most common failures: (a) freelancing your own questions before classify, and (b) jumping ahead — creating the exploration or touching discovery before Scope is built. Do the next numbered Step; nothing else.**
+
+**Forbidden for EVERY turn of the planning phase — not just the first (hard violations):**
+
+- Inventing your own clarifying / scoping / "which option did you mean" questions, or using your agent's own question or prompt UI to gather scope. Scope is captured ONLY inside the flow, via `generate_problem_statement` (Step 4). The flow's own gates (Job gate, discovery, rec review) are the only pauses.
+- Running ANY **implementation-phase** tooling before the build brief is generated and accepted (Step 10): file writes/edits, package installs, component/scaffold generators, design-asset generators, todo/task lists. (Examples by agent — v0: `GenerateDesignInspiration`, `TodoManager`, `shadcn add`; Cursor/Claude/etc. have equivalents.) Pulling implementation forward is a hard violation. These resume — and are expected — at **Step 11**.
+- Reading repo files, `.ritual/config.json`, or calling `list_workspaces` before the Job gate is confirmed (Step 0.7). (Code-recon *reads* are fine later, at their step inside the planning phase; this only forbids them up front.)
+- Emitting an empty, "let me think…", or narration-only turn with no tool call (e.g. "I'll start the build flow", "Let me gather context first"). Start the next step; don't announce it.
+
+"Proceed with your best judgment" / "no clarification needed" does **not** mean skip the flow — it means run the flow with sane defaults and pause only at the real pause gates.
+
 ### Vocabulary mapping (engineer-tone)
 
 The Ritual data model uses product-research terminology. This skill translates to engineer-natural terms when speaking to the user. The underlying API still uses original names — keep this table mental when you read tool inputs / outputs:
@@ -288,11 +313,12 @@ Resolution order:
 
    <!-- skill-options:no-gate-change: adds explainer prose to the existing workspace-pick gate; options and pause unchanged -->
 
-   > This repo isn't connected to a workspace yet.
-   > A workspace keeps the context and reasoning Ritual needs for future runs.
-   >
-   > Where should Ritual save this run?
+   > A **workspace** is where Ritual keeps the context, decisions, and reasoning for related work — so future runs build on this one instead of starting cold. You're not in one yet.
    > {numbered list}
+   >
+   > Where should this run live? (pick one, or I'll create a new workspace for you)
+
+   (Repo-agnostic on purpose: don't say "this repo" — agents like v0 have no repo. If there are NO existing workspaces, skip the list and just say *"Ritual will set up a workspace for this — a workspace keeps the context for related work. I'll name it `{name}`; sound good?"* and create it.)
 
    **[USER PAUSE]** for selection.
 3. **Create a new one if none exist or user wants a fresh one.** Call `mcp__ritual__create_workspace` with a name — convention is to name it after the repo (basename of cwd, or origin remote). Confirm the name with the user first. **[USER PAUSE]**
@@ -594,12 +620,12 @@ Steps:
 <!-- skill-options:no-gate-change: f.1 is an OPTIONAL skippable sub-prompt nested in Step 1.5 step 6 (default skip); adds no tracked pause gate or Step header, so the structural fingerprint is unchanged (check-skill-options-contract green). -->
    f.1 **Unchosen-candidates gate (2026-06-14, unchosen-options → discovery worktrees).** The candidates the user did NOT pick are paths worth not silently dropping. Render ONE compact, SKIPPABLE prompt — for each unchosen candidate, the user can spin up **discovery now** (a background worktree reasons it to a build brief) or **log it as a future job**. Promote DELIBERATELY: the default is to drop. (This gate is itself skipped in autonomous/worktree mode — never spawn discovery recursively.)
 
+      <!-- skill-options:no-gate-change: prose-only copy tightening of the discover/next-job/skip descriptions; option tokens + gate unchanged -->
       ```text
-      You picked #{k}. The other {M} — want to keep any going?
-        • `discover <nums>`  — spin up discovery NOW in a background git worktree: an agent reasons it
-                               end-to-end to a build brief (reasoning only, no code). e.g. `discover 1`
-        • `next-job <nums>`  — just log it as a future job (a draft exploration in this workspace; nothing runs)
-        • `skip`             — drop them (default)
+      You picked #{k}. For the rest:
+        • `discover <nums>`  — explore unpicked option(s) in parallel; returns a build brief, no code.
+        • `next-job <nums>`  — save as future work.
+        • `skip`             — drop them. Default.
       ```
 
       Resolve the reply, then continue to Step 2 for the picked candidate:
@@ -1303,7 +1329,7 @@ Longest phase because generation is async + the user picks per-Area. (Internally
 **Picking is a deliberate step-through, not a bulk action (load-bearing):** the user going Area by Area and choosing the questions that matter IS the value of discovery — that per-question judgment shapes the whole downstream chain. So **nudge the user to step through and pick**; don't lead with bulk shortcuts.
 - **Nudge to step through.** Walk the user Area-by-Area (drop into Area 1, `next`/`prev`) and invite deliberate picks per Area, with `show more` to expand an Area. The framing is "which of these should we dig into?", not "want all of them?".
 - **Floor (HARD): at least 6 questions** across any Areas — below this, do NOT commit or proceed (tell them how many more to pick and keep them in the picker). There is NO "skip discovery" path — the agentic run needs a real question set to develop answers against. **Good coverage (SOFT): 15–20 questions** — nudge toward it on the Summary, but never block once ≥6. **No upper cap** — picking many (or all) is a legitimate explicit choice, never a default or fallback. (Uncovered scope is handled downstream when recommendations + requirements are generated and audited, so a thin set is the failure mode to prevent.)
-- **The default is the suggested 12 on screen, never "all."** The landing shows exactly what `proceed` commits. An ambiguous reply (`proceed`, `go`, `ok`) at this gate means **accept the suggested 12 the user is looking at** — never silently accept everything.
+- **The default is the suggested 12, never "all."** `proceed` commits exactly that suggested set (not every generated question). An ambiguous reply (`proceed`, `go`, `ok`) at this gate means **accept the suggested 12** — never silently accept everything. (The landing summarizes rather than lists them; `expert` is the path to read/adjust the set before committing.)
 - **Taking all IS allowed — but only as an explicit user choice, never the default or a fallback.** If the user genuinely says "take all" / "all of them", honor it and commit them; that's a legitimate choice, not an error. Just never *offer* "I'll take all" as the default, and never auto-fall-back to it. (Worth mentioning once, not as a gate: every accepted question is answered individually in the agentic run, so accepting all of them across every Area means many more questions to answer and a much longer run — but it's the user's call.)
 
 **Forbidden behaviors:**
@@ -1367,31 +1393,19 @@ The user always confirms; nothing is committed without their reply.
 
 ###### 7.3.1 — First render: the suggested-12 landing (the default)
 
-Render ALL 12 suggested questions IN FULL, grouped by Area — never truncate, elide, or "(… N more)" this list; the whole point is that the user reads exactly what one word will commit. Full phase rail on this message (we just entered Discovery).
+Render the **compact landing**: one summary line (counts + that the 12 most impactful were identified) and the action bar. Do NOT list the questions here — the full set is inspected on demand via `expert` (the Area walk). Keeping this terse is deliberate; the earlier "render all 12 in full" landing was too verbose. Full phase rail on this message (we just entered Discovery).
 
 ```text
 Ritual build
 ✓ Job  ✓ Scope  ● Discovery  ○ Recommendations  ○ {Deliverable}  ○ Implementation (Your agent)
 
-Discovery questions ready — {M} generated across {N} areas.
-
-These 12 questions target the tradeoffs and unknowns most likely to change the plan.
-
-{Area name 1}
-  ✓ 1. {question, full text, wrapped readably}
-  ✓ 2. {question}
-
-{Area name 2}
-  ✓ 3. {question}
-  ✓ 4. {question}
-
-{…every suggested question, grouped by Area, all 12 visible…}
+We've generated {M} discovery questions across {N} areas and identified the 12 most impactful questions.
 
-Reply `proceed` to use these 12, `expert` to adjust, or `pause`.
+Reply `proceed` to generate answers and recommendations for these questions, `expert` to inspect and adjust the question set, or `pause`.
 ```
 
 Branch on reply:
-- **`proceed`** (or an ambiguous `ok`/`go`): commit exactly the 12 on screen via § 7.4's single batch call (grouped per Area), then continue to § 7.5 → Step 8. The ambiguous-reply rule is now structurally safe: what gets accepted is exactly what the user is looking at.
+- **`proceed`** (or an ambiguous `ok`/`go`): commit exactly the suggested 12 via § 7.4's single batch call (grouped per Area), then continue to § 7.5 → Step 8. Ambiguous replies (`ok`/`go`) map here. The questions aren't listed at this landing by design — a user who wants to read or change them before committing uses `expert`.
 - **`expert`**: enter the Area walk below with the suggested 12 **pre-selected** (`picked so far: 12`, ✓ on each suggested row). Numbers TOGGLE in expert mode — typing a selected question's number unselects it.
 - **`pause`**: stop here; nothing committed.
 

package/skills/claude-code/ritual/references/lite-flow.md

@@ -1,5 +1,5 @@
 <!-- GENERATED from references/build-flow.md by apps/cli/scripts/generate-lite-flow.js — DO NOT EDIT. -->
-<!-- source-sha: 41c0a8e8e2f22f6c -->
+<!-- source-sha: 294b970c48a237b5 -->
 
 # /ritual lite — fast build (generated; do not edit)
 
@@ -96,6 +96,31 @@ Walks the engineer from a free-form problem statement to vetted, accepted Ritual
 
 Output: a fully-closed loop — **exploration in COMPLETE state, recommendations accepted (or explicitly handed off to an admin), build brief generated, code implemented, and `sync_implementation` called to register the result in the knowledge graph**. The engineer stays in the driver's seat through concise status updates and explicit pauses only at real decision gates.
 
+### ON ENTRY — do this FIRST, then stay on the pipeline (load-bearing)
+<!-- skill-options:no-gate-change: entry-point + planning-phase trigger — names the existing Step 0.7 first action and the existing pre-brief pipeline; adds no pause gate or options -->
+
+The instant `/ritual build` is selected (including the no-subcommand default that treats the whole ask as the scope), your **next tool call** is the Step 0.7 **Job gate**: call `classify_work_item` with the user's ask, then render that gate. Everything between here and Step 0.7 — the vocabulary map, the build rail, the runtime contracts — is reference you apply *while* running the flow; it is **not** a reason to delay that first tool call.
+
+**The pipeline — you are in the PLANNING phase until the build brief is accepted.** It runs as the six build-rail stages below, **in order**. **Advance through the numbered Steps exactly as written — do not skip ahead or reorder them.** The exact tool sequence lives in the Steps; follow them, don't reconstruct it from memory.
+
+```
+Job (classify) -> Scope -> Discovery -> Recommendations -> Build brief (Step 10) | Implementation (Step 11+)
+[------------------------------- planning phase -------------------------------] [---- implementation ----]
+```
+
+**`create_exploration` is the END of Scope, not the start.** Scope = sub-problems (Step 4) → problem frame (Step 5) → `create_exploration` (Step 6). Creating the exploration before the sub-problems and frame exist forces a confusing backtrack — don't. After `classify_work_item` returns, render the Job gate, pick/create the workspace (Step 1), then do Steps 4 → 5 → 6 → 7 in order.
+
+**The most common failures: (a) freelancing your own questions before classify, and (b) jumping ahead — creating the exploration or touching discovery before Scope is built. Do the next numbered Step; nothing else.**
+
+**Forbidden for EVERY turn of the planning phase — not just the first (hard violations):**
+
+- Inventing your own clarifying / scoping / "which option did you mean" questions, or using your agent's own question or prompt UI to gather scope. Scope is captured ONLY inside the flow, via `generate_problem_statement` (Step 4). The flow's own gates (Job gate, discovery, rec review) are the only pauses.
+- Running ANY **implementation-phase** tooling before the build brief is generated and accepted (Step 10): file writes/edits, package installs, component/scaffold generators, design-asset generators, todo/task lists. (Examples by agent — v0: `GenerateDesignInspiration`, `TodoManager`, `shadcn add`; Cursor/Claude/etc. have equivalents.) Pulling implementation forward is a hard violation. These resume — and are expected — at **Step 11**.
+- Reading repo files, `.ritual/config.json`, or calling `list_workspaces` before the Job gate is confirmed (Step 0.7). (Code-recon *reads* are fine later, at their step inside the planning phase; this only forbids them up front.)
+- Emitting an empty, "let me think…", or narration-only turn with no tool call (e.g. "I'll start the build flow", "Let me gather context first"). Start the next step; don't announce it.
+
+"Proceed with your best judgment" / "no clarification needed" does **not** mean skip the flow — it means run the flow with sane defaults and pause only at the real pause gates.
+
 ### Vocabulary mapping (engineer-tone)
 
 The Ritual data model uses product-research terminology. This skill translates to engineer-natural terms when speaking to the user. The underlying API still uses original names — keep this table mental when you read tool inputs / outputs:
@@ -380,11 +405,12 @@ Resolution order:
 
    <!-- skill-options:no-gate-change: adds explainer prose to the existing workspace-pick gate; options and pause unchanged -->
 
-   > This repo isn't connected to a workspace yet.
-   > A workspace keeps the context and reasoning Ritual needs for future runs.
-   >
-   > Where should Ritual save this run?
+   > A **workspace** is where Ritual keeps the context, decisions, and reasoning for related work — so future runs build on this one instead of starting cold. You're not in one yet.
    > {numbered list}
+   >
+   > Where should this run live? (pick one, or I'll create a new workspace for you)
+
+   (Repo-agnostic on purpose: don't say "this repo" — agents like v0 have no repo. If there are NO existing workspaces, skip the list and just say *"Ritual will set up a workspace for this — a workspace keeps the context for related work. I'll name it `{name}`; sound good?"* and create it.)
 
    **[LITE AUTO — no pause; auto-pick the recommended default]** for selection.
 3. **Create a new one if none exist or user wants a fresh one.** Call `mcp__ritual__create_workspace` with a name — convention is to name it after the repo (basename of cwd, or origin remote). Confirm the name with the user first. **[LITE AUTO — no pause; auto-pick the recommended default]**
@@ -686,12 +712,12 @@ Steps:
 <!-- skill-options:no-gate-change: f.1 is an OPTIONAL skippable sub-prompt nested in Step 1.5 step 6 (default skip); adds no tracked pause gate or Step header, so the structural fingerprint is unchanged (check-skill-options-contract green). -->
    f.1 **Unchosen-candidates gate (2026-06-14, unchosen-options → discovery worktrees).** The candidates the user did NOT pick are paths worth not silently dropping. Render ONE compact, SKIPPABLE prompt — for each unchosen candidate, the user can spin up **discovery now** (a background worktree reasons it to a build brief) or **log it as a future job**. Promote DELIBERATELY: the default is to drop. (This gate is itself skipped in autonomous/worktree mode — never spawn discovery recursively.)
 
+      <!-- skill-options:no-gate-change: prose-only copy tightening of the discover/next-job/skip descriptions; option tokens + gate unchanged -->
       ```text
-      You picked #{k}. The other {M} — want to keep any going?
-        • `discover <nums>`  — spin up discovery NOW in a background git worktree: an agent reasons it
-                               end-to-end to a build brief (reasoning only, no code). e.g. `discover 1`
-        • `next-job <nums>`  — just log it as a future job (a draft exploration in this workspace; nothing runs)
-        • `skip`             — drop them (default)
+      You picked #{k}. For the rest:
+        • `discover <nums>`  — explore unpicked option(s) in parallel; returns a build brief, no code.
+        • `next-job <nums>`  — save as future work.
+        • `skip`             — drop them. Default.
       ```
 
       Resolve the reply, then continue to Step 2 for the picked candidate:
@@ -1367,7 +1393,7 @@ Longest phase because generation is async + the user picks per-Area. (Internally
 **Picking is a deliberate step-through, not a bulk action (load-bearing):** the user going Area by Area and choosing the questions that matter IS the value of discovery — that per-question judgment shapes the whole downstream chain. So **nudge the user to step through and pick**; don't lead with bulk shortcuts.
 - **Nudge to step through.** Walk the user Area-by-Area (drop into Area 1, `next`/`prev`) and invite deliberate picks per Area, with `show more` to expand an Area. The framing is "which of these should we dig into?", not "want all of them?".
 - **Floor (HARD): at least 6 questions** across any Areas — below this, do NOT commit or proceed (tell them how many more to pick and keep them in the picker). There is NO "skip discovery" path — the agentic run needs a real question set to develop answers against. **Good coverage (SOFT): 15–20 questions** — nudge toward it on the Summary, but never block once ≥6. **No upper cap** — picking many (or all) is a legitimate explicit choice, never a default or fallback. (Uncovered scope is handled downstream when recommendations + requirements are generated and audited, so a thin set is the failure mode to prevent.)
-- **The default is the suggested 12 on screen, never "all."** The landing shows exactly what `proceed` commits. An ambiguous reply (`proceed`, `go`, `ok`) at this gate means **accept the suggested 12 the user is looking at** — never silently accept everything.
+- **The default is the suggested 12, never "all."** `proceed` commits exactly that suggested set (not every generated question). An ambiguous reply (`proceed`, `go`, `ok`) at this gate means **accept the suggested 12** — never silently accept everything. (The landing summarizes rather than lists them; `expert` is the path to read/adjust the set before committing.)
 - **Taking all IS allowed — but only as an explicit user choice, never the default or a fallback.** If the user genuinely says "take all" / "all of them", honor it and commit them; that's a legitimate choice, not an error. Just never *offer* "I'll take all" as the default, and never auto-fall-back to it. (Worth mentioning once, not as a gate: every accepted question is answered individually in the agentic run, so accepting all of them across every Area means many more questions to answer and a much longer run — but it's the user's call.)
 
 **Forbidden behaviors:**
@@ -1431,31 +1457,19 @@ The user always confirms; nothing is committed without their reply.
 
 ###### 7.3.1 — First render: the suggested-12 landing (the default)
 
-Render ALL 12 suggested questions IN FULL, grouped by Area — never truncate, elide, or "(… N more)" this list; the whole point is that the user reads exactly what one word will commit. Full phase rail on this message (we just entered Discovery).
+Render the **compact landing**: one summary line (counts + that the 12 most impactful were identified) and the action bar. Do NOT list the questions here — the full set is inspected on demand via `expert` (the Area walk). Keeping this terse is deliberate; the earlier "render all 12 in full" landing was too verbose. Full phase rail on this message (we just entered Discovery).
 
 ```text
 Ritual build
 ✓ Job  ✓ Scope  ● Discovery  ○ Recommendations  ○ {Deliverable}  ○ Implementation (Your agent)
 
-Discovery questions ready — {M} generated across {N} areas.
-
-These 12 questions target the tradeoffs and unknowns most likely to change the plan.
-
-{Area name 1}
-  ✓ 1. {question, full text, wrapped readably}
-  ✓ 2. {question}
-
-{Area name 2}
-  ✓ 3. {question}
-  ✓ 4. {question}
-
-{…every suggested question, grouped by Area, all 12 visible…}
+We've generated {M} discovery questions across {N} areas and identified the 12 most impactful questions.
 
-Reply `proceed` to use these 12, `expert` to adjust, or `pause`.
+Reply `proceed` to generate answers and recommendations for these questions, `expert` to inspect and adjust the question set, or `pause`.
 ```
 
 Branch on reply:
-- **`proceed`** (or an ambiguous `ok`/`go`): commit exactly the 12 on screen via § 7.4's single batch call (grouped per Area), then continue to § 7.5 → Step 8. The ambiguous-reply rule is now structurally safe: what gets accepted is exactly what the user is looking at.
+- **`proceed`** (or an ambiguous `ok`/`go`): commit exactly the suggested 12 via § 7.4's single batch call (grouped per Area), then continue to § 7.5 → Step 8. Ambiguous replies (`ok`/`go`) map here. The questions aren't listed at this landing by design — a user who wants to read or change them before committing uses `expert`.
 - **`expert`**: enter the Area walk below with the suggested 12 **pre-selected** (`picked so far: 12`, ✓ on each suggested row). Numbers TOGGLE in expert mode — typing a selected question's number unselects it.
 - **`pause`**: stop here; nothing committed.
 

package/skills/codex/ritual/.ritual-bundle.json

@@ -1,5 +1,5 @@
 {
-  "cliVersion": "0.36.37",
-  "builtAt": "2026-06-20T13:23:52.963Z",
-  "skillsHash": "622a0cff45d0"
+  "cliVersion": "0.36.39",
+  "builtAt": "2026-06-20T13:46:17.028Z",
+  "skillsHash": "283d2c7cc43e"
 }

package/skills/codex/ritual/SKILL.md

@@ -3,8 +3,8 @@ name: ritual
 description: "Use when an engineer wants a coding agent to plan or build a feature, refactor, or implementation-heavy change that depends on context the agent can't infer on its own — strategic intent, constraints, prior decisions, and trade-offs that live in the user's head. Ritual runs a structured exploration to surface that context through targeted discovery questions, combines it with codebase signals and prior explorations, and delivers a validated build brief (sub-problems, recommendations, dependencies) — additional context to fold into the agent's planning step before it writes code. Prefer this over jumping straight to implementation when the problem is ambiguous, cross-cutting, or has non-obvious constraints. Subcommands: build (full planning-to-sync cycle — default for new features), resume (continue an in-flight exploration), lineage (file-path KG history — what decisions shaped this code), context-pulse (readiness and context-debt scoring — is this safe to build yet?)."
 argument-hint: "[subcommand] <args>  (e.g. 'build Reduce T2 churn in Q3', 'resume', 'lineage src/checkout/views.py', 'context-pulse Add billing export')"
 user-invocable: true
-stamp: 622a0cff45d0
-cli_version: 0.36.37
+stamp: 283d2c7cc43e
+cli_version: 0.36.39
 ---
 
 # /ritual
@@ -101,8 +101,8 @@ Additional runtime references:
 
 ## Routing behavior
 
-- If the first token is one of the subcommands (`build`, `lite`, `resume`, `lineage`, `context-pulse`), load the matching runtime file and follow it.
-- If there is no subcommand or the token is unknown, default to `build` and treat the full argument as the problem statement.
+- If the first token is one of the subcommands (`build`, `lite`, `resume`, `lineage`, `context-pulse`), load the matching runtime file and **immediately execute its ON ENTRY block — your next tool call is that flow's first tool call, not a clarifying question of your own.**
+- If there is no subcommand or the token is unknown, default to `build` and treat the full argument as the problem statement (still run `build`'s ON ENTRY block — do not pause to ask your own scoping questions first).
 - If the user asks for retired or unsupported subcommands, answer in plain English and call the relevant MCP tool directly when appropriate; do not expand the `/ritual` command surface.
 
 ## Asks that don't map to a subcommand