@skrr-ai/cli 0.1.23 → 0.1.25

package/dist/commands/spaces/work-sync/reconcile.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../../base-command");
+const work_sync_1 = require("../../../lib/work-sync");
+/**
+ * `skrr spaces work-sync reconcile <space>` — answer the divergence question
+ * without a browser, and repair what it finds.
+ *
+ * Root `CLAUDE.md` records that two Work Sync exit criteria were knowingly
+ * overridden, and that "an unexplained board divergence is a live hypothesis, not
+ * an impossibility, and is the first thing to suspect." `work-sync telemetry`
+ * reports whether the browser's convergence detector has ever RUN. This answers
+ * the underlying question directly: it compares every published projection entry
+ * against authoritative task truth server-side, and `upserts` is the count that
+ * disagreed.
+ *
+ * That matters because the detector only runs where a board is open. A Space
+ * nobody has visited since the detector shipped reports zero comparisons forever,
+ * which is indistinguishable from health in the telemetry and is not health. This
+ * command needs no board, no browser, and no visitor.
+ *
+ * IT WRITES, and the help says so plainly rather than burying it. The endpoint is
+ * editor-gated because it republishes projection rows that clients will see. It
+ * never mutates task truth — the projection is derived, and a republished card is
+ * a corrected copy of a Task nobody touched — and on a healthy scope it finds
+ * nothing and changes nothing, so the verification and the repair are the same
+ * call. There is deliberately no dry-run flag to add: a read-only variant would be
+ * a second implementation of the comparison, which is how the two answers start
+ * disagreeing.
+ */
+class SpacesWorkSyncReconcile extends base_command_1.BaseCommand {
+    static description = 'Compare a Space Work Sync projection against task truth and repair what diverged (writes)';
+    static examples = [
+        '<%= config.bin %> spaces work-sync reconcile <space-id>',
+        '<%= config.bin %> spaces work-sync reconcile <space-id> --json',
+    ];
+    static args = {
+        space: core_1.Args.string({ description: 'Space ID', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(SpacesWorkSyncReconcile);
+        let result;
+        try {
+            result = await (0, work_sync_1.reconcileWorkSyncScope)(args.space);
+        }
+        catch (err) {
+            this.handleApiError(err);
+            return;
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        const diverged = (result.upserts || 0) +
+            (result.removes || 0) +
+            (result.summaryUpserts || 0) +
+            (result.summaryRemoves || 0);
+        // Lead with the verdict, because it is the whole reason to run this. A table
+        // of four zeros under no summary line makes the reader do the addition.
+        if (diverged === 0) {
+            this.log('No divergence: every published projection entry matches task truth.');
+        }
+        else {
+            this.log(`Divergence found and repaired: ${diverged} ${diverged === 1 ? 'entry' : 'entries'}.`);
+            this.log('');
+            this.log(`  stale task cards republished   ${result.upserts || 0}`);
+            this.log(`  task cards removed             ${result.removes || 0}`);
+            this.log(`  stale summaries republished    ${result.summaryUpserts || 0}`);
+            this.log(`  summaries removed              ${result.summaryRemoves || 0}`);
+        }
+        if (result.backlog > 0) {
+            this.log('');
+            this.log(`${result.backlog} repair ${result.backlog === 1 ? 'row was' : 'rows were'} already queued ` +
+                'by earlier publish failures. A successful run settles them; one that failed again is kept.');
+        }
+        if (result.truncated) {
+            this.log('');
+            // Never let a partial pass read as a clean one. The scope read is capped at
+            // 1000 rows, so a larger Space was only checked as far as the cap.
+            this.log('PARTIAL: this Space is larger than the 1000-row reconciliation cap, so the ' +
+                'verdict above covers a prefix of it and not the whole Space.');
+        }
+    }
+}
+exports.default = SpacesWorkSyncReconcile;

package/dist/commands/spaces/work-sync/telemetry.d.ts

@@ -0,0 +1,29 @@
+import { BaseCommand } from '../../../base-command';
+/**
+ * `skrr spaces work-sync telemetry <space>` — Work Sync's own exit criteria.
+ *
+ * Work Sync v1 is ON at 100% (owner decision, 2026-09-08) with two criteria
+ * knowingly overridden rather than satisfied. The server has computed the verdict
+ * the whole time, and nothing outside the API could read it — so checking the
+ * criteria meant querying the production database by hand, which is why nobody
+ * did. An exit criterion that can only be read by hand is one that does not get
+ * read.
+ *
+ * The verdict is printed as the server decided it. This command does not
+ * re-derive it: the same rule that keeps `tasks expectations` reading the server's
+ * judgement rather than computing its own applies here, and for the same reason —
+ * a CLI that reached a different conclusion from the service would leave the
+ * reader unable to tell which was lying.
+ */
+export default class SpacesWorkSyncTelemetry extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        space: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        limit: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/spaces/work-sync/telemetry.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../../base-command");
+const work_sync_1 = require("../../../lib/work-sync");
+/**
+ * `skrr spaces work-sync telemetry <space>` — Work Sync's own exit criteria.
+ *
+ * Work Sync v1 is ON at 100% (owner decision, 2026-09-08) with two criteria
+ * knowingly overridden rather than satisfied. The server has computed the verdict
+ * the whole time, and nothing outside the API could read it — so checking the
+ * criteria meant querying the production database by hand, which is why nobody
+ * did. An exit criterion that can only be read by hand is one that does not get
+ * read.
+ *
+ * The verdict is printed as the server decided it. This command does not
+ * re-derive it: the same rule that keeps `tasks expectations` reading the server's
+ * judgement rather than computing its own applies here, and for the same reason —
+ * a CLI that reached a different conclusion from the service would leave the
+ * reader unable to tell which was lying.
+ */
+class SpacesWorkSyncTelemetry extends base_command_1.BaseCommand {
+    static description = "Show Work Sync's convergence telemetry for a Space and the server's rollout verdict";
+    static examples = [
+        '<%= config.bin %> spaces work-sync telemetry <space-id>',
+        '<%= config.bin %> spaces work-sync telemetry <space-id> --json',
+    ];
+    static args = {
+        space: core_1.Args.string({ description: 'Space ID', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+        limit: core_1.Flags.integer({
+            description: 'Most recent telemetry rows to summarize (1-10000, default 5000)',
+        }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(SpacesWorkSyncTelemetry);
+        let summary;
+        try {
+            summary = await (0, work_sync_1.fetchWorkSyncTelemetrySummary)(args.space, { limit: flags.limit });
+        }
+        catch (err) {
+            this.handleApiError(err);
+            return;
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(summary, null, 2));
+            return;
+        }
+        this.log(`Verdict:       ${summary.rollout.verdict}`);
+        this.log(`Sampled rows:  ${summary.sampledEvents}`);
+        this.log(`Repair backlog: ${summary.repairBacklog}`);
+        if (summary.coverage && summary.coverage.hits + summary.coverage.misses > 0) {
+            const { hits, misses, hitRate } = summary.coverage;
+            this.log(`Coverage:      ${hits} hits · ${misses} misses` +
+                (hitRate === null ? '' : ` (${Math.round(hitRate * 1000) / 10}% of cold opens)`));
+        }
+        // Before the zero-events early return: writes are measured from the command
+        // queue, not from board telemetry, so a Space can have one without the other.
+        const commandRows = Object.entries(summary.commands || {}).sort(([a], [b]) => a.localeCompare(b));
+        if (commandRows.length > 0) {
+            const percent = (value) => value === null ? 'n/a' : `${Math.round(value * 1000) / 10}%`;
+            this.log('');
+            this.log('Writes (durable command queue):');
+            for (const [kind, stats] of commandRows) {
+                this.log(`  ${kind.padEnd(20)} ${stats.commands} commands · ${stats.accepted} accepted · ` +
+                    `${stats.pending} pending · ${stats.deadLettered} refused`);
+                this.log(`  ${''.padEnd(20)} version conflicts ${stats.versionConflicts} ` +
+                    `(${percent(stats.rates.versionConflict)} of settled) · authorization changed ` +
+                    `${stats.authorizationChanged} (${percent(stats.rates.authorizationChanged)}) · ` +
+                    `duplicate deliveries ${stats.duplicateDeliveries} ` +
+                    `(${percent(stats.rates.duplicateDelivery)} of deliveries)`);
+            }
+        }
+        // Zero sampled rows is a REAL answer and the most misread one: it means
+        // nothing has been measured in this Space, not that everything is fine. The
+        // server already distinguishes it (`insufficient_evidence`); say so here too
+        // rather than printing an empty table under a clean-looking verdict.
+        if (summary.sampledEvents === 0) {
+            this.log('');
+            this.log('No telemetry has been recorded for this Space. That is not evidence of health — ' +
+                'it means no board in this Space has reported, so nothing has been measured.');
+            return;
+        }
+        const rows = Object.entries(summary.events).sort(([a], [b]) => a.localeCompare(b));
+        if (rows.length > 0) {
+            this.log('');
+            this.log('Events:');
+            for (const [event, stats] of rows) {
+                const parts = [`count ${stats.count}`];
+                if (stats.mismatchCount > 0)
+                    parts.push(`mismatches ${stats.mismatchCount}`);
+                if (stats.p50DurationMs !== null) {
+                    parts.push(`p50 ${stats.p50DurationMs}ms`, `p95 ${stats.p95DurationMs}ms`);
+                }
+                if (stats.p50Bytes !== null) {
+                    parts.push(`p50 ${stats.p50Bytes}B`, `p95 ${stats.p95Bytes}B`);
+                }
+                this.log(`  ${event.padEnd(20)} ${parts.join(' · ')}`);
+            }
+        }
+        if (summary.rollout.reasons.length > 0) {
+            this.log('');
+            this.log('Holding because:');
+            for (const reason of summary.rollout.reasons) {
+                // An unexplained code is the thing this command exists to avoid: the
+                // reader is being told a rollout is held and needs to know by what.
+                this.log(`  ${reason}`);
+                const explanation = work_sync_1.WORK_SYNC_HOLD_REASONS[reason];
+                if (explanation)
+                    this.log(`    ${explanation}`);
+            }
+        }
+    }
+}
+exports.default = SpacesWorkSyncTelemetry;

package/dist/commands/tasks/activity.js

@@ -6,6 +6,7 @@ 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");
+const task_legacy_1 = require("../../lib/task-legacy");
 function activityRow(entry) {
     const actor = entry.actor;
     const actorText = actor
@@ -110,7 +111,10 @@ class TasksActivity extends base_command_1.BaseCommand {
         const r = response;
         const items = r?.data ?? [];
         if (items.length === 0) {
-            this.log('No activity.');
+            // "No activity." was a claim about the TASK. It is only ever a claim about
+            // this VIEW: a Task predating the canonical model has its history in the
+            // legacy activity log, which this endpoint does not read.
+            this.log(await (0, task_legacy_1.emptyCanonicalView)(args.id, 'Activity'));
             return;
         }
         (0, format_1.renderTable)(items.map(activityRow), [

package/dist/commands/tasks/assign.js

@@ -74,7 +74,7 @@ class TasksAssign extends base_command_1.BaseCommand {
             options: ['agent', 'human'],
         }),
         list: core_1.Flags.boolean({
-            description: "List the task's space members (who can be assigned) and exit",
+            description: "List the task's space members and exit (your own unshared agents can also be assigned, by id)",
         }),
         json: core_1.Flags.boolean({ description: 'Output as JSON' }),
     };

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

@@ -1,9 +1,13 @@
 import { BaseCommand } from '../../base-command';
-export declare function describePendingReview({ statusType, taskId, resultId, bin, }: {
+export declare function describePendingReview({ statusType, taskId, resultId, bin, advisories, }: {
     statusType: unknown;
     taskId: string;
     resultId?: string;
     bin: string;
+    advisories?: Array<{
+        code: string;
+        message: string;
+    }>;
 }): string | null;
 export default class TasksComplete extends BaseCommand {
     static description: string;

package/dist/commands/tasks/complete.js

@@ -43,11 +43,24 @@ function optionalString(value) {
 function stringArray(value) {
     return Array.isArray(value) ? value.map((item) => String(item).trim()).filter(Boolean) : [];
 }
-function describePendingReview({ statusType, taskId, resultId, bin, }) {
+function describePendingReview({ statusType, taskId, resultId, bin, advisories, }) {
     if (statusType !== 'review')
         return null;
-    return ('The Result was submitted, but the Task is not done yet. An independent reviewer must ' +
-        `accept this exact Result with: ${bin} tasks review ${taskId} --result-id ${resultId || '<result-id>'} --decision accepted`);
+    // Say which thing is actually holding the Task. This used to assert a missing
+    // reviewer unconditionally, so a Task held by unmet Expectations was reported
+    // as needing review — and the command it handed over failed every time, both
+    // because the block was elsewhere and because a submitter may not accept their
+    // own Result (`TASK_REVIEW_SELF_ACCEPTANCE`).
+    const expectationAdvisory = (advisories || []).find((row) => row.code === 'task_acceptance_not_met' || /expectation/i.test(row.code || ''));
+    if (expectationAdvisory) {
+        return ('The Result was submitted, but the Task is not done yet: its Expectations are not all ' +
+            `settled. ${expectationAdvisory.message} ` +
+            `Settle each with: ${bin} tasks expectations assess ${taskId} <expectation-id> ` +
+            '--decision met|waived --reason "..."');
+    }
+    return ('The Result was submitted, but the Task is not done yet. It is waiting on an independent ' +
+        `accepted Review — someone OTHER than the submitter runs: ${bin} tasks review ${taskId} ` +
+        `--result-id ${resultId || '<result-id>'} --decision accepted`);
 }
 class TasksComplete extends base_command_1.BaseCommand {
     static description = 'Submit one versioned Result and advance the Task workflow';
@@ -247,6 +260,7 @@ class TasksComplete extends base_command_1.BaseCommand {
             taskId,
             resultId: result.result.id,
             bin: this.config.bin,
+            advisories: result.advisories,
         });
         if (pending)
             this.log(pending);

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

@@ -58,6 +58,7 @@ export default class TasksCreate extends BaseCommand {
         'dri-agent': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'dri-user': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         expect: import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'review-policy': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'execution-mode': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'start-date': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'due-date': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;

package/dist/commands/tasks/create.js

@@ -192,6 +192,13 @@ class TasksCreate extends base_command_1.BaseCommand {
                 " Injected into the agent's instructions and checked against what the run produced. " +
                 'Omit to inherit the space default.',
         }),
+        'review-policy': core_1.Flags.string({
+            options: ['none', 'required'],
+            description: 'Whether closing this Task needs someone other than the Result author to accept it. ' +
+                "Default 'none': the Expectations you declare are already your definition of done. " +
+                "Use 'required' when the work warrants a second pair of eyes — it applies to every " +
+                'executor, human or agent.',
+        }),
         'execution-mode': core_1.Flags.string({
             description: 'Who executes the task: agent or human. Required when both Humans and Agents are ' +
                 'assigned. Passing "human" with no assignee flags files the task against you, ' +
@@ -453,8 +460,9 @@ class TasksCreate extends base_command_1.BaseCommand {
             defaultAgentResolution = {
                 applied: false,
                 source: 'none',
-                note: 'Created unassigned: the agent bound to this session is not a member of that space. ' +
-                    'Add it to the space, or pass an assignee explicitly.',
+                note: 'Created unassigned: the agent bound to this session is not a member of that space, ' +
+                    'and it is not your own agent shared with no one else, which is the only other way ' +
+                    'an agent can work there. Add it to the space, or pass an assignee explicitly.',
             };
             try {
                 const result = await this.createTaskOrRecover(payload);
@@ -565,9 +573,14 @@ class TasksCreate extends base_command_1.BaseCommand {
         const dropped = (0, tasks_1.droppedDefaultAssignees)(resolution, memberIds);
         const warnings = [];
         if (dropped.agentIds.length > 0) {
+            // Membership is one of TWO consents the server accepts (AgentTaskConsent);
+            // the other — your own agent, shared with no one else — needs the agent's
+            // sharing, which a dry run does not read. So this says what decides it
+            // rather than predicting a drop that owner delegation would not make.
             warnings.push(`The defaulted assignee agent ${dropped.agentIds.join(', ')} is not a member of ` +
-                `space ${spaceId}, so the real create will drop it and record the task ` +
-                'unassigned. Add the agent to the space, or pass an assignee explicitly.');
+                `space ${spaceId}. The real create keeps it only if it is your own agent shared ` +
+                'with no one else; otherwise it records the task unassigned. Add the agent to the ' +
+                'space, or pass an assignee explicitly.');
         }
         if (dropped.userIds.length > 0) {
             warnings.push(`The defaulted assignee ${dropped.userIds.join(', ')} is not a member of space ` +

package/dist/commands/tasks/deliverable/add.js

@@ -17,7 +17,20 @@ const tasks_1 = require("../../../lib/tasks");
  * optional structured one.
  */
 class TasksDeliverableAdd extends base_command_1.BaseCommand {
-    static description = 'Record something this task produced (a commit, a page, a URL, a file, a message, a dataset)';
+    static description = 'Record something this task produced (a commit, a page, a URL, a file, a message, a dataset).\n' +
+        '\n' +
+        'IDENTITY is the part before @; LOCATION is the part after it. They are not the same ' +
+        'grammar as `--expect`, where the same-looking `code:origin/main` names a DESTINATION ' +
+        'rather than a thing that exists. Here `origin/main` is where the commit landed, and ' +
+        'the commit SHA is what is identified.\n' +
+        '\n' +
+        'Two Deliverables share one Resource when their identity matches, scoped to the ' +
+        'workspace. A bare relative path has no global meaning, so `docs/report.md` from two ' +
+        'different repositories in one workspace IS the same Resource — pass --provider and a ' +
+        "provider id when you mean a specific system's object, which moves the identity into " +
+        "that provider's namespace. Without --version or a content digest the version is " +
+        '`locator_only`: nothing pins which revision it is, and a later sighting of the same ' +
+        'coordinate may be different bytes.';
     static examples = [
         '<%= config.bin %> tasks deliverable add <task-id> code:a1b2c3d@origin/main',
         '<%= config.bin %> tasks deliverable add <task-id> page:d_92@Engineering/deploy',
@@ -27,8 +40,9 @@ class TasksDeliverableAdd extends base_command_1.BaseCommand {
     static args = {
         task: core_1.Args.string({ description: 'Task id or ref', required: true, ignoreStdin: true }),
         coordinate: core_1.Args.string({
-            description: '<kind>[/<format>]:<identity>[@<location>] — e.g. code:a1b2c3d@origin/main, ' +
-                'file/pdf:report_92@Drive/Reports',
+            description: '<kind>[/<format>]:<identity>[@<location>] — identity before @, location after. ' +
+                'e.g. code:a1b2c3d@origin/main, file/pdf:report_92@Drive/Reports. ' +
+                'Kinds: code, file, page, url, message, dataset',
             required: true,
             ignoreStdin: true,
         }),
@@ -44,7 +58,11 @@ class TasksDeliverableAdd extends base_command_1.BaseCommand {
             hidden: true,
         }),
         title: core_1.Flags.string({ description: 'Human-readable Deliverable name' }),
-        provider: core_1.Flags.string({ description: 'Provider, such as github or drive' }),
+        provider: core_1.Flags.string({
+            description: 'Provider, such as github or drive. This CHANGES the Resource identity: it moves the ' +
+                "key from the locator namespace into the provider's, so the same coordinate with and " +
+                'without --provider are two different Resources',
+        }),
         version: core_1.Flags.string({ description: 'Exact provider version, such as a full commit SHA' }),
         'content-digest': core_1.Flags.string({ description: 'Integrity digest for this exact version' }),
         expectation: core_1.Flags.string({ multiple: true, description: 'Expectation id this satisfies' }),

package/dist/commands/tasks/deliverable/list.js

@@ -4,6 +4,25 @@ const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../../base-command");
 const task_resolver_1 = require("../../../lib/task-resolver");
+/**
+ * `locator_only` is the storage word, and it appeared on nearly every row with
+ * nothing saying what it meant. It is not a defect — it is the honest statement
+ * that nothing pins WHICH revision this is — so the label says that.
+ */
+function fidelityLabel(value) {
+    switch (value) {
+        case 'managed_copy':
+            return 'exact version archived';
+        case 'content_digest':
+            return 'exact version (content verified)';
+        case 'provider_version':
+            return 'exact version (provider revision)';
+        case 'locator_only':
+            return 'version not pinned — the coordinate may change under you';
+        default:
+            return value || 'unknown fidelity';
+    }
+}
 class TasksDeliverableList extends base_command_1.BaseCommand {
     static description = 'List Deliverables with exact version, location, and evidence state';
     static args = {
@@ -29,8 +48,10 @@ class TasksDeliverableList extends base_command_1.BaseCommand {
         if (!result.data.length)
             return this.log('No Deliverables recorded.');
         for (const item of result.data) {
-            this.log(`${item.linkId} · ${item.title || item.identity || item.kind}\n` +
-                `  ${item.location || 'no locator'} · ${item.versionFidelity} · ${item.status} · ${item.evidenceLevel}`);
+            this.log(`${item.linkId} · ${item.kind}${item.format ? `/${item.format}` : ''} · ` +
+                `${item.title || item.identity || '(untitled)'}\n` +
+                `  ${item.location || 'no locator'} · ${fidelityLabel(item.versionFidelity)} · ` +
+                `${item.status} · ${item.evidenceLevel}`);
         }
     }
 }

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

@@ -10,8 +10,16 @@ const task_artifact_flags_1 = require("../../../lib/task-artifact-flags");
 const tasks_1 = require("../../../lib/tasks");
 class TasksEventsAppend extends base_command_1.BaseCommand {
     static hidden = true;
-    static summary = 'Append a typed, durable task event';
-    static description = 'Compatibility adapter for historical Event vocabulary; use `tasks updates add`.';
+    // The SUMMARY is what `tasks --help` and the first line of `--help` show, and
+    // it is the only line most readers see. Saying only "Append a typed, durable
+    // task event" there while the deprecation lived in the long DESCRIPTION meant
+    // the retired vocabulary read as the intended path — which is how it kept
+    // getting exercised.
+    static summary = 'DEPRECATED compatibility spelling for `tasks updates add` — append a legacy task event';
+    static description = 'DEPRECATED compatibility adapter for the historical Event vocabulary. Every kind is ' +
+        'stored as a canonical Update, so `--kind handoff` and `--kind checkpoint` both become ' +
+        '`progress`, and `--kind started|lifecycle` writes only to the Activity ledger and will ' +
+        'NOT appear in `tasks updates list`. Use `tasks updates add` instead.';
     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"',
@@ -91,7 +99,27 @@ class TasksEventsAppend extends base_command_1.BaseCommand {
         }
         if (path && result && typeof result === 'object' && 'entry' in result)
             result = result.entry;
-        this.log(flags.json ? JSON.stringify(result, null, 2) : `Appended event to task ${task.id}.`);
+        if (flags.json)
+            return this.log(JSON.stringify(result, null, 2));
+        // The old receipt named neither what was written nor where to find it, so a
+        // caller could not tell a successful compatibility write from a no-op — and
+        // this command silently becomes a canonical Update of a DIFFERENT type.
+        const written = result || {};
+        if (written.canonicalType) {
+            this.log(`Recorded on ${task.id} as a ${written.canonicalType} Update` +
+                `${written.id ? ` (${written.id})` : ''}.`);
+            this.log(`\`tasks events append\` is a compatibility spelling; \`${this.config.bin} tasks updates add\` ` +
+                `is the canonical command, and \`${this.config.bin} tasks updates list\` reads them back.`);
+            return;
+        }
+        // `--kind started|lifecycle` produces no Update at all: it writes a
+        // `task.lifecycle.changed` row to the Activity ledger. The old receipt was
+        // byte-identical to the Update case, so a caller was told "appended" and
+        // then could not find it in the surface the deprecation notice points at.
+        this.log(`Recorded on ${task.id} in the Activity ledger` +
+            `${written.id ? ` (${written.id})` : ''} — NOT as a Task Update.`);
+        this.log(`Read it with \`${this.config.bin} tasks activity ${task.id}\`; it will not appear in ` +
+            `\`${this.config.bin} tasks updates list\`.`);
     }
 }
 exports.default = TasksEventsAppend;

package/dist/commands/tasks/expectations/assess.d.ts

@@ -3,7 +3,7 @@ export default class TasksExpectationsAssess extends BaseCommand {
     static description: string;
     static args: {
         task: import("@oclif/core/lib/interfaces").Arg<string | undefined, Record<string, unknown>>;
-        expectation: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        expectation: import("@oclif/core/lib/interfaces").Arg<string | undefined, Record<string, unknown>>;
     };
     static flags: {
         task: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;

package/dist/commands/tasks/expectations/assess.js

@@ -9,9 +9,24 @@ const api_fetch_1 = require("../../../lib/api-fetch");
 const session_task_endpoints_1 = require("../../../lib/session-task-endpoints");
 class TasksExpectationsAssess extends base_command_1.BaseCommand {
     static description = 'Assess one current Task Expectation with evidence and a reason';
+    // Both positionals are declared optional because oclif REJECTS an args table
+    // whose optional entry precedes a required one — it throws `Invalid argument
+    // spec` at parse time, before any network call, which made this command
+    // impossible to invoke in any form. Since a declared Expectation hard-gates
+    // closure (`TaskClosurePolicy.assertTaskMayClose`) and re-assessment is the
+    // only way back, that parse failure was a permanent close-deadlock for every
+    // Task carrying one. The two supported shapes are disambiguated in `run()`.
     static args = {
-        task: core_1.Args.string({ required: false, ignoreStdin: true, description: 'Task id or ref' }),
-        expectation: core_1.Args.string({ required: true, ignoreStdin: true, description: 'Expectation id' }),
+        task: core_1.Args.string({
+            required: false,
+            ignoreStdin: true,
+            description: 'Task id or ref; omit inside a task runtime',
+        }),
+        expectation: core_1.Args.string({
+            required: false,
+            ignoreStdin: true,
+            description: 'Expectation id',
+        }),
     };
     static flags = {
         task: core_1.Flags.string({ description: 'Task id; overrides runtime context' }),
@@ -31,7 +46,18 @@ class TasksExpectationsAssess extends base_command_1.BaseCommand {
     async run() {
         this.requireAuth();
         const { args, flags } = await this.parse(TasksExpectationsAssess);
-        const task = (0, task_resolver_1.resolveTaskIdentity)({ positionalId: args.task, flagTask: flags.task });
+        // `assess <task> <expectation>` gives both; `assess <expectation>` inside a
+        // task runtime gives one, and it is the Expectation.
+        const expectationId = args.expectation ?? args.task;
+        if (!expectationId) {
+            this.error('An Expectation id is required: `tasks expectations assess <task> <expectation>`', {
+                exit: 1,
+            });
+        }
+        const task = (0, task_resolver_1.resolveTaskIdentity)({
+            positionalId: args.expectation ? args.task : undefined,
+            flagTask: flags.task,
+        });
         const evidenceRefs = (flags.evidence || []).map((raw) => {
             const split = raw.indexOf(':');
             if (split < 1)
@@ -53,16 +79,16 @@ class TasksExpectationsAssess extends base_command_1.BaseCommand {
         try {
             const data = {
                 ...payload,
-                expectationId: args.expectation,
+                expectationId,
                 idempotencyKey: flags['idempotency-key'] ||
-                    (0, outbox_1.idempotencyKeyFor)('task-expectation-assessment', task.id, JSON.stringify({ expectationId: args.expectation, ...payload })),
+                    (0, outbox_1.idempotencyKeyFor)('task-expectation-assessment', task.id, JSON.stringify({ expectationId, ...payload })),
             };
             const sessionPath = await (0, session_task_endpoints_1.sessionScopedTaskPath)('assessment');
             result = sessionPath
                 ? await (0, api_fetch_1.apiFetch)(sessionPath, { method: 'POST', body: data })
                 : await data_provider_1.dataService.assessTaskExpectation({
                     taskId: task.id,
-                    expectationId: args.expectation,
+                    expectationId,
                     data,
                 });
         }
@@ -71,7 +97,7 @@ class TasksExpectationsAssess extends base_command_1.BaseCommand {
         }
         if (flags.json)
             return this.log(JSON.stringify(result, null, 2));
-        this.log(`Recorded ${args.expectation} as ${flags.decision}.`);
+        this.log(`Recorded ${expectationId} as ${flags.decision}.`);
     }
 }
 exports.default = TasksExpectationsAssess;