@skrr-ai/cli 0.1.22 → 0.1.24

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

@@ -0,0 +1,21 @@
+import { BaseCommand } from '../../../base-command';
+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 | undefined, Record<string, unknown>>;
+    };
+    static flags: {
+        task: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        decision: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        reason: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'result-id': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'run-id': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'resource-link-id': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        evidence: import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'spec-version': import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'idempotency-key': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

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

@@ -0,0 +1,103 @@
+"use strict";
+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 outbox_1 = require("../../../lib/outbox");
+const task_resolver_1 = require("../../../lib/task-resolver");
+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; 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' }),
+        decision: core_1.Flags.string({ required: true, options: ['met', 'unmet', 'waived'] }),
+        reason: core_1.Flags.string({ required: true, description: 'Why this assessment is justified' }),
+        'result-id': core_1.Flags.string({ description: 'Result this assessment concerns' }),
+        'run-id': core_1.Flags.string({ description: 'Canonical assessor Run for a generic API call' }),
+        'resource-link-id': core_1.Flags.string({ description: 'Deliverable Resource link supporting it' }),
+        evidence: core_1.Flags.string({
+            multiple: true,
+            description: 'Evidence reference as <kind>:<id-or-uri>',
+        }),
+        'spec-version': core_1.Flags.integer({ description: 'Task specification version being assessed' }),
+        'idempotency-key': core_1.Flags.string({ description: 'Stable retry key' }),
+        json: core_1.Flags.boolean({ description: 'Output JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(TasksExpectationsAssess);
+        // `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)
+                this.error('--evidence must be <kind>:<id-or-uri>', { exit: 1 });
+            const kind = raw.slice(0, split);
+            const value = raw.slice(split + 1);
+            return /^https?:|^file:/.test(value) ? { kind, uri: value } : { kind, id: value };
+        });
+        const payload = {
+            decision: flags.decision,
+            runId: flags['run-id'],
+            reason: flags.reason,
+            resultId: flags['result-id'],
+            resourceLinkId: flags['resource-link-id'],
+            evidenceRefs,
+            expectedSpecVersion: flags['spec-version'],
+        };
+        let result;
+        try {
+            const data = {
+                ...payload,
+                expectationId,
+                idempotencyKey: flags['idempotency-key'] ||
+                    (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,
+                    data,
+                });
+        }
+        catch (error) {
+            this.handleApiError(error);
+        }
+        if (flags.json)
+            return this.log(JSON.stringify(result, null, 2));
+        this.log(`Recorded ${expectationId} as ${flags.decision}.`);
+    }
+}
+exports.default = TasksExpectationsAssess;

