@skrr-ai/cli 0.1.9 → 0.1.11

package/dist/commands/tasks/actionability.js

@@ -56,8 +56,47 @@ class TasksActionability extends base_command_1.BaseCommand {
             this.log(`Eligible:     ${a.actorRefs.map((ref) => `${ref.kind}:${ref.id}`).join(', ')}`);
         }
         if (a.allowedActions.length) {
-            this.log(`Actions:      ${a.allowedActions.map((action) => action.action).join(', ')}`);
+            // These are SERVER action names, not commands, and printing them bare as
+            // `Actions: retry_task, resolve_task_hold` reads as a list of things to
+            // run — so a reader tries `skrr resolve_task_hold` and finds nothing.
+            // That gap is what OSK-3815 fixed for one of them by adding `tasks
+            // retry`; naming the verb beside each is the rest of it.
+            //
+            // Unmapped actions print bare on purpose. Inventing a plausible verb for
+            // an action whose resolution is genuinely a review conversation is worse
+            // than saying nothing — the reader would chase a command that does not
+            // do what the name suggests.
+            const width = Math.max(...a.allowedActions.map((action) => action.action.length));
+            this.log('Actions:');
+            for (const { action } of a.allowedActions) {
+                const verb = ACTION_VERBS[action];
+                this.log(`  ${action.padEnd(width)}${verb ? `  →  ${verb}` : ''}`);
+            }
         }
     }
 }
 exports.default = TasksActionability;
+/**
+ * Server action name → the `skrr` command that performs it.
+ *
+ * Only mappings verified against the command surface are listed. Four actions
+ * are deliberately absent: `request_changes` and `inspect_workflow` resolve
+ * through a review conversation rather than one verb, and `inspect_dependency`
+ * / `inspect_workflow` are readings rather than actions — the blocker they
+ * point at is already printed above as the reason.
+ */
+const ACTION_VERBS = {
+    answer_human_input: 'skrr tasks input answer <id>',
+    assign_task: 'skrr tasks assign <id> --agent <agent-id>',
+    complete_task: 'skrr tasks complete <id>',
+    dismiss_human_input: 'skrr tasks input dismiss <id>',
+    interrupt_task: 'skrr tasks interrupt <id>',
+    request_approval: 'skrr tasks approvals create <id>',
+    resolve_approval: 'skrr tasks approvals resolve <id>',
+    resolve_task_hold: 'skrr tasks move <id> --status <status>',
+    retry_task: 'skrr tasks retry <id>',
+    set_execution_mode: 'skrr tasks update <id> --execution-mode <agent|human>',
+    start_task: 'skrr tasks start <id>',
+    triage_task: 'skrr tasks triage <id>',
+    unschedule_task: 'skrr tasks unschedule <id>',
+};

package/dist/commands/tasks/activity.d.ts

@@ -17,6 +17,35 @@ export type ActivityRow = {
     details: string;
 };
 export declare function activityRow(entry: ActivityEntry): ActivityRow;
+export type RunFailure = {
+    runId: string;
+    message: string;
+    code: string | null;
+    causeClass: string | null;
+};
+/**
+ * The failure reasons the activity log carries, indexed by run. (S3 dogfood finding)
+ *
+ * `tasks runs` shows `errors: 1` beside a `failed` run and no message, because
+ * the run projection does not carry one — that gap is server-side and this
+ * cannot close it. What the activity log DOES carry is the full string, on the
+ * `execution_failed` entry, with the `runId` right beside it:
+ *
+ *   { action: 'execution_failed',
+ *     details: { runId, error, code: 'MCP_CONNECTION_UNHEALTHY', causeClass: 'agent_error' } }
+ *
+ * so the join is exact rather than a guess. Reading it is the honest half of
+ * the fix: the reason is surfaced where it is genuinely known, and never
+ * synthesised where it is not.
+ *
+ * Deliberately keyed ONLY on an explicit `details.runId`. An entry without one
+ * is skipped rather than attributed to the newest run — a failure pinned to the
+ * wrong run reads exactly like a true one, and is worse than none.
+ *
+ * Last entry wins per run: activity is append-ordered, so a re-finalization
+ * that recorded a better reason should not be shadowed by the first attempt.
+ */
+export declare function runFailuresFromActivity(entries: unknown): Map<string, RunFailure>;
 export default class TasksActivity extends BaseCommand {
     static description: string;
     static examples: string[];

package/dist/commands/tasks/activity.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.activityRow = activityRow;
+exports.runFailuresFromActivity = runFailuresFromActivity;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
@@ -13,6 +14,52 @@ function activityRow(entry) {
         details: (0, format_1.formatCell)(entry.details ?? entry.metadata),
     };
 }
