humanish 0.39.0 → 0.41.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":"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"}

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.39.0`; it is not an exhaustive inventory of command/result envelopes. Exported types,
+`0.41.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

@@ -16,7 +16,7 @@ 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.39.0`)
+## Current Program Truth (source `0.41.0`)
 
 The package source and repository implementation in this tree agree on these
 points:
@@ -33,7 +33,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 and live-proven on computer-use | 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`) | An adopter-hosted / app-url ingress plane; real-provider delivery |
 
 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/principles/three-roles.md

@@ -0,0 +1,68 @@
+# Three roles: researcher, stakeholder, participant
+
+Humanish runs user research. Every design decision should be checked against the
+three people a study actually involves, because they want different things and
+conflating any two of them produces a specific, recurring class of bug.
+
+## The roles
+
+**The researcher** designs the study and runs it. In humanish this is usually an
+agent invoking the CLI, not a person clicking. A researcher wants a protocol they
+can express and defend: tasks with success criteria, a panel with declared
+coverage, a pilot before the panel spends, and structured per-task outcomes back.
+They care about rigor and control, and they need output they can reason over and
+adjust.
+
+**The stakeholder** watches. In a real study they sit behind the glass in the
+viewing room; here they open Observer, `watch`, or `serve`. They want none of the
+protocol. They want to know what happened, where people got stuck, how bad it is,
+and whether anyone succeeded — moments, severity, and the denominator.
+
+**The participant** is the persona. They have a goal, limited patience, and their
+own idea of how the product works. They are the subject of the study, never its
+instrument.
+
+## Why the distinction earns its place
+
+Two of humanish's worst bugs were category errors between these roles, not
+missing features.
+
+**Fusing the participant into the harness** made abandonment look like a
+malfunction. `gave_up` mapped to a `failed` status, so a persona giving up — the
+single most valuable thing a usability study produces — dragged the run verdict
+red as though the instrument had broken. A participant abandoning a task is a
+finding. The harness only fails when the harness fails.
+
+**Fusing the researcher's question with the stakeholder's** put one pass/fail
+verdict on a bundle that answers two different questions. "Is this evidence
+trustworthy?" is genuinely pass/fail: did the harness do what it claimed, with a
+real sandbox, real actions, and cost lines nobody forged. "What did we learn?" has
+no pass/fail at all — asking whether a study passed is a category error. Because
+there was one slot, a session that stopped early had to be called `passed`, and a
+truncated study was reported as a green one.
+
+## Checks worth applying
+
+When adding a surface, a default, or a verdict, ask:
+
+- **Which role is this for?** A knob that serves the researcher does not belong in
+  the stakeholder's view, and a highlight reel is not evidence.
+- **Is this a participant outcome or a harness outcome?** Abandonment, confusion,
+  and running out of session are things that happened to a participant. Only a
+  broken sandbox, a forged artifact, or an unreachable service is a harness
+  failure.
+- **Does the number travel with its denominator?** A stakeholder behind glass
+  forms conclusions from vivid moments; that is the classic failure of the viewing
+  room, and it is why researchers synthesize rather than letting the room decide.
+  Anything shown to a stakeholder carries its count and its confidence, or it
+  becomes a machine for manufacturing certainty from n=1.
+- **Would a researcher recognize this as a study?** Budgets are recruiting
+  decisions made once, up front — how many participants can we afford. No
+  researcher has ever ended a session because it got expensive.
+
+## Related
+
+- [invariants-and-defaults.md](invariants-and-defaults.md) — fail-closed rules and
+  what defaults are allowed to assume
+- [actor-fidelity.md](actor-fidelity.md) — what a claim about persona realism can
+  and cannot mean

package/docs/ramp/README.md

@@ -2,7 +2,7 @@
 
 Status: public-safe contributor and agent ramp.
 
-Package/source version in this tree: `0.39.0` (2026-08-08). The containment boundary introduced in
+Package/source version in this tree: `0.41.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.39.0",
+  "version": "0.41.0",
   "description": "Open-source-safe CLI for persona simulation, observer review, and public-safe feedback drafts.",
   "author": "Daniel G Wilson <daniel@danielgwilson.com>",
   "keywords": [