taskchef 7.2.0 → 7.3.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.2.0",
+  "version": "7.3.0",
   "description": "Dispatch work from a data-only workspace to visible Codex project tasks.",
   "author": {
     "name": "Favo Yang",

package/README.md

@@ -87,17 +87,18 @@ $taskchef-delegate In payments, add structured logs for failed retries and test
 
 TaskChef prepares a UUID and marker, persists the task before native creation,
 creates the executor, and returns its task link. New executor instructions keep
-the assignment visible immediately after the marker and end with an explicit
-`$taskchef-executor` invocation. That skill reads the executor's own
-`CODEX_THREAD_ID`, self-links, and reports lifecycle state. Independent outcomes
-may become separate executors; dependent work should stay together.
+the assignment visible from the first line, then place the correlation marker
+immediately before an explicit `$taskchef-executor` invocation. That skill
+reads the executor's own `CODEX_THREAD_ID`, self-links, and reports lifecycle
+state. Independent outcomes may become separate executors; dependent work
+should stay together.
 
 For example, TaskChef generates this shape:
 
 ```text
-<!-- taskchef_id=c0f010ff-84f2-4838-a69d-0ff1f5d721d7 -->
 Fix duplicate charges after a retry and add a regression test.
 
+<!-- taskchef_id=c0f010ff-84f2-4838-a69d-0ff1f5d721d7 -->
 Use $taskchef-executor to execute and report this delegated TaskChef assignment.
 ```
 

package/docs/firstmate-taskchef-comparison.md

@@ -108,7 +108,7 @@ also insert an interpretation layer between user and worker.
 
 ### TaskChef
 
-**Fact:** `prepare_dispatch` allocates a TaskChef UUID and exact first-line
+**Fact:** `prepare_dispatch` allocates a TaskChef UUID and exact correlation
 marker. `record_task` persists the marked instruction before native task
 creation. The executor then reads its own `CODEX_THREAD_ID` and calls
 `link_task`; the dispatcher neither searches recent tasks nor repairs identity.

package/docs/spec.md

@@ -18,7 +18,7 @@ is dated research, not contract.
 | **Delegated task** | One independently useful outcome represented by one TaskChef task UUID and snapshot. |
 | **Executor** | The native Codex task created to own and perform one delegated task. |
 | **Task record** | One complete JSON object in `tasks.jsonl`; it contains immutable intent/project fields and mutable identity/result fields. |
-| **Marker** | The exact first instruction line `<!-- taskchef_id=<lowercase full UUID> -->`; new instructions begin the assignment on the next line. |
+| **Marker** | The exact correlation line `<!-- taskchef_id=<lowercase full UUID> -->`; new instructions place it after the complete assignment and immediately before the executor-skill invocation. |
 | **Record-before-create** | Persisting a link-pending task before asking Codex to create its executor. |
 | **Self-linking** | The executor's one-way registration of its own canonical Codex UUIDv7 from `CODEX_THREAD_ID`. |
 | **Link-pending** | A working task whose `threadId` is null and `updatedBy` is `dispatcher`. |
@@ -102,10 +102,11 @@ fields MUST NOT change after recording.
 
 1. The dispatcher MUST call `prepare_dispatch` once per outcome.
 2. It MUST choose exactly one configured project and exact native-project path.
-3. It MUST build the instruction with the returned marker as line 1, the user's
-   outcome beginning on line 2, and exactly one concise explicit
-   `$taskchef-executor` invocation at the end after one blank line. It MUST NOT
-   inline the executor protocol into a new instruction.
+3. It MUST build the instruction with the user's outcome beginning on line 1
+   and remaining uninterrupted, followed by one blank line, the returned
+   marker, and exactly one concise explicit `$taskchef-executor` invocation on
+   the final line. It MUST NOT inline the executor protocol into a new
+   instruction.
 4. It MUST call `record_task` with `threadId: null` before native creation.
 5. It MUST create exactly one native Codex executor and return immediately.
 6. The executor MUST read its own `CODEX_THREAD_ID` and call `link_task`
@@ -122,10 +123,15 @@ If native creation fails after recording, the dispatcher MUST call
 A link failure MUST remain visible and retryable; the executor MUST report it
 visibly and MUST NOT continue substantive work.
 
-Previously recorded instructions with the former blank line and inline
-executor protocol MUST remain marker-readable and executable. Their
+Previously recorded instructions with a first-line HTML marker, the older
+first-line `# taskchef_id=<full UUID>` heading, or the former blank line and
+inline executor protocol MUST remain marker-readable and executable. Their
 `report_result` calls MUST remain supported by the deprecated alias. New
-instructions MUST use the explicit executor skill contract above.
+instructions MUST use the trailing marker and explicit executor skill contract
+above. A historical first-line instruction with an executor-skill invocation
+MUST contain exactly one invocation as its final line. A former inline-protocol
+instruction MUST retain non-whitespace task-specific content beyond its known
+lifecycle paragraphs.
 
 `needs_input` MUST mean a semantic user decision or missing fact. A native
 approval prompt MUST remain live Codex state and MUST NOT be stored as
@@ -176,7 +182,7 @@ new preparation values, though it writes no state.
 | `id` | Non-empty string; MUST equal the instruction marker. |
 | `project` | Non-empty configured project path. |
 | `title` | Non-empty string. |
-| `instruction` | Non-empty string beginning with the exact marker and at least one following instruction line. |
+| `instruction` | Non-empty string containing exactly one accepted marker and a non-empty assignment. New instructions use the required trailing marker and executor-invocation scaffold; historical first-line forms remain accepted. |
 | `threadId` | Literal null. |
 
 **Structured output:** `{ task: Task }`.

package/docs/workflows.md

@@ -68,10 +68,11 @@ Record-before-create makes native creation failure observable. Executor
 self-linking removes dispatcher-side polling, task search, title matching, and
 parent/child identity inference.
 
-The generated task body begins immediately after the first-line marker and
-ends with one explicit `$taskchef-executor` invocation. Older recorded tasks
-whose marker is followed by a blank line and inline protocol remain readable;
-the deprecated `report_result` alias preserves their semantic callbacks.
+The generated task begins with the complete assignment, then places its marker
+immediately before one explicit `$taskchef-executor` invocation. Older
+recorded tasks with first-line HTML or heading markers and former inline
+protocol remain readable; the deprecated `report_result` alias preserves their
+semantic callbacks.
 
 ## State reporting
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.2.0",
+  "version": "7.3.0",
   "description": "A non-blocking interactive dispatcher for visible Codex tasks.",
   "license": "MIT",
   "author": "Favo Yang",

package/skills/taskchef-delegate/SKILL.md

@@ -10,11 +10,18 @@ and return immediately.
 
 ## Invocation boundary
 
-A task whose initial structured `codexDelegation.input` starts with an exact
-`<!-- taskchef_id=<full UUID> -->` marker already owns that delegated
-assignment. Execute it in the current task. Do not re-dispatch it merely
-because it concerns TaskChef or a configured project. Explicit requests to
-delegate separate work remain valid.
+A task whose initial structured `codexDelegation.input` contains either the
+exact new trailing TaskChef marker plus final `$taskchef-executor` invocation,
+an exact first-line HTML marker, or the historical first-line
+`# taskchef_id=<full UUID>` heading already owns that delegated assignment.
+This includes former inline-protocol tasks that lack the skill invocation.
+An owned instruction must have exactly one accepted marker and a non-whitespace
+task-specific assignment. If it contains an executor-skill invocation, require
+exactly one as the final line. Marker-only, duplicate-marker, scaffold-only, or
+misplaced-invocation inputs are not valid delegated tasks. Execute a valid one
+in the current task. Do not re-dispatch it merely because it concerns TaskChef
+or a configured project. Explicit requests to delegate separate work remain
+valid.
 
 Use the bundled `prepare_dispatch`, `record_task`, and `report_state` MCP tools
 directly. Never fall back to shell writes. If a required tool is unavailable,
@@ -43,11 +50,13 @@ stop and report that the TaskChef plugin must be reloaded or installed.
    match and an exact native-project path. Ask instead of guessing.
 4. Build each executor instruction in this exact shape:
 
-   - Keep the preparation's exact marker as the first line.
-   - Begin the actual assignment on the second line, with no blank line after
-     the marker.
-   - End the instruction after one blank line with exactly:
+   - Begin with the actual assignment on the first line and keep its complete
+     body uninterrupted.
+   - After the assignment, add one blank line and the preparation's exact
+     marker on its own line.
+   - Immediately after the marker, end the instruction with exactly:
      `Use $taskchef-executor to execute and report this delegated TaskChef assignment.`
+   - Include exactly one marker and exactly one executor-skill invocation.
    - Do not inline executor ownership, identity, linking, or result-reporting
      protocol. The explicitly invoked executor skill owns those mechanics.
 

package/skills/taskchef-executor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: taskchef-executor
-description: "Execute an assignment whose first instruction line is an exact TaskChef task marker, including executor ownership, self-linking, per-turn lifecycle reporting, identity safety, and final semantic state. Use when explicitly invoked by a delegated TaskChef instruction or when resuming that same executor task. Do not use to dispatch work or report on other TaskChef tasks."
+description: "Execute an assignment carrying either the new exact TaskChef marker-plus-invocation scaffold or an accepted historical first-line TaskChef marker or inline protocol. Includes executor ownership, self-linking, per-turn lifecycle reporting, identity safety, and final semantic state. Use when explicitly invoked by a new delegated instruction or when resuming the same new or historical executor task. Do not use to dispatch work or report on other TaskChef tasks."
 ---
 
 # TaskChef Executor
@@ -9,10 +9,12 @@ Own and execute the delegated assignment in the current Codex task. Do not
 re-dispatch it merely because it concerns TaskChef or a configured project.
 Explicit requests to delegate separate work remain valid.
 
-The instruction's exact first line is
-`<!-- taskchef_id=<full UUID> -->`. Treat that UUID as the TaskChef task ID.
-The assignment is the remaining instruction body; the final explicit skill
-invocation is lifecycle scaffolding, not part of the requested deliverable.
+New instructions present the complete assignment first, followed by one blank
+line, the exact `<!-- taskchef_id=<full UUID> -->` marker, and the final
+explicit skill invocation. Treat that UUID as the TaskChef task ID. The
+assignment is everything before the blank line that precedes the marker; the
+marker and invocation are lifecycle scaffolding, not part of the deliverable.
+Require exactly one marker and do not infer an ID from similar prose.
 
 ## Start every execution turn
 
@@ -66,4 +68,12 @@ Existing delegated tasks may include the former inline ownership, linking, and
 re-dispatching. Prefer `report_state` when available. If an older installed
 TaskChef exposes only `report_result`, follow its inline protocol; after an
 upgrade, the deprecated `report_result` alias remains available for exact
-legacy retries.
+legacy retries. Also accept historical instructions whose exact HTML marker is
+the first line, with or without the former blank line, and the older exact
+first-line `# taskchef_id=<full UUID>` heading. These compatibility forms do
+not change the identity or lifecycle rules above. For either first-line form,
+the assignment follows the marker. Ignore the final executor invocation and
+any recognizable former inline ownership, linking, working-state, or
+result-reporting paragraphs as lifecycle scaffolding; execute the remaining
+task-specific body. Require non-whitespace task-specific content and never
+treat an invocation by itself as an assignment.

package/src/delegation.js

@@ -9,11 +9,34 @@ export const EXECUTOR_WORKING_PARAGRAPH = "After a successful initial link, and
 /** @deprecated Historical v7 inline-prompt snapshot. New delegations use taskchef-executor. */
 export const EXECUTOR_RESULT_PARAGRAPH = "Before ending, read this exact Codex thread again and call TaskChef report_state for the same current working turn with status completed, needs_input, or failed and a concise summary. Use needs_input only for a semantic decision or information the user must provide; a native approval prompt is live Codex state, not a TaskChef result. Do not include secrets, transcripts, or raw command output.";
 export const EXECUTOR_SKILL_INVOCATION = "Use $taskchef-executor to execute and report this delegated TaskChef assignment.";
+const HISTORICAL_RESULT_WITH_TURN_PARAGRAPH = "Before ending, call the TaskChef report_result MCP tool with the marked task ID, this executor's self-linked thread ID, the current turn ID from an exact native read of that same thread, completed, needs_input, or failed, and a concise summary. Never reuse a prior turn ID after a follow-up. Use needs_input only for a semantic decision or information the user must provide; a native approval prompt is live Codex state, not a TaskChef result. Do not include secrets, transcripts, or raw command output.";
+const HISTORICAL_RESULT_PARAGRAPH = "Before ending, call the TaskChef report_result MCP tool with completed, needs_input, or failed and a concise summary. Use needs_input only for a semantic decision or information the user must provide; a native approval prompt is live Codex state, not a TaskChef result. Do not include secrets, transcripts, or raw command output.";
+const HISTORICAL_EXECUTOR_SCAFFOLD_LINES = new Set([
+  EXECUTOR_OWNERSHIP_PARAGRAPH,
+  EXECUTOR_LINK_PARAGRAPH,
+  EXECUTOR_WORKING_PARAGRAPH,
+  EXECUTOR_RESULT_PARAGRAPH,
+  HISTORICAL_RESULT_WITH_TURN_PARAGRAPH,
+  HISTORICAL_RESULT_PARAGRAPH,
+]);
+const HISTORICAL_INLINE_PROTOCOLS = [
+  [EXECUTOR_OWNERSHIP_PARAGRAPH, EXECUTOR_LINK_PARAGRAPH, EXECUTOR_WORKING_PARAGRAPH, EXECUTOR_RESULT_PARAGRAPH],
+  [EXECUTOR_OWNERSHIP_PARAGRAPH, EXECUTOR_LINK_PARAGRAPH, HISTORICAL_RESULT_WITH_TURN_PARAGRAPH],
+  [EXECUTOR_OWNERSHIP_PARAGRAPH, HISTORICAL_RESULT_PARAGRAPH],
+  [EXECUTOR_OWNERSHIP_PARAGRAPH],
+];
+
+function hasTaskSpecificContent(lines) {
+  return lines.some((line) => (
+    line.trim().length > 0 && !HISTORICAL_EXECUTOR_SCAFFOLD_LINES.has(line)
+  ));
+}
 
 const UUID_SOURCE = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
 const UUID_PATTERN = new RegExp(`^${UUID_SOURCE}$`);
 const CODEX_UUID_V7_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 const TASKCHEF_MARKER_PATTERN = new RegExp(`^<!-- taskchef_id=(${UUID_SOURCE}) -->$`);
+const LEGACY_TASKCHEF_MARKER_PATTERN = new RegExp(`^# taskchef_id=(${UUID_SOURCE})$`);
 
 function requireObject(value, name) {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${name} must be an object`);
@@ -89,10 +112,66 @@ export function taskChefMarker(taskId) {
 
 export function parseTaskChefMarker(instruction) {
   if (typeof instruction !== "string") return null;
-  const firstLine = instruction.split(/\r?\n/, 1)[0];
-  const currentMatch = firstLine.match(TASKCHEF_MARKER_PATTERN);
-  if (currentMatch === null) return null;
-  return /^[^\r\n]*\r?\n[\s\S]+$/.test(instruction) ? currentMatch[1] : null;
+  const lines = instruction.split(/\r\n|\r|\n/);
+  const hasHistoricalAssignment = () => {
+    const rest = lines.slice(1);
+    const executorSkillInvocationIndices = rest.flatMap((line, index) => (
+      line === EXECUTOR_SKILL_INVOCATION ? [index] : []
+    ));
+    if (executorSkillInvocationIndices.length > 0) {
+      const bodyLines = rest.slice(0, -2);
+      return executorSkillInvocationIndices.length === 1
+        && executorSkillInvocationIndices[0] === rest.length - 1
+        && lines.at(-1) === EXECUTOR_SKILL_INVOCATION
+        && lines.at(-2) === ""
+        && bodyLines.length > 0
+        && bodyLines[0].trim().length > 0
+        && bodyLines.at(-1).trim().length > 0
+        && hasTaskSpecificContent(bodyLines)
+        && !bodyLines.some((line) => HISTORICAL_EXECUTOR_SCAFFOLD_LINES.has(line));
+    }
+
+    const containsInlineScaffold = rest.some((line) => HISTORICAL_EXECUTOR_SCAFFOLD_LINES.has(line));
+    if (!containsInlineScaffold) return rest.join("\n").trim().length > 0;
+    return HISTORICAL_INLINE_PROTOCOLS.some((protocol) => {
+      const prefix = ["", ...protocol.flatMap((line) => [line, ""])];
+      if (!prefix.every((line, index) => rest[index] === line)) return false;
+      const bodyLines = rest.slice(prefix.length);
+      return hasTaskSpecificContent(bodyLines)
+        && !bodyLines.some((line) => HISTORICAL_EXECUTOR_SCAFFOLD_LINES.has(line));
+    });
+  };
+  const currentMatches = lines.flatMap((line, index) => {
+    const match = line.match(TASKCHEF_MARKER_PATTERN);
+    return match === null ? [] : [{ id: match[1], index }];
+  });
+  const legacyMatches = lines.flatMap((line, index) => {
+    const match = line.match(LEGACY_TASKCHEF_MARKER_PATTERN);
+    return match === null ? [] : [{ id: match[1], index }];
+  });
+  if (currentMatches.length + legacyMatches.length !== 1) return null;
+
+  if (legacyMatches.length === 1) {
+    const [{ id, index }] = legacyMatches;
+    if (index !== 0) return null;
+    return hasHistoricalAssignment() ? id : null;
+  }
+
+  const [{ id, index }] = currentMatches;
+  if (index === 0) {
+    return hasHistoricalAssignment() ? id : null;
+  }
+  const executorSkillReferences = instruction.match(/\$taskchef-executor\b/gi) ?? [];
+  const isTrailingScaffold = index === lines.length - 2
+    && index >= 2
+    && lines[0].trim().length > 0
+    && lines.at(-3) === ""
+    && lines.at(-4).trim().length > 0
+    && lines.at(-1) === EXECUTOR_SKILL_INVOCATION
+    && hasTaskSpecificContent(lines.slice(0, index - 1))
+    && !lines.slice(0, index - 1).some((line) => HISTORICAL_EXECUTOR_SCAFFOLD_LINES.has(line))
+    && executorSkillReferences.length === 1;
+  return isTrailingScaffold ? id : null;
 }
 
 export function prepareDelegation(instruction, { taskId = randomUUID() } = {}) {
@@ -101,14 +180,25 @@ export function prepareDelegation(instruction, { taskId = randomUUID() } = {}) {
     throw new Error("instruction must begin with useful task content on its first line");
   }
   const body = rawBody.replace(/(?:(?:\r\n|\r|\n)[^\S\r\n]*)+$/, "");
-  if (parseTaskChefMarker(body) !== null) throw new Error("instruction already contains a TaskChef marker");
+  if (body.split(/\r\n|\r|\n/).some((line) => (
+    TASKCHEF_MARKER_PATTERN.test(line) || LEGACY_TASKCHEF_MARKER_PATTERN.test(line)
+  ))) {
+    throw new Error("instruction already contains a TaskChef marker");
+  }
   if (/\$taskchef-executor\b/i.test(body)) {
     throw new Error("instruction contains a reserved TaskChef executor skill reference");
   }
+  const bodyLines = body.split(/\r\n|\r|\n/);
+  if (!hasTaskSpecificContent(bodyLines)) {
+    throw new Error("instruction must contain task-specific content, not only TaskChef lifecycle scaffolding");
+  }
+  if (bodyLines.some((line) => HISTORICAL_EXECUTOR_SCAFFOLD_LINES.has(line))) {
+    throw new Error("instruction contains reserved historical TaskChef lifecycle scaffolding");
+  }
   const id = requireUuid(taskId);
   return {
     id,
-    instruction: `${taskChefMarker(id)}\n${body}\n\n${EXECUTOR_SKILL_INVOCATION}`,
+    instruction: `${body}\n\n${taskChefMarker(id)}\n${EXECUTOR_SKILL_INVOCATION}`,
   };
 }
 

package/src/mcp.js

@@ -114,7 +114,7 @@ export function createTaskChefMcpServer({
     },
     async (input) => {
       if (parseTaskChefMarker(input.instruction) !== input.id) {
-        throw new Error("record_task instruction must start with its exact TaskChef marker");
+        throw new Error("record_task instruction must contain its exact TaskChef marker in an accepted scaffold");
       }
       const task = await record(workspace, input);
       return toolResult("task", task, `Recorded TaskChef task ${task.id}.`);

package/src/workspace.js

@@ -737,7 +737,7 @@ async function validateDispatchShape(dispatch, name = "task") {
     id,
     project,
     title: requireString(dispatch.title, `${name}.title`).trim(),
-    instruction: requireString(dispatch.instruction, `${name}.instruction`).trim(),
+    instruction: requireString(dispatch.instruction, `${name}.instruction`),
     threadId: dispatch.threadId === null
       ? null
       : normalizeDurableThreadId(dispatch.threadId, `${name}.threadId`),