@skrr-ai/cli 0.1.119 → 0.1.120

package/dist/commands/goals/key-results/assess.d.ts

@@ -0,0 +1,36 @@
+import type { KeyResultEvidenceRef } from '@skrr-ai/data-provider';
+import { BaseCommand } from '../../../base-command';
+/**
+ * `skrr goals key-results assess <goal-id> <kr-id>` — record a judgment of a
+ * key result (OSK-17987, decision D4). Wraps
+ * `POST /api/goals/:goalId/key-results/:krId/assessments` (data-provider
+ * `assessKeyResult`).
+ *
+ * How a key result is going is a judgment, and an Agent may make it — marking
+ * it `done` included. Nothing is refused for what is judged; the server records
+ * WHO judged (from the authenticated runtime: a Run proves an Agent, otherwise
+ * the credential decides), why, and on what evidence, and keeps every judgment
+ * (`goals key-results history`). A person overrides by judging again.
+ */
+export default class GoalsKeyResultsAssess extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        goalId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        krId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        status: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        rationale: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        evidence: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        progress: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}
+/**
+ * `<kind>:<id-or-uri>` → a reference. A value that looks like a URL is a `uri`,
+ * anything else an `id` — the same reading `tasks expectations assess` uses.
+ * Exported for `assess.spec.ts`.
+ */
+export declare function parseEvidenceRef(raw: string): KeyResultEvidenceRef;

