@skrr-ai/cli 0.1.15 → 0.1.18

package/dist/commands/commitments/create.js

@@ -1,18 +1,142 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasEventCapableWatchedSource = hasEventCapableWatchedSource;
+exports.assertEventDrivenWatchedSource = assertEventDrivenWatchedSource;
+exports.createCadenceFromFlags = createCadenceFromFlags;
 exports.autonomyStagingNotice = autonomyStagingNotice;
 const core_1 = require("@oclif/core");
 const base_command_1 = require("../../base-command");
 const web_url_1 = require("../../lib/web-url");
 const prompt_1 = require("../../lib/prompt");
 const triggers_1 = require("../../lib/triggers");
+const commitment_product_1 = require("../../lib/commitment-product");
 const commitments_1 = require("../../lib/commitments");
+const DEFAULT_EVENT_DRIVEN_BACKSTOP_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_EVENT_SOURCES = new Set(['github', 'slack', 'email', 'calendar']);
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function configuredId(config, ...keys) {
+    return keys.some((key) => {
+        const value = config?.[key];
+        return typeof value === 'string' && value.trim().length > 0;
+    });
+}
+function hasStructurallyValidExplicitEvent(config) {
+    const events = config?.events;
+    if (!Array.isArray(events))
+        return false;
+    return events.some((value) => {
+        const event = record(value);
+        if (!event)
+            return false;
+        if (typeof event.entityType !== 'string' || !event.entityType.trim())
+            return false;
+        if (typeof event.eventType !== 'string' || !event.eventType.trim())
+            return false;
+        if (event.filterField === undefined)
+            return true;
+        if (typeof event.filterField !== 'string')
+            return false;
+        return !event.filterField
+            .split('.')
+            .some((part) => ['__proto__', 'constructor', 'prototype'].includes(part));
+    });
+}
+/**
+ * True only when the authored create body can materialize at least one event
+ * binding. A polling-only source must not make `--event-driven` look successful
+ * while the resulting Commitment still wakes exclusively on its backstop.
+ */
+function hasEventCapableWatchedSource(payload) {
+    const goalId = typeof payload.goalId === 'string' && payload.goalId.trim().length > 0;
+    const watchedSources = Array.isArray(payload.watchedSources) ? payload.watchedSources : [];
+    return watchedSources.some((value) => {
+        const sourceEntry = record(value);
+        if (!sourceEntry || sourceEntry.enabled === false || typeof sourceEntry.source !== 'string') {
+            return false;
+        }
+        const source = sourceEntry.source;
+        const config = record(sourceEntry.config);
+        // For these four sources, TriggerSync owns a default event family. An
+        // explicit empty or malformed event list intentionally suppresses it.
+        if (DEFAULT_EVENT_SOURCES.has(source)) {
+            return Array.isArray(config?.events) ? hasStructurallyValidExplicitEvent(config) : true;
+        }
+        if (source === 'tasks') {
+            return (goalId || configuredId(config, 'taskId', 'goalId', 'keyResultId'));
+        }
+        if (source === 'goal') {
+            return goalId || configuredId(config, 'goalId', 'keyResultId');
+        }
+        if (source === 'space')
+            return configuredId(config, 'spaceId');
+        if (source === 'conversations')
+            return configuredId(config, 'conversationId');
+        if (source === 'messages')
+            return configuredId(config, 'groupChatId');
+        if (source === 'agent_initiatives') {
+            return configuredId(config, 'initiativeId', 'cloudCodingTaskId');
+        }
+        if (source === 'documents')
+            return configuredId(config, 'artifactIdentifier');
+        if (source === 'monitor')
+            return configuredId(config, 'monitorId');
+        // Custom bindings are still server-validated against the source-specific
+        // wake allowlist. At this boundary, require at least a structurally valid
+        // event row instead of treating any non-empty array as event capability.
+        return hasStructurallyValidExplicitEvent(config);
+    });
+}
+function assertEventDrivenWatchedSource(payload) {
+    if (record(payload.cadence)?.mode !== 'event_plus_interval' ||
+        hasEventCapableWatchedSource(payload)) {
+        return;
+    }
+    throw new Error('Event-driven cadence (--event-driven or --cadence-mode event_plus_interval) requires at least one event-capable watched source. ' +
+        'Add --watch github (or another event-capable source), or choose an interval-only cadence.');
+}
+/**
+ * Resolve the create-time cadence flags into the API payload.
+ *
+ * `--event-driven` is deliberately a complete shortcut rather than an alias
+ * for the mode string: event delivery is an accelerator, so the contract must
+ * always retain a timed safety net even when the author omits `--cadence`.
+ */
+function createCadenceFromFlags({ eventDriven, cadence: cadenceInput, cadenceMode, timezone, }) {
+    if (eventDriven) {
+        if (cadenceMode && cadenceMode !== 'event_plus_interval') {
+            throw new Error(`--event-driven cannot be combined with --cadence-mode ${cadenceMode}. ` +
+                'Use --event-driven alone or --cadence-mode event_plus_interval.');
+        }
+        return {
+            mode: 'event_plus_interval',
+            intervalMs: cadenceInput
+                ? (0, commitments_1.parseIntervalToMs)(cadenceInput)
+                : DEFAULT_EVENT_DRIVEN_BACKSTOP_MS,
+            ...(timezone ? { timezone } : {}),
+        };
+    }
+    const cadence = {};
+    if (cadenceInput) {
+        cadence.intervalMs = (0, commitments_1.parseIntervalToMs)(cadenceInput);
+        cadence.mode = cadenceMode || 'interval';
+    }
+    else if (cadenceMode) {
+        cadence.mode = cadenceMode;
+    }
+    if (timezone)
+        cadence.timezone = timezone;
+    return Object.keys(cadence).length ? cadence : undefined;
+}
 /**
- * Public commitment creation is intentionally trust-first: an action-capable
- * mode requested in the create payload is staged as suggestions_only until an
- * owner explicitly grants it. That safety boundary must be visible at the CLI
- * boundary; otherwise a successful create response reads like the requested
- * autonomy is live when it is not.
+ * Creation preserves the policy its author wrote, so the mode that comes back
+ * is normally the mode that was asked for. When it is not — normalization
+ * rejected the value, or a governance layer sits lower — the difference has to
+ * be said out loud at the CLI boundary; otherwise a successful create response
+ * reads like the requested autonomy is live when something else is running.
  */
 function autonomyStagingNotice({ payload, commitment, bin, }) {
     const requestedPolicy = payload.policy && typeof payload.policy === 'object' && !Array.isArray(payload.policy)
@@ -21,14 +145,21 @@ function autonomyStagingNotice({ payload, commitment, bin, }) {
     const returnedPolicy = commitment.policy && typeof commitment.policy === 'object' && !Array.isArray(commitment.policy)
         ? commitment.policy
         : {};
-    const requested = typeof requestedPolicy.autonomyMode === 'string' ? requestedPolicy.autonomyMode : '';
+    const requested = typeof payload.mode === 'string'
+        ? payload.mode
+        : typeof requestedPolicy.autonomyMode === 'string'
+            ? requestedPolicy.autonomyMode
+            : '';
     const admitted = typeof returnedPolicy.autonomyMode === 'string' ? returnedPolicy.autonomyMode : '';
-    if (!requested || requested === admitted || requested === 'off')
+    if (!requested ||
+        (0, commitment_product_1.productMode)(requested) === (0, commitment_product_1.productMode)(admitted || 'suggestions_only') ||
+        requested === 'off') {
         return undefined;
+    }
     const id = typeof commitment.id === 'string' ? commitment.id : '<commitment-id>';
     return [
-        `Requested autonomy ${requested} was staged as ${admitted || 'suggestions_only'} for review; it is not active yet.`,
-        `To grant it explicitly: ${bin} commitments autonomy ${id} --mode ${requested} --reason "<why this scope is safe>"`,
+        `Requested mode ${(0, commitment_product_1.productModeLabel)(requested)} was not applied; this commitment is running as ${(0, commitment_product_1.productModeLabel)(admitted || 'suggestions_only')}.`,
+        `To set it explicitly: ${bin} commitments mode ${id} ${(0, commitment_product_1.productMode)(requested)}`,
     ].join('\n');
 }
 /**
@@ -45,9 +176,11 @@ class CommitmentsCreate extends base_command_1.BaseCommand {
     static description = 'Create a commitment (a durable agent contract)';
     static examples = [
         '<%= config.bin %> commitments create --agent <agent-id> --title "Ship v2" --outcome "v2 is live for all users" --cadence 6h',
-        '<%= config.bin %> commitments create --agent <agent-id> --title "Hiring loop" --outcome "Every candidate hears back in 48h" --watch tasks --watch email --cadence 12h --status active',
+        '<%= config.bin %> commitments create --agent <agent-id> --title "Hiring loop" --outcome "Every candidate hears back in 48h" --watch tasks --watch email --cadence 12h',
         '<%= config.bin %> commitments create --agent <agent-id> --title "SLA" --outcome "p95 under 200ms" --criterion "p95 latency confirmed" --evaluator metric --measure <measure-id>',
+        '<%= config.bin %> commitments create --agent <agent-id> --title "AWS cost watch" --outcome "Cost regressions are investigated" --agent-directive-file ./aws-cost-policy.md',
         '<%= config.bin %> commitments create --from-json commitment.json --json',
+        '<%= config.bin %> commitments create --agent <agent-id> --title "Keep CI healthy" --outcome "Failed checks are repaired" --watch github --event-driven --mode execute --delivery draft-pr --repo owner/repo --base main --status draft',
     ];
     static flags = {
         json: core_1.Flags.boolean({ description: 'Output the created commitment as JSON' }),
@@ -64,10 +197,16 @@ class CommitmentsCreate extends base_command_1.BaseCommand {
             description: 'The outcome to hold true — required when setting any target field',
         }),
         description: core_1.Flags.string({ description: 'Longer description' }),
+        'agent-directive': core_1.Flags.string({
+            description: 'Per-Commitment domain policy (max 8,000 characters). Mutually exclusive with --agent-directive-file.',
+        }),
+        'agent-directive-file': core_1.Flags.string({
+            description: 'Read the per-Commitment domain policy from a text file, or - for stdin. Mutually exclusive with --agent-directive.',
+        }),
         goal: core_1.Flags.string({ description: 'Link to a goal ID' }),
         status: core_1.Flags.string({
-            description: 'Create as draft (default) or active',
-            options: ['draft', 'active'],
+            description: 'Create as a draft (default); activate later with commitments resume',
+            options: ['draft'],
         }),
         deadline: core_1.Flags.string({ description: 'ISO-8601 deadline for an `achieve` commitment' }),
         criterion: core_1.Flags.string({
@@ -108,16 +247,45 @@ class CommitmentsCreate extends base_command_1.BaseCommand {
             multiple: true,
         }),
         cadence: core_1.Flags.string({
-            description: 'Check interval, e.g. "15m", "6h", "1d" (1m..30d). Implies --cadence-mode interval.',
+            description: 'Check interval, e.g. "15m", "6h", "30d" (1m..365d). Defaults to interval mode; with --event-driven, this is the timed backstop.',
+        }),
+        'event-driven': core_1.Flags.boolean({
+            description: 'Wake on matching watched-source events, with a timed backstop from --cadence (default 24h). Requires an event-capable watched source and cannot be combined with a different --cadence-mode.',
         }),
         'cadence-mode': core_1.Flags.string({
-            description: 'Cadence mode (default: interval when --cadence is set, else manual)',
-            options: [...commitments_1.COMMITMENT_CADENCE_MODES],
+            description: 'Advanced cadence mode (default: interval when --cadence is set, else manual). Prefer --event-driven for event_plus_interval with a 24h default backstop.',
+            options: [...commitments_1.COMMITMENT_AUTHORABLE_CADENCE_MODES],
         }),
         timezone: core_1.Flags.string({ description: 'IANA timezone for the cadence' }),
+        mode: core_1.Flags.string({
+            description: 'How the commitment progresses (default Monitor)',
+            options: [...commitment_product_1.COMMITMENT_PRODUCT_MODES],
+        }),
+        delivery: core_1.Flags.string({
+            description: 'Where Prepare or Execute coding work is delivered; Monitor is report-only',
+            options: [...commitment_product_1.COMMITMENT_DELIVERY_CHOICES],
+        }),
+        repo: core_1.Flags.string({ description: 'Delivery repository, owner/repo' }),
+        base: core_1.Flags.string({ description: 'Delivery target branch' }),
         autonomy: core_1.Flags.string({
-            description: 'How much the commitment may act without asking (default suggestions_only)',
+            // `--help` is where someone decides what to type, so the ceiling that can
+            // still bind has to be stated HERE and not only in the notice that
+            // corrects them afterwards. `commitments autonomy --mode` learned the
+            // same lesson: what it must not keep is the silence.
+            description: 'Compatibility flag. Prefer --mode monitor|prepare|execute. Workspace administrator rules remain binding.',
             options: [...commitments_1.COMMITMENT_AUTONOMY_MODES],
+            hidden: true,
+        }),
+        isolation: core_1.Flags.string({
+            // Omitting this is not the same as passing `shared`: an omitted value
+            // leaves the daemon's own isolation heuristic in force, while `shared` is
+            // an explicit contract that suppresses it. Say so here, because `--help`
+            // is where someone decides which of the two they mean.
+            description: 'Where autonomous runs do their work. "ephemeral" cuts a one-shot git worktree per run ' +
+                'and destroys it after; "shared" lands them on the daemon working tree, in place. ' +
+                'Omit to leave the runtime default. Cannot be combined with a remediation capability.',
+            options: [...commitments_1.COMMITMENT_EXECUTION_ISOLATION_MODES],
+            hidden: true,
         }),
         'max-nudges': core_1.Flags.integer({ description: 'Max user nudges per day (0..20)' }),
     };
@@ -125,6 +293,7 @@ class CommitmentsCreate extends base_command_1.BaseCommand {
         this.requireAuth();
         const { flags } = await this.parse(CommitmentsCreate);
         let payload;
+        let deliveryNormalizedForMonitor = false;
         try {
             // `createBodySchema` is a z.strictObject, so unwrap a `plan --json`
             // envelope and drop any key it does not declare (a contract dumped from
@@ -138,6 +307,12 @@ class CommitmentsCreate extends base_command_1.BaseCommand {
                 payload.title = flags.title;
             if (flags.description !== undefined)
                 payload.description = flags.description;
+            const agentDirective = await (0, commitments_1.readCommitmentAgentDirective)({
+                directive: flags['agent-directive'],
+                file: flags['agent-directive-file'],
+            });
+            if (agentDirective !== undefined)
+                payload.agentDirective = agentDirective;
             if (flags.goal)
                 payload.goalId = flags.goal;
             if (flags.status)
@@ -182,25 +357,47 @@ class CommitmentsCreate extends base_command_1.BaseCommand {
             });
             if (built)
                 payload.watchedSources = built;
-            const cadence = {};
-            if (flags.cadence) {
-                cadence.intervalMs = (0, commitments_1.parseIntervalToMs)(flags.cadence);
-                cadence.mode = flags['cadence-mode'] || 'interval';
-            }
-            else if (flags['cadence-mode']) {
-                cadence.mode = flags['cadence-mode'];
-            }
-            if (flags.timezone)
-                cadence.timezone = flags.timezone;
-            if (Object.keys(cadence).length)
+            const cadence = createCadenceFromFlags({
+                eventDriven: flags['event-driven'],
+                cadence: flags.cadence,
+                cadenceMode: flags['cadence-mode'],
+                timezone: flags.timezone,
+            });
+            if (cadence)
                 payload.cadence = cadence;
+            assertEventDrivenWatchedSource(payload);
             const policy = {};
             if (flags.autonomy)
                 policy.autonomyMode = flags.autonomy;
+            if (flags.mode && flags.autonomy)
+                throw new Error('Use --mode or the compatibility --autonomy flag, not both.');
+            if (flags.mode)
+                payload.mode = (0, commitment_product_1.productMode)(flags.mode);
+            if (flags.delivery)
+                payload.delivery = (0, commitment_product_1.deliveryInput)(flags.delivery, flags);
+            else if (flags.repo || flags.base)
+                throw new Error('--repo and --base require --delivery.');
+            if (flags.isolation)
+                policy.executionIsolation = flags.isolation;
             if (flags['max-nudges'] !== undefined)
                 policy.maxUserNudgesPerDay = flags['max-nudges'];
             if (Object.keys(policy).length)
                 payload.policy = policy;
+            const payloadPolicy = payload.policy && typeof payload.policy === 'object' && !Array.isArray(payload.policy)
+                ? payload.policy
+                : {};
+            const selectedMode = typeof payload.mode === 'string'
+                ? payload.mode
+                : typeof payloadPolicy.autonomyMode === 'string'
+                    ? payloadPolicy.autonomyMode
+                    : 'monitor';
+            if (payload.delivery && typeof payload.delivery === 'object' && !Array.isArray(payload.delivery)) {
+                const declared = payload.delivery;
+                const coherent = (0, commitment_product_1.deliveryForProductMode)(selectedMode, declared);
+                deliveryNormalizedForMonitor =
+                    (0, commitment_product_1.productMode)(selectedMode) === 'monitor' && declared.mode !== 'report_only';
+                payload.delivery = coherent;
+            }
         }
         catch (err) {
             this.error(err.message, { exit: 1 });
@@ -215,6 +412,9 @@ class CommitmentsCreate extends base_command_1.BaseCommand {
                 exit: 1,
             });
         }
+        // Creation is authoring only. Activation is a separate resume boundary
+        // that runs the current preflight; JSON imports cannot bypass it.
+        payload.status = 'draft';
         let commitment;
         try {
             commitment = await commitments_1.commitmentApi.create(payload);
@@ -231,6 +431,9 @@ class CommitmentsCreate extends base_command_1.BaseCommand {
             });
             if (notice)
                 this.warn(notice);
+            if (deliveryNormalizedForMonitor) {
+                this.warn('Monitor is report-only, so the requested code-delivery destination was not stored. Use --mode prepare or --mode execute to deliver code.');
+            }
             return;
         }
         this.log('Created commitment:');
@@ -244,6 +447,10 @@ class CommitmentsCreate extends base_command_1.BaseCommand {
             this.log('');
             this.log(notice);
         }
+        if (deliveryNormalizedForMonitor) {
+            this.log('');
+            this.log('Monitor is report-only, so delivery was set to Report only. Choose Prepare or Execute to deliver code.');
+        }
         if (commitment.status === 'draft') {
             this.log('');
             this.log(`Activate it with:  ${this.config.bin} commitments resume ${commitment.id}`);

package/dist/commands/commitments/delivery.d.ts

@@ -0,0 +1,16 @@
+import { BaseCommand } from '../../base-command';
+export default class CommitmentsDelivery extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        mode: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        repo: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        base: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        reason: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/commitments/delivery.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../base-command");
+const commitments_1 = require("../../lib/commitments");
+const commitment_product_1 = require("../../lib/commitment-product");
+const web_url_1 = require("../../lib/web-url");
+class CommitmentsDelivery extends base_command_1.BaseCommand {
+    static description = 'Declare where Prepare or Execute delivers work; Monitor is always report-only';
+    static examples = [
+        '<%= config.bin %> commitments delivery <id> draft-pr --repo owner/repo --base main',
+    ];
+    static args = {
+        id: core_1.Args.string({ required: true, ignoreStdin: true }),
+        mode: core_1.Args.string({
+            required: true,
+            description: 'Delivery destination. Code destinations require Prepare or Execute (or a Pack Shadow promotion target).',
+            options: [
+                ...commitment_product_1.COMMITMENT_DELIVERY_CHOICES,
+                ...commitment_product_1.COMMITMENT_DELIVERY_CHOICES.map((mode) => mode.replace(/-/g, '_')),
+            ],
+        }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output the complete contract as JSON' }),
+        repo: core_1.Flags.string({ description: 'GitHub repository, owner/repo' }),
+        base: core_1.Flags.string({ description: 'Delivery target branch, such as main' }),
+        reason: core_1.Flags.string({ description: 'Reason recorded with this contract change' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(CommitmentsDelivery);
+        try {
+            const current = (await commitments_1.commitmentApi.get(args.id)).commitment;
+            const requested = (0, commitment_product_1.deliveryInput)(args.mode, flags);
+            const stagingForPromotion = current.pack?.phase === 'shadow';
+            const targetPolicy = stagingForPromotion
+                ? current.pack?.policyBeforeShadow || current.policy
+                : current.policy;
+            const productContract = targetPolicy?.workPromotionModel === 'monitor_prepare_execute_v1';
+            if (productContract &&
+                (0, commitment_product_1.productMode)(targetPolicy?.autonomyMode) === 'monitor' &&
+                requested.mode !== 'report_only') {
+                throw new Error(stagingForPromotion
+                    ? 'This Pack promotion target is Monitor, so its delivery must be report-only. Set the commitment mode to Prepare or Execute before staging code delivery.'
+                    : 'Monitor is report-only. Set the commitment mode to Prepare or Execute before selecting code delivery.');
+            }
+            const delivery = { ...current.delivery, ...requested };
+            const result = await commitments_1.commitmentApi.delivery(args.id, {
+                delivery,
+                expectedVersion: current.version,
+                ...(flags.reason ? { reason: flags.reason } : {}),
+            });
+            const linked = (0, web_url_1.withCommitmentUrl)(this.cliConfig.baseURL, result);
+            if (flags.json)
+                return this.log(JSON.stringify(linked, null, 2));
+            const renderedDelivery = stagingForPromotion
+                ? result.pack?.deliveryBeforeShadow || delivery
+                : result.delivery;
+            this.log(`${stagingForPromotion ? 'Promotion delivery staged' : 'Delivery'}: ${(0, commitment_product_1.deliveryLabel)(renderedDelivery?.mode)}${renderedDelivery?.repo ? ` · ${renderedDelivery.repo}` : ''}${renderedDelivery?.baseBranch ? ` → ${renderedDelivery.baseBranch}` : ''}`);
+            if (stagingForPromotion) {
+                this.log('Live Shadow delivery remains Report only until explicit promotion.');
+            }
+            this.log(`URL: ${linked.url}`);
+        }
+        catch (error) {
+            this.handleApiError(error);
+        }
+    }
+}
+exports.default = CommitmentsDelivery;

package/dist/commands/commitments/doctor.d.ts

@@ -0,0 +1,20 @@
+import { BaseCommand } from '../../base-command';
+export declare function doctorVerdict(input: {
+    commitment?: Record<string, unknown>;
+    preflight?: Record<string, unknown>;
+    operatingState?: Record<string, unknown>;
+}): {
+    verdict: string;
+    next: string;
+};
+export default class CommitmentsDoctor extends BaseCommand {
+    static description: string;
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        strict: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/commitments/doctor.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.doctorVerdict = doctorVerdict;
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../base-command");
+const commitments_1 = require("../../lib/commitments");
+function doctorVerdict(input) {
+    const commitment = input.commitment || {};
+    const preflight = input.preflight || {};
+    const operatingState = input.operatingState || {};
+    const blocker = operatingState.firstActionableBlocker;
+    if (blocker?.code) {
+        return { verdict: 'blocked', next: String(blocker.remediation || 'Inspect the Commitment') };
+    }
+    if (operatingState.status === 'waiting_approval') {
+        return { verdict: 'waiting_approval', next: 'Open the pending prepared action for review' };
+    }
+    if (operatingState.coverage && operatingState.coverage.complete === false) {
+        return { verdict: 'degraded', next: 'Retry doctor; one or more operating-state projections are unavailable' };
+    }
+    if (operatingState.status && commitment.status === 'active') {
+        const status = String(operatingState.status);
+        return {
+            verdict: ['on_track', 'healthy'].includes(status) ? 'active_healthy' : status,
+            next: 'skrr commitments trace <id> --limit 50',
+        };
+    }
+    if (commitment.status !== 'active')
+        return { verdict: 'blocked', next: 'skrr commitments resume <id>' };
+    if (preflight.verdict === 'blocked')
+        return { verdict: 'blocked', next: 'skrr commitments preflight <id> --json' };
+    const attention = preflight.attention;
+    if (attention?.allowed === false)
+        return { verdict: 'attention_suppressed', next: 'skrr commitments effective-policy <id>' };
+    return { verdict: 'active_healthy', next: 'skrr commitments trace <id> --limit 50' };
+}
+class CommitmentsDoctor extends base_command_1.BaseCommand {
+    static description = 'Summarize commitment readiness and the next operator action';
+    static args = {
+        id: core_1.Args.string({ description: 'Commitment ID', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output the composed health report as JSON' }),
+        strict: core_1.Flags.boolean({
+            description: 'Exit non-zero unless the commitment is active and healthy',
+        }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(CommitmentsDoctor);
+        let commitment;
+        let shown;
+        try {
+            shown = (await commitments_1.commitmentApi.get(args.id));
+            commitment = (shown.commitment || {});
+        }
+        catch (error) {
+            this.handleApiError(error);
+            return;
+        }
+        const operatingState = (shown.operatingState || {});
+        const diagnosis = doctorVerdict({ commitment, operatingState });
+        const report = {
+            ...diagnosis,
+            commitment,
+            abilities: shown.abilities,
+            operatingState,
+            observedAt: new Date().toISOString(),
+        };
+        if (flags.json)
+            this.log(JSON.stringify(report, null, 2));
+        else {
+            this.log(`Verdict: ${diagnosis.verdict}`);
+            this.log(`Next:    ${diagnosis.next.replace('<id>', args.id)}`);
+            const autonomy = operatingState.autonomy;
+            if (autonomy) {
+                this.log(`Mode:    ${(0, commitments_1.commitmentAutonomyLabel)(String(autonomy.declaredMode || ''))} → ${(0, commitments_1.commitmentAutonomyLabel)(String(autonomy.effectiveMode || ''))}`);
+            }
+            const approvals = operatingState.approvals;
+            if (approvals?.pendingCount)
+                this.log(`Waiting approval: ${String(approvals.pendingCount)}`);
+        }
+        if (flags.strict && !['healthy', 'active_healthy'].includes(diagnosis.verdict)) {
+            process.exitCode = 1;
+        }
+    }
+}
+exports.default = CommitmentsDoctor;

package/dist/commands/commitments/effective-policy.d.ts

@@ -1,4 +1,5 @@
 import { BaseCommand } from '../../base-command';
+export declare function effectivePolicyLines(policy: Record<string, any>): string[];
 /** Show the policy actually governing a Commitment without changing it. */
 export default class CommitmentsEffectivePolicy extends BaseCommand {
     static description: string;
@@ -8,6 +9,7 @@ export default class CommitmentsEffectivePolicy extends BaseCommand {
     };
     static flags: {
         json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        verbose: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
 }

package/dist/commands/commitments/effective-policy.js

@@ -1,8 +1,46 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.effectivePolicyLines = effectivePolicyLines;
 const core_1 = require("@oclif/core");
 const base_command_1 = require("../../base-command");
 const commitments_1 = require("../../lib/commitments");
+const commitment_product_1 = require("../../lib/commitment-product");
+function effectivePolicyLines(policy) {
+    const governance = policy.governance || {};
+    const owner = policy.owner || {};
+    const lines = [`Mode in force: ${(0, commitment_product_1.productModeLabel)(governance.effectiveAutonomyMode)}`];
+    if (governance.blocked) {
+        lines.push(`Workspace status: blocked${governance.blockedReason ? ` — ${governance.blockedReason}` : ''}`);
+    }
+    else {
+        lines.push('Workspace status: allowed');
+    }
+    if (governance.workspaceMaxMode) {
+        lines.push(`Workspace Mode ceiling: ${(0, commitment_product_1.productModeLabel)(governance.workspaceMaxMode)}`);
+    }
+    if (Array.isArray(governance.workspaceModeOverrides)) {
+        for (const override of governance.workspaceModeOverrides) {
+            if (override?.effectiveMode) {
+                lines.push(`Workspace override: ${(0, commitment_product_1.productModeLabel)(override.effectiveMode)} — ${override.policy || 'configured administrator rule'}${override.configuredValue ? ` (${override.configuredValue})` : ''}`);
+            }
+        }
+    }
+    if (Array.isArray(governance.allowedCommitmentDeliveryModes)) {
+        lines.push(`Workspace delivery allowlist: ${governance.allowedCommitmentDeliveryModes.length ? governance.allowedCommitmentDeliveryModes.map(commitment_product_1.deliveryLabel).join(', ') : 'none'}`);
+    }
+    if (Array.isArray(governance.requireAttestedAccessForDeliveryModes) && governance.requireAttestedAccessForDeliveryModes.length) {
+        lines.push(`Runtime attestation required for: ${governance.requireAttestedAccessForDeliveryModes.map(commitment_product_1.deliveryLabel).join(', ')}`);
+    }
+    const runLimit = owner.actionRunsPerDay;
+    if (runLimit) {
+        lines.push(`Owner action-run limit: ${runLimit.mode === 'unbounded' ? 'Unlimited' : `${runLimit.value}/day`}`);
+    }
+    const cost = policy.billing;
+    if (cost?.effectiveCostLimitUsd != null) {
+        lines.push(`Effective daily cost limit: $${Number(cost.effectiveCostLimitUsd).toFixed(2)}`);
+    }
+    return lines;
+}
 /** Show the policy actually governing a Commitment without changing it. */
 class CommitmentsEffectivePolicy extends base_command_1.BaseCommand {
     static description = 'Show the owner, workspace, and infrastructure policy currently governing a commitment';
@@ -15,6 +53,7 @@ class CommitmentsEffectivePolicy extends base_command_1.BaseCommand {
     };
     static flags = {
         json: core_1.Flags.boolean({ description: 'Output the complete effective policy as JSON' }),
+        verbose: core_1.Flags.boolean({ description: 'Append raw compatibility and diagnostic policy JSON' }),
     };
     async run() {
         this.requireAuth();
@@ -27,11 +66,17 @@ class CommitmentsEffectivePolicy extends base_command_1.BaseCommand {
             this.handleApiError(err);
             return;
         }
-        // The response is deliberately provenance-rich and evolves with each policy
-        // layer. Preserve that shape rather than flattening it into a lossy table.
-        if (!flags.json)
-            this.log('Effective policy:');
-        this.log(JSON.stringify(policy, null, 2));
+        if (flags.json) {
+            this.log(JSON.stringify(policy, null, 2));
+            return;
+        }
+        this.log('Effective policy:');
+        for (const line of effectivePolicyLines(policy))
+            this.log(`  ${line}`);
+        if (flags.verbose) {
+            this.log('\nRaw compatibility diagnostics:');
+            this.log(JSON.stringify(policy, null, 2));
+        }
     }
 }
 exports.default = CommitmentsEffectivePolicy;