humanish 0.106.1 → 0.108.0

package/dist/lab/tasks.d.ts

@@ -4,20 +4,20 @@ declare const TASK_FUNNEL_SCHEMA: "humanish.task-funnel.v1";
  * One task in a protocol. It has two halves that belong to two different people, and keeping them
  * apart is the point of the type.
  *
- * `goal` belongs to the PARTICIPANT. It is what they are asked to do, in their language, and it is
+ * `goal` belongs to the participant. It is what they are asked to do, in their language, and it is
  * the only half that reaches the prompt.
  *
- * `success` belongs to the RESEARCHER. It is how the task will be measured, and the participant
- * never sees it — a moderator does not read the success criterion aloud, because telling someone
+ * `success` belongs to the researcher. It is how the task will be measured, and the participant
+ * never sees it. A moderator does not read the success criterion aloud, because telling someone
  * how they will be judged changes what they do. A persona told "you succeed when the URL contains
  * /dashboard" will go find that URL, which measures the instruction rather than the product.
  */
 export interface LabTask {
     /** Stable id, used in evidence and in the funnel. Researcher-facing. */
     id: string;
-    /** PARTICIPANT-FACING. What they are asked to do. The only half that reaches the prompt. */
+    /** Participant-facing. What they are asked to do. The only half that reaches the prompt. */
     goal: string;
-    /** RESEARCHER-FACING. Observation-shaped proof the task happened. Never rendered to the
+    /** Researcher-facing. Observation-shaped proof the task happened. Never rendered to the
      *  participant. Absent means the task is narrative-only: it is asked for but cannot be measured,
      *  and the funnel says so rather than quietly counting it as failed. */
     success?: StopWhen;
@@ -38,12 +38,12 @@ export interface TaskFunnel {
     total: number;
     /** Tasks observed complete. */
     completed: number;
-    /** Declared tasks with no `done` criterion — shown to the participant, never observable. */
+    /** Declared tasks with no `done` criterion: shown to the participant, never observable. */
     unobservable: number;
-    /** The first task that was NOT observed complete: where this participant stopped. */
+    /** The first task that was not observed complete: where this participant stopped. */
     stoppedAt?: string;
     /** Per-task, in declaration order. `inputsObserved` is false when the task declares criteria
-     *  whose inputs (url, text, appState) NEVER arrived in any observation this session, so the
+     *  whose inputs (url, text, appState) never arrived in any observation this session, so the
      *  task was never actually measured. Absent when the task completed or is unobservable. */
     tasks: Array<{
         id: string;
@@ -53,20 +53,20 @@ export interface TaskFunnel {
         inputsObserved?: boolean;
     }>;
     /** Observable tasks that were never measured, because the inputs their criteria need never
-     *  arrived. Reported SEPARATELY from failures: a task nobody could observe is a gap in our
-     *  instrument, and reporting it as 0-completed blames the participant for it (#514). */
+     *  arrived. Reported separately from failures: a task nobody could observe is a gap in our
+     *  instrument, and reporting it as 0-completed blames the participant for it. */
     unmeasured: number;
 }
 /**
- * Tracks task completion across a session. Stateful on purpose: a task completes ONCE, on the first
- * observation that satisfies it, and stays complete even if the participant navigates away — you do
+ * Tracks task completion across a session. Stateful on purpose: a task completes once, on the first
+ * observation that satisfies it, and stays complete even if the participant navigates away; you do
  * not un-sign-up by going back to the home page.
  */
 export declare class TaskTracker {
     private readonly tasks;
     private readonly completions;
     /** Which observation fields were ever populated this session. A criterion whose field never
-     *  arrived was never evaluated against anything, however many turns ran (#514). */
+     *  arrived was never evaluated against anything, however many turns ran. */
     private readonly fieldsSeen;
     constructor(tasks: readonly LabTask[]);
     /** Evaluate every still-incomplete task against one observation. Returns newly completed tasks. */
@@ -78,10 +78,10 @@ export declare class TaskTracker {
     funnel(): TaskFunnel;
 }
 /**
- * The task list as the PARTICIPANT reads it: numbered, in order, in their own language.
+ * The task list as the participant reads it: numbered, in order, in their own language.
  *
  * Reads `goal` and nothing else. The success criteria are the researcher's instrument and never
- * appear here — a participant who is told how they will be measured optimizes for the measurement,
+ * appear here: a participant who is told how they will be measured optimizes for the measurement,
  * and the study stops being about the product. A test pins this, because it is the kind of leak a
  * later convenience change makes without noticing.
  */

package/dist/lab/tasks.js

@@ -1,32 +1,32 @@
 // Tasks: the researcher's protocol, expressed as config (docs/principles/three-roles.md).
 //
-// A lab could declare a prose `mission` and nothing else. That is a brief, not a protocol — and it
+// A lab could declare a prose `mission` and nothing else. That is a brief, not a protocol, and it
 // left "where did people get stuck" answerable only from an actor's own narration, which is the one
 // source a study should not have to take on faith.
 //
-// Real usability studies are built from discrete TASKS, each with a written success criterion, and
+// Real usability studies are built from discrete tasks, each with a written success criterion, and
 // the result is a funnel: how far each participant got before they stopped. That funnel is the
 // finding. A single pass/fail per participant throws it away.
 //
-// The criterion language is `stopWhen`, unchanged and already load-bearing elsewhere: a task is
+// The criterion language is `stopWhen`, unchanged and already used by stop conditions: a task is
 // done when an observation satisfies it. Reusing it means a task criterion is exactly as expressive
 // as a stop condition, and an author who knows one knows the other.
 //
-// A task's completion is CORROBORATED, not self-reported. The actor saying "I signed up" does not
+// A task's completion is corroborated, not self-reported. The actor saying "I signed up" does not
 // complete a task; the observed URL, page text, or app state does. That distinction is the whole
 // reason to declare tasks at all.
 import { evaluateStopWhen, } from "../actors/stop-conditions.js";
 const TASK_FUNNEL_SCHEMA = "humanish.task-funnel.v1";
 /**
- * Tracks task completion across a session. Stateful on purpose: a task completes ONCE, on the first
- * observation that satisfies it, and stays complete even if the participant navigates away — you do
+ * Tracks task completion across a session. Stateful on purpose: a task completes once, on the first
+ * observation that satisfies it, and stays complete even if the participant navigates away; you do
  * not un-sign-up by going back to the home page.
  */
 export class TaskTracker {
     tasks;
     completions = new Map();
     /** Which observation fields were ever populated this session. A criterion whose field never
-     *  arrived was never evaluated against anything, however many turns ran (#514). */
+     *  arrived was never evaluated against anything, however many turns ran. */
     fieldsSeen = new Set();
     constructor(tasks) {
         this.tasks = tasks;
@@ -77,7 +77,7 @@ export class TaskTracker {
         const tasks = this.tasks.map((task) => {
             const completion = this.completions.get(task.id);
             const observable = task.success !== undefined;
-            // A task counts as measured when at least ONE field its criteria read was populated by some
+            // A task counts as measured when at least one field its criteria read was populated by some
             // observation. `any` semantics: any satisfiable rule needed a field we actually saw.
             const required = observable ? this.fieldsRequiredBy(task) : [];
             const inputsObserved = required.length === 0 ? true : required.some((field) => this.fieldsSeen.has(field));
@@ -91,12 +91,12 @@ export class TaskTracker {
                 ...(observable && completion === undefined ? { inputsObserved } : {}),
             };
         });
-        // Where they stopped is the first task not observed complete — the thing a researcher reads
+        // Where they stopped is the first task not observed complete, the thing a researcher reads
         // first. An unobservable task cannot be "where they stopped", because nothing could have
         // proven otherwise; skipping it avoids blaming a participant for a gap in the protocol.
         // A task we never measured cannot be "where they stopped" either, for the same reason an
         // unobservable one cannot: nothing could have proven otherwise, so naming it blames the
-        // participant for our gap (#514).
+        // participant for our gap.
         const stoppedAt = tasks.find((task) => task.observable && !task.completed && task.inputsObserved !== false)?.id;
         return {
             schema: TASK_FUNNEL_SCHEMA,
@@ -110,10 +110,10 @@ export class TaskTracker {
     }
 }
 /**
- * The task list as the PARTICIPANT reads it: numbered, in order, in their own language.
+ * The task list as the participant reads it: numbered, in order, in their own language.
  *
  * Reads `goal` and nothing else. The success criteria are the researcher's instrument and never
- * appear here — a participant who is told how they will be measured optimizes for the measurement,
+ * appear here: a participant who is told how they will be measured optimizes for the measurement,
  * and the study stops being about the product. A test pins this, because it is the kind of leak a
  * later convenience change makes without noticing.
  */
@@ -131,9 +131,9 @@ export function formatTaskFunnel(funnel) {
     const stopped = funnel.stoppedAt === undefined ? "" : `, stopped at "${funnel.stoppedAt}"`;
     const unobservable = funnel.unobservable === 0 ? "" : `, ${funnel.unobservable} with no completion criterion`;
     // Named separately from failures. "0/3 completed" alone reads as "no participant managed it",
-    // which is the wrong story when the criterion was never evaluated against anything (#514).
+    // which is the wrong story when the criterion was never evaluated against anything.
     const unmeasured = funnel.unmeasured === 0
         ? ""
-        : `, ${funnel.unmeasured} NEVER MEASURED (the observations their criteria read never arrived)`;
+        : `, ${funnel.unmeasured} never measured (the observations their criteria read never arrived)`;
     return `${base}${stopped}${unobservable}${unmeasured}`;
 }