humanish 0.40.0 → 0.42.0

package/dist/tasks.js

@@ -0,0 +1,101 @@
+// 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
+// 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
+// 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
+// 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
+// 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 "./stop-conditions.js";
+export 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
+ * not un-sign-up by going back to the home page.
+ */
+export class TaskTracker {
+    tasks;
+    completions = new Map();
+    constructor(tasks) {
+        this.tasks = tasks;
+    }
+    /** Evaluate every still-incomplete task against one observation. Returns newly completed tasks. */
+    observe(observation, turn) {
+        const fresh = [];
+        for (const task of this.tasks) {
+            if (task.success === undefined || this.completions.has(task.id))
+                continue;
+            const match = evaluateStopWhen(task.success, observation);
+            if (!match)
+                continue;
+            const completion = {
+                id: task.id,
+                turn,
+                matchedRuleIndex: match.ruleIndex,
+                matchedKinds: match.kinds
+            };
+            this.completions.set(task.id, completion);
+            fresh.push(completion);
+        }
+        return fresh;
+    }
+    /** The funnel as it stands. */
+    funnel() {
+        const tasks = this.tasks.map((task) => {
+            const completion = this.completions.get(task.id);
+            return {
+                id: task.id,
+                completed: completion !== undefined,
+                observable: task.success !== undefined,
+                ...(completion === undefined ? {} : { turn: completion.turn })
+            };
+        });
+        // 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.
+        const stoppedAt = tasks.find((task) => task.observable && !task.completed)?.id;
+        return {
+            schema: TASK_FUNNEL_SCHEMA,
+            total: tasks.length,
+            completed: tasks.filter((task) => task.completed).length,
+            unobservable: tasks.filter((task) => !task.observable).length,
+            ...(stoppedAt === undefined ? {} : { stoppedAt }),
+            tasks
+        };
+    }
+}
+/**
+ * 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,
+ * 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.
+ */
+export function renderTaskPrompt(tasks) {
+    if (tasks.length === 0)
+        return undefined;
+    const lines = tasks.map((task, index) => `${index + 1}. ${task.goal}`);
+    return `Work through these in order:\n${lines.join("\n")}`;
+}
+/** One line a stakeholder can read, with the denominator attached. */
+export function formatTaskFunnel(funnel) {
+    if (funnel.total === 0)
+        return "no tasks declared";
+    const base = `${funnel.completed}/${funnel.total} tasks completed`;
+    const stopped = funnel.stoppedAt === undefined ? "" : `, stopped at "${funnel.stoppedAt}"`;
+    const unobservable = funnel.unobservable === 0
+        ? ""
+        : `, ${funnel.unobservable} with no completion criterion`;
+    return `${base}${stopped}${unobservable}`;
+}
+//# sourceMappingURL=tasks.js.map

package/dist/tasks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tasks.js","sourceRoot":"","sources":["../src/tasks.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,EAAE;AACF,mGAAmG;AACnG,oGAAoG;AACpG,mDAAmD;AACnD,EAAE;AACF,mGAAmG;AACnG,+FAA+F;AAC/F,8DAA8D;AAC9D,EAAE;AACF,gGAAgG;AAChG,oGAAoG;AACpG,oEAAoE;AACpE,EAAE;AACF,kGAAkG;AAClG,iGAAiG;AACjG,kCAAkC;AAElC,OAAO,EAAE,gBAAgB,EAAgD,MAAM,sBAAsB,CAAC;AAEtG,MAAM,CAAC,MAAM,kBAAkB,GAAG,yBAAkC,CAAC;AAkDrE;;;;GAIG;AACH,MAAM,OAAO,WAAW;IAGO;IAFZ,WAAW,GAAG,IAAI,GAAG,EAA0B,CAAC;IAEjE,YAA6B,KAAyB;QAAzB,UAAK,GAAL,KAAK,CAAoB;IAAG,CAAC;IAE1D,mGAAmG;IACnG,OAAO,CAAC,WAAqC,EAAE,IAAY;QACzD,MAAM,KAAK,GAAqB,EAAE,CAAC;QACnC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC9B,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAAE,SAAS;YAC1E,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;YAC1D,IAAI,CAAC,KAAK;gBAAE,SAAS;YACrB,MAAM,UAAU,GAAmB;gBACjC,EAAE,EAAE,IAAI,CAAC,EAAE;gBACX,IAAI;gBACJ,gBAAgB,EAAE,KAAK,CAAC,SAAS;gBACjC,YAAY,EAAE,KAAK,CAAC,KAAK;aAC1B,CAAC;YACF,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;YAC1C,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACzB,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,+BAA+B;IAC/B,MAAM;QACJ,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;YACpC,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACjD,OAAO;gBACL,EAAE,EAAE,IAAI,CAAC,EAAE;gBACX,SAAS,EAAE,UAAU,KAAK,SAAS;gBACnC,UAAU,EAAE,IAAI,CAAC,OAAO,KAAK,SAAS;gBACtC,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,CAAC;aAC/D,CAAC;QACJ,CAAC,CAAC,CAAC;QACH,4FAA4F;QAC5F,yFAAyF;QACzF,wFAAwF;QACxF,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC;QAC/E,OAAO;YACL,MAAM,EAAE,kBAAkB;YAC1B,KAAK,EAAE,KAAK,CAAC,MAAM;YACnB,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM;YACxD,YAAY,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM;YAC7D,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC;YACjD,KAAK;SACN,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAyB;IACxD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACzC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,GAAG,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACvE,OAAO,iCAAiC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AAC7D,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,gBAAgB,CAAC,MAAkB;IACjD,IAAI,MAAM,CAAC,KAAK,KAAK,CAAC;QAAE,OAAO,mBAAmB,CAAC;IACnD,MAAM,IAAI,GAAG,GAAG,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,KAAK,kBAAkB,CAAC;IACnE,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,iBAAiB,MAAM,CAAC,SAAS,GAAG,CAAC;IAC3F,MAAM,YAAY,GAAG,MAAM,CAAC,YAAY,KAAK,CAAC;QAC5C,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,KAAK,MAAM,CAAC,YAAY,+BAA+B,CAAC;IAC5D,OAAO,GAAG,IAAI,GAAG,OAAO,GAAG,YAAY,EAAE,CAAC;AAC5C,CAAC"}

