@ze-norm/cli 0.11.5 → 0.13.0

package/dist/config/schema.d.ts

@@ -1,6 +1,16 @@
 export interface ZenormConfig {
     org?: string;
     apiUrl?: string;
+    /**
+     * Opt into coding-agent mode for local `zenorm work` runs: instead of running
+     * each task headlessly, launch the active coding agent (the one named by
+     * `--agent`) as a LIVE interactive session seeded with the spec handoff. The
+     * operator works with the agent, then closes it to release the worker and
+     * continue to the next task. Off by default; the `--interactive` flag
+     * overrides this. Requires a usable local TTY at run time (fails loud
+     * otherwise — see `interactive-agent.ts`).
+     */
+    interactive?: boolean;
 }
 export declare function validateConfig(raw: unknown): ZenormConfig;
 //# sourceMappingURL=schema.d.ts.map

package/dist/config/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,CAuBzD"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,CA8BzD"}

package/dist/config/schema.js

@@ -17,5 +17,11 @@ export function validateConfig(raw) {
         }
         config.apiUrl = obj["apiUrl"];
     }
+    if ("interactive" in obj) {
+        if (typeof obj["interactive"] !== "boolean") {
+            throw new CliError('.zenorm.json: "interactive" must be a boolean');
+        }
+        config.interactive = obj["interactive"];
+    }
     return config;
 }

package/dist/util/markdown.d.ts

@@ -21,4 +21,20 @@ export type SpecBlock = {
  * the agent sees a clean "## goals", "## acceptance_criterion" structure.
  */
 export declare function blocksToMarkdown(blocks: SpecBlock[]): string;
+export type AttachmentRecord = {
+    id: string;
+    fileName: string;
+    fileSize: number;
+    mimeType: string;
+    status: string;
+};
+/**
+ * Render the spec's ready attachments as an "## Attachments" markdown section
+ * for the worker work context. Lists fileName — mimeType — pretty size only;
+ * the file CONTENT/bytes are never inlined (binary can't be, and no AC needs
+ * download). Callers must pass ONLY ready attachments — the server is the gate
+ * (the `?status=ready` filter), this renderer does not re-filter. Returns an
+ * empty string when there are none so `pull` can omit the section.
+ */
+export declare function attachmentsToMarkdown(attachments: AttachmentRecord[]): string;
 //# sourceMappingURL=markdown.d.ts.map

package/dist/util/markdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/util/markdown.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAmB1D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAqB1E;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACvC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,CA+B5D"}
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/util/markdown.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAmB1D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAqB1E;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACvC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,CA+B5D;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAmBF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,gBAAgB,EAAE,GAAG,MAAM,CAO7E"}

package/dist/util/markdown.js

@@ -77,6 +77,40 @@ export function blocksToMarkdown(blocks) {
     }
     return out.join("\n").trimEnd();
 }
+/**
+ * Render a human-readable byte size (e.g. 1536 → "1.5 KB"). Used for the
+ * attachments listing only — purely cosmetic.
+ */
+function prettySize(bytes) {
+    if (!Number.isFinite(bytes) || bytes < 0)
+        return `${bytes} B`;
+    const units = ["B", "KB", "MB", "GB"];
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    const rounded = unit === 0 ? value : Math.round(value * 10) / 10;
+    return `${rounded} ${units[unit]}`;
+}
+/**
+ * Render the spec's ready attachments as an "## Attachments" markdown section
+ * for the worker work context. Lists fileName — mimeType — pretty size only;
+ * the file CONTENT/bytes are never inlined (binary can't be, and no AC needs
+ * download). Callers must pass ONLY ready attachments — the server is the gate
+ * (the `?status=ready` filter), this renderer does not re-filter. Returns an
+ * empty string when there are none so `pull` can omit the section.
+ */
+export function attachmentsToMarkdown(attachments) {
+    if (attachments.length === 0)
+        return "";
+    const out = ["## Attachments", ""];
+    for (const a of attachments) {
+        out.push(`- ${a.fileName} — ${a.mimeType} — ${prettySize(a.fileSize)}`);
+    }
+    return out.join("\n");
+}
 function humanizeType(type) {
     return type.split("_").map((s) => s.charAt(0).toUpperCase() + s.slice(1)).join(" ");
 }