package/dist/commands/goals/key-results/assess.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseEvidenceRef = parseEvidenceRef;
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../../base-command");
+const history_1 = require("./history");
+/**
+ * `skrr goals key-results assess <goal-id> <kr-id>` — record a judgment of a
+ * key result (OSK-17987, decision D4). Wraps
+ * `POST /api/goals/:goalId/key-results/:krId/assessments` (data-provider
+ * `assessKeyResult`).
+ *
+ * How a key result is going is a judgment, and an Agent may make it — marking
+ * it `done` included. Nothing is refused for what is judged; the server records
+ * WHO judged (from the authenticated runtime: a Run proves an Agent, otherwise
+ * the credential decides), why, and on what evidence, and keeps every judgment
+ * (`goals key-results history`). A person overrides by judging again.
+ */
+class GoalsKeyResultsAssess extends base_command_1.BaseCommand {
+    static description = 'Record a judgment of a key result: its status, why, and what it rests on';
+    static examples = [
+        '<%= config.bin %> goals key-results assess <goal-id> <kr-id> --status at_risk --rationale "Signups flat for two weeks"',
+        '<%= config.bin %> goals key-results assess <goal-id> <kr-id> --status done --rationale "Shipped and adopted" --evidence task:OSK-42 --evidence url:https://example.com/dashboard',
+        '<%= config.bin %> goals key-results assess <goal-id> <kr-id> --status on_track --progress 60 --rationale "3 of 5 cohorts migrated"',
+    ];
+    static args = {
+        goalId: core_1.Args.string({ description: 'Goal ID', required: true, ignoreStdin: true }),
+        krId: core_1.Args.string({ description: 'Key Result ID', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        status: core_1.Flags.string({
+            description: 'Your judgment of how the key result is going',
+            required: true,
+            options: [...data_provider_1.KEY_RESULT_STATUS_VALUES],
+        }),
+        rationale: core_1.Flags.string({
+            description: 'Why: what you looked at and what it showed',
+            required: true,
+        }),
+        evidence: core_1.Flags.string({
+            description: 'What it rests on, as <kind>:<id-or-uri> (repeatable)',
+            multiple: true,
+        }),
+        progress: core_1.Flags.integer({
+            description: 'Optional: how far along it is, 0–100',
+            min: 0,
+            max: 100,
+        }),
+        json: core_1.Flags.boolean({ description: 'Output the assessed key result as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(GoalsKeyResultsAssess);
+        let evidenceRefs = [];
+        try {
+            evidenceRefs = (flags.evidence || []).map(parseEvidenceRef);
+        }
+        catch (err) {
+            this.error(err.message, { exit: 1 });
+        }
+        let kr;
+        try {
+            kr = await data_provider_1.dataService.assessKeyResult({
+                goalId: args.goalId,
+                krId: args.krId,
+                data: {
+                    status: flags.status,
+                    rationale: flags.rationale,
+                    ...(flags.progress !== undefined ? { progress: flags.progress } : {}),
+                    ...(evidenceRefs.length > 0 ? { evidenceRefs } : {}),
+                },
+            });
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        // An unattended judgment the Space's write policy held for approval
+        // (`202 pending_approval`, OSK-17994): nothing was recorded yet.
+        if (this.reportHeldSpaceWrite(kr, { json: flags.json }))
+            return;
+        if (flags.json) {
+            this.printJsonResult(kr);
+            return;
+        }
+        const k = kr;
+        // Echo what the SERVER recorded — in particular who it says judged, which
+        // is read from this process's credential and Run, not from anything sent.
+        this.log(`Assessed key result ${k.id ?? args.krId} on goal ${args.goalId}.`);
+        if (k.assessment) {
+            for (const line of (0, history_1.describeAssessment)(k.assessment))
+                this.log(line);
+        }
+    }
+}
+exports.default = GoalsKeyResultsAssess;
+/**
+ * `<kind>:<id-or-uri>` → a reference. A value that looks like a URL is a `uri`,
+ * anything else an `id` — the same reading `tasks expectations assess` uses.
+ * Exported for `assess.spec.ts`.
+ */
+function parseEvidenceRef(raw) {
+    const split = raw.indexOf(':');
+    if (split < 1 || split === raw.length - 1) {
+        throw new Error(`--evidence must be <kind>:<id-or-uri> (got "${raw}")`);
+    }
+    const kind = raw.slice(0, split);
+    const value = raw.slice(split + 1);
+    return /^https?:|^file:/.test(value) ? { kind, uri: value } : { kind, id: value };
+}

package/dist/commands/goals/key-results/history.d.ts

@@ -0,0 +1,30 @@
+import type { KeyResultAssessment } from '@skrr-ai/data-provider';
+import { BaseCommand } from '../../../base-command';
+/**
+ * `skrr goals key-results history <goal-id> <kr-id>` — every judgment of a key
+ * result, newest first (OSK-17987). Wraps
+ * `GET /api/goals/:goalId/key-results/:krId/assessments` (data-provider
+ * `listKeyResultAssessments`).
+ *
+ * Each row says who judged — `agent`, `person` or `automation`, as the server
+ * read it from the credential and Run, never as the writer claimed — and an
+ * override reads as one: a person's row directly above an agent's.
+ */
+export default class GoalsKeyResultsHistory extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        goalId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        krId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        limit: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        cursor: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}
+/** `agent`, `person`, `automation` — what the server recorded, never guessed. */
+export declare function describeAssessor(assessment: KeyResultAssessment | undefined | null): string;
+/** The lines `assess` and `show` print for one judgment. */
+export declare function describeAssessment(assessment: KeyResultAssessment): string[];

package/dist/commands/goals/key-results/history.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeAssessor = describeAssessor;
+exports.describeAssessment = describeAssessment;
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../../base-command");
+const format_1 = require("../../../lib/format");
+/**
+ * `skrr goals key-results history <goal-id> <kr-id>` — every judgment of a key
+ * result, newest first (OSK-17987). Wraps
+ * `GET /api/goals/:goalId/key-results/:krId/assessments` (data-provider
+ * `listKeyResultAssessments`).
+ *
+ * Each row says who judged — `agent`, `person` or `automation`, as the server
+ * read it from the credential and Run, never as the writer claimed — and an
+ * override reads as one: a person's row directly above an agent's.
+ */
+class GoalsKeyResultsHistory extends base_command_1.BaseCommand {
+    static description = "List a key result's judgments, newest first";
+    static examples = [
+        '<%= config.bin %> goals key-results history <goal-id> <kr-id>',
+        '<%= config.bin %> goals key-results history <goal-id> <kr-id> --limit 50 --json',
+    ];
+    static args = {
+        goalId: core_1.Args.string({ description: 'Goal ID', required: true, ignoreStdin: true }),
+        krId: core_1.Args.string({ description: 'Key Result ID', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        limit: core_1.Flags.integer({ description: 'How many judgments to show (1–100)', min: 1, max: 100 }),
+        cursor: core_1.Flags.string({ description: 'Continue from a previous page' }),
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(GoalsKeyResultsHistory);
+        let page;
+        try {
+            page = await data_provider_1.dataService.listKeyResultAssessments(args.goalId, args.krId, {
+                ...(flags.limit !== undefined ? { limit: flags.limit } : {}),
+                ...(flags.cursor ? { cursor: flags.cursor } : {}),
+            });
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        if (flags.json) {
+            this.printJsonResult(page);
+            return;
+        }
+        const entries = page?.data ?? [];
+        if (entries.length === 0) {
+            this.log('No judgments recorded for this key result.');
+            return;
+        }
+        (0, format_1.renderTable)(entries.map((entry) => ({
+            rev: String(entry.revisionNumber ?? '-'),
+            at: formatAt(entry.assessment?.at),
+            status: String(entry.assessment?.status ?? '-'),
+            by: describeAssessor(entry.assessment),
+            progress: typeof entry.assessment?.progress === 'number'
+                ? `${Math.round(entry.assessment.progress)}%`
+                : '-',
+            why: oneLine(entry.assessment?.rationale) || '(no reason given)',
+        })), [
+            { key: 'rev', header: 'REV' },
+            { key: 'at', header: 'AT' },
+            { key: 'status', header: 'STATUS' },
+            { key: 'by', header: 'BY' },
+            { key: 'progress', header: 'PROGRESS' },
+            { key: 'why', header: 'WHY', maxWidth: 60 },
+        ], (line) => this.log(line));
+        if (page?.has_more && page.next_cursor) {
+            this.log(`More: --cursor ${page.next_cursor}`);
+        }
+    }
+}
+exports.default = GoalsKeyResultsHistory;
+/** `agent`, `person`, `automation` — what the server recorded, never guessed. */
+function describeAssessor(assessment) {
+    const kind = assessment?.assessedBy?.kind;
+    return kind === 'agent' || kind === 'person' || kind === 'automation' ? kind : 'unattributed';
+}
+/** The lines `assess` and `show` print for one judgment. */
+function describeAssessment(assessment) {
+    const lines = [`Status:     ${assessment.status} (${describeAssessor(assessment)})`];
+    if (typeof assessment.progress === 'number') {
+        lines.push(`Progress:   ${Math.round(assessment.progress)}% (judged)`);
+    }
+    lines.push(`Why:        ${oneLine(assessment.rationale) || '(no reason given)'}`);
+    for (const ref of assessment.evidenceRefs ?? []) {
+        lines.push(`Evidence:   ${ref.kind}:${ref.id ?? ref.uri ?? ''}`);
+    }
+    if (assessment.runId)
+        lines.push(`Run:        ${assessment.runId}`);
+    lines.push(`At:         ${formatAt(assessment.at)}`);
+    return lines;
+}
+function oneLine(text) {
+    return typeof text === 'string' ? text.replace(/\s+/g, ' ').trim() : '';
+}
+function formatAt(at) {
+    return at ? String(at).slice(0, 19).replace('T', ' ') : '-';
+}

package/dist/commands/goals/key-results/list.d.ts

@@ -1,10 +1,11 @@
 import { BaseCommand } from '../../../base-command';
 /**
  * `skrr goals key-results list <goal-id>` — the goal's Key Results (the
- * measurable OKR outcomes under it). For KRs in `auto` progress mode the server
- * computes progress from the linked tasks' done ratio; `resolveKeyResultProgress`
- * surfaces that computed value, falling back to the stored `progress` for
- * `manual` KRs.
+ * measurable OKR outcomes under it). PROGRESS is the current judgment's number
+ * when it stated one (decision D4), else the server-computed linked-task ratio
+ * for `auto` KRs and the stored `progress` for `manual` ones
+ * (`resolveKeyResultProgress`). BY is who set the status; TASKS DONE is the
+ * activity signal (linked tasks done / linked), shown beside the judgment.
  *
  * Wraps `GET /api/goals/:goalId/key-results` (data-provider `listKeyResults`).
  */

package/dist/commands/goals/key-results/list.js

@@ -7,10 +7,11 @@ const base_command_1 = require("../../../base-command");
 const format_1 = require("../../../lib/format");
 /**
  * `skrr goals key-results list <goal-id>` — the goal's Key Results (the
- * measurable OKR outcomes under it). For KRs in `auto` progress mode the server
- * computes progress from the linked tasks' done ratio; `resolveKeyResultProgress`
- * surfaces that computed value, falling back to the stored `progress` for
- * `manual` KRs.
+ * measurable OKR outcomes under it). PROGRESS is the current judgment's number
+ * when it stated one (decision D4), else the server-computed linked-task ratio
+ * for `auto` KRs and the stored `progress` for `manual` ones
+ * (`resolveKeyResultProgress`). BY is who set the status; TASKS DONE is the
+ * activity signal (linked tasks done / linked), shown beside the judgment.
  *
  * Wraps `GET /api/goals/:goalId/key-results` (data-provider `listKeyResults`).
  */
@@ -50,13 +51,17 @@ class GoalsKeyResultsList extends base_command_1.BaseCommand {
             .sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
             .map((kr) => {
             const progress = (0, data_provider_1.resolveKeyResultProgress)(kr);
+            const activity = (0, data_provider_1.resolveKeyResultActivity)(kr);
             return {
                 id: String(kr.id ?? '-'),
                 title: String(kr.title ?? '-'),
                 status: String(kr.status ?? '-'),
+                // Who set the status: the server's reading of the credential and Run.
+                by: (0, data_provider_1.keyResultAssessorKind)(kr) ?? '-',
                 mode: String(kr.progressMode ?? '-'),
                 progress: typeof progress === 'number' ? `${Math.round(progress)}%` : '-',
-                linked: kr._linkedTaskCount != null ? String(kr._linkedTaskCount) : '-',
+                // Linked tasks done — activity beside the judgment, not the progress.
+                activity: activity ? `${activity.done}/${activity.total}` : '-',
                 order: String(kr.order ?? 0),
             };
         });
@@ -64,9 +69,10 @@ class GoalsKeyResultsList extends base_command_1.BaseCommand {
             { key: 'id', header: 'ID' },
             { key: 'title', header: 'TITLE', maxWidth: 44 },
             { key: 'status', header: 'STATUS' },
+            { key: 'by', header: 'BY' },
             { key: 'mode', header: 'MODE' },
             { key: 'progress', header: 'PROGRESS' },
-            { key: 'linked', header: 'TASKS' },
+            { key: 'activity', header: 'TASKS DONE' },
             { key: 'order', header: 'ORDER' },
         ], (line) => this.log(line));
     }

package/dist/commands/goals/key-results/show.d.ts

@@ -2,8 +2,10 @@ import { BaseCommand } from '../../../base-command';
 /**
  * `skrr goals key-results show <goal-id> <kr-id>` — full detail for one key
  * result. Wraps `GET /api/goals/:goalId/key-results/:krId` (data-provider
- * `getKeyResult`). For `auto` KRs the displayed progress is the server-computed
- * value; the stored `progress` field is only authoritative in `manual` mode.
+ * `getKeyResult`). Progress is the current judgment's number when it stated
+ * one (decision D4); otherwise the server-computed value for `auto` KRs and the
+ * stored `progress` for `manual` ones. Linked-task completion is printed
+ * separately as ACTIVITY, and the status says who set it.
  */
 export default class GoalsKeyResultsShow extends BaseCommand {
     static description: string;

package/dist/commands/goals/key-results/show.js

@@ -3,11 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../../base-command");
+const history_1 = require("./history");
 /**
  * `skrr goals key-results show <goal-id> <kr-id>` — full detail for one key
  * result. Wraps `GET /api/goals/:goalId/key-results/:krId` (data-provider
- * `getKeyResult`). For `auto` KRs the displayed progress is the server-computed
- * value; the stored `progress` field is only authoritative in `manual` mode.
+ * `getKeyResult`). Progress is the current judgment's number when it stated
+ * one (decision D4); otherwise the server-computed value for `auto` KRs and the
+ * stored `progress` for `manual` ones. Linked-task completion is printed
+ * separately as ACTIVITY, and the status says who set it.
  */
 class GoalsKeyResultsShow extends base_command_1.BaseCommand {
     static description = 'Show a key result';
@@ -38,18 +41,36 @@ class GoalsKeyResultsShow extends base_command_1.BaseCommand {
         }
         const k = kr;
         const progress = (0, data_provider_1.resolveKeyResultProgress)(k);
+        const assessment = (0, data_provider_1.currentKeyResultAssessment)(k);
+        const activity = (0, data_provider_1.resolveKeyResultActivity)(k);
         this.log(`ID:         ${k.id}`);
         this.log(`Goal:       ${k.goalId}`);
         this.log(`Title:      ${k.title}`);
         if (k.description) {
             this.log(`Description: ${k.description}`);
         }
-        this.log(`Status:     ${k.status}`);
+        this.log(`Status:     ${k.status} ${assessment ? `(${(0, history_1.describeAssessor)(assessment)})` : '(not assessed)'}`);
         this.log(`Mode:       ${k.progressMode}`);
         this.log(`Progress:   ${typeof progress === 'number' ? `${Math.round(progress)}%` : '-'}`);
-        if (k.progressMode === 'auto') {
+        if (typeof assessment?.progress === 'number') {
+            this.log('  (judged in the latest assessment)');
+        }
+        else if (k.progressMode === 'auto') {
             this.log(`  (computed from ${k._linkedTaskCount ?? 0} linked task(s))`);
         }
+        this.log(`Activity:   ${activity ? `${activity.done} of ${activity.total} linked task(s) done` : '-'}`);
+        if (assessment) {
+            const why = assessment.rationale?.replace(/\s+/g, ' ').trim();
+            this.log(`Judged:     ${String(assessment.at ?? '')
+                .slice(0, 19)
+                .replace('T', ' ')}`);
+            this.log(`Why:        ${why || '(no reason given)'}`);
+            for (const ref of assessment.evidenceRefs ?? []) {
+                this.log(`Evidence:   ${ref.kind}:${ref.id ?? ref.uri ?? ''}`);
+            }
+            if (assessment.runId)
+                this.log(`Run:        ${assessment.runId}`);
+        }
         this.log(`Order:      ${k.order ?? 0}`);
     }
 }

package/dist/commands/goals/key-results/update.d.ts

@@ -4,6 +4,10 @@ import { BaseCommand } from '../../../base-command';
  * `PATCH /api/goals/:goalId/key-results/:krId` (data-provider `updateKeyResult`).
  * Only the fields you pass change. `--clear-description` sends `description:
  * null`, the server's signal to clear the field (distinct from an empty string).
+ *
+ * `--status` and `--progress` are a judgment (decision D4): the server records
+ * them as an assessment with who made it and no reason. To say why and on what
+ * evidence, use `goals key-results assess`.
  */
 export default class GoalsKeyResultsUpdate extends BaseCommand {
     static description: string;

package/dist/commands/goals/key-results/update.js

@@ -6,11 +6,16 @@ const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../../base-command");
 const prompt_1 = require("../../../lib/prompt");
+const history_1 = require("./history");
 /**
  * `skrr goals key-results update <goal-id> <kr-id>` — patch a key result. Wraps
  * `PATCH /api/goals/:goalId/key-results/:krId` (data-provider `updateKeyResult`).
  * Only the fields you pass change. `--clear-description` sends `description:
  * null`, the server's signal to clear the field (distinct from an empty string).
+ *
+ * `--status` and `--progress` are a judgment (decision D4): the server records
+ * them as an assessment with who made it and no reason. To say why and on what
+ * evidence, use `goals key-results assess`.
  */
 class GoalsKeyResultsUpdate extends base_command_1.BaseCommand {
     static description = 'Update a key result';
@@ -92,6 +97,10 @@ class GoalsKeyResultsUpdate extends base_command_1.BaseCommand {
         catch (err) {
             this.handleApiError(err);
         }
+        // A status or progress edit is a judgment the Space's write policy may hold
+        // for approval (`202 pending_approval`, OSK-17994): nothing was changed yet.
+        if (this.reportHeldSpaceWrite(updated, { json: flags.json }))
+            return;
         if (flags.json) {
             this.log(JSON.stringify(updated, null, 2));
             return;
@@ -106,10 +115,15 @@ class GoalsKeyResultsUpdate extends base_command_1.BaseCommand {
             .map((field) => `${field}=${describeField(k, field)}`)
             .join(' ');
         this.log(`Updated key result ${k.id ?? args.krId} on goal ${args.goalId}: ${echo}`);
-        // The write echoes the number back, so without this the caller has every
-        // reason to believe it took — and then `key-results list` shows `-`.
-        if (k.progressMode === 'auto' && flags.progress !== undefined) {
-            this.warn(`The value is stored. ${AUTO_MODE_NOTE}`);
+        // A status or progress edit is recorded as a judgment; say whose the server
+        // recorded it as (read from this credential and Run, not from anything
+        // sent), and that it carries no reason.
+        if (flags.status !== undefined || flags.progress !== undefined) {
+            const assessment = k.assessment;
+            if (assessment) {
+                this.log(`Recorded as a judgment by: ${(0, history_1.describeAssessor)(assessment)}, with no reason given. ` +
+                    'Use `goals key-results assess --rationale` to say why.');
+            }
         }
         // `done` beside `25%` on one row, with nothing reconciling them. The two
         // ARE independent axes — a key result can be closed out incomplete, and
@@ -148,23 +162,3 @@ function describeField(kr, field) {
         return '(not returned)';
     return typeof value === 'string' ? value : JSON.stringify(value);
 }
-/**
- * Why an `auto` key result reads as `-` from the CLI.
- *
- * Auto progress is computed from tasks linked to THIS key result
- * (`Task.keyResultIds`), and the task↔key-result link is a DOCUMENTED
- * omission from the CLI surface — it sits in `domain-api-parity.spec.ts`'s
- * allowlist with a stated reason. So `--progress-mode auto` is offered by a
- * surface that cannot make it move, and `resolveKeyResultProgress` renders
- * `_computedProgress ?? null` for auto, i.e. `-`, while a `--progress` value
- * you set is stored and returned by `update`.
- *
- * The result was one CLI reporting two different values for one field: the
- * write echoed 40 and the list showed `-`. Saying so at the point of use is
- * the honest fix; silently rendering the stored number instead would hide a
- * real distinction (a manual value is not a computed one), and adding the
- * link command would reverse a recorded decision.
- */
-const AUTO_MODE_NOTE = 'Auto progress is computed from tasks linked to this key result, and linking a task to a key ' +
-    'result is deliberately not in the CLI — so this reads as "-" here until it is linked ' +
-    'elsewhere. Use --progress-mode manual to track a number from the CLI.';

package/dist/commands/goals/plan-now.js

@@ -23,7 +23,12 @@ const TIMEOUT_STATUSES = new Set([408, 504, 524]);
  * to run later. Everything else (`goal_archived`, `goal_planner_disabled`, …)
  * needs the user to change something first, so a script retrying it would spin.
  */
-const TRANSIENT_SKIP_REASONS = new Set(['lock_held', 'not_due', 'schedule_superseded']);
+const TRANSIENT_SKIP_REASONS = new Set([
+    'lock_held',
+    'not_due',
+    'schedule_superseded',
+    'goal_turn_unreadable',
+]);
 /**
  * Turn the planner's internal `reason` enum into a sentence.
  *
@@ -66,6 +71,10 @@ function describePlannerReason(reason) {
             return 'the planner ran and found nothing to add or refine';
         case 'one_voice_busy':
             return 'another agent was already speaking for this owner, so the tick stayed quiet';
+        case 'goal_loop_holds_turn':
+            return "a goal_advance loop holds this goal's planning turn, so the planner stood down (ask the loop instead: `commitments check-now <id>`; cancelling it or detaching its advance link hands the goal back)";
+        case 'goal_turn_unreadable':
+            return 'whether a goal_advance loop holds this goal could not be read, so the planner did not run';
         default:
             // `one_voice_<something>` is a family the server composes at run time.
             if (reason.startsWith('one_voice_')) {
@@ -199,9 +208,11 @@ class GoalsPlanNow extends base_command_1.BaseCommand {
             const retry = transient
                 ? ` Re-run \`${this.config.bin} goals plan-now ${args.id}\` to try again.`
                 : '';
+            const loop = r?.commitmentId ? ` The loop is commitment ${r.commitmentId}.` : '';
             this.failWithCliError({
                 message: `The planner did not run for goal ${args.id}` +
                     (reasonText ? `: ${reasonText}.` : '.') +
+                    loop +
                     backfilled +
                     retry,
                 code: 'PLANNER_TICK_NOT_RUN',

package/dist/commands/goals/planner-compare.d.ts

@@ -0,0 +1,30 @@
+import { type GoalPlanningComparison } from '@skrr-ai/data-provider';
+import { BaseCommand } from '../../base-command';
+/** The comparison as the lines the command prints. Pure, so it is tested as such. */
+export declare function comparisonLines(result: GoalPlanningComparison): string[];
+/**
+ * `skrr goals planner-compare <goal-id>` (OSK-18012): GoalPlanner beside the
+ * Goal's `goal_advance` loop, read from `GET /api/goals/:goalId/planning-comparison`.
+ *
+ * What it is for: the evidence to retire the planner for this Goal. Over a
+ * window of at least seven days in which each holder held the Goal: the loop
+ * turned at the Goal's pace (its turns and the planner ticks it held), it judged
+ * the key results (the planner never does), its open and failed work is no
+ * worse than the planner's, the key results it held over moved no worse, and
+ * concurrent turns are 0. Every stop of the loop is explained in its Cycles
+ * (`commitments cycles <id>`).
+ */
+export default class GoalsPlannerCompare extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        days: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        since: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        until: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}