package/dist/commands/tasks/expectations.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
+const data_provider_2 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
 /**
  * `skrr tasks expectations <task>` — what this task owes, and how far each got.
@@ -21,25 +22,63 @@ const STATE_LABEL = {
     unverified: 'needs a look',
     underway: 'on its way',
     owed: 'not yet',
-    unjudged: 'needs a person',
+    unassessed: 'needs assessment',
 };
+/**
+ * The evidence gap, on the rows where a reader can act on it.
+ *
+ * `unverified` and `underway` BOTH mean "something was produced and pinned to
+ * this Expectation, and it is not enough yet" — they differ only in whether the
+ * thing has been observed as available. Printing the gap on the first and
+ * nothing on the second is what made the careful path unreadable: an operator
+ * who pinned a deliverable saw `on its way` and had no way to learn that the
+ * bar was `external_receipt` and their own report could never clear it.
+ *
+ * It stays off the rows where it is noise: a met or waived row has nothing
+ * outstanding, and an `owed`/`unassessed` row has no deliverable to compare
+ * against, so naming a required authority there describes a hypothetical.
+ */
+const PINNED_STATES = new Set(['unverified', 'underway']);
+function evidenceGap(expectation) {
+    /*
+     * A `met` row settled BELOW its declared bar says so.
+     *
+     * `@merged-to-main` asks for `external_receipt` and is satisfiable by a person
+     * typing "I checked git log". That is allowed on purpose — refusing it is the
+     * deadlock the ladder exists to prevent — but every surface then read as though
+     * a receipt had arrived: the row said `done`, the rollup said `met`, and the
+     * recorded gap was visible only to someone who dumped the assessment rows and
+     * already knew the field existed.
+     */
+    if (expectation.evidenceShortfall) {
+        const { provided, required } = expectation.evidenceShortfall;
+        return `  (vouched at ${provided}, asked for ${required})`;
+    }
+    if (!PINNED_STATES.has(expectation.state))
+        return '';
+    if (!expectation.evidenceLevel || !expectation.requiredEvidence)
+        return '';
+    if (expectation.evidenceLevel === expectation.requiredEvidence)
+        return '';
+    return `  (has ${expectation.evidenceLevel}, needs ${expectation.requiredEvidence})`;
+}
 function line(expectation) {
     const label = STATE_LABEL[expectation.state] || expectation.state;
-    // A judged expectation is stated as NOT a gate. A list that reads like a
-    // contract while enforcing nothing is worse than no list, because it is
-    // trusted.
-    const gate = expectation.gating ? '' : '  (does not block completion)';
     const from = expectation.source === 'space' ? '  [space default]' : '';
-    // Only shown when the work exists and the evidence is short — stating the
-    // required authority on every row would be noise on the rows where it is
-    // already satisfied or not yet relevant.
-    const evidence = expectation.state === 'unverified'
-        ? `  (has ${expectation.evidenceAuthority}, needs ${expectation.requiredAuthority})`
-        : '';
-    return `  ${expectation.id.padEnd(18)} ${label.padEnd(14)} ${expectation.sentence}${evidence}${gate}${from}`;
+    /*
+     * `sentence` before `text`.
+     *
+     * The server resolves `sentence` through `describeExpectation`, which is what
+     * appends a preset's destination — so `@wiki-page-published:Engineering/Deploy`
+     * and the same preset at `Ops/Oncall` are distinguishable. Printing `text`
+     * rendered the preset's fixed copy and dropped the one part that says WHICH
+     * thing is owed. The fallback is for a row that predates the resolved field.
+     */
+    const sentence = expectation.sentence || expectation.text;
+    return `  ${expectation.id.padEnd(18)} ${label.padEnd(18)} ${sentence}${evidenceGap(expectation)}${from}`;
 }
 class TasksExpectations extends base_command_1.BaseCommand {
-    static description = 'Show what a task must produce and how far each expectation got ("Done when")';
+    static description = 'Show what must be true before the Task can close and the evidence-backed assessment state';
     static examples = [
         '<%= config.bin %> tasks expectations <task-id>',
         '<%= config.bin %> tasks expectations <task-id> --json',
@@ -68,7 +107,7 @@ class TasksExpectations extends base_command_1.BaseCommand {
         if (acceptance.expectations.length === 0) {
             // An empty contract is a real answer, not an unfilled field. Say so
             // plainly rather than prompting for something most tasks do not owe.
-            this.log('Nothing durable is expected of this task.');
+            this.log('No Expectations were declared for this Task.');
             return;
         }
         // The evidence read fails OPEN by design, so "produced nothing" and "we
@@ -78,20 +117,44 @@ class TasksExpectations extends base_command_1.BaseCommand {
             this.warn('Could not read what this task produced — the states below may understate it. ' +
                 'This is not a claim that nothing was produced.');
         }
-        this.log('Done when:');
+        this.log('Expectations:');
         for (const expectation of acceptance.expectations) {
             this.log(line(expectation));
         }
         const gating = acceptance.expectations.filter((e) => e.gating);
-        const met = gating.filter((e) => e.met).length;
+        // `met: true` is the GATE's answer — a waiver unblocks closure exactly as a
+        // pass does — but it is the wrong REPORT. Counting them together printed
+        // "2 of 2 met" for a Task where one expectation was dropped, which is the
+        // one thing a reader checking this line needs to know.
+        const waived = gating.filter((e) => e.state === 'waived').length;
+        const met = gating.filter((e) => e.met).length - waived;
         this.log('');
-        this.log(`${met} of ${gating.length} met  ·  overall: ${acceptance.state}`);
-        // Only the ones actually stored on the task can be judged. A space default
-        // is synthesised per read, so pointing at `tasks judge` for one would send
-        // the reader at a command that can only refuse it.
-        const settleable = acceptance.expectations.filter((e) => e.state === 'unjudged' && e.source !== 'space').length;
+        this.log(`${met} of ${gating.length} met${waived > 0 ? ` · ${waived} waived` : ''}  ·  overall: ${acceptance.state}`);
+        // Space defaults are copied into the Task at creation. `source=space`
+        // remains useful provenance, but these are Task-owned Expectations now and
+        // are assessed exactly like explicitly declared ones.
+        /*
+         * A typed check nothing evaluates behaves exactly like `manual`.
+         *
+         * `EXPECTATION_CHECK_METHODS` declares six methods and the judge evaluates
+         * one: a `deliverable` check is compared against the ledger, and
+         * `task_state`, `goal_state`, `metric` and `llm_review` return `unassessed`
+         * forever. Verified against production — a `metric` check naming measureId,
+         * operator and target stores fine and is never looked at. The row read
+         * identically to a hand-written sentence, so somebody who chose
+         * `metric: cycle_time lt 2` had no way to learn the platform was not
+         * measuring it (OSK-8488).
+         */
+        const unevaluated = acceptance.expectations.filter((e) => (0, data_provider_2.declaresUnevaluatedCheck)(e));
+        if (unevaluated.length > 0) {
+            const methods = [...new Set(unevaluated.map((e) => e.check?.method).filter(Boolean))].join(', ');
+            this.log(`${unevaluated.length} declare${unevaluated.length === 1 ? 's' : ''} a typed check nothing ` +
+                `evaluates yet (${methods}) — a person settles ${unevaluated.length === 1 ? 'it' : 'them'} ` +
+                'exactly as if the check said `manual`.');
+        }
+        const settleable = acceptance.expectations.filter((e) => e.state === 'unassessed').length;
         if (settleable > 0) {
-            this.log(`${settleable} awaiting a person — settle with \`${this.config.bin} tasks judge\`.`);
+            this.log(`${settleable} awaiting assessment — use \`${this.config.bin} tasks expectations assess\`.`);
         }
         // Named separately from `unjudged`, and with a different command, because
         // the two look alike on the board and are not: one needs a verdict on prose,
@@ -102,9 +165,42 @@ class TasksExpectations extends base_command_1.BaseCommand {
                 `\`${this.config.bin} tasks deliverable confirm\`, or lower the bar with ` +
                 `\`${this.config.bin} tasks trust\`.`);
         }
-        const inherited = acceptance.unjudged - settleable;
-        if (inherited > 0) {
-            this.log(`${inherited} inherited from the space default — declare them on the task to settle them.`);
+        // `underway` had no trailer at all, which is why pinning a deliverable read
+        // as no progress: the row said `on its way` and nothing named the lever.
+        // A Deliverable is recorded `local` by default, so this is the state the
+        // ORDINARY `tasks deliverable add` lands in — the common case, not an edge.
+        const underway = acceptance.expectations.filter((e) => e.state === 'underway').length;
+        if (underway > 0) {
+            this.log(`${underway} recorded but not yet observed as available — say it arrived with ` +
+                `\`${this.config.bin} tasks deliverable confirm\`, or re-record it with ` +
+                `\`--status available\`.`);
+        }
+        // Counted separately from the unmet ones: these no longer block anything, and
+        // the reader's question about them is not "what do I do" but "how good is this
+        // record". Saying it once beats repeating the rungs on every row.
+        const shortfalls = acceptance.expectations.filter((e) => e.evidenceShortfall).length;
+        if (shortfalls > 0) {
+            this.log(`${shortfalls} settled below the evidence ${shortfalls === 1 ? 'bar it' : 'bars they'} ` +
+                `declared — allowed, and recorded as such on the assessment.`);
+        }
+        // Said once, for the whole task: `external_receipt` is the one bar no CLI
+        // command can clear. The only receipt producer in the platform is PR
+        // integration, so an operator staring at a row that needs one would
+        // otherwise keep looking for the command that supplies it.
+        const receiptBarred = acceptance.expectations.filter((e) => !e.met && e.requiredEvidence === 'external_receipt').length;
+        if (receiptBarred > 0) {
+            this.log(`${receiptBarred} ask${receiptBarred === 1 ? 's' : ''} for an external provider receipt, ` +
+                `which only an integration can supply — settle by hand with ` +
+                `\`${this.config.bin} tasks expectations assess\` (the gap is recorded), or lower the ` +
+                `bar with \`${this.config.bin} tasks trust\`.`);
+        }
+        // Settled, not "met" — a waiver settles an Expectation as surely as a pass,
+        // and splitting the two in the count above must not make this trailer fire
+        // on a Task where nothing is actually outstanding.
+        const settled = gating.filter((e) => e.met).length;
+        if (gating.length > settled) {
+            this.log('');
+            this.log('The current Result cannot be accepted while these Expectations remain unmet.');
         }
     }
 }

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

@@ -14,6 +14,7 @@ import { BaseCommand } from '../../base-command';
  * expectation is that somebody actually looked.
  */
 export default class TasksJudge extends BaseCommand {
+    static hidden: boolean;
     static description: string;
     static examples: string[];
     static args: {

package/dist/commands/tasks/judge.js

@@ -18,7 +18,8 @@ const base_command_1 = require("../../base-command");
  * expectation is that somebody actually looked.
  */
 class TasksJudge extends base_command_1.BaseCommand {
-    static description = 'Settle a judged expectation with a verdict and a stated reason';
+    static hidden = true;
+    static description = 'Compatibility alias for `tasks expectations assess`';
     static examples = [
         '<%= config.bin %> tasks judge <task-id> e2 --verdict met --reason "Read it end to end; a non-engineer follows it."',
         '<%= config.bin %> tasks judge <task-id> e2 --verdict unmet --reason "Still assumes the reader knows the schema."',

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

@@ -1,16 +1,7 @@
 import { BaseCommand } from '../../base-command';
-/**
- * "What did the agent produce for this task?" in one call.
- *
- * Answering that used to mean three commands and a jq hop: `tasks comments list`
- * for the canonical TASK_OUTPUT block, `tasks runs` / `execution-summary` for
- * whether the run even finished, and `tasks show --json | jq .conversationId`
- * piped into `messages list` for the agent's actual words. This command joins
- * them and states plainly when a piece is missing.
- */
 export default class TasksOutput extends BaseCommand {
+    static hidden: boolean;
     static description: string;
-    static examples: string[];
     static args: {
         id: import("@oclif/core/lib/interfaces").Arg<string | undefined, Record<string, unknown>>;
     };
@@ -20,5 +11,4 @@ export default class TasksOutput extends BaseCommand {
         full: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
-    private renderHuman;
 }