package/docs/contracts/schemas.md

@@ -3,7 +3,7 @@
 Date: 2026-06-02 (current-state note updated 2026-07-14)
 
 Status: reference map for the major contracts shipped through source version
-`0.40.0`; it is not an exhaustive inventory of command/result envelopes. Exported types,
+`0.42.0`; it is not an exhaustive inventory of command/result envelopes. Exported types,
 schema constants, parsers, and validators in `src/` are authoritative. Rows
 marked "reserved" name layering intent only — no code emits or validates them
 yet. Do not emit a reserved schema.

package/docs/goals/current.md

@@ -1,6 +1,6 @@
 # Current Goals
 
-Status date: 2026-08-05 (rev 17)
+Status date: 2026-08-11 (rev 18)
 
 This page is the current public-safe operating goal for `humanish`. Keep it
 short enough to reread before a coding session and concrete enough that future
@@ -16,7 +16,20 @@ Humanish should be the open-source CLI that lets a maintainer ask:
 The answer should be observable, verifiable, public-safe, and easy to turn into
 actionable feedback.
 
-## Current Program Truth (source `0.40.0`)
+What humanish runs is synthetic user research, and every surface is checked
+against the three people a study involves — researcher, stakeholder,
+participant ([docs/principles/three-roles.md](../principles/three-roles.md)).
+The operational consequences: a study declares `tasks` with success criteria
+the participant never sees and gets a per-task completion funnel back; budgets
+are study-level recruiting decisions (`execution.caps.maxTotalUsd`) with
+per-lane caps as backstops; sessions end because the participant finished, not
+because a timer fired; abandonment and reported friction are findings that
+become feedback candidates, not failures. Receipts: the email-gated signup
+study completed, reproduced, and produced a real accessibility finding via a
+keyboard-first participant
+([docs/goals/email-gated-signup/receipts/](email-gated-signup/receipts/)).
+
+## Current Program Truth (source `0.42.0`)
 
 The package source and repository implementation in this tree agree on these
 points:
@@ -33,7 +46,7 @@ The immutable 2026-06-10 proof-roadmap packet is paired with a
 | Public proof | A legible four-persona Observer hero from a verified real public-application study (commit-pinned drawDB) shipped in the npm payload (`0.16.0`) | Coverage beyond a single studied subject; the stratified breadth panel remains unbuilt |
 | OSS meta-lab | Dry-run contract and separate disposable smoke harness | Live meta-lab execution; disabled until repository instructions and actor credentials have an isolated boundary |
 | Observer serving | `watch`/`observe` loopback servers plus `serve` — the run-library surface with loopback default, capability-link exposure, `share_ready`-gated open mode, and optional operator-run tunnel; streams never served remotely | A remote live-stream (`--live-streams`) design; a persistent capability-link store; a control plane that can start runs |
-| Off-app comms | Vendor-neutral in-sandbox email/SMS catch, a minimal persona inbox surface, and digest-only `humanish.comms-thread.v1` evidence; wired into the computer-use and shared-world routes over both HTTP and SMTP; live-proven end to end on 2026-08-08 — a persona signed up for a public app, read the emailed link in its inbox, and reached the signed-in product (`docs/goals/email-gated-signup/receipts/signup-verify-live-2026-08-08.md`) | An adopter-hosted / app-url ingress plane; real-provider delivery |
+| Off-app comms | Vendor-neutral in-sandbox email/SMS catch, a minimal persona inbox surface, and digest-only `humanish.comms-thread.v1` evidence; wired into the computer-use and shared-world routes over both HTTP and SMTP; live-proven end to end on 2026-08-08 — a persona signed up for a public app, read the emailed link in its inbox, and reached the signed-in product (`docs/goals/email-gated-signup/receipts/signup-verify-live-2026-08-08.md`); the adopter-hosted / app-url ingress plane is wired on the CUA and concurrent external-public routes (#387/#380, 2026-08-11) | Real-provider delivery; a live adopter-hosted receipt |
 
 Capability proof and adopter replacement are different gates. A deterministic
 test or kept live receipt proves that a Humanish mechanism works. The depth-axis

package/docs/ramp/README.md

@@ -2,7 +2,7 @@
 
 Status: public-safe contributor and agent ramp.
 
-Package/source version in this tree: `0.40.0` (2026-08-08). The containment boundary introduced in
+Package/source version in this tree: `0.42.0` (2026-08-11). The containment boundary introduced in
 `0.15.1` remains in force: managed run and output paths bind to validated
 physical filesystem identities, and stored provider IDs are evidence, not
 cleanup authority. The bundled OSS meta-lab is dry-run only until

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.40.0",
+  "version": "0.42.0",
   "description": "Open-source-safe CLI for persona simulation, observer review, and public-safe feedback drafts.",
   "author": "Daniel G Wilson <daniel@danielgwilson.com>",
   "keywords": [