@akagilnc/pi-workflow-roles 0.1.2207 → 0.1.2212

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.2207",
+  "version": "0.1.2212",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/resources/engine-dispatch.md

@@ -0,0 +1,41 @@
+# Engine labor dispatch (shared across all engines)
+
+This note is the single source for **how labor is dispatched** to any optional
+engine. Every per-engine note under `resources/engines/<name>.md` covers only
+that engine's CLI technical parameters (executable, flags, output formats,
+host-measured constraints); it must not restate or contradict the dispatch
+rules here.
+
+Material is data for the model, not a code contract. Do not invent package flags.
+
+## What goes into the prompt
+
+The labor prompt carries **task + paths only**:
+
+- the task itself: goal, constraints, required output shape;
+- paths the engine reads itself: worktree root, ticket/issue number, frozen
+  attachment paths, run/dossier directory pointers (e.g. `AK_ROLE_RUN_DIR`).
+
+**Never paste material bodies into argv or the prompt** — no review bundles,
+no distilled-evidence dumps, no receipt JSON, no full briefs copied out of the
+ticket. Material lives in the worktree and on the ticket; both the seat and
+the outsourced process run from the project root and read those bytes
+themselves. Stuffing large bodies into argv/prompt is the verified cause of
+`spawn ENAMETOOLONG` failures (ming #1234 reviewer r1, 2026-08-17).
+
+## Process shape
+
+- When the package detour tool is available, start exactly one subprocess per
+  labor invocation through it, with argv assembled from the engine note plus
+  these dispatch rules; return the stdout labor content to the same role
+  session for the existing typed submission path.
+- One labor turn = one process (not one process for the whole role run).
+
+## Failure handling
+
+Once an engine is selected, the detour is mandatory: you MUST actually invoke
+that engine CLI. On any spawn, auth, quota, model-id, stream-stall,
+connection-drop, or other engine-process failure, return the typed failure and
+STOP — the run fails. In-seat labor after a detour failure is FORBIDDEN, and so
+is skipping the detour to work in-seat. Zero invocations is a violation, not a
+fallback. Do not silently swap to another engine id.

package/resources/engines/agy.md

@@ -1,12 +1,11 @@
 # agy engine method material
 
-This file is packaged method material for the optional `agy` labor engine
-(Gemini-family CLI on the host). When a role run selects this engine, read
-these bytes and follow the local CLI's actual interface for the labor detour.
-Return the labor result to the same role session so typed submission stays on
-the existing in-session path.
+This file is packaged technical material for the optional `agy` labor engine
+(Gemini-family CLI on the host).
 
-Material is data for the model, not a code contract. Do not invent package flags.
+Before invoking the engine, read `../engine-dispatch.md`, resolving that path
+relative to this note. This note only covers this engine's CLI technical
+parameters.
 
 ## Invocation examples (local agy CLI)
 
@@ -18,13 +17,3 @@ log file for diagnostics:
 ```bash
 agy --sandbox --print 'YOUR_LABOR_PROMPT' --log-file /tmp/agy-labor.log
 ```
-
-- Treat a quota/auth error like any other engine failure (do not retry-loop).
-
-## Failure handling
-
-The detour is mandatory: you MUST actually invoke the CLI. On any spawn,
-quota, or model failure, return the typed failure and STOP — the run fails.
-In-seat labor after a detour failure is FORBIDDEN, and so is skipping the
-detour to work in-seat. Zero invocations is a violation, not a fallback.
-Do not silently swap to another engine id.

package/resources/engines/codex.md

@@ -1,12 +1,11 @@
 # codex engine method material
 
-This file is packaged method material for the optional `codex` labor engine
-(Codex CLI on the host). When a role run selects this engine, read these
-bytes and follow the local CLI's actual interface for the labor detour. Return
-the labor result to the same role session so typed submission stays on the
-existing in-session path.
+This file is packaged technical material for the optional `codex` labor engine
+(Codex CLI on the host).
 
-Material is data for the model, not a code contract. Do not invent package flags.
+Before invoking the engine, read `../engine-dispatch.md`, resolving that path
+relative to this note. This note only covers this engine's CLI technical
+parameters.
 
 ## Invocation examples (local Codex CLI)
 
@@ -43,12 +42,4 @@ codex exec --skip-git-repo-check --ephemeral --json "YOUR_LABOR_PROMPT"
 ```
 
 Prefer `codex exec --help` on the host over any remembered flag set. Do not wrap
-this engine behind `ak-role` flags. Later host quota/auth failures are separate
-from argv acceptance — re-check the local CLI if a turn fails after session start.
-
-When the package detour tool is available, start exactly one subprocess per
-labor invocation through it with argv assembled from this material and the
-local CLI; return the stdout labor content to the same session for the existing
-typed submission path. One labor turn = one process (not one process for the
-whole role run). If the detour fails, continue labor in-session on the seat main
-road and still submit via the existing typed path.
+this engine behind `ak-role` flags.

package/resources/engines/cursor.md

@@ -1,11 +1,11 @@
 # cursor engine method material
 
-This file is packaged method material for the optional `cursor` labor engine.
-When a role run selects this engine, read these bytes and follow the local CLI's
-actual interface for the labor detour. Return the labor result to the same role
-session so typed submission stays on the existing in-session path.
+This file is packaged technical material for the optional `cursor` labor
+engine.
 
-Material is data for the model, not a code contract. Do not invent package flags.
+Before invoking the engine, read `../engine-dispatch.md`, resolving that path
+relative to this note. This note only covers this engine's CLI technical
+parameters.
 
 ## Invocation examples (local Cursor Agent CLI)
 
@@ -30,10 +30,3 @@ agent -p --force --output-format stream-json "YOUR_LABOR_PROMPT"
 
 Prefer `agent --help` on the host over any remembered flag set. Do not wrap this
 engine behind `ak-role` flags.
-
-When the package detour tool is available, start exactly one subprocess per
-labor invocation through it with argv assembled from this material and the
-local CLI; return the stdout labor content to the same session for the existing
-typed submission path. One labor turn = one process (not one process for the
-whole role run). If the detour fails, continue labor in-session on the seat main
-road and still submit via the existing typed path.

package/resources/engines/grok-4.6.md

@@ -1,12 +1,11 @@
 # grok-4.6 engine method material
 
-This file is packaged method material for the optional `grok-4.6` labor engine
-(Grok CLI on the host). When a role run selects this engine, read these bytes
-and follow the local CLI's actual interface for the labor detour. Return the
-labor result to the same role session so typed submission stays on the
-existing in-session path.
+This file is packaged technical material for the optional `grok-4.6` labor
+engine (Grok CLI on the host).
 
-Material is data for the model, not a code contract. Do not invent package flags.
+Before invoking the engine, read `../engine-dispatch.md`, resolving that path
+relative to this note. This note only covers this engine's CLI technical
+parameters.
 
 ## Invocation examples (local Grok CLI)
 
@@ -37,16 +36,6 @@ grok --prompt-file /path/to/labor-prompt.md -m grok-4.6 --always-approve --outpu
   alias `--effort`; a low-tier run completed correctly). If the mandate names
   no tier, use the seat's ordered thinking tier; never omit the flag — the
   CLI default is not guaranteed to match the ordered tier.
-- **Labor prompt must be seat-authored**: write the complete task brief into a
-  temp file and pass it via `--prompt-file`. Attachments/receipt JSON are
-  evidence material, not the prompt body — feeding them directly is rejected
-  by the CLI as non-ACP JSON (`JSON object must have a type field`;
-  live-verified 2026-08-21).
-
-## Failure handling
-
-The detour is mandatory: you MUST actually invoke the CLI. On any spawn,
-quota, or model failure, return the typed failure and STOP — the run fails.
-In-seat labor after a detour failure is FORBIDDEN, and so is skipping the
-detour to work in-seat. Zero invocations is a violation, not a fallback.
-Do not silently swap to another engine id.
+- Feeding raw JSON directly through `--prompt-file` is rejected by the CLI as
+  non-ACP JSON (`JSON object must have a type field`; live-verified
+  2026-08-21).

package/resources/engines/kimi.md

@@ -1,12 +1,11 @@
 # kimi engine method material
 
-This file is packaged method material for the optional `kimi` labor engine
-(Kimi Code CLI on the host). When a role run selects this engine, read these
-bytes and follow the local CLI's actual interface for the labor detour. Return
-the labor result to the same role session so typed submission stays on the
-existing in-session path.
+This file is packaged technical material for the optional `kimi` labor engine
+(Kimi Code CLI on the host).
 
-Material is data for the model, not a code contract. Do not invent package flags.
+Before invoking the engine, read `../engine-dispatch.md`, resolving that path
+relative to this note. This note only covers this engine's CLI technical
+parameters.
 
 ## Invocation examples (local Kimi Code CLI)
 
@@ -52,10 +51,3 @@ kimi -p "YOUR_LABOR_PROMPT" --output-format text
 
 Prefer `kimi --help` on the host over any remembered flag set. Do not wrap this
 engine behind `ak-role` flags.
-
-When the package detour tool is available, start exactly one subprocess per
-labor invocation through it with argv assembled from this material and the
-local CLI; return the stdout labor content to the same session for the existing
-typed submission path. One labor turn = one process (not one process for the
-whole role run). If the detour fails, continue labor in-session on the seat main
-road and still submit via the existing typed path.

package/resources/engines/opencode.md

@@ -1,12 +1,11 @@
 # opencode engine method material
 
-This file is packaged method material for the optional `opencode` labor engine
-(OpenCode CLI on the host; the GLM cheap-pool leg runs through it). When a role
-run selects this engine, read these bytes and follow the local CLI's actual
-interface for the labor detour. Return the labor result to the same role session
-so typed submission stays on the existing in-session path.
+This file is packaged technical material for the optional `opencode` labor
+engine (OpenCode CLI on the host; the GLM cheap-pool leg runs through it).
 
-Material is data for the model, not a code contract. Do not invent package flags.
+Before invoking the engine, read `../engine-dispatch.md`, resolving that path
+relative to this note. This note only covers this engine's CLI technical
+parameters.
 
 ## Invocation examples (local OpenCode CLI)
 
@@ -25,11 +24,3 @@ opencode run -m opencode-go/glm-5.2 "YOUR_LABOR_PROMPT"
   permissions for unattended runs (both per official docs).
 - Output goes to stdout; long prompts may be passed via shell heredoc or a
   file read into the argument — follow the installed CLI's actual interface.
-
-## Failure handling
-
-The detour is mandatory: you MUST actually invoke the CLI. On any spawn,
-quota, or model failure, return the typed failure and STOP — the run fails.
-In-seat labor after a detour failure is FORBIDDEN, and so is skipping the
-detour to work in-seat. Zero invocations is a violation, not a fallback.
-Do not silently swap to another engine id.

package/resources/engines/opus.md

@@ -1,12 +1,11 @@
 # opus engine method material
 
-This file is packaged method material for the optional `opus` labor engine
-(Claude Code CLI on the host). When a role run selects this engine, read these
-bytes and follow the local CLI's actual interface for the labor detour. Return
-the labor result to the same role session so typed submission stays on the
-existing in-session path.
+This file is packaged technical material for the optional `opus` labor engine
+(Claude Code CLI on the host).
 
-Material is data for the model, not a code contract. Do not invent package flags.
+Before invoking the engine, read `../engine-dispatch.md`, resolving that path
+relative to this note. This note only covers this engine's CLI technical
+parameters.
 
 ## Invocation examples (local Claude Code CLI)
 
@@ -39,10 +38,3 @@ not from intermediate stream rows.
 
 Prefer `claude --help` on the host over any remembered flag set. Do not wrap this
 engine behind `ak-role` flags.
-
-When the package detour tool is available, start exactly one subprocess per
-labor invocation through it with argv assembled from this material and the
-local CLI; return the stdout labor content to the same session for the existing
-typed submission path. One labor turn = one process (not one process for the
-whole role run). If the detour fails, continue labor in-session on the seat main
-road and still submit via the existing typed path.

package/resources/engines/ox-alpha.md

@@ -1,13 +1,11 @@
 # ox-alpha engine method material
 
-This file is packaged method material for the optional `ox-alpha` labor engine
-(OpenRouter stealth preview model, reached via OpenCode CLI or the OpenRouter
-chat-completions API). When a role run selects this engine, read these bytes
-and follow the local CLI / API's actual interface for the labor detour. Return
-the labor result to the same role session so typed submission stays on the
-existing in-session path.
+This file is packaged technical material for the optional `ox-alpha` labor
+engine (OpenRouter stealth preview model, reached via OpenCode CLI).
 
-Material is data for the model, not a code contract. Do not invent package flags.
+Before invoking the engine, read `../engine-dispatch.md`, resolving that path
+relative to this note. This note only covers this engine's CLI technical
+parameters.
 
 ## Identity and warnings
 
@@ -39,40 +37,8 @@ Smoke: prompt `只回两个字：收到` → `收到` (agentic leg usable).
 
 - `-m openrouter/stealth/ox-alpha` selects the model; confirm the current id
   with `opencode models` before long labor — stealth ids can vanish.
-- **Labor prompt must be seat-authored**: write the complete task brief
-  (goal, constraints, required output shape, and any evidence the seat has
-  already distilled) into the prompt argument or a temp file the seat reads
-  in. Attachments/receipt JSON are evidence material, not the prompt body —
-  feed a self-contained brief the way the grok-4.6 note requires a
-  seat-authored `--prompt-file`.
 - Effort tier: align with the labor mandate's ordered tier (`low` / `medium` /
   `high`). Live wall-times on the same 148KB grading payload:
   low 73s / medium 59s / high 228s — all produced correct three-state verdicts.
   Prefer the ordered tier; when the mandate is silent, medium was the
   fastest correct run on that payload.
-
-### Bare OpenRouter API (fallback only)
-
-Endpoint `https://openrouter.ai/api/v1/chat/completions`, model
-`stealth/ox-alpha`. Live lessons from long grading jobs — do not invent
-extra flags beyond these verified constraints:
-
-- **Must** send `"stream": true`. Buffered (non-stream) responses keep the
-  connection alive with empty fill bytes and stall out (live: 540s, no body).
-- **Must** send explicit `"reasoning": {"effort": "low|medium|high"}` matching
-  the ordered tier. Default effort burns `max_tokens` on thinking and finishes
-  with `finish=length` and 0 content characters.
-- Reconstruct the answer by concatenating SSE `delta.content` chunks in order.
-  `delta.reasoning` is the thinking stream, not the answer — do not treat it
-  as the labor result.
-- Large payloads (>140KB) are connection-unstable (three consecutive drops
-  recorded). On drop: shrink the brief or retry; do not keep hammering the
-  same oversized body.
-
-## Failure handling
-
-On any spawn, auth, model-id, stream-stall, or connection-drop failure, return
-the typed failure and STOP — the run fails. In-seat labor after a detour
-failure is FORBIDDEN, and so is skipping the detour to work in-seat. Zero
-invocations is a violation, not a fallback. Do not silently swap to another
-engine id.