package/dist/zenorm-skills/skills/execute-task/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: execute-task
-description: Execute ZeNorm work — either a full spec (all tasks in order) or
-  a single task by ID. Use when the `/zenorm` dispatcher hands off, when the
-  user says "implement spec <key>", "do task <id>", or references a ZeNorm
-  spec/task. Always pulls the full spec so the agent has the complete picture
-  before writing code. Fails fast on any unsatisfied acceptance criterion.
+description: >-
+  Execute ZeNorm work — a full spec (all tasks in order) or a single task by
+  ID. This is the implementation engine the `/zenorm` dispatcher hands off to;
+  `/zenorm` is the preferred user-facing entry point because it manages the
+  session id and the final sync. Use this skill directly only when the
+  dispatcher hands off, or when a user explicitly asks to execute a specific
+  ZeNorm spec/task by key or id and the dispatcher is unavailable. Always pulls
+  the full spec so the agent has the complete picture before writing code.
+  Fails fast on any unsatisfied acceptance criterion.
 ---
 
 # Execute ZeNorm Spec or Task
@@ -20,6 +24,16 @@ of truth — read it first, every time, even for a single task.
 
 If unclear, ask the user. Do not guess.
 
+Two flags may follow the target:
+- `--session-id=<id>` — the session id to thread through every `task complete`
+  call (see "Session id").
+- `--dispatched` — set when the `/zenorm` dispatcher invoked you. It means the
+  **dispatcher owns the final `zenorm-sync`**, so you must NOT run sync
+  yourself when you finish — just return your report and let the dispatcher
+  flush. Without this flag you were invoked directly, so the final
+  `zenorm-sync` is yours to run. This keeps sync single-owner: exactly one
+  sync per flow, never a double post. (See "Handing off to sync" at the end.)
+
 ## Always: load full context first
 
 Run both before touching code, regardless of mode:
@@ -115,15 +129,42 @@ foundational slice that later tasks depend on, re-run the check yourself or
 spawn a short verifier subagent. Then update the AC ledger. Only then
 delegate the next task.
 
+## The blocked-task contract
+
+This is the one rule that protects ZeNorm's spec state from drifting away
+from reality, so it is stated once here and referenced from every workflow
+below. When a task **cannot** be finished — a check won't pass, an AC can't
+be met, a decision is the user's to make:
+
+- **Leave it `active`.** Do not flip it to `done`.
+- **Do NOT call `zenorm task complete` on it.** That command auto-flips
+  status to `done`, which would falsely claim the work landed. The status
+  exists to tell the truth about what's finished.
+- **Record the blocker** — what failed, what you tried, why you're stuck —
+  in your final report and in the hand-off to `zenorm-sync`, so it reaches
+  the user-facing summary.
+- **Never claim the spec/task is complete** if any task is still `active` or
+  any AC is unmet. Silent success on partial work is the exact failure this
+  contract prevents.
+
+A finished task is the opposite: post its rich outcome with `task complete`
+(which flips it to `done`). Everywhere below that says "treat as a failure"
+or "stop and report the blocker," this is the contract it means.
+
 ## Spec mode workflow
 
 1. **State the goal.** Write the spec's acceptance criteria into your thread
    as the completion condition (the AC ledger). Map each task to the AC(s)
    it advances so you steer toward the goal, not just down the task list.
-2. **Walk tasks in list order**, one slice at a time. For each task with
-   status `planned` or `todo`:
+2. **Walk tasks in list order**, one slice at a time. Pick up every task that
+   is not yet finished — status `planned`, `todo`, **or** `active` with no
+   posted outcome (an `active`-but-outcome-less task was pre-claimed for you,
+   e.g. by the `zenorm work` daemon, and still needs implementing — do not skip
+   it). Skip only tasks already `done` (or `active` *with* an outcome). For each
+   such task:
    1. `zenorm task update <task-id> --status=active` (you, the orchestrator,
-      own this call).
+      own this call). A task already `active` from a daemon pre-claim stays
+      `active` — this is a no-op for it, not a reason to skip it.
    2. **Delegate the slice to a subagent** with the brief above — goal +
       the AC(s) it advances, context, constraints, the verification it must
       run, and the structured report (changes, evidence, intent signals).
@@ -156,15 +197,13 @@ delegate the next task.
       information; pass them forward). Re-confirm its result. If it still
       fails after ~2 attempts, **stop** — do not loop a third. A stuck slice
       usually means missing information or a decision only the user can make.
