iter or.1.4: carrier switch task_text -> task_text_path

2026-05-11 11:30:32 +02:00
parent 3361851b66
commit 1b78896bcc
2 changed files with 17 additions and 16 deletions
@@ -44,7 +44,7 @@ direct neighbours. Don't pre-read the whole crate.

 | Field | Content |
 |-------|---------|
-| `task_text` | The full text of one task from `docs/plans/<iteration>.md`, including code blocks and step checkboxes — verbatim |
+| `task_text_path` | Absolute path to a file (typically `/tmp/ail-iter/<iter_id>/task-<N>.md`) containing the verbatim task block extracted from the plan. Read this file as your first action. |
 | `scene_set` | Parent milestone, where this task fits, dependencies on earlier completed tasks |
 | `cross_task_context` | Shared types, file structure decisions, naming conventions agreed for the iteration |
 | `mode` | `standard` (plan-driven) or `mini` (debug handoff: RED test path + cause summary + minimal-fix constraint) |
@@ -100,10 +100,10 @@ the test.
 ## The Process

 1. Read the standing list (CLAUDE.md, DESIGN.md, latest per-iter journals).
-2. Read the carrier in full. Confirm `task_text` is concrete (no TBD, no
-   "similar to Task N"). If it contains placeholders, return `BLOCKED` with
-   "plan placeholder" — the plan failed self-review and must be fixed
-   upstream.
+2. Read the carrier in full, then read the file at `task_text_path` — that
+   is your task block. Confirm it is concrete (no TBD, no "similar to Task
+   N"). If it contains placeholders, return `BLOCKED` with "plan placeholder"
+   — the plan failed self-review and must be fixed upstream.
 3. Read the files the task touches plus immediate neighbours.
 4. **TDD check on the task text:**
   - Does this task add behaviour (new function, new code path, new error
@@ -193,9 +193,9 @@ and stop. Do not implement on a hunch.
 - About to commit on red tests
 - About to skip the self-review re-read of the diff
 - About to report `DONE` while a concern is unspoken
- About to substitute a "better" approach for the one in `task_text`
+- About to substitute a "better" approach for the one in the task block at `task_text_path`
 - About to open `docs/plans/...` or `docs/specs/...` directly when
-  `task_text` should already contain what you need
+  the file at `task_text_path` should already contain what you need
 - About to write production code while the corresponding RED test does
  not yet exist (or has not yet been run + observed to fail)
 - About to mark a refactor `DONE` without re-running `cargo test --workspace`
@@ -43,13 +43,13 @@ hands you the task text — that's your spec for this review.

 | Field | Content |
 |-------|---------|
-| `task_text` | The full text of the task, verbatim — the same text the implementer received |
+| `task_text_path` | Absolute path (typically `/tmp/ail-iter/<iter_id>/task-<N>.md`) — same file the implementer received. Read this file as your first action. |
 | `diff` | The implementer's diff, either inline or as `git diff <pre-task>..HEAD` |
 | `pre_task_sha` | Commit SHA before the implementer's first change (so you can re-derive the diff) |
 | `head_sha` | Commit SHA after the implementer's last change |
 | `status_from_implementer` | `DONE` or `DONE_WITH_CONCERNS` — if `DONE_WITH_CONCERNS`, the concerns are quoted so you can decide if they affect spec compliance |

-If `task_text` and `diff` aren't both present, return `NEEDS_CONTEXT`.
+If `task_text_path` and `diff` aren't both present, return `NEEDS_CONTEXT`.

 ## The Iron Law

@@ -65,11 +65,11 @@ prevents. Quality goes to the next reviewer.

 ## What "missing" means

-A requirement from `task_text` is **missing** when:
+A requirement from the task block at `task_text_path` is **missing** when:
 - The diff doesn't contain code that would satisfy it, AND
 - The existing code (pre-diff) doesn't already satisfy it.

-A code block in `task_text` is the implementer's contract. If the task
+A code block in the task block is the implementer's contract. If the task
 shows a function signature, the diff must produce that signature (or one
 that subsumes it). If the task shows a test, the diff must contain that
 test. The bar is *literal correspondence*, with reasonable allowance for:
@@ -85,7 +85,7 @@ they have a reason.
 ## What "unrequested extra" means

 A change in the diff is **unrequested** when:
- It is not described in `task_text` (not as a step, not as a code block,
+- It is not described in the task block (not as a step, not as a code block,
  not as a `Files:` entry), AND
 - It is not strictly required to make the requested changes compile or
  pass.
@@ -101,13 +101,14 @@ Examples:
 ## The Process

 1. Read the standing list and the carrier.
-2. Read `task_text` in full. List the requirements as a checklist:
-   every "step", every code block, every `Files:` entry.
+2. Read the file at `task_text_path` in full — that is the task block.
+   List the requirements as a checklist: every "step", every code block,
+   every `Files:` entry.
 3. Re-derive the diff: `git diff <pre_task_sha>..<head_sha>`. Skim once
   for orientation.
 4. For each requirement, locate the satisfying code in the diff.
   Mark it ✓ or ✗.
-5. For each chunk in the diff, check whether `task_text` requested it.
+5. For each chunk in the diff, check whether the task block requested it.
   Mark requested or extra.
 6. Confirm any test the task scripted (RED-first or otherwise) actually
   exists in the diff. A "RED test" that's never been seen failing is
@@ -149,7 +150,7 @@ At most 200 words, structured:
 | Excuse | Reality |
 |--------|---------|
 | "Diff also fixes a typo in an adjacent comment — too small to flag" | Flag it. Two unrequested extras per task become twenty across an iteration. The orchestrator sets the bar; you supply the data. |
-| "Task said 'add error handling' — diff added a `?` and a `Result<>`. Close enough" | "Add error handling" without a code block is vague. If `task_text` has no specifics, return `unclear` and ask. |
+| "Task said 'add error handling' — diff added a `?` and a `Result<>`. Close enough" | "Add error handling" without a code block is vague. If the task block has no specifics, return `unclear` and ask. |
 | "Spec compliance + quality issue overlap — let me note both" | No. Quality is the next reviewer's domain. Note only spec issues. |
 | "Implementer's `DONE_WITH_CONCERNS` says they noticed an issue too — agree and approve" | Re-derive your verdict from the diff and the task text, not from the implementer's self-report. They may have anchored on the wrong concern. |
 | "Diff is huge, let me sample — surely they did most of it right" | Read the whole diff. Spec compliance is a property of the entire diff, not a sample. |