@workser/cli 0.6.1 → 0.6.2

package/dist/index.js

@@ -4485,6 +4485,76 @@ same rule.
 - **Cloud and local are different environments.** \`env set\` configures the
   cloud; the files in the app folder configure this computer. Don't hand-edit
   one to change the other.
+`
+  },
+  {
+    topic: "goals",
+    title: "Business goals & phases",
+    summary: "The level above a task \u2014 a business requirement too big for one sitting, and the ordered phases that deliver it.",
+    commands: ["goal"],
+    source: "skills/workser/reference/goals.md",
+    body: `# Business goals & phases
+
+A **goal** is a business requirement \u2014 "customers can buy from my site" \u2014 that
+does not fit in one task. It carries an ordered list of **phase names**; a task
+joins one by carrying that name (\`workser task create --goal <id> --phase <name>\`).
+A phase has no existence apart from the tasks inside it, so it cannot drift from
+the work it names.
+
+\`\`\`
+workser goal list
+workser goal show <id>
+workser goal create <title> --phase <name...> [--outcome <text>]
+                            [--criteria <json>]
+workser goal update <id> [--title <text>] [--outcome <text>]
+                         [--phase <name...>] [--status <value>]
+workser goal check <id> <criterionId> --phase <name> (--pass|--fail|--reset) [--note <text>]
+\`\`\`
+
+Status is one of: proposed, agreed, working, delivered, abandoned.
+
+## A goal has to be argued for
+
+Most requests are one task and should stay one task. Turning a two-hour job into
+four milestones buries the owner in ceremony before anything is built \u2014 use
+\`workser task create\` unless you can genuinely name two-plus slices that each
+deliver something the owner would notice.
+
+\`\`\`
+workser goal create "Launch checkout" \\
+  --phase "Cart" --phase "Payment" --phase "Receipts" \\
+  --outcome "A customer can buy something and get a receipt"
+\`\`\`
+
+\`--phase\` needs 2\u20136 names. Propose the shape only \u2014 nothing is created until the
+owner agrees it; planning phase four now is waste, since it will change once
+phase one is real.
+
+## Acceptance criteria are agreed with the shape
+
+\`--criteria\` maps each phase name to the owner's own sentences about what "done"
+means for it, e.g. \`'{"Payment":["A customer can pay by card and gets a receipt"]}'\`.
+Written afterwards they only describe what got built; written with the shape they
+can still change the plan.
+
+Record whether one is met with \`workser goal check\`:
+
+\`\`\`
+workser goal check g_123 c1 --phase Payment --pass \\
+  --note "Tested a card payment end to end; receipt emailed."
+\`\`\`
+
+\`--note\` is required on \`--pass\` \u2014 a tick the owner cannot verify is worse than no
+tick.
+
+## Joining tasks to a goal
+
+\`\`\`
+workser task create "Build the payment form" --goal g_123 --phase Payment
+\`\`\`
+
+A goal's apps and progress are derived from the tasks that join it, not declared
+up front \u2014 most of the apps a goal will touch don't exist when it's proposed.
 `
   },
   {
@@ -7858,7 +7928,22 @@ var TYPES = [
   "approval",
   "confirmation",
   "file_upload",
-  "information"
+  "information",
+  /**
+   * "Add an app to this project, and do it for me."
+   *
+   * NOT an approval with a well-worded message. What the user is agreeing to
+   * is real infrastructure — a repository, hosting, a folder on their machine,
+   * sometimes a database — and they are entitled to see WHICH app before they
+   * agree, which a sentence and a Yes button cannot show. Needs `--app-type`;
+   * `--app-name` is what it will be called.
+   *
+   * You cannot create an app yourself, and that is deliberate: an agent must
+   * not be able to provision things on somebody's account by deciding to. This
+   * asks. Their click is what creates it, and the answer tells you the new
+   * app's id so the rest of your plan can be scoped to it.
+   */
+  "create_app"
 ];
 function registerAsk(program3) {
   program3.command("ask <message>").description("Ask the user a question and wait for their answer").option(
@@ -7870,6 +7955,12 @@ function registerAsk(program3) {
     "a choice (repeat for each; implies --type choice)",
     collect,
     []
+  ).option(
+    "--app-type <type>",
+    "create_app only: web | mobile | api | worker | cron | python"
+  ).option(
+    "--app-name <name>",
+    "create_app only: what the app should be called"
   ).option("--priority <level>", "low | normal | high | urgent", "normal").option(
     "--timeout <seconds>",
     "how long to wait before giving up (default: 600, max: 3600)",
@@ -7896,6 +7987,12 @@ function registerAsk(program3) {
           { code: "bad_request" }
         );
       }
+      if (type === "create_app" && !opts.appType) {
+        throw new WorkserError(
+          "Say which kind of app: `--app-type mobile`.",
+          { code: "bad_request" }
+        );
+      }
       const timeoutSeconds = Number(opts.timeout);
       if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0) {
         throw new WorkserError("--timeout must be a positive number.", {
@@ -7909,6 +8006,8 @@ function registerAsk(program3) {
           title: opts.title || deriveTitle(message),
           message,
           options: options.length ? options : void 0,
+          appType: opts.appType,
+          appName: opts.appName,
           priority: opts.priority,
           timeoutSeconds
         }
@@ -8203,10 +8302,18 @@ function registerTask(program3) {
     action(async ({ ctx, args }) => {
       const id = args[0] || ctx.parentTaskId || resolveTaskId(ctx);
       const row = await api(ctx, `/v1/project-tasks/${encodeURIComponent(id)}`);
-      ok(row, () => printTask(row));
+      const goalId = row.goal_id;
+      const goal = goalId ? await api(
+        ctx,
+        `/v1/project-goals/${encodeURIComponent(goalId)}`
+      ).catch(() => null) : null;
+      ok({ ...row, goal }, () => printTask(row, goal));
     })
   );
-  task.command("create <title>").description("Open a new root task for the project team").option("--note <text>", "context, constraints and expected outcome").option("--kind <value>", `what it produces (${KINDS2.join(" | ")})`).option("--label <value...>", "labels to put on the task").option("--app <id...>", "apps the task touches").option("--infra <ref...>", "shared setup it touches").action(
+  task.command("create <title>").description("Open a new root task for the project team").option("--note <text>", "context, constraints and expected outcome").option("--kind <value>", `what it produces (${KINDS2.join(" | ")})`).option("--label <value...>", "labels to put on the task").option("--app <id...>", "apps the task touches").option("--infra <ref...>", "shared setup it touches").option("--goal <id>", "the business goal this delivers part of").option(
+    "--phase <name>",
+    "which slice of that goal \u2014 must match one of its phase names"
+  ).action(
     action(async ({ ctx, args, opts }) => {
       requireProject(ctx);
       if (opts.kind !== void 0) assertOneOf("--kind", opts.kind, KINDS2);
@@ -8219,6 +8326,10 @@ function registerTask(program3) {
           summary: opts.note,
           category: opts.kind,
           labels: opts.label,
+          // The level above this task, when it has one. Most tasks do not —
+          // a goal has to be argued for, never assumed.
+          goalId: opts.goal,
+          phase: opts.phase,
           targets: [
             ...(opts.app ?? []).map((appId) => ({ kind: "app", appId })),
             ...(opts.infra ?? []).map((ref) => ({ kind: "infra", ref }))
@@ -8271,13 +8382,13 @@ function registerTask(program3) {
       });
     })
   );
-  const subtask = task.command("subtask").description("The steps a task is broken into");
+  const subtask = task.command("subtask").description("The subtasks a task is broken into");
   subtask.command("add <title>").description(
-    'Add one step, e.g. `workser task subtask add "Build the upload screen" --role web`'
-  ).option("--task <id>", "the parent task (defaults to the task this run is inside)").option("--role <value>", `who does it (${ROLES.join(" | ")})`).option("--kind <value>", `what it produces (${KINDS2.join(" | ")})`).option("--note <text>", "one sentence on what this step does").option(
+    'Add one subtask, e.g. `workser task subtask add "Build the upload screen" --role web`'
+  ).option("--task <id>", "the parent task (defaults to the task this run is inside)").option("--role <value>", `who does it (${ROLES.join(" | ")})`).option("--kind <value>", `what it produces (${KINDS2.join(" | ")})`).option("--note <text>", "one sentence on what this subtask does").option(
     "--app <id...>",
-    "the app this step is for \u2014 one id runs the step inside that app's folder; leave it off and the step runs at the project, seeing every app"
-  ).option("--infra <ref...>", "shared setup it touches (database | storage | auth | hosting | jobs)").option("--scope <path...>", "files or folders THIS step owns").option("--depends-on <id...>", "steps that must finish first (key or id)").action(
+    "the app this subtask is for \u2014 one id runs it inside that app's folder; leave it off and it runs at the project, seeing every app"
+  ).option("--infra <ref...>", "shared setup it touches (database | storage | auth | hosting | jobs)").option("--scope <path...>", "files or folders THIS subtask owns").option("--depends-on <id...>", "subtasks that must finish first (key or id)").action(
     action(async ({ ctx, args, opts }) => {
       const parent = resolveTaskId(ctx, opts.task);
       if (opts.role !== void 0) assertOneOf("--role", opts.role, ROLES);
@@ -8304,21 +8415,21 @@ function registerTask(program3) {
       });
     })
   );
-  subtask.command("list [taskId]").description("The steps of a task, in order").action(
+  subtask.command("list [taskId]").description("The subtasks of a task, in order").action(
     action(async ({ ctx, args }) => {
       const id = resolveTaskId(ctx, args[0]);
       const row = await api(ctx, `/v1/project-tasks/${encodeURIComponent(id)}`);
       const rows = row.subtasks ?? [];
       ok(rows, () => {
         if (!rows.length) {
-          line(import_picocolors28.default.dim("No steps yet."));
+          line(import_picocolors28.default.dim("No subtasks yet."));
           return;
         }
         rows.forEach((r, i) => line(formatSubtask(r, i + 1)));
       });
     })
   );
-  subtask.command("update <id>").description("Change a step \u2014 its title, its role, what it touches").option("--title <text>").option("--note <text>").option("--role <value>", ROLES.join(" | ")).option("--kind <value>", KINDS2.join(" | ")).option("--scope <path...>", "replaces the step's scope entirely").action(
+  subtask.command("update <id>").description("Change a subtask \u2014 its title, its role, what it touches").option("--title <text>").option("--note <text>").option("--role <value>", ROLES.join(" | ")).option("--kind <value>", KINDS2.join(" | ")).option("--scope <path...>", "replaces the subtask's scope entirely").action(
     action(async ({ ctx, args, opts }) => {
       if (opts.role !== void 0) assertOneOf("--role", opts.role, ROLES);
       if (opts.kind !== void 0) assertOneOf("--kind", opts.kind, KINDS2);
@@ -8339,7 +8450,7 @@ function registerTask(program3) {
       ok(row, () => line(`${import_picocolors28.default.green("updated")} ${import_picocolors28.default.bold(row.title)}`));
     })
   );
-  subtask.command("remove <id>").description("Drop a step from the plan (only before the work starts)").action(
+  subtask.command("remove <id>").description("Remove a subtask (only before the work starts)").action(
     action(async ({ ctx, args }) => {
       await api(ctx, `/v1/project-tasks/${encodeURIComponent(args[0])}`, {
         method: "DELETE"
@@ -8359,7 +8470,7 @@ function registerTask(program3) {
     })
   );
   task.command("resume [id]").description(
-    "Put a step the owner stopped back in the queue \u2014 only when they ask you to carry on"
+    "Put a task the owner stopped back in the queue \u2014 only when they ask you to carry on"
   ).action(
     action(async ({ ctx, args }) => {
       const id = resolveTaskId(ctx, args[0]);
@@ -8442,7 +8553,7 @@ function registerTask(program3) {
       ok(row, () => line(`${import_picocolors28.default.green(row.approval_state)} ${import_picocolors28.default.bold(row.title)}`));
     })
   );
-  task.command("done [id]").description("Record what a step produced, and move it to ready").option("--summary <text>", "what changed, in the owner's words").action(
+  task.command("done [id]").description("Record what a subtask produced, and move it to ready").option("--summary <text>", "what changed, in the owner's words").action(
     action(async ({ ctx, args, opts }) => {
       const id = resolveTaskId(ctx, args[0]);
       await api(ctx, `/v1/project-tasks/${encodeURIComponent(id)}`, {
@@ -8483,7 +8594,7 @@ async function resolveDeps(ctx, parentId, given) {
     const id = byKey.get(g);
     if (!id) {
       throw new WorkserError(
-        `"${g}" is not a step of this task. Run \`workser task subtask list\` to see them.`,
+        `"${g}" is not a subtask of this task. Run \`workser task subtask list\` to see them.`,
         { code: "bad_request" }
       );
     }
@@ -8515,11 +8626,12 @@ function formatSubtask(r, index) {
   return `${head}
 ${import_picocolors28.default.dim(wrapped)}`;
 }
-function printTask(row) {
+function printTask(row, goal) {
   line(`${import_picocolors28.default.bold(row.title)}  ${import_picocolors28.default.dim(row.key ?? row.id)}`);
   line(`${statusTag2(row.status)}  approval: ${row.approval_state}`);
   if (row.summary) line(`
 ${row.summary}`);
+  if (goal) printGoalContext(row, goal);
   if (row.targets?.length) {
     line(
       `
@@ -8528,23 +8640,53 @@ touches: ${row.targets.map((t) => t.appName ?? t.ref ?? t.kind).join(", ")}`
   }
   if (row.subtasks?.length) {
     line(`
-${import_picocolors28.default.bold("steps")}`);
+${import_picocolors28.default.bold("subtasks")}`);
     row.subtasks.forEach((s, i) => line(formatSubtask(s, i + 1)));
     line(
       import_picocolors28.default.dim(
         `
-Run \`workser artifact list\` to see what these steps produced,`
+Run \`workser artifact list\` to see what these subtasks produced,`
       )
     );
     line(
       import_picocolors28.default.dim(
-        `or \`workser artifact list --step <id>\` for one step's output alone.`
+        `or \`workser artifact list --step <id>\` for one subtask's output alone.`
       )
     );
   } else {
-    line(import_picocolors28.default.dim("\nNo steps yet."));
+    line(import_picocolors28.default.dim("\nNo subtasks yet."));
   }
 }
+function printGoalContext(row, goal) {
+  const mine = row.phase ?? null;
+  line(`
+${import_picocolors28.default.bold("part of")}: ${goal.title}`);
+  if (goal.outcome) line(import_picocolors28.default.dim(`done means: ${goal.outcome}`));
+  const progress = goal.progress ?? [];
+  for (const p of progress) {
+    const where = p.total === 0 ? "not started" : `${p.done} of ${p.total} done`;
+    const here = mine && p.name === mine ? import_picocolors28.default.cyan("  <- this task") : "";
+    const mark = p.state === "done" ? import_picocolors28.default.green("*") : import_picocolors28.default.dim("-");
+    line(`  ${mark} ${p.name} \u2014 ${where}${here}`);
+  }
+  const next = progress.find((p) => p.state !== "done");
+  const running = progress.some((p) => p.state === "working");
+  if (next && !running) {
+    line(
+      import_picocolors28.default.dim(
+        `
+Nothing is running. The next part waiting is "${next.name}" \u2014 offer it to them in a sentence rather than starting it unasked.`
+      )
+    );
+  } else if (!next) {
+    line(import_picocolors28.default.dim("\nEvery part of this plan is done. Say so, and offer to wrap it up."));
+  }
+  line(
+    import_picocolors28.default.dim(
+      "The plan is a reference for what was agreed, not a rule about what may run. Work can start on any part at any time if they ask for it."
+    )
+  );
+}
 function statusTag2(status) {
   switch (status) {
     case "ready":
@@ -8562,6 +8704,219 @@ function statusTag2(status) {
   }
 }
 
+// src/commands/goal.ts
+var import_picocolors29 = __toESM(require_picocolors(), 1);
+var STATUSES3 = ["proposed", "agreed", "working", "delivered", "abandoned"];
+function registerGoal(program3) {
+  const goal = program3.command("goal").description("Business goals and the phases that deliver them");
+  goal.command("list").description("What this project is working towards").action(
+    action(async ({ ctx }) => {
+      requireProject(ctx);
+      const rows = await api(ctx, "/v1/project-goals", {
+        query: { projectId: ctx.projectId }
+      }) ?? [];
+      ok(rows, () => {
+        if (!rows.length) {
+          line(import_picocolors29.default.dim("No goals yet \u2014 every task here stands on its own."));
+          return;
+        }
+        for (const g of rows) line(formatGoal(g));
+      });
+    })
+  );
+  goal.command("show <id>").description("One goal: its phases, and how far each has got").action(
+    action(async ({ ctx, args }) => {
+      const row = await api(
+        ctx,
+        `/v1/project-goals/${encodeURIComponent(String(args[0]))}`
+      );
+      ok(row, () => printGoal(row));
+    })
+  );
+  goal.command("create <title>").description(
+    "Propose a business goal and the phases that deliver it \u2014 the owner agrees the shape before any task exists"
+  ).option(
+    "--outcome <text>",
+    "what 'done' means for the whole thing, in the owner's words"
+  ).option(
+    "--phase <name...>",
+    "ordered phase names \u2014 each must deliver something the owner would notice"
+  ).option(
+    "--criteria <json>",
+    `what "done" means per phase, in the OWNER's words: '{"Checkout":["A customer can pay by card and gets a receipt"]}'`
+  ).action(
+    action(async ({ ctx, args, opts }) => {
+      requireProject(ctx);
+      const phases = opts.phase ?? [];
+      if (phases.length < 2) {
+        throw new WorkserError(
+          "A goal needs at least two phases. If you can't name two slices that each deliver something the owner would notice, this is one task \u2014 use `workser task create`."
+        );
+      }
+      if (phases.length > 6) {
+        throw new WorkserError(
+          "More than six phases is a conversation, not a plan. Propose the first few and agree the rest as you go."
+        );
+      }
+      let criteria = {};
+      if (opts.criteria) {
+        try {
+          criteria = JSON.parse(opts.criteria);
+        } catch {
+          throw new WorkserError(
+            `--criteria must be JSON mapping each phase name to a list of sentences, e.g. '{"Checkout":["A customer can pay by card"]}'`
+          );
+        }
+        const unknown = Object.keys(criteria).filter(
+          (name) => !phases.includes(name)
+        );
+        if (unknown.length) {
+          throw new WorkserError(
+            `--criteria names phases that aren't in this goal: ${unknown.join(", ")}. Phases are: ${phases.join(", ")}.`
+          );
+        }
+      }
+      const row = await api(ctx, "/v1/project-goals", {
+        body: {
+          projectId: ctx.projectId,
+          title: args[0],
+          outcome: opts.outcome,
+          phases: phases.map((name) => ({
+            name,
+            criteria: (criteria[name] ?? []).map((text, i) => ({
+              id: `c${i + 1}`,
+              text,
+              met: null
+            }))
+          })),
+          channelId: ctx.projectChannelId,
+          sourceMessageId: ctx.projectChannelMessageId
+        }
+      });
+      ok(row, () => {
+        success(`Proposed ${import_picocolors29.default.bold(row?.title ?? "goal")}`);
+        printGoal(row);
+        line(
+          import_picocolors29.default.dim(
+            "\nNothing has been created yet. The owner agrees the shape first."
+          )
+        );
+      });
+    })
+  );
+  goal.command("check <id> <criterionId>").description("Record whether an acceptance criterion is met").requiredOption("--phase <name>", "which part of the plan it belongs to").option("--pass", "it is met").option("--fail", "it is not met").option("--reset", "back to unchecked").option("--note <text>", "what you checked, and how").action(
+    action(async ({ ctx, args, opts }) => {
+      const chosen = [opts.pass, opts.fail, opts.reset].filter(Boolean);
+      if (chosen.length !== 1) {
+        throw new WorkserError(
+          "Pass exactly one of --pass, --fail or --reset."
+        );
+      }
+      if (opts.pass && !opts.note) {
+        throw new WorkserError(
+          "--note is required on a pass: say what you checked. A tick the owner cannot verify is worse than no tick."
+        );
+      }
+      const met = opts.pass ? true : opts.fail ? false : null;
+      const row = await api(
+        ctx,
+        `/v1/project-goals/${encodeURIComponent(String(args[0]))}/criteria/${encodeURIComponent(String(args[1]))}`,
+        { method: "POST", body: { phase: opts.phase, met, note: opts.note } }
+      );
+      ok(
+        row,
+        () => line(
+          row?.recorded ? met === true ? import_picocolors29.default.green("recorded \u2014 met") : met === false ? import_picocolors29.default.yellow("recorded \u2014 not met") : import_picocolors29.default.dim("recorded \u2014 back to unchecked") : import_picocolors29.default.yellow(
+            "couldn't record it \u2014 check the goal id, the phase name and the criterion id"
+          )
+        )
+      );
+    })
+  );
+  goal.command("update <id>").description("Change the shape, or move the goal along").option("--title <text>", "the owner's words for what they want").option("--outcome <text>", "what 'done' means").option("--phase <name...>", "replace the ordered phase list").option("--status <value>", `one of: ${STATUSES3.join(" | ")}`).action(
+    action(async ({ ctx, args, opts }) => {
+      if (opts.status && !STATUSES3.includes(opts.status)) {
+        throw new WorkserError(
+          `Unknown status "${opts.status}". Use one of: ${STATUSES3.join(", ")}.`
+        );
+      }
+      const row = await api(
+        ctx,
+        `/v1/project-goals/${encodeURIComponent(String(args[0]))}`,
+        {
+          method: "PATCH",
+          body: {
+            title: opts.title,
+            outcome: opts.outcome,
+            phases: opts.phase,
+            status: opts.status
+          }
+        }
+      );
+      ok(row, () => printGoal(row));
+    })
+  );
+}
+function appScope(g) {
+  const n = g.appIds?.length ?? 0;
+  if (!n) return "";
+  return import_picocolors29.default.dim(`  ${n} part${n === 1 ? "" : "s"} of the system`);
+}
+function formatGoal(g) {
+  const where = g.currentPhase && g.status !== "delivered" ? import_picocolors29.default.dim(`  now: ${g.currentPhase}`) : "";
+  const count = g.taskTotal != null ? import_picocolors29.default.dim(`  ${g.taskDone}/${g.taskTotal} done`) : "";
+  return `${statusTag3(g.status)} ${g.title}${appScope(g)}${where}${count}  ${import_picocolors29.default.dim(g.id)}`;
+}
+function printGoal(g) {
+  if (!g) return;
+  line(`${import_picocolors29.default.bold(g.title)}  ${import_picocolors29.default.dim(g.id)}`);
+  line(statusTag3(g.status));
+  if (g.outcome) line(`
+done means: ${g.outcome}`);
+  const progress = g.progress ?? [];
+  if (!progress.length) {
+    line(import_picocolors29.default.dim("\nNo phases agreed yet."));
+    return;
+  }
+  line(`
+${import_picocolors29.default.bold("phases")}`);
+  for (const p of progress) {
+    const bar2 = p.total > 0 ? `${p.done}/${p.total} done` : import_picocolors29.default.dim("nothing filed yet");
+    const mark = p.state === "done" ? import_picocolors29.default.green("done") : p.state === "working" ? import_picocolors29.default.blue("working") : import_picocolors29.default.dim("waiting");
+    line(
+      `  ${import_picocolors29.default.dim(String(p.index).padStart(2, "0"))} ${p.name}  ${mark}  ${import_picocolors29.default.dim(bar2)}`
+    );
+    for (const c of p.criteria ?? []) {
+      const tick = c.met === true ? import_picocolors29.default.green("\u2713") : c.met === false ? import_picocolors29.default.red("\u2717") : import_picocolors29.default.dim("\xB7");
+      line(`       ${tick} ${c.text}  ${import_picocolors29.default.dim(c.id)}`);
+      if (c.note) line(import_picocolors29.default.dim(`         ${c.note}`));
+    }
+  }
+  const current = progress.find((p) => p.name === g.currentPhase);
+  if (current) {
+    line(
+      import_picocolors29.default.dim(
+        `
+${current.name} \u2014 ${current.done} of ${current.total} done (phase ${current.index} of ${progress.length}).`
+      )
+    );
+  }
+}
+function statusTag3(status) {
+  switch (status) {
+    case "agreed":
+      return import_picocolors29.default.cyan("[agreed]");
+    case "working":
+      return import_picocolors29.default.blue("[working]");
+    case "delivered":
+      return import_picocolors29.default.green("[delivered]");
+    case "abandoned":
+      return import_picocolors29.default.dim("[abandoned]");
+    default:
+      return import_picocolors29.default.yellow("[proposed]");
+  }
+}
+
 // src/role-guard.ts
 var READS = [
   // `requirement` sits beside `doc` and `decision` because it is the same kind
@@ -8599,7 +8954,19 @@ var READS = [
   // Reading the plan and what is used against it. An agent proposing "add
   // another project" can only sensibly propose it if it can find out the plan
   // allows two and two already exist.
-  "usage"
+  "usage",
+  // RECORDING WHAT YOU PRODUCED IS NOT CHANGING THE PROJECT.
+  // Every dispatched role is told, in its own preamble, to run `workser
+  // artifact list` before non-trivial work and `workser artifact add` when it
+  // finishes something the owner should get. Five roles — pm, qa, security,
+  // analyst, sre — were then refused the verb here, so the instruction and the
+  // guard contradicted each other: the agent kept trying to obey an order this
+  // file would not let it obey, and burned its run doing it. It belongs beside
+  // `doc`, `decision` and `board`, which are already in this list and also
+  // have `create` subcommands — these write the project's RECORD, not the
+  // project. What stops a reviewer editing code is its filesystem mode, and
+  // that is untouched.
+  "artifact"
 ];
 var BUILDS = [
   ...READS,
@@ -8608,7 +8975,6 @@ var BUILDS = [
   "db",
   "storage",
   "checkpoint",
-  "artifact",
   "image",
   "design",
   "ask",
@@ -8644,6 +9010,33 @@ var NEVER = {
   // proposed has removed the only gate this product has.
   "task approval": "Only the owner can approve a plan."
 };
+var READ_PAIRS = /* @__PURE__ */ new Set([
+  // The project's own brand and design notes.
+  "design show",
+  // What exists, and what it is wired to.
+  "app list",
+  "app tools",
+  // Shape, never contents-by-arbitrary-SQL.
+  "db list",
+  "db tables",
+  "db schema",
+  // What is stored, not what is in it.
+  "storage list",
+  "storage ls",
+  "checkpoint list",
+  "workflow list",
+  "workflow get",
+  "workflow runs",
+  "workflow nodes",
+  "tool list",
+  // The business data an analyst exists to read.
+  "business resources",
+  "business list",
+  "business get",
+  // The database service's own inventory.
+  "neon status",
+  "neon list"
+]);
 function assertRoleMayRun(argv) {
   const role = (process.env.WORKSER_ROLE ?? "").trim();
   if (!role) return;
@@ -8654,6 +9047,7 @@ function assertRoleMayRun(argv) {
   if (NEVER[pair] && !(pair === "task approval" && (commandArgv[2] === "request" || !commandArgv[2]))) {
     throw new WorkserError(NEVER[pair], { code: "role_forbidden" });
   }
+  if (READ_PAIRS.has(pair)) return;
   const allowed = ROLE_VERBS[role];
   const list = allowed ?? READS;
   if (!list.includes(verb)) {
@@ -8694,7 +9088,7 @@ function stripLeadingGlobalOptions(argv) {
 }
 
 // src/commands/decision.ts
-var import_picocolors29 = __toESM(require_picocolors(), 1);
+var import_picocolors30 = __toESM(require_picocolors(), 1);
 function registerDecision(program3) {
   const decision = program3.command("decision").description("Read and record the project's architecture decisions");
   decision.command("list").description("Every decision on record \u2014 read this before changing how something works").option("--limit <n>", "cap the number returned (newest first)").action(
@@ -8707,11 +9101,11 @@ function registerDecision(program3) {
       rows = applyLimit(rows, opts.limit);
       ok(rows, () => {
         if (!rows.length) {
-          line(import_picocolors29.default.dim("No decisions recorded yet."));
+          line(import_picocolors30.default.dim("No decisions recorded yet."));
           return;
         }
         for (const r of rows) {
-          line(`${import_picocolors29.default.dim(r.id)}  ${import_picocolors29.default.dim(shortDate(r.createdAt))}  ${r.title}`);
+          line(`${import_picocolors30.default.dim(r.id)}  ${import_picocolors30.default.dim(shortDate(r.createdAt))}  ${r.title}`);
           line(`    ${truncate(r.decision, 100)}`);
         }
       });
@@ -8725,16 +9119,16 @@ function registerDecision(program3) {
         `/v1/projects/${projectId}/architecture-decisions/${args[0]}`
       );
       ok(row, () => {
-        line(`${import_picocolors29.default.bold(row.title)}  ${import_picocolors29.default.dim(row.id)}`);
-        line(import_picocolors29.default.dim(`${row.status} \xB7 ${shortDate(row.createdAt)}`));
+        line(`${import_picocolors30.default.bold(row.title)}  ${import_picocolors30.default.dim(row.id)}`);
+        line(import_picocolors30.default.dim(`${row.status} \xB7 ${shortDate(row.createdAt)}`));
         line(`
-${import_picocolors29.default.bold("Context")}
+${import_picocolors30.default.bold("Context")}
 ${row.context}`);
         line(`
-${import_picocolors29.default.bold("Decision")}
+${import_picocolors30.default.bold("Decision")}
 ${row.decision}`);
         if (row.consequences) line(`
-${import_picocolors29.default.bold("Consequences")}
+${import_picocolors30.default.bold("Consequences")}
 ${row.consequences}`);
       });
     })
@@ -8763,7 +9157,7 @@ ${row.consequences}`);
         refId: row?.id,
         output: { decision: row }
       });
-      ok(row, () => line(`Recorded decision ${import_picocolors29.default.bold(row?.id ?? "")} \u2014 ${title}`));
+      ok(row, () => line(`Recorded decision ${import_picocolors30.default.bold(row?.id ?? "")} \u2014 ${title}`));
     })
   );
   const requirement = program3.command("requirement").description("Read and record the project's requirements");
@@ -8775,11 +9169,11 @@ ${row.consequences}`);
       rows = applyLimit(rows, opts.limit);
       ok(rows, () => {
         if (!rows.length) {
-          line(import_picocolors29.default.dim("No requirements recorded yet."));
+          line(import_picocolors30.default.dim("No requirements recorded yet."));
           return;
         }
         for (const r of rows) {
-          line(`${import_picocolors29.default.dim(r.id)}  ${r.status.padEnd(9)}  ${r.title}`);
+          line(`${import_picocolors30.default.dim(r.id)}  ${r.status.padEnd(9)}  ${r.title}`);
         }
       });
     })
@@ -8792,8 +9186,8 @@ ${row.consequences}`);
         `/v1/projects/${projectId}/requirements/${args[0]}`
       );
       ok(row, () => {
-        line(`${import_picocolors29.default.bold(row.title)}  ${import_picocolors29.default.dim(row.id)}`);
-        line(import_picocolors29.default.dim(`${row.status} \xB7 ${shortDate(row.createdAt)}`));
+        line(`${import_picocolors30.default.bold(row.title)}  ${import_picocolors30.default.dim(row.id)}`);
+        line(import_picocolors30.default.dim(`${row.status} \xB7 ${shortDate(row.createdAt)}`));
         line(`
 ${row.body}`);
       });
@@ -8819,7 +9213,7 @@ ${row.body}`);
         refId: row?.id,
         output: { requirement: row }
       });
-      ok(row, () => line(`Recorded requirement ${import_picocolors29.default.bold(row?.id ?? "")} \u2014 ${title}`));
+      ok(row, () => line(`Recorded requirement ${import_picocolors30.default.bold(row?.id ?? "")} \u2014 ${title}`));
     })
   );
   requirement.command("update <id>").description(
@@ -8848,7 +9242,7 @@ ${row.body}`);
           code: "bad_request"
         });
       }
-      ok(row, () => line(`Updated requirement ${import_picocolors29.default.bold(row.id)} \u2014 ${row.title} (${row.status})`));
+      ok(row, () => line(`Updated requirement ${import_picocolors30.default.bold(row.id)} \u2014 ${row.title} (${row.status})`));
     })
   );
 }
@@ -8871,7 +9265,7 @@ function shortDate(iso) {
 }
 
 // src/commands/doc.ts
-var import_picocolors30 = __toESM(require_picocolors(), 1);
+var import_picocolors31 = __toESM(require_picocolors(), 1);
 
 // src/mermaid-fences.ts
 function hasDiagram(code) {
@@ -8916,13 +9310,13 @@ function registerDoc(program3) {
       }) ?? [];
       ok(rows, () => {
         if (!rows.length) {
-          line(import_picocolors30.default.dim("No documents yet."));
+          line(import_picocolors31.default.dim("No documents yet."));
           return;
         }
         for (const r of rows) {
-          const link = r.workItemId ? import_picocolors30.default.dim(` \u21B3 ${r.workItemId}`) : "";
-          const file = r.filePath ? import_picocolors30.default.dim(`  ${r.filePath}`) : "";
-          line(`${import_picocolors30.default.dim(r.id)}  ${r.title}${link}${file}`);
+          const link = r.workItemId ? import_picocolors31.default.dim(` \u21B3 ${r.workItemId}`) : "";
+          const file = r.filePath ? import_picocolors31.default.dim(`  ${r.filePath}`) : "";
+          line(`${import_picocolors31.default.dim(r.id)}  ${r.title}${link}${file}`);
         }
       });
     })
@@ -8936,17 +9330,17 @@ function registerDoc(program3) {
       );
       if (opts.markdown) {
         ok({ id: row.id, title: row.title, filePath: row.filePath }, () => {
-          line(`${import_picocolors30.default.bold(row.title)}  ${import_picocolors30.default.dim(row.id)}`);
+          line(`${import_picocolors31.default.bold(row.title)}  ${import_picocolors31.default.dim(row.id)}`);
           line(
-            row.filePath ? `Read it at ${import_picocolors30.default.bold(row.filePath)} (relative to the project folder).` : import_picocolors30.default.dim("This document has no markdown mirror on disk yet.")
+            row.filePath ? `Read it at ${import_picocolors31.default.bold(row.filePath)} (relative to the project folder).` : import_picocolors31.default.dim("This document has no markdown mirror on disk yet.")
           );
         });
         return;
       }
       ok(row, () => {
-        line(`${import_picocolors30.default.bold(row.title)}  ${import_picocolors30.default.dim(row.id)}`);
-        if (row.workItemId) line(import_picocolors30.default.dim(`linked to work item ${row.workItemId}`));
-        if (row.filePath) line(import_picocolors30.default.dim(`markdown mirror: ${row.filePath}`));
+        line(`${import_picocolors31.default.bold(row.title)}  ${import_picocolors31.default.dim(row.id)}`);
+        if (row.workItemId) line(import_picocolors31.default.dim(`linked to work item ${row.workItemId}`));
+        if (row.filePath) line(import_picocolors31.default.dim(`markdown mirror: ${row.filePath}`));
         line("");
         line(row.contentJson);
       });
@@ -8975,7 +9369,7 @@ function registerDoc(program3) {
         refId: row?.id,
         output: { document: row }
       });
-      ok(row, () => line(`Created document ${import_picocolors30.default.bold(row?.id ?? "")} \u2014 ${title}`));
+      ok(row, () => line(`Created document ${import_picocolors31.default.bold(row?.id ?? "")} \u2014 ${title}`));
     })
   );
   doc.command("diagram <id>").description(
@@ -9001,19 +9395,19 @@ function registerDoc(program3) {
         diagrams: diagrams.map((code) => ({ kind: diagramKind(code), code }))
       };
       ok(payload, () => {
-        line(`${import_picocolors30.default.bold(row.title)}  ${import_picocolors30.default.dim(row.id)}`);
+        line(`${import_picocolors31.default.bold(row.title)}  ${import_picocolors31.default.dim(row.id)}`);
         if (markdown === null) {
           line(
-            import_picocolors30.default.dim(
+            import_picocolors31.default.dim(
               row.filePath ? `Could not read ${row.filePath} from this folder.` : "This document has no markdown mirror on disk yet."
             )
           );
         } else if (!diagrams.length) {
-          line(import_picocolors30.default.dim("No diagrams in this document."));
+          line(import_picocolors31.default.dim("No diagrams in this document."));
         } else {
           for (const [i, code] of diagrams.entries()) {
             const kind = diagramKind(code) ?? "diagram";
-            line(`${import_picocolors30.default.dim(String(i + 1))}  ${kind}  ${import_picocolors30.default.dim(`${code.split("\n").length} lines`)}`);
+            line(`${import_picocolors31.default.dim(String(i + 1))}  ${kind}  ${import_picocolors31.default.dim(`${code.split("\n").length} lines`)}`);
           }
         }
       });
@@ -9049,7 +9443,7 @@ function registerDoc(program3) {
           code: "bad_request"
         });
       }
-      ok(row, () => line(`Updated document ${import_picocolors30.default.bold(row.id)} \u2014 ${row.title}`));
+      ok(row, () => line(`Updated document ${import_picocolors31.default.bold(row.id)} \u2014 ${row.title}`));
     })
   );
 }
@@ -9063,7 +9457,7 @@ function readMirror(cwd, filePath) {
 }
 
 // src/commands/design.ts
-var import_picocolors31 = __toESM(require_picocolors(), 1);
+var import_picocolors32 = __toESM(require_picocolors(), 1);
 function registerDesign(program3) {
   const design = program3.command("design").description("Read the project's brand (colours, fonts, logo)");
   design.command("show").description("Show this project's brand \u2014 read it before writing any UI").option("--raw", "print the generated token files verbatim instead of a summary").action(
@@ -9077,11 +9471,11 @@ function registerDesign(program3) {
       if (opts.raw) {
         ok(files, () => {
           if (!files.length) {
-            line(import_picocolors31.default.dim("No brand set for this project."));
+            line(import_picocolors32.default.dim("No brand set for this project."));
             return;
           }
           for (const f of files) {
-            line(import_picocolors31.default.bold(f.path));
+            line(import_picocolors32.default.bold(f.path));
             line(f.contents);
             line("");
           }
@@ -9098,21 +9492,21 @@ function registerDesign(program3) {
       } : { hasBrand: false, colors: {}, fonts: {}, brand: {}, files: [] };
       ok(summary, () => {
         if (!tokens) {
-          line(import_picocolors31.default.dim("No brand set for this project \u2014 choose sensible styling yourself."));
+          line(import_picocolors32.default.dim("No brand set for this project \u2014 choose sensible styling yourself."));
           return;
         }
         for (const [name, value] of Object.entries(tokens.brand)) {
-          line(`${import_picocolors31.default.dim(name.padEnd(12))} ${value}`);
+          line(`${import_picocolors32.default.dim(name.padEnd(12))} ${value}`);
         }
         for (const [name, value] of Object.entries(tokens.color)) {
-          line(`${import_picocolors31.default.dim(`color.${name}`.padEnd(12))} ${value}`);
+          line(`${import_picocolors32.default.dim(`color.${name}`.padEnd(12))} ${value}`);
         }
         for (const [name, value] of Object.entries(tokens.font)) {
-          line(`${import_picocolors31.default.dim(`font.${name}`.padEnd(12))} ${value}`);
+          line(`${import_picocolors32.default.dim(`font.${name}`.padEnd(12))} ${value}`);
         }
         line("");
         line(
-          import_picocolors31.default.dim(
+          import_picocolors32.default.dim(
             `Generated into the working tree as ${files.map((f) => f.path).join(", ")} \u2014 wire those in, never edit them.`
           )
         );
@@ -9143,7 +9537,7 @@ function unwrap(group) {
 }
 
 // src/commands/api.ts
-var import_picocolors32 = __toESM(require_picocolors(), 1);
+var import_picocolors33 = __toESM(require_picocolors(), 1);
 import { readdirSync, readFileSync as readFileSync3, statSync as statSync2 } from "fs";
 import { join as join3, relative, sep } from "path";
 
@@ -9257,10 +9651,10 @@ function registerApi(program3) {
       const appId = requireApp(opts.app);
       const res = await api(ctx, `/v1/apps/${encodeURIComponent(appId)}/api/requests`);
       ok(res, () => {
-        for (const note of res?.notes ?? []) line(import_picocolors32.default.dim(note));
+        for (const note of res?.notes ?? []) line(import_picocolors33.default.dim(note));
         for (const r of res?.requests ?? []) {
           line(
-            `${import_picocolors32.default.dim(r.method.padEnd(6))}${r.path}${r.note ? import_picocolors32.default.dim(`  ${r.note}`) : ""}`
+            `${import_picocolors33.default.dim(r.method.padEnd(6))}${r.path}${r.note ? import_picocolors33.default.dim(`  ${r.note}`) : ""}`
           );
         }
       });
@@ -9294,14 +9688,14 @@ function registerApi(program3) {
       );
       ok(res, () => {
         if (!res?.ok) {
-          line(import_picocolors32.default.red(res?.error ?? "The service did not answer."));
+          line(import_picocolors33.default.red(res?.error ?? "The service did not answer."));
           return;
         }
         const code = `${res.status}${res.statusText ? ` ${res.statusText}` : ""}`;
-        const colour2 = res.status && res.status < 300 ? import_picocolors32.default.green : res.status && res.status < 500 ? import_picocolors32.default.yellow : import_picocolors32.default.red;
-        line(`${colour2(code)}  ${import_picocolors32.default.dim(`${res.durationMs}ms  ${res.url}`)}`);
+        const colour2 = res.status && res.status < 300 ? import_picocolors33.default.green : res.status && res.status < 500 ? import_picocolors33.default.yellow : import_picocolors33.default.red;
+        line(`${colour2(code)}  ${import_picocolors33.default.dim(`${res.durationMs}ms  ${res.url}`)}`);
         if (res.body) line(res.body);
-        if (res.truncated) line(import_picocolors32.default.dim("(answer truncated)"));
+        if (res.truncated) line(import_picocolors33.default.dim("(answer truncated)"));
       });
       if (!res?.ok) process.exitCode = 1;
     })
@@ -9321,15 +9715,15 @@ function registerApi(program3) {
         for (const r of report.routes) {
           const known = report.missing.some((m) => m.path === r.path);
           line(
-            `${known ? import_picocolors32.default.yellow("undocumented") : import_picocolors32.default.green("documented  ")}  ${r.path}${import_picocolors32.default.dim(`  ${r.file}`)}`
+            `${known ? import_picocolors33.default.yellow("undocumented") : import_picocolors33.default.green("documented  ")}  ${r.path}${import_picocolors33.default.dim(`  ${r.file}`)}`
           );
         }
         for (const p of report.stale) {
-          line(`${import_picocolors32.default.dim("in spec only ")}  ${p}`);
+          line(`${import_picocolors33.default.dim("in spec only ")}  ${p}`);
         }
         line("");
         if (report.ok && specFile) success(summary);
-        else line(import_picocolors32.default.yellow(summary));
+        else line(import_picocolors33.default.yellow(summary));
       });
       if (opts.check && !report.ok) {
         throw new WorkserError(summary, { code: "bad_request" });
@@ -9400,7 +9794,7 @@ function listRepoFiles(root, maxDepth = 8) {
 }
 
 // src/commands/analysis.ts
-var import_picocolors33 = __toESM(require_picocolors(), 1);
+var import_picocolors34 = __toESM(require_picocolors(), 1);
 import { readFileSync as readFileSync4 } from "fs";
 function registerAnalysis(program3) {
   const cmd = program3.command("analysis").description("Run Python analysis locally, recorded in the task");
@@ -9410,14 +9804,14 @@ function registerAnalysis(program3) {
       const res = await api(ctx, path);
       ok(res, () => {
         line(
-          `${res?.available ? import_picocolors33.default.green("python") : import_picocolors33.default.red("python")}  ${res?.version ?? "not found"}  ${import_picocolors33.default.dim(res?.python ?? "")}`
+          `${res?.available ? import_picocolors34.default.green("python") : import_picocolors34.default.red("python")}  ${res?.version ?? "not found"}  ${import_picocolors34.default.dim(res?.python ?? "")}`
         );
         for (const lib of res?.libraries ?? []) {
           line(
-            `${lib.present ? import_picocolors33.default.green(lib.name) : import_picocolors33.default.yellow(lib.name)}${import_picocolors33.default.dim(lib.present ? "" : "  missing")}`
+            `${lib.present ? import_picocolors34.default.green(lib.name) : import_picocolors34.default.yellow(lib.name)}${import_picocolors34.default.dim(lib.present ? "" : "  missing")}`
           );
         }
-        for (const note of res?.notes ?? []) line(import_picocolors33.default.dim(note));
+        for (const note of res?.notes ?? []) line(import_picocolors34.default.dim(note));
       });
       if (!res?.available) process.exitCode = 1;
     })
@@ -9439,15 +9833,15 @@ function registerAnalysis(program3) {
       );
       ok(res, () => {
         if (res?.stdout) line(res.stdout.replace(/\n$/, ""));
-        if (res?.stderr) line(import_picocolors33.default.dim(res.stderr.replace(/\n$/, "")));
-        if (res?.truncated) line(import_picocolors33.default.dim("(output truncated)"));
+        if (res?.stderr) line(import_picocolors34.default.dim(res.stderr.replace(/\n$/, "")));
+        if (res?.truncated) line(import_picocolors34.default.dim("(output truncated)"));
         const took = `${Math.round((res?.durationMs ?? 0) / 100) / 10}s`;
         line(
-          res?.ok ? import_picocolors33.default.green(`\u2713 ${res.summary ?? "It finished."}`) + import_picocolors33.default.dim(`  ${took}`) : import_picocolors33.default.yellow(res?.summary ?? "It did not finish.") + import_picocolors33.default.dim(`  ${took}`)
+          res?.ok ? import_picocolors34.default.green(`\u2713 ${res.summary ?? "It finished."}`) + import_picocolors34.default.dim(`  ${took}`) : import_picocolors34.default.yellow(res?.summary ?? "It did not finish.") + import_picocolors34.default.dim(`  ${took}`)
         );
         if (res && !res.sandboxed) {
           line(
-            import_picocolors33.default.dim(
+            import_picocolors34.default.dim(
               "This platform has no OS sandbox, so the script ran with your own file access."
             )
           );
@@ -9475,7 +9869,7 @@ function readCode(file, inline) {
 }
 
 // src/commands/scan.ts
-var import_picocolors34 = __toESM(require_picocolors(), 1);
+var import_picocolors35 = __toESM(require_picocolors(), 1);
 import { spawnSync as spawnSync2 } from "child_process";
 import { existsSync as existsSync3, readFileSync as readFileSync5, readdirSync as readdirSync2, statSync as statSync3 } from "fs";
 import { join as join4, relative as relative2, sep as sep2 } from "path";
@@ -9759,22 +10153,22 @@ function runPermissions(cwd, findings, checked, skipped) {
 }
 function print2(report, summary) {
   for (const s of report.skipped) {
-    line(`${import_picocolors34.default.yellow("not checked")}  ${s.check}${import_picocolors34.default.dim(` \u2014 ${s.reason}`)}`);
+    line(`${import_picocolors35.default.yellow("not checked")}  ${s.check}${import_picocolors35.default.dim(` \u2014 ${s.reason}`)}`);
   }
   for (const f of report.findings) {
-    const where = f.file ? import_picocolors34.default.dim(`  ${f.file}${f.line ? `:${f.line}` : ""}`) : "";
+    const where = f.file ? import_picocolors35.default.dim(`  ${f.file}${f.line ? `:${f.line}` : ""}`) : "";
     line(`${severityTag(f.severity)}  ${f.title}${where}`);
-    line(`             ${import_picocolors34.default.dim(f.fix)}`);
+    line(`             ${import_picocolors35.default.dim(f.fix)}`);
   }
   if (report.findings.length || report.skipped.length) line("");
   if (report.ok && !report.skipped.length) success(summary);
-  else if (report.ok) line(import_picocolors34.default.yellow(summary));
-  else line(import_picocolors34.default.red(summary));
+  else if (report.ok) line(import_picocolors35.default.yellow(summary));
+  else line(import_picocolors35.default.red(summary));
 }
 function severityTag(severity) {
-  if (severity === "high") return import_picocolors34.default.red("serious    ");
-  if (severity === "medium") return import_picocolors34.default.yellow("worth fixing");
-  return import_picocolors34.default.dim("minor      ");
+  if (severity === "high") return import_picocolors35.default.red("serious    ");
+  if (severity === "medium") return import_picocolors35.default.yellow("worth fixing");
+  return import_picocolors35.default.dim("minor      ");
 }
 function git(cwd, args) {
   try {
@@ -9835,7 +10229,7 @@ function listRepoFiles2(root, maxDepth = 8) {
 }
 
 // src/commands/health.ts
-var import_picocolors35 = __toESM(require_picocolors(), 1);
+var import_picocolors36 = __toESM(require_picocolors(), 1);
 function registerHealth(program3) {
   program3.command("health").description("Check that the published apps in this project are still answering").option("--app <webAppId>", "check one app rather than all of them").action(
     action(async ({ ctx, opts }) => {
@@ -9849,16 +10243,16 @@ function registerHealth(program3) {
 }
 function print3(res) {
   if (!res?.checks?.length) {
-    line(import_picocolors35.default.dim(res?.note ?? "Nothing to check."));
+    line(import_picocolors36.default.dim(res?.note ?? "Nothing to check."));
     return;
   }
   for (const c of res.checks) {
-    const mark = c.ok ? import_picocolors35.default.green("up  ") : import_picocolors35.default.red("down");
-    const timing = import_picocolors35.default.dim(`${c.ms}ms`);
-    const detail = c.ok ? timing : import_picocolors35.default.dim(`${c.error ?? "no answer"}${c.failures > 1 ? ` \xB7 ${c.failures} in a row` : ""}`);
-    line(`  ${mark}  ${c.appName} ${import_picocolors35.default.dim(`(${c.environment})`)}  ${c.url}  ${detail}`);
+    const mark = c.ok ? import_picocolors36.default.green("up  ") : import_picocolors36.default.red("down");
+    const timing = import_picocolors36.default.dim(`${c.ms}ms`);
+    const detail = c.ok ? timing : import_picocolors36.default.dim(`${c.error ?? "no answer"}${c.failures > 1 ? ` \xB7 ${c.failures} in a row` : ""}`);
+    line(`  ${mark}  ${c.appName} ${import_picocolors36.default.dim(`(${c.environment})`)}  ${c.url}  ${detail}`);
     if (c.incidentOpened) {
-      line(import_picocolors35.default.yellow(`        An incident has been opened on the board for this.`));
+      line(import_picocolors36.default.yellow(`        An incident has been opened on the board for this.`));
     }
   }
   const down = res.checks.filter((c) => !c.ok);
@@ -9871,14 +10265,14 @@ function print3(res) {
   }
   const production = down.filter((c) => c.environment === "production").length;
   line(
-    import_picocolors35.default.red(
+    import_picocolors36.default.red(
       `${down.length} of ${res.checks.length} not answering` + (production ? ` \u2014 ${production} customer-facing.` : " (preview only).")
     )
   );
 }
 
 // src/commands/urls.ts
-var import_picocolors36 = __toESM(require_picocolors(), 1);
+var import_picocolors37 = __toESM(require_picocolors(), 1);
 function registerUrls(program3) {
   program3.command("urls").description("The stable preview and production addresses of every app in this project").option("--app <webAppId>", "just one app").action(
     action(async ({ ctx, opts }) => {
@@ -9892,20 +10286,20 @@ function registerUrls(program3) {
       const summary = urlsSummary(rows);
       ok({ rows, summary }, () => {
         for (const row of rows) {
-          const label = import_picocolors36.default.dim(row.environment.padEnd(10));
-          const value = row.url ? import_picocolors36.default.cyan(row.url) : import_picocolors36.default.dim(row.note ?? "not published");
+          const label = import_picocolors37.default.dim(row.environment.padEnd(10));
+          const value = row.url ? import_picocolors37.default.cyan(row.url) : import_picocolors37.default.dim(row.note ?? "not published");
           line(`  ${row.appName.padEnd(22)} ${label} ${value}`);
         }
         line("");
         if (rows.some((r) => r.url)) success(summary);
-        else line(import_picocolors36.default.yellow(summary));
+        else line(import_picocolors37.default.yellow(summary));
       });
     })
   );
 }
 
 // src/commands/deployments.ts
-var import_picocolors37 = __toESM(require_picocolors(), 1);
+var import_picocolors38 = __toESM(require_picocolors(), 1);
 function registerDeployments(program3) {
   const cmd = program3.command("deployments").description("Deployment history, and putting a build in front of customers");
   cmd.command("list").description("What has been built, newest first").option("--app <webAppId>", "just one app (default: every app in the project)").option("--env <environment>", "preview or production").option("--limit <n>", "how many to show", "20").action(
@@ -9923,7 +10317,7 @@ function registerDeployments(program3) {
       ok(res, () => {
         if (!items.length) {
           return line(
-            import_picocolors37.default.dim(
+            import_picocolors38.default.dim(
               environment ? `Nothing has been deployed to ${environment} yet.` : "Nothing has been deployed yet. `workser deploy` builds the first one."
             )
           );
@@ -9943,13 +10337,13 @@ function registerDeployments(program3) {
       ).catch(() => null) : null;
       ok({ ...dep, logs }, () => {
         line(formatDeployment(dep));
-        if (dep?.error_message) line(import_picocolors37.default.red(`  ${dep.error_message}`));
+        if (dep?.error_message) line(import_picocolors38.default.red(`  ${dep.error_message}`));
         const events = logs?.events ?? [];
         for (const e of events) {
-          line(`  ${import_picocolors37.default.dim(String(e.type ?? "log"))}  ${e.text ?? ""}`);
+          line(`  ${import_picocolors38.default.dim(String(e.type ?? "log"))}  ${e.text ?? ""}`);
         }
         if (opts.logs && !events.length) {
-          line(import_picocolors37.default.dim("  That build produced no output."));
+          line(import_picocolors38.default.dim("  That build produced no output."));
         }
       });
     })
@@ -9993,16 +10387,16 @@ function printPromoted(res, version) {
   const what = version === null ? "the latest build" : `version ${version}`;
   const url = res.url ?? res.vercel_url;
   success(`Production is being rebuilt from ${what}.`);
-  if (url) line(import_picocolors37.default.dim(`It will be at ${url}`));
-  line(import_picocolors37.default.dim("`workser deploy status` follows it."));
+  if (url) line(import_picocolors38.default.dim(`It will be at ${url}`));
+  line(import_picocolors38.default.dim("`workser deploy status` follows it."));
 }
 function formatDeployment(d) {
   if (!d) return "";
-  const version = d.version !== void 0 ? import_picocolors37.default.yellow(`v${d.version}`) : import_picocolors37.default.dim("v?");
-  const env = import_picocolors37.default.dim((d.environment ?? "?").padEnd(10));
+  const version = d.version !== void 0 ? import_picocolors38.default.yellow(`v${d.version}`) : import_picocolors38.default.dim("v?");
+  const env = import_picocolors38.default.dim((d.environment ?? "?").padEnd(10));
   const app = d.webAppName ? `${d.webAppName}  ` : "";
-  const when = import_picocolors37.default.dim(formatTime2(d.created_at));
-  const url = d.url ? "  " + import_picocolors37.default.cyan(d.url) : "";
+  const when = import_picocolors38.default.dim(formatTime2(d.created_at));
+  const url = d.url ? "  " + import_picocolors38.default.cyan(d.url) : "";
   return `${version}  ${env} ${colorStatus(d.status ?? "")}  ${app}${when}${url}`;
 }
 function formatTime2(t) {
@@ -10012,7 +10406,7 @@ function formatTime2(t) {
 }
 
 // src/commands/usage.ts
-var import_picocolors38 = __toESM(require_picocolors(), 1);
+var import_picocolors39 = __toESM(require_picocolors(), 1);
 
 // src/usage.ts
 var NEAR_LIMIT_FRACTION = 0.8;
@@ -10107,7 +10501,7 @@ function registerUsage(program3) {
 function print4(report) {
   const dims = report.dimensions ?? [];
   if (!dims.length) {
-    return line(import_picocolors38.default.dim("Nothing to measure for this project yet."));
+    return line(import_picocolors39.default.dim("Nothing to measure for this project yet."));
   }
   const width = Math.max(...dims.map((d) => d.label.length));
   for (const d of dims) {
@@ -10116,23 +10510,23 @@ function print4(report) {
   line("");
   const summary = usageSummary(report);
   const worst = dims.map(usageState);
-  if (worst.includes("over")) line(import_picocolors38.default.red(summary));
+  if (worst.includes("over")) line(import_picocolors39.default.red(summary));
   else if (worst.includes("near") || worst.includes("unknown"))
-    line(import_picocolors38.default.yellow(summary));
+    line(import_picocolors39.default.yellow(summary));
   else success(summary);
 }
 function gauge(d, _labelWidth) {
   const drawn = bar(d);
-  return drawn ? `  ${import_picocolors38.default.dim(drawn)}` : "";
+  return drawn ? `  ${import_picocolors39.default.dim(drawn)}` : "";
 }
 function colour(d) {
   switch (usageState(d)) {
     case "over":
-      return d.kind === "hard" ? import_picocolors38.default.red : import_picocolors38.default.yellow;
+      return d.kind === "hard" ? import_picocolors39.default.red : import_picocolors39.default.yellow;
     case "near":
-      return import_picocolors38.default.yellow;
+      return import_picocolors39.default.yellow;
     case "unknown":
-      return import_picocolors38.default.dim;
+      return import_picocolors39.default.dim;
     default:
       return (s) => s;
   }
@@ -10140,7 +10534,7 @@ function colour(d) {
 
 // src/index.ts
 var pkg = {
-  version: true ? "0.6.1" : "0.0.0-dev"
+  version: true ? "0.6.2" : "0.0.0-dev"
 };
 var program2 = new Command();
 program2.name("workser").description(
@@ -10193,6 +10587,7 @@ registerAsk(program2);
 registerSearch(program2);
 registerBoard(program2);
 registerTask(program2);
+registerGoal(program2);
 registerDecision(program2);
 registerDoc(program2);
 registerDesign(program2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workser/cli",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Workser CLI — give your local AI agent native DevOps & infrastructure on Workser. The agent runs `workser …` to provision, deploy, and manage real apps.",
   "license": "MIT",
   "type": "module",

package/skills/workser/SKILL.md

@@ -18,6 +18,7 @@ load.
 
 | You need to… | Commands | Run |
 | --- | --- | --- |
+| Track a business requirement too big for one task, and its phases | `goal …` | `workser help goals` |
 | See what was decided or written down for this project | `decision …`, `requirement …`, `doc …` | `workser help sdlc-entities` |
 | Follow the project's brand — colours, fonts, logo | `design …` | `workser help brand` |
 | Provision or query Postgres; list end users | `db …`, `auth …` | `workser help database` |

package/skills/workser/reference/goals.md

@@ -0,0 +1,69 @@
+---
+topic: goals
+title: Business goals & phases
+summary: The level above a task — a business requirement too big for one sitting, and the ordered phases that deliver it.
+commands: [goal]
+---
+
+# Business goals & phases
+
+A **goal** is a business requirement — "customers can buy from my site" — that
+does not fit in one task. It carries an ordered list of **phase names**; a task
+joins one by carrying that name (`workser task create --goal <id> --phase <name>`).
+A phase has no existence apart from the tasks inside it, so it cannot drift from
+the work it names.
+
+```
+workser goal list
+workser goal show <id>
+workser goal create <title> --phase <name...> [--outcome <text>]
+                            [--criteria <json>]
+workser goal update <id> [--title <text>] [--outcome <text>]
+                         [--phase <name...>] [--status <value>]
+workser goal check <id> <criterionId> --phase <name> (--pass|--fail|--reset) [--note <text>]
+```
+
+Status is one of: proposed, agreed, working, delivered, abandoned.
+
+## A goal has to be argued for
+
+Most requests are one task and should stay one task. Turning a two-hour job into
+four milestones buries the owner in ceremony before anything is built — use
+`workser task create` unless you can genuinely name two-plus slices that each
+deliver something the owner would notice.
+
+```
+workser goal create "Launch checkout" \
+  --phase "Cart" --phase "Payment" --phase "Receipts" \
+  --outcome "A customer can buy something and get a receipt"
+```
+
+`--phase` needs 2–6 names. Propose the shape only — nothing is created until the
+owner agrees it; planning phase four now is waste, since it will change once
+phase one is real.
+
+## Acceptance criteria are agreed with the shape
+
+`--criteria` maps each phase name to the owner's own sentences about what "done"
+means for it, e.g. `'{"Payment":["A customer can pay by card and gets a receipt"]}'`.
+Written afterwards they only describe what got built; written with the shape they
+can still change the plan.
+
+Record whether one is met with `workser goal check`:
+
+```
+workser goal check g_123 c1 --phase Payment --pass \
+  --note "Tested a card payment end to end; receipt emailed."
+```
+
+`--note` is required on `--pass` — a tick the owner cannot verify is worse than no
+tick.
+
+## Joining tasks to a goal
+
+```
+workser task create "Build the payment form" --goal g_123 --phase Payment
+```
+
+A goal's apps and progress are derived from the tasks that join it, not declared
+up front — most of the apps a goal will touch don't exist when it's proposed.