-      Then: do not advance to the next task, do not mark the failed task
-      done, do **not** call `task complete` for it (that would auto-flip to
-      done). Leave it `active` and record the blocker in your final report
-      and in the hand-off to `zenorm-sync` so it lands in the user-facing
-      summary.
+      Do not advance to the next task. Apply **The blocked-task contract**
+      above: leave it `active`, do not `task complete` it, record the blocker.
 3. **Create subtasks for discovered work** rather than silently expanding
    scope: `zenorm task create <spec-key> --title="..."`.
 4. After all tasks pass, run the **final-spec verification** below.
-5. Hand off to `zenorm-sync` for outcome flush.
+5. **Finish:** see "Handing off to sync" — if `--dispatched`, return your
+   report and let the dispatcher sync; otherwise run `zenorm-sync` yourself.
 
 ## Single-task mode workflow
 
@@ -186,8 +225,8 @@ optional (fine if the task is large), not required.
    <task-id> --summary="..." --session-id=<id>` (with whichever of
    `--decisions`, `--steering`, `--preferences`, `--deviations`,
    `--discoveries` apply). This auto-flips status to `done`.
-5. On failure: stop, leave the task `active`, do not call `task complete`,
-   report what failed.
+5. On failure: stop and apply **The blocked-task contract** above (leave it
+   `active`, no `task complete`, record the blocker).
 6. **Final end-to-end pass.** Before sync, prove the task behaviorally, as
    end-to-end as the local environment allows — drive the running app the
    way a user exercises each AC (`playwright-cli` for browser surfaces with
@@ -199,14 +238,21 @@ optional (fine if the task is large), not required.
    mask a failure to reach green). For a large task this is worth a fresh
    verification subagent (see spec-mode Final-spec verification); for a
    small one, do it inline.
-7. Hand off to `zenorm-sync` (success or failure).
+7. **Finish:** see "Handing off to sync" — sync ownership depends on
+   `--dispatched`.
 
 ## Session id
 
-Use the session id the `/zenorm` dispatcher generated. If you were invoked
-directly (no dispatcher), generate one once at the start:
-`zn-$(date +%s)-$(openssl rand -hex 2)` (or similar) and reuse it across
-every `task complete` call in this invocation.
+The `/zenorm` dispatcher passes one in `--session-id=<id>` — use that exact
+value for every `task complete` call. If you were invoked directly (no
+`--session-id` arg), mint one once at the start by running this command (never
+copy a literal id from this doc):
+
+```sh
+echo "zn-$(date +%s)-$(openssl rand -hex 2)"
+```
+
+Reuse that id across every `task complete` call in this invocation.
 
 ## Per-task verification (fail-fast)
 
@@ -225,9 +271,10 @@ relevant acceptance criterion is demonstrably satisfied. Before flipping to
   mutator, a schema field) with the UI change that exercises it and verify
   the pair. Always check `playwright-cli console error` — a clean snapshot
   with red console errors is still a broken page.
-- If any check fails: **do not mark done**. Fix the underlying problem
-  or report the blocker. Never bypass with `--no-verify` or skip the
-  failing check.
+- If any check fails: fix the underlying problem, or — if you can't — apply
+  **The blocked-task contract** (leave `active`, no `task complete`, record
+  the blocker). Never bypass with `--no-verify` or skip the failing check to
+  reach a false green.
 
 ## Final-spec verification (spec mode)
 
@@ -289,6 +336,23 @@ then confirm its verdict yourself.
    working feature reported as done is the exact failure this pass exists
    to catch.
 
+## Handing off to sync
+
+`zenorm-sync` flushes any gap outcomes and prints the final report. Exactly
+one sync runs per flow — who runs it depends on how you were invoked:
+
+- **Invoked with `--dispatched`** (the `/zenorm` dispatcher called you): the
+  **dispatcher owns the final sync**. Do NOT run `zenorm-sync` yourself —
+  finish your work, return your report (success or blocker), and let the
+  dispatcher sync. Running it here too would double-post.
+- **Invoked directly** (no `--dispatched`): the final sync is **yours**. After
+  your last task — success or hard stop — run `zenorm-sync` so outcomes are
+  flushed and the stop hook (`zenorm session-check`) doesn't wedge the
+  session.
+
+Either way, sync runs whether the work succeeded or hard-stopped on a
+blocker; the partial-state report is part of the contract.
+
 ## Output contract
 
 Report at the end:
@@ -312,4 +376,6 @@ exists to prevent.
   means a later `git add` sweeps it into slice N+1's commit. Verify
   `git diff --staged` before each commit.
 - If acceptance criteria are ambiguous, ask the user. Do not guess.
-- After completion (or hard stop), invoke `zenorm-sync` to post outcomes.
+- After completion (or hard stop), the final `zenorm-sync` must run — but
+  only **you** run it when invoked directly. Under `--dispatched`, the
+  dispatcher owns it (see "Handing off to sync").

package/dist/zenorm-skills/skills/zenorm/SKILL.md

@@ -1,96 +1,92 @@
 ---
 name: zenorm
 description: >-
-  Dispatcher for ZeNorm spec-driven work. Use when the user invokes `/zenorm`,
-  says "implement spec <key>", "work on spec <key>", "continue spec <key>",
-  "sync zenorm", or otherwise references ZeNorm specs/tasks by key (e.g.
-  "AUTH-123") or UUID. Routes the request to the right focused skill:
-  full-spec execution, single-task execution, or session sync-back.
+  Dispatcher for explicit ZeNorm spec-driven work. Use when the user invokes
+  `/zenorm ...`, or explicitly asks to execute, implement, run, continue, or
+  sync a ZeNorm spec or task — e.g. "implement spec AUTH-123", "run this
+  ZeNorm spec", "continue spec Z-9", "do ZeNorm task <uuid>", "sync zenorm",
+  "wrap up the ZeNorm session". It routes to the right focused skill:
+  full-spec execution, single-task execution, or session sync-back, and owns
+  the session id and the final outcome flush. Do NOT trigger merely because a
+  message mentions a spec key or discusses a spec — only on an explicit
+  request to act on ZeNorm work.
 ---
 
 # ZeNorm Dispatcher
 
-You are the entry point for ZeNorm work. Your job is to read the user's
-request, pick the right focused skill, and hand off — not to do the work
-yourself.
+You are the entry point for ZeNorm work. Read the request, pick the right
+focused skill, hand off — do not do the work yourself. You own two things the
+child skills rely on: the **session id** and the **single final sync**.
 
-## Inputs
+## Routing
 
-Raw user phrase (`$ARGUMENTS`): everything after `/zenorm`.
+`$ARGUMENTS` is everything after `/zenorm`. Run the resolver — it strips
+verbs, classifies the target, and resolves spec keys of ANY shape (code,
+slug, or UUID) against the CLI so you do not guess:
 
-Examples:
-- `/zenorm implement spec Z-123`
-- `/zenorm Z-123`
-- `/zenorm task <task-uuid>`
-- `/zenorm sync`
-- `/zenorm continue Z-123`
+```sh
+scripts/resolve.sh $ARGUMENTS
+```
 
-## Routing rules
+It prints exactly one line. Act on it:
 
-Parse `$ARGUMENTS`, strip leading verbs (`implement`, `work on`, `continue`,
-`do`, `run`, `execute`), then dispatch:
+| Resolver output                | Action                                                                       |
+|--------------------------------|------------------------------------------------------------------------------|
+| `ROUTE=spec KEY=<k> SID=<s>`   | run `execute-task` with `<k> --session-id=<s> --dispatched`                   |
+| `ROUTE=task ID=<id> SID=<s>`   | run `execute-task` with `task <id> --session-id=<s> --dispatched`             |
+| `ROUTE=sync`                   | run `zenorm-sync` (no args)                                                   |
+| `ERROR=<msg>`                  | Show `<msg>` to the user and ask them to confirm the key — do not guess       |
 
-| Trimmed input shape                        | Skill to invoke              | Args passed                |
-|--------------------------------------------|------------------------------|----------------------------|
-| `spec <key-or-id>` / `<key-or-id>` (spec)  | `execute-task` (spec mode)   | the spec key or UUID       |
-| `task <task-uuid>`                         | `execute-task` (single-task) | the task UUID              |
-| `sync` / empty after a work session        | `zenorm-sync`                | the spec key (from config) |
+Only ask the user to clarify on an `ERROR` line — never reject a key yourself
+for looking unfamiliar. The resolver already checked it against the CLI.
 
-A bare UUID is ambiguous — resolve by trying spec lookup first
-(`zenorm pull <id>`); if that fails treat it as a task ID.
+The `--dispatched` flag tells `execute-task` that *you* (the dispatcher) own
+the final `zenorm-sync`, so it will not run its own. This keeps sync
+single-owner: exactly one sync per `/zenorm` invocation, no double posts. (If
+a user runs `execute-task` directly without going through you, it has no
+`--dispatched` flag and syncs itself — that path stays correct too.)
 
-If the request does not match any pattern, ask the user which spec or task
-they mean. Do not guess.
+## How to invoke a child skill
 
-## Invocation
+Invoke `execute-task` / `zenorm-sync` with the `Skill` tool if your harness
+exposes one — do not narrate the dispatch. The child skill runs its own
+`zenorm pull` / `task list`, so do not pre-fetch.
 
-Invoke the chosen skill by name using the `Skill` tool — do not narrate
-the dispatch. The skill itself will run `zenorm pull`, `zenorm task list`,
-etc., so you do not pre-fetch.
+**If there is no `Skill` tool, or it refuses** (e.g. "disabled in
+skillOverrides", "not found", or the skill isn't in your available list):
+this is normal on some agents. Read the sibling skill file directly and
+follow it as instructions — the file IS the skill. Paths to try:
 
-Concrete examples:
-- `/zenorm implement spec AUTH-123` → call `Skill(skill="execute-task", args="AUTH-123")`
-- `/zenorm task d43b96b1-...` → call `Skill(skill="execute-task", args="task d43b96b1-...")`
-- `/zenorm sync` → call `Skill(skill="zenorm-sync", args="")`
-
-**Fallback if the `Skill` tool refuses for ANY of the child skills**
-(e.g. "disabled in skillOverrides", "not found", or it doesn't appear in
-your available-skills list): read the skill file directly and follow it
-as instructions. Paths:
 - `./skills/execute-task/SKILL.md` and `./skills/zenorm-sync/SKILL.md`
   inside this plugin
 - `.claude/skills/{execute-task,zenorm-sync}/SKILL.md` in a local checkout
 
-The file IS the skill — apply the same fallback to `zenorm-sync` if it
-also refuses. Do not give up because the harness gated the Skill tool.
+Apply the same fallback to `zenorm-sync`. Do not abandon the flow because the
+harness gated a tool — the work and the sync still have to happen.
+
+## The final sync is mandatory
 
 After the focused skill finishes — **whether it succeeded or hard-stopped on
-a blocker** — invoke `zenorm-sync` to flush outcomes. Sync runs in both
-cases; the partial-state report is part of the contract. The session-stop
-hook (`zenorm session-check`) will block stop otherwise.
+a blocker** — run `zenorm-sync` to flush outcomes and print the report. Sync
+runs in *both* cases; the partial-state report is part of the contract, not a
+success-only nicety. The session-stop hook (`zenorm session-check`) blocks
+ending the session until outcomes are posted, so skipping sync just wedges
+the user.
 
-## Session id convention
+## Session id
 
-Generate one session id at the start of the dispatch and pass it to every
-`task complete` call across this whole flow. Format:
-`zn-<unix-timestamp>-<short-random>` (e.g. `zn-1717449600-a7f3`). Reuse the
-same id for every task in the same `/zenorm` invocation so outcomes group
-correctly and the stop hook's idempotency check works.
+`resolve.sh` mints a fresh session id per dispatch and prints it as `SID=<id>`
+on the ROUTE line. Pass that exact `SID` to the child skill (see the routing
+table). Never invent, generate, or copy a session id yourself — use the one
+the resolver gave you. The child skill threads it to every `task complete`
+call so outcomes group as one session, and a fresh dispatch always gets a
+distinct id.
 
 ## What NOT to do here
 
-- Do not implement code in this skill — delegate to `execute-task`.
-- Do not mark tasks done here — `execute-task` and `zenorm-sync` own that.
-- Do not skip `zenorm-sync` even if the work was small. The hook will
-  block stop until outcomes are posted.
-- Do not invent new spec keys or task IDs. If the user's reference is
-  unresolvable, stop and ask.
-
-## Available CLI commands (for the skills you dispatch to)
-
-- `zenorm pull <key-or-id>` — full spec markdown (goals, constraints, ACs)
-- `zenorm task list <spec-key-or-id>` — task list with statuses
-- `zenorm task update <task-id> --status=<planned|todo|active|done>`
-- `zenorm task create <spec-key> --title="..."` — discovered subtask
-- `zenorm task complete <task-id> --summary="..." --session-id=<id>` — flush outcome
-- `zenorm whoami` — confirm auth/org context
+- Do not implement code in this skill — that is `execute-task`'s job.
+- Do not mark tasks done or post outcomes here — `execute-task` and
+  `zenorm-sync` own that.
+- Do not skip the final `zenorm-sync`, even for small work. The stop hook
+  blocks until outcomes are posted.
+- Do not invent spec keys or task ids. On an `ERROR` line, stop and ask.

package/dist/zenorm-skills/skills/zenorm/evals/evals.json

@@ -0,0 +1,41 @@
+{
+  "skill_name": "zenorm",
+  "notes": "Dispatch-skill evals. Subagents get a stub `zenorm` CLI on PATH (evals/stub-zenorm.sh symlinked as `zenorm`) so routing + the --dispatched/sync contract run offline. Every CLI call is logged to $ZENORM_STUB_LOG; assertions inspect that log plus the transcript. The point is routing correctness and the single-sync / blocked-task contract, NOT real implementation.",
+  "evals": [
+    {
+      "id": 0,
+      "name": "spec-dispatch-single-sync",
+      "prompt": "/zenorm implement spec Z-EVAL",
+      "expected_output": "Runs resolve.sh, routes to execute-task with --session-id and --dispatched, execute-task does NOT run its own zenorm-sync, dispatcher runs exactly ONE zenorm-sync at the end. Exactly one session id threads through all task complete calls.",
+      "files": []
+    },
+    {
+      "id": 1,
+      "name": "sync-only-route",
+      "prompt": "/zenorm sync",
+      "expected_output": "Routes to zenorm-sync only. Does NOT invoke execute-task, does NOT implement code, prints the final spec/task report.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "name": "no-trigger-on-discussion",
+      "prompt": "I'm looking at spec Z-EVAL and I'm not sure the greeting endpoint AC is worded well. What do you think \"Hello, X\" should do if name is empty? Just discussing, don't change anything.",
+      "expected_output": "The zenorm dispatcher should NOT trigger — this is discussion about a spec, not a request to execute/run/sync it. The agent answers the question directly without routing to execute-task or running resolve.sh.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "name": "direct-execute-self-sync",
+      "prompt": "Run execute-task directly on spec Z-EVAL (do not go through the /zenorm dispatcher). When you finish, who owns the final sync?",
+      "expected_output": "execute-task invoked WITHOUT --dispatched runs its OWN zenorm-sync at the end (because no dispatcher is in the loop). Exactly one sync still runs.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "name": "blocked-task-stays-active",
+      "prompt": "/zenorm implement spec Z-EVAL. Note: task t2 (health endpoint) cannot be verified in this environment — its check will never pass. Handle it correctly.",
+      "expected_output": "t1 gets completed normally. t2 is left status=active: the agent must NOT call `zenorm task complete` on t2 (that would falsely flip it to done), and must NOT claim the spec is complete. The blocker is reported and the final sync still runs.",
+      "files": []
+    }
+  ]
+}

package/dist/zenorm-skills/skills/zenorm/evals/stub-zenorm.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Stub `zenorm` CLI for dispatch-skill evals. Put this dir on PATH (named
+# `zenorm`) so the dispatch skills can run end-to-end offline — no auth, no
+# network, no real spec store. It returns canned data for one fixture spec
+# (Z-EVAL) and logs every call to $ZENORM_STUB_LOG so assertions can inspect
+# exactly which commands the agent issued (routing, --dispatched, --session-id,
+# whether `task complete` was called on a blocked task, etc.).
+#
+# Fixture: spec Z-EVAL has 2 tasks.
+#   t1 (todo)  — "Add greeting endpoint"      → satisfiable, agent should complete
+#   t2 (todo)  — "Wire impossible-to-verify"  → the eval prompt may mark blocked
+set -euo pipefail
+
+LOG="${ZENORM_STUB_LOG:-/tmp/zenorm-stub.log}"
+echo "CALL: $*" >>"$LOG"
+
+cmd="${1:-}"; shift || true
+
+case "$cmd" in
+  whoami)
+    echo "stub-user @ stub-org (ZENORM_STUB)"
+    ;;
+  pull)
+    # $1 = spec ref. Only Z-EVAL resolves.
+    ref="${1:-}"
+    if [ "$ref" = "Z-EVAL" ] || [ "$ref" = "z-eval" ]; then
+      cat <<'SPEC'
+# Spec Z-EVAL — Greeting service
+
+## Goal
+Expose a greeting endpoint and a health endpoint.
+
+## Constraints
+- Use pnpm only.
+
+## Acceptance criteria
+- AC1: GET /greet?name=X returns "Hello, X".
+- AC2: GET /health returns 200 with {status:"ok"}.
+SPEC
+    else
+      echo "err: spec '$ref' not found" >&2
+      exit 1
+    fi
+    ;;
+  task)
+    sub="${1:-}"; shift || true
+    case "$sub" in
+      list)
+        cat <<'TASKS'
+t1  todo  Add greeting endpoint
+t2  todo  Add health endpoint
+TASKS
+        ;;
+      start-spec)
+        echo "started spec ${1:-} (tasks planned->todo)" >&2
+        ;;
+      update)
+        echo "updated ${*}"
+        ;;
+      create)
+        echo "created task: ${*}"
+        ;;
+      complete)
+        echo "completed task: ${*}"
+        ;;
+      *)
+        echo "err: unknown task subcommand '$sub'" >&2; exit 2 ;;
+    esac
+    ;;
+  *)
+    echo "err: unknown command '$cmd'" >&2; exit 2 ;;
+esac

package/dist/zenorm-skills/skills/zenorm/scripts/resolve.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# ZeNorm dispatch resolver.
+# Takes the raw `/zenorm` argument string, strips leading verbs, classifies the
+# target, and (for spec targets) resolves it via `zenorm pull` so the agent
+# does not have to guess key shape. Prints exactly one ROUTE line on success,
+# or an ERROR line the agent can surface verbatim.
+#
+# Output contract (always one of):
+#   ROUTE=sync
+#   ROUTE=task ID=<token> SID=<session-id>
+#   ROUTE=spec KEY=<token> SID=<session-id>
+#   ERROR=<message>
+# SID is a fresh session id minted per dispatch; the agent passes it to every
+# `task complete` call so outcomes group as one session in the dashboard.
+set -euo pipefail
+
+raw="${*:-}"
+
+# One fresh session id per dispatch. Generated here so the agent never invents
+# or copies a literal — it reads SID off the ROUTE line below. Unique per
+# invocation: two separate runs get distinct ids and group as separate sessions
+# in the dashboard.
+SID="zn-$(date +%s)-$(openssl rand -hex 2)"
+
+# Strip leading verbs and an optional `spec` keyword, collapse whitespace.
+trimmed="$(printf '%s' "$raw" \
+  | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//' \
+  | sed -E 's/^(implement|work on|continue|do|run|execute)[[:space:]]+//I' \
+  | sed -E 's/^spec[[:space:]]+//I')"
+
+# Empty -> sync.
+if [ -z "$trimmed" ] || printf '%s' "$trimmed" | grep -qiE '^sync$'; then
+  echo "ROUTE=sync"
+  exit 0
+fi
+
+# Explicit task target.
+if printf '%s' "$trimmed" | grep -qiE '^task[[:space:]]+'; then
+  id="$(printf '%s' "$trimmed" | sed -E 's/^task[[:space:]]+//I' | awk '{print $1}')"
+  echo "ROUTE=task ID=$id SID=$SID"
+  exit 0
+fi
+
+# Otherwise: first token is a candidate spec key of ANY shape. Resolve it.
+token="$(printf '%s' "$trimmed" | awk '{print $1}')"
+
+if zenorm pull "$token" >/dev/null 2>&1; then
+  # Deterministic, non-agent step: starting execution of a spec moves all of
+  # its `planned` tasks into `todo`. Idempotent — safe to re-run. Failure here
+  # must not block routing, so log to stderr and keep the one-line contract.
+  zenorm task start-spec "$token" 1>&2 || \
+    echo "warn: 'task start-spec $token' failed; tasks not advanced to todo" 1>&2
+  echo "ROUTE=spec KEY=$token SID=$SID"
+  exit 0
+fi
+
+# Spec pull failed. If it looks like a UUID, retry as a task id.
+if printf '%s' "$token" | grep -qiE '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'; then
+  echo "ROUTE=task ID=$token SID=$SID"
+  exit 0
+fi
+
+# Genuinely unresolvable. Surface the real CLI error.
+err="$(zenorm pull "$token" 2>&1 || true)"
+echo "ERROR=spec '$token' did not resolve: $err"
+exit 1