+/**
+ * The failure reasons the activity log carries, indexed by run. (S3 dogfood finding)
+ *
+ * `tasks runs` shows `errors: 1` beside a `failed` run and no message, because
+ * the run projection does not carry one — that gap is server-side and this
+ * cannot close it. What the activity log DOES carry is the full string, on the
+ * `execution_failed` entry, with the `runId` right beside it:
+ *
+ *   { action: 'execution_failed',
+ *     details: { runId, error, code: 'MCP_CONNECTION_UNHEALTHY', causeClass: 'agent_error' } }
+ *
+ * so the join is exact rather than a guess. Reading it is the honest half of
+ * the fix: the reason is surfaced where it is genuinely known, and never
+ * synthesised where it is not.
+ *
+ * Deliberately keyed ONLY on an explicit `details.runId`. An entry without one
+ * is skipped rather than attributed to the newest run — a failure pinned to the
+ * wrong run reads exactly like a true one, and is worse than none.
+ *
+ * Last entry wins per run: activity is append-ordered, so a re-finalization
+ * that recorded a better reason should not be shadowed by the first attempt.
+ */
+function runFailuresFromActivity(entries) {
+    const out = new Map();
+    if (!Array.isArray(entries))
+        return out;
+    for (const raw of entries) {
+        const entry = raw;
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const details = entry.details;
+        if (!details || typeof details !== 'object')
+            continue;
+        const runId = typeof details.runId === 'string' ? details.runId.trim() : '';
+        const message = typeof details.error === 'string' ? details.error.trim() : '';
+        if (!runId || !message)
+            continue;
+        out.set(runId, {
+            runId,
+            message,
+            code: typeof details.code === 'string' ? details.code : null,
+            causeClass: typeof details.causeClass === 'string' ? details.causeClass : null,
+        });
+    }
+    return out;
+}
 /** Same contract as `tasks monitor`'s timestamp column — never throws, never prints "undefined". */
 function formatTime(value) {
     if (!value)

package/dist/commands/tasks/complete.d.ts

@@ -41,6 +41,52 @@ export interface DurableCompletionResult {
  * old server and fall through to the legacy comment-first path.
  */
 export declare function resolveCanonicalCompletionTaskId(taskRef: string, lookup: (taskRef: string) => Promise<unknown>): Promise<string>;
+/**
+ * The canonical id AND the status it is in.
+ *
+ * The status comes free: this lookup already happens on the user path, so the
+ * re-completion guard below costs no extra round trip on the common case. It is
+ * also the only way to make the success line honest — `tasks complete` printed
+ * "Moved task X to done" unconditionally, so a task that was ALREADY done got a
+ * report of a state transition that did not happen.
+ */
+export declare function resolveCompletionTarget(taskRef: string, lookup: (taskRef: string) => Promise<unknown>): Promise<{
+    id: string;
+    status: string | null;
+}>;
+/**
+ * What a second `tasks complete` on an already-closed task should do.
+ *
+ * The repo contract calls this "the only terminal closeout", and a task has one
+ * canonical outcome — but a second run used to succeed silently, post another
+ * TASK_OUTPUT block, and leave `tasks output` rendering the throwaway one as
+ * authoritative. The real summary and its artifacts link were still on the task
+ * but no longer canonical, which is the worst of the available failures: no
+ * error, no warning, exit 0, and a record that now says something different.
+ *
+ * Refusing outright would break the case that makes retries safe. A completion
+ * whose response is lost — a flaky connection, a re-run script — SHOULD be able
+ * to run again, and today it collapses server-side on the shared
+ * `X-Idempotency-Key`. Turning that into a hard failure would force every
+ * caller to write its own is-it-already-done check.
+ *
+ * So the axis is not "again or not", it is "the SAME again, or something
+ * different":
+ *
+ *   - identical report  → `noop`, exit 0. Nothing to do, and saying so is more
+ *     honest than re-posting an identical block.
+ *   - differing report  → `refuse`. Superseding a canonical outcome is a real
+ *     decision, so it takes `--amend` and says so.
+ *   - not yet terminal  → `proceed`, unchanged.
+ *
+ * Pure, so the rule is testable without a server.
+ */
+export declare function decideRecompletion(opts: {
+    priorStatus: string | null;
+    canonicalBody: string | null;
+    incomingBody: string;
+    amend: boolean;
+}): 'proceed' | 'noop' | 'refuse';
 /** A 404 from the /complete endpoint means an old server without the route. */
 export declare function isCompleteEndpointMissing(err: unknown): boolean;
 /**
@@ -90,6 +136,7 @@ export default class TasksComplete extends BaseCommand {
         json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         task: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'from-json': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        amend: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         status: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
         summary: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         artifacts: import("@oclif/core/lib/interfaces").OptionFlag<string[], import("@oclif/core/lib/interfaces").CustomOptions>;

package/dist/commands/tasks/complete.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TaskCompletionMismatchError = void 0;
 exports.resolveCanonicalCompletionTaskId = resolveCanonicalCompletionTaskId;
+exports.resolveCompletionTarget = resolveCompletionTarget;
+exports.decideRecompletion = decideRecompletion;
 exports.isCompleteEndpointMissing = isCompleteEndpointMissing;
 exports.completeTaskDurably = completeTaskDurably;
 const core_1 = require("@oclif/core");
@@ -16,7 +18,9 @@ const prompt_1 = require("../../lib/prompt");
 const task_report_1 = require("../../lib/task-report");
 const task_resolver_1 = require("../../lib/task-resolver");
 const task_instruction_offer_1 = require("../../lib/task-instruction-offer");
+const task_transcript_1 = require("../../lib/task-transcript");
 const web_url_1 = require("../../lib/web-url");
+const tasks_1 = require("../../lib/tasks");
 /**
  * Mutation endpoints require the task's canonical UUID even though the CLI
  * accepts human-readable refs and titles. Resolve the display reference before
@@ -24,12 +28,65 @@ const web_url_1 = require("../../lib/web-url");
  * old server and fall through to the legacy comment-first path.
  */
 async function resolveCanonicalCompletionTaskId(taskRef, lookup) {
+    return (await resolveCompletionTarget(taskRef, lookup)).id;
+}
+/** Terminal workflow states — a task in one of these has already been closed out. */
+const TERMINAL_STATUSES = new Set(['done', 'failed']);
+/**
+ * The canonical id AND the status it is in.
+ *
+ * The status comes free: this lookup already happens on the user path, so the
+ * re-completion guard below costs no extra round trip on the common case. It is
+ * also the only way to make the success line honest — `tasks complete` printed
+ * "Moved task X to done" unconditionally, so a task that was ALREADY done got a
+ * report of a state transition that did not happen.
+ */
+async function resolveCompletionTarget(taskRef, lookup) {
     const task = (await lookup(taskRef));
     const id = typeof task?.id === 'string' ? task.id.trim() : '';
     if (!id) {
         throw new Error(`Task ${taskRef} did not resolve to a canonical id.`);
     }
-    return id;
+    return { id, status: typeof task?.status === 'string' ? task.status : null };
+}
+/**
+ * What a second `tasks complete` on an already-closed task should do.
+ *
+ * The repo contract calls this "the only terminal closeout", and a task has one
+ * canonical outcome — but a second run used to succeed silently, post another
+ * TASK_OUTPUT block, and leave `tasks output` rendering the throwaway one as
+ * authoritative. The real summary and its artifacts link were still on the task
+ * but no longer canonical, which is the worst of the available failures: no
+ * error, no warning, exit 0, and a record that now says something different.
+ *
+ * Refusing outright would break the case that makes retries safe. A completion
+ * whose response is lost — a flaky connection, a re-run script — SHOULD be able
+ * to run again, and today it collapses server-side on the shared
+ * `X-Idempotency-Key`. Turning that into a hard failure would force every
+ * caller to write its own is-it-already-done check.
+ *
+ * So the axis is not "again or not", it is "the SAME again, or something
+ * different":
+ *
+ *   - identical report  → `noop`, exit 0. Nothing to do, and saying so is more
+ *     honest than re-posting an identical block.
+ *   - differing report  → `refuse`. Superseding a canonical outcome is a real
+ *     decision, so it takes `--amend` and says so.
+ *   - not yet terminal  → `proceed`, unchanged.
+ *
+ * Pure, so the rule is testable without a server.
+ */
+function decideRecompletion(opts) {
+    const { priorStatus, canonicalBody, incomingBody, amend } = opts;
+    if (!priorStatus || !TERMINAL_STATUSES.has(priorStatus))
+        return 'proceed';
+    if (amend)
+        return 'proceed';
+    // No canonical block to disagree with — a task closed by a path that skipped
+    // it, so writing one is an addition rather than a replacement.
+    if (canonicalBody === null)
+        return 'proceed';
+    return canonicalBody.trim() === incomingBody.trim() ? 'noop' : 'refuse';
 }
 /** A 404 from the /complete endpoint means an old server without the route. */
 function isCompleteEndpointMissing(err) {
@@ -144,6 +201,9 @@ class TasksComplete extends base_command_1.BaseCommand {
         'from-json': core_1.Flags.string({
             description: 'Path to JSON with taskId, status, summary, artifacts, and verdict; "-" for stdin',
         }),
+        amend: core_1.Flags.boolean({
+            description: 'Supersede the canonical outcome of an already-completed task. Without it, a differing report on a closed task is refused',
+        }),
         status: core_1.Flags.string({
             description: 'TASK_OUTPUT status',
             options: ['completed', 'failed'],
@@ -221,6 +281,16 @@ class TasksComplete extends base_command_1.BaseCommand {
             ]) || 'none',
             verdict: flags.verdict,
         });
+        // `--verdict` is deliberately not enumerated — a reviewer task passes a
+        // JSON posture object, and `normalizeReviewPosture` accepts synonyms. But
+        // when it recognises nothing it derives the posture from the criteria
+        // rather than failing, so a typo is recorded and silently means something
+        // else. Warn over the set the server actually matches; never refuse.
+        if (!(0, tasks_1.verdictIsRecognized)(input.verdict)) {
+            this.warn(`Verdict "${input.verdict}" is not one the server recognises ` +
+                `(${tasks_1.RECOGNIZED_TASK_VERDICTS.join(', ')}, or a JSON review posture). ` +
+                'It will be recorded as written, and a review will fall back to what the criteria imply.');
+        }
         let taskIdentity;
         try {
             taskIdentity = (0, task_resolver_1.resolveTaskIdentity)({
@@ -316,18 +386,88 @@ class TasksComplete extends base_command_1.BaseCommand {
             noMove: !!flags['no-move'],
         };
         const completionIdempotencyKey = (0, outbox_1.idempotencyKeyFor)('task-complete', taskIdentity.id, JSON.stringify(completionPayload));
+        const sessionCompletionPath = autonomousSessionCompletionPath();
+        // Resolved OUTSIDE the write's try/catch. It is a GET, so a failure here is
+        // not a queueable write — and the re-completion guard has to be able to
+        // refuse without `queueWriteOrFail` treating the refusal as an outage worth
+        // replaying later.
+        //
+        // The session endpoint derives its task from the trusted run claim and does
+        // not need (or permit) a broad task lookup. The normal user and
+        // delegated-daemon path does: task routes read OSK refs, while mutation
+        // services key on UUIDs. Passing the ref straight through caused the atomic
+        // endpoint's task-level 404 to look like "endpoint missing"; legacy fallback
+        // then posted TASK_OUTPUT before its move 404'd.
+        let completionTaskId = taskIdentity.id;
+        // Captured at resolution so the guard and the success line can both tell
+        // "already closed" from "just closed".
+        let priorStatus = null;
+        if (!sessionCompletionPath) {
+            try {
+                const target = await resolveCompletionTarget(await this.resolveTaskReference(taskIdentity.id), (taskRef) => data_provider_1.dataService.getTask(taskRef, { enrich: false }));
+                completionTaskId = target.id;
+                priorStatus = target.status;
+            }
+            catch (err) {
+                this.handleApiError(err);
+            }
+        }
+        // A task that is already closed gets one extra read, and only then — the
+        // first completion of a task never pays for this.
+        if (decideRecompletion({
+            priorStatus,
+            canonicalBody: '',
+            incomingBody: body,
+            amend: flags.amend,
+        }) !== 'proceed') {
+            let canonicalBody = null;
+            try {
+                canonicalBody = (await (0, task_transcript_1.fetchLatestTaskOutputComment)(completionTaskId))?.body ?? null;
+            }
+            catch {
+                // Unreadable history must not block a completion: falling through to
+                // `proceed` is exactly today's behaviour, which is the safe direction
+                // for a guard whose whole job is to protect a record it cannot see.
+                canonicalBody = null;
+            }
+            const decision = decideRecompletion({
+                priorStatus,
+                canonicalBody,
+                incomingBody: body,
+                amend: flags.amend,
+            });
+            if (decision === 'noop') {
+                const url = (0, web_url_1.taskUrlFrom)(this.cliConfig.baseURL, { id: completionTaskId });
+                if (flags.json) {
+                    this.log(JSON.stringify({
+                        taskId: completionTaskId,
+                        status: priorStatus,
+                        alreadyCompleted: true,
+                        changed: false,
+                        url: url ? `${url}#task-outcome` : url,
+                    }, null, 2));
+                    return;
+                }
+                this.log(`Already ${priorStatus}; this report is identical to the canonical one — nothing to do.`);
+                if (url)
+                    this.log(`Outcome: ${url}#task-outcome`);
+                return;
+            }
+            if (decision === 'refuse') {
+                this.failWithCliError({
+                    message: `Task ${completionTaskId} is already ${priorStatus}, and this report differs from its canonical ` +
+                        `outcome — completing again would silently replace it (artifacts included).\n` +
+                        `  → re-run with \`--amend\` to supersede it deliberately, or read what is there now with ` +
+                        `\`${this.config.bin} tasks output ${completionTaskId}\`.`,
+                    code: 'TASK_ALREADY_COMPLETED',
+                    exit: 1,
+                    retryable: false,
+                    details: { taskId: completionTaskId, status: priorStatus },
+                });
+            }
+        }
         let result;
         try {
-            const sessionCompletionPath = autonomousSessionCompletionPath();
-            // The session endpoint derives its task from the trusted run claim and
-            // does not need (or permit) a broad task lookup. The normal user and
-            // delegated-daemon path does: task routes read OSK refs, while mutation
-            // services key on UUIDs. Passing the ref straight through caused the
-            // atomic endpoint's task-level 404 to look like "endpoint missing";
-            // legacy fallback then posted TASK_OUTPUT before its move 404'd.
-            const completionTaskId = sessionCompletionPath
-                ? taskIdentity.id
-                : await resolveCanonicalCompletionTaskId(await this.resolveTaskReference(taskIdentity.id), (taskRef) => data_provider_1.dataService.getTask(taskRef, { enrich: false }));
             result = await completeTaskDurably({
                 taskId: completionTaskId,
                 status,
@@ -409,7 +549,14 @@ class TasksComplete extends base_command_1.BaseCommand {
             : undefined;
         this.log(`Posted TASK_OUTPUT comment ${commentId ?? '?'} on task ${completedTaskId}`);
         if (movedTask) {
-            this.log(`Moved task ${completedTaskId} to ${movedTask.status}`);
+            // Only claim a transition that happened. This printed unconditionally, so
+            // `tasks complete` on an already-done task reported "Moved task X to
+            // done" when nothing moved — a state change asserted by the one tool the
+            // reader is trusting to tell them the state.
+            const newStatus = movedTask.status;
+            this.log(priorStatus && priorStatus === newStatus
+                ? `Task ${completedTaskId} was already ${newStatus}; the outcome was amended.`
+                : `Moved task ${completedTaskId} to ${newStatus}`);
         }
         if (report) {
             const url = (0, web_url_1.taskUrlFrom)(this.cliConfig.baseURL, movedTask ?? { id: completedTaskId });

package/dist/commands/tasks/create.d.ts

@@ -1,4 +1,30 @@
 import { BaseCommand } from '../../base-command';
+/**
+ * Whether the estimate we asked for survived the write. (S3 dogfood finding)
+ *
+ * `--estimate 3` exited 0 with empty stderr and stored `null`. The value is
+ * dropped because an estimate is a SPACE-owned vocabulary: `assertTaskEstimateAllowed`
+ * resolves the scale up the Space's ancestor chain, and a chain with no
+ * `estimateScale` anywhere resolves to the `none` default — which allows no
+ * value, so the field is simply not persisted. It does not throw, because
+ * "this Space does not track estimates" is a legitimate configuration rather
+ * than a bad request.
+ *
+ * That is defensible server-side. What is not defensible is the CLI sending a
+ * value, receiving a response that plainly does not contain it, and reporting
+ * success — the caller cannot tell "stored" from "discarded" without a second
+ * read they have no reason to make.
+ *
+ * So this is a POSTCONDITION check on the response we already have: no extra
+ * round trip, and exact rather than predicted — it reports what the server
+ * actually did, including snapping a value onto a coarser scale. It warns and
+ * does not fail: the task WAS created, and exiting non-zero over one dropped
+ * field would be a worse lie than the silence it replaces.
+ *
+ * Same shape as `warnDroppedDefaultAssignees` below, which does this for a
+ * silently-dropped assignee (OSK-4857).
+ */
+export declare function droppedEstimateWarning(requested: number | undefined, written: Record<string, unknown> | null | undefined, spaceId?: string | null): string | null;
 export default class TasksCreate extends BaseCommand {
     static description: string;
     static examples: string[];

package/dist/commands/tasks/create.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.droppedEstimateWarning = droppedEstimateWarning;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
@@ -7,6 +8,49 @@ const prompt_1 = require("../../lib/prompt");
 const tasks_1 = require("../../lib/tasks");
 const task_instruction_offer_1 = require("../../lib/task-instruction-offer");
 const web_url_1 = require("../../lib/web-url");
+/**
+ * Whether the estimate we asked for survived the write. (S3 dogfood finding)
+ *
+ * `--estimate 3` exited 0 with empty stderr and stored `null`. The value is
+ * dropped because an estimate is a SPACE-owned vocabulary: `assertTaskEstimateAllowed`
+ * resolves the scale up the Space's ancestor chain, and a chain with no
+ * `estimateScale` anywhere resolves to the `none` default — which allows no
+ * value, so the field is simply not persisted. It does not throw, because
+ * "this Space does not track estimates" is a legitimate configuration rather
+ * than a bad request.
+ *
+ * That is defensible server-side. What is not defensible is the CLI sending a
+ * value, receiving a response that plainly does not contain it, and reporting
+ * success — the caller cannot tell "stored" from "discarded" without a second
+ * read they have no reason to make.
+ *
+ * So this is a POSTCONDITION check on the response we already have: no extra
+ * round trip, and exact rather than predicted — it reports what the server
+ * actually did, including snapping a value onto a coarser scale. It warns and
+ * does not fail: the task WAS created, and exiting non-zero over one dropped
+ * field would be a worse lie than the silence it replaces.
+ *
+ * Same shape as `warnDroppedDefaultAssignees` below, which does this for a
+ * silently-dropped assignee (OSK-4857).
+ */
+function droppedEstimateWarning(requested, written, spaceId) {
+    if (requested === undefined || requested === null)
+        return null;
+    if (!written || typeof written !== 'object')
+        return null;
+    const stored = written.estimate;
+    if (stored === requested)
+        return null;
+    const subject = spaceId ? `space ${spaceId}` : 'this Space';
+    if (typeof stored === 'number') {
+        return (`--estimate ${requested} was stored as ${stored}: the estimate scale on ${subject} does ` +
+            `not allow ${requested}, so the server snapped it to the nearest value it does.`);
+    }
+    return (`--estimate ${requested} was NOT stored — the task came back with no estimate. ` +
+        `Estimates are owned by the Space: ${subject} (and every ancestor it inherits from) has no ` +
+        'estimate scale, so the value is discarded rather than rejected. ' +
+        'Set one with `spaces update <space> --estimate-scale <scale> --estimate-migration <clear|migrate>`.');
+}
 class TasksCreate extends base_command_1.BaseCommand {
     static description = 'Create a new task';
     static examples = [
@@ -100,7 +144,17 @@ class TasksCreate extends base_command_1.BaseCommand {
         }),
         'start-date': core_1.Flags.string({ description: 'Planned start date (ISO string)' }),
         'due-date': core_1.Flags.string({ description: 'Due date (ISO string)' }),
-        estimate: core_1.Flags.integer({ description: 'Estimate value from the Space estimate scale' }),
+        estimate: core_1.Flags.integer({
+            // Names the prerequisite AND how to satisfy it. The first version of this
+            // help said the scale was reachable only from the web UI, which was true
+            // when written and stopped being true the moment `spaces update` grew the
+            // flag — a help string asserting a limitation has to be revisited when the
+            // limitation is lifted, or it becomes the most authoritative wrong answer
+            // in the product.
+            description: 'Estimate value from the Space estimate scale. Requires a scale on the Space (or an ' +
+                'ancestor it inherits from); with none set, the server drops the value. Set one with ' +
+                '`spaces update <space> --estimate-scale <scale> --estimate-migration <clear|migrate>`.',
+        }),
         tag: core_1.Flags.string({ description: 'Tag (repeatable)', multiple: true }),
         'label-id': core_1.Flags.string({
             description: 'Attach a task label by id (repeatable). Manage labels with `skrr tasks labels`. ' +
@@ -333,6 +387,11 @@ class TasksCreate extends base_command_1.BaseCommand {
             }
         }
         const url = (0, web_url_1.taskUrlFrom)(this.cliConfig.baseURL, created);
+        // Before either output path, and via `warn` so it reaches stderr — `--json`
+        // stdout stays a parseable task row.
+        const estimateWarning = droppedEstimateWarning(flags.estimate, created, payload.spaceId);
+        if (estimateWarning)
+            this.warn(estimateWarning);
         if (flags.json) {
             // The raw task row alone cannot tell a script the assignee it implicitly
             // asked for was dropped (`assigneeAgentIds: []`) from "nobody was ever

package/dist/commands/tasks/events/append.d.ts

@@ -1,6 +1,8 @@
 import { BaseCommand } from '../../../base-command';
 export default class TasksEventsAppend extends BaseCommand {
+    static summary: string;
     static description: string;
+    static examples: string[];
     static args: {
         id: import("@oclif/core/lib/interfaces").Arg<string | undefined, Record<string, unknown>>;
     };

package/dist/commands/tasks/events/append.js

@@ -8,12 +8,38 @@ const api_fetch_1 = require("../../../lib/api-fetch");
 const session_task_endpoints_1 = require("../../../lib/session-task-endpoints");
 const tasks_1 = require("../../../lib/tasks");
 class TasksEventsAppend extends base_command_1.BaseCommand {
-    static description = 'Append a typed, durable task event';
-    static args = { id: core_1.Args.string({ required: false, ignoreStdin: true }) };
+    static summary = 'Append a typed, durable task event';
+    static description = 'Records one meaningful work boundary — a decision, a material change, evidence, a blocker, ' +
+        'or a handoff — on the task you are executing. Not a log of tool calls: an event that is ' +
+        'worth reading six weeks from now. `skrr tasks timeline <id>` reads them back.';
+    static examples = [
+        '<%= config.bin %> tasks events append <task-id> --kind checkpoint --idempotency-key "<task-id>:first-pass" --summary "Parser handles nested fences"',
+        '<%= config.bin %> tasks events append <task-id> --kind decision --idempotency-key "<task-id>:storage-choice" --summary "Chose the CRDT path" --evidence "A direct contentHtml write is reverted by the next render tick"',
+        '<%= config.bin %> tasks events append <task-id> --kind verification --idempotency-key "<task-id>:verified" --summary "Repro no longer reproduces" --artifact <commit-sha>',
+    ];
+    static args = {
+        id: core_1.Args.string({
+            required: false,
+            ignoreStdin: true,
+            description: 'Task ID. Optional inside a task runtime, which supplies it',
+        }),
+    };
     static flags = {
-        task: core_1.Flags.string(),
-        json: core_1.Flags.boolean(),
-        'idempotency-key': core_1.Flags.string({ required: true }),
+        task: core_1.Flags.string({
+            description: 'Task ID; overrides the runtime context and the positional',
+        }),
+        json: core_1.Flags.boolean({ description: 'Output the created event as JSON' }),
+        // The semantics here are the ones that actually bite, and they lived only
+        // in the platform's instruction block: a key names ONE update permanently.
+        // Retried with the same text the server silently returns the original; with
+        // DIFFERENT text it refuses with 409 TASK_EVENT_IDEMPOTENCY_CONFLICT. A
+        // caller who does not know that reads a dedupe as a successful write.
+        'idempotency-key': core_1.Flags.string({
+            required: true,
+            description: 'Stable key naming THIS update permanently, e.g. "<task-id>:verified". Reuse it only to ' +
+                'retry the same update — reused with identical text the original is returned, with ' +
+                'different text the server refuses (409 TASK_EVENT_IDEMPOTENCY_CONFLICT)',
+        }),
         // Enumerated so `--help` lists the kinds and a bad value is rejected by the
         // flag parser (naming the choices) rather than by the server's opaque
         // `Invalid request data` / HTTP_400. (OSK-4888)
@@ -22,11 +48,16 @@ class TasksEventsAppend extends base_command_1.BaseCommand {
             description: 'Event kind at a meaningful work boundary',
             options: [...tasks_1.TASK_WORK_EVENT_KINDS],
         }),
-        summary: core_1.Flags.string({ required: true }),
-        changed: core_1.Flags.string(),
-        next: core_1.Flags.string(),
-        evidence: core_1.Flags.string(),
-        artifact: core_1.Flags.string({ multiple: true, description: 'Artifact reference; repeatable' }),
+        summary: core_1.Flags.string({ required: true, description: 'What is newly true, in one sentence' }),
+        changed: core_1.Flags.string({ description: 'What moved — the concrete change this event records' }),
+        next: core_1.Flags.string({ description: 'What happens next, or who owns the next decision' }),
+        evidence: core_1.Flags.string({
+            description: 'Why it is true — an observation, command output, or a before → after',
+        }),
+        artifact: core_1.Flags.string({
+            multiple: true,
+            description: 'Durable reference: a file path, commit sha, or URL. Repeatable. "in the conversation" is not an artifact',
+        }),
     };
     async run() {
         this.requireAuth();