arreio 1.0.0-dev.1

package/skills/work/references/task-execution-rules.md

@@ -0,0 +1,116 @@
+---
+title: Task Execution Rules
+description: Authoritative reference for the Execute phase (and the gates Prepare records). Defines the per-task Red/Green/Refactor gates, the retry-limit and blocked-transition policy, the resume policy, the skip transition, and the snapshot-and-continue regression policy. Execute and Prepare defer to these definitions; neither re-encodes them.
+type: reference
+version: 1.0
+timestamp: "2026-08-07"
+---
+
+# Task Execution Rules
+
+Authoritative reference for the **Execute** phase and the per-task gates Prepare records. Defines the per-task **Red/Green/Refactor** gates, the **retry-limit** and **blocked** transition, the **resume** policy, the **skip** transition, and the **snapshot-and-continue** regression policy. Execute enforces these; Prepare records the applicable set and thresholds read-only; neither re-encodes them.
+
+## Core Invariants (inherited from `/plan`)
+
+- **One Acceptance Criterion per task** — each task carries exactly one AC and exactly one `files.test` asserting it.
+- **Test-first** — every task runs Red → Green → Refactor; the failing test is written and confirmed **before** implementation.
+- **Idempotent status** — `completed` tasks are never re-opened and index checkboxes are ticked forward only (never reset).
+
+## Per-Task Gates
+
+| Gate      | Criteria (authoritative)                                                                                                       | On pass                          | On fail                     |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- | --------------------------- |
+| **Red**   | The new test at `files.test[0]` exists and **fails for the right reason** — the assertion matching the AC fires; not a setup/import/compile error. On resume, if the test already passes, the task may already be done (re-check the AC). | Proceed to Green | If it passes immediately: re-check AC → may be `completed`; if setup error: log and fix the test |
+| **Green** | The task's single AC test now passes **and** there is no new regression beyond the Prepare baseline (see Regression Policy).   | Proceed to Refactor              | Increment retry; on retry-limit → `blocked` |
+| **Refactor** | Cleanup of naming/duplication/structure; the AC test stays green **and** no regression. No behavior change.               | Complete transition             | Revert the refactor; retry once; then `blocked` |
+
+## Retry-Limit and Blocked Transition
+
+- **Default retry-limit per task: 2** attempts to reach Green from a confirmed Red.
+- Reaching the limit without Green transitions the task to **`blocked`**:
+  - Set frontmatter `status: blocked` with a recorded `reason` (the failing assertion snapshot, which gate failed, the last error).
+  - Leave the index checklist as `- [ ]` and append `— blocked: <reason>`.
+  - Per the execution mode: `inline`/`serial` pause and surface; `parallel` blocks only dependents in later waves.
+- A `blocked` task is **not auto-retried** on resume — it is carried with its reason (see Resume Policy). To retry it, the user re-runs Work and explicitly proceeds (the task's `status` is reset to `not-started` only on an Edit & Retry of Triage/Prepare).
+
+## Resume Policy (authoritative)
+
+On re-entry (re-running Work), before running each task, read its task-file frontmatter `status`:
+
+| status        | Action on resume                                                          |
+| ------------- | ------------------------------------------------------------------------- |
+| `completed`   | Skip (never re-open); checkbox stays `- [x]` (never reset)               |
+| `blocked`     | Carry with recorded reason; not auto-retried                              |
+| `skipped`     | Carry with recorded reason; not auto-retried                              |
+| `in-progress` | Re-enter the cycle at the appropriate gate (the last-run gate); do not tick the checkbox until a gate passes |
+| `not-started` | Run the full Red → Green → Refactor cycle                                 |
+
+The orchestrator's quality gate #4 requires the end state to be coherent: no task left `in-progress`; the index checklist matches task files.
+
+## Skip Transition
+
+- Skipping a task requires **explicit user confirmation** — never auto-skip.
+- Set frontmatter `status: skipped` with a recorded `reason`.
+- Leave the index checkbox as `- [ ]` and append `— skipped: <reason>`.
+- A `skipped` task is not auto-retried on resume (Resume Policy).
+
+## Complete Transition
+
+When the Refactor gate passes:
+- Set frontmatter `status: completed`.
+- Flip the task file's `## Acceptance Criteria` checkbox to `- [x]`.
+- In `docs/tasks/<work-id>/index.md`, tick that task's row from `- [ ]` to `- [x]` (forward only).
+
+## Snapshot-and-Continue Regression Policy (authoritative)
+
+When Prepare recorded `baseline: snapshot-and-continue` (the suite was red at baseline), a Prepare-recorded **known-failing test set** is the snapshot. Execute's regression gate behaves as follows:
+
+- A failing test in the snapshot is **not** a regression (it was already failing).
+- A **new** failing test (not in the snapshot) **is** a regression and fails the Green/Refactor gate.
+- A snapshot test that now **passes** is an improvement, not a regression (do not block on it; record it for Review).
+
+When `baseline: green`, the snapshot is empty — any failure is a regression.
+
+When `baseline: red` without a snapshot-and-continue decision, Prepare must resolve the policy before Execute runs (it is a Prepare Smart pause trigger).
+
+## Mid-Task Interruption
+
+If Execute is interrupted mid-task:
+- Set frontmatter `status: in-progress` (so a resume re-enters the cycle at the right gate).
+- Do **not** tick the checkbox.
+- On resume, re-enter at the last-attempted gate for that task.
+
+## Per-Task Execution Cycle (Execute Step 3 follows this)
+
+```
+for each runnable task (status not-started | in-progress):
+  gate Red:
+    write/confirm the AC test at files.test[0]
+    run it; assert it fails for the right reason
+    if passes immediately -> re-check AC (may be completed on resume)
+  gate Green:
+    implement minimum code in files.create / files.modify
+    run the AC test; assert green with no new regression (snapshot policy)
+    on fail -> increment retry; on retry-limit -> blocked
+  gate Refactor:
+    clean up; re-run the AC test; assert green with no regression
+    on fail -> revert refactor; retry once -> else blocked
+  complete transition:
+    status -> completed; checkbox -> - [x]; index ticked - [ ] -> - [x]
+```
+
+## Failure-Condition Reference
+
+| Trigger                                                | Outcome per this reference                                  |
+| ------------------------------------------------------ | ----------------------------------------------------------- |
+| Red passes immediately on a `not-started` task         | Re-check AC; if genuinely satisfied, mark `completed`      |
+| Green not reached within retry-limit (2)                | Task → `blocked` with reason + assertion snapshot          |
+| Refactor introduces a regression                        | Revert the refactor; retry once; then `blocked`            |
+| New regression on a `completed` task's Refactor re-run   | Surfaced as a Review Smart pause trigger (do not auto-mark) |
+| Runner command fails (not an assertion failure)         | Category 6 recovery per [error-handling.md](error-handling.md) |
+
+## Notes
+
+- This reference is the single source of truth for gate criteria, the retry-limit, blocked/skip/complete/resume transitions, and the snapshot-and-continue regression policy.
+- Prepare records the applicable set and thresholds **read-only** in the Execution Plan; Execute enforces them; Review verifies they were enforced (not re-defined inline).
+- The 2-attempt default mirrors the per-phase retry-limit philosophy in [error-handling.md](error-handling.md) but is task-scoped (a blocked task is not a phase termination).

package/skills/work/references/templates/artifacts/execution-log.md

@@ -0,0 +1,123 @@
+---
+title: Execution Log Artifact
+description: Template for the Execution Log produced by the Execute phase. Carries the per-task result table (outcome + gate trace + reason), aggregator counts, and the regression-detection summary; consumed by Review.
+type: template
+version: 1.0
+timestamp: "2026-08-07"
+---
+
+# Execution Log Artifact
+
+The product of the **Execute** phase is an Execution Log: a per-task result table with outcomes (`completed` / `blocked` / `skipped`), the Red/Green/Refactor gate trace, and any `reason`, plus aggregator counts and a regression-detection summary. Review consumes it.
+
+## Schema
+
+```yaml
+execute-id: YYYY-MM-DD-NNN-execute
+prepare-id: YYYY-MM-DD-NNN-prepare
+triage-id: YYYY-MM-DD-NNN-triage
+work-id: YYYY-MM-DD-NNN
+work-branch: work/<short-description> | null   # inherited from the Work Manifest
+input-shape: plan-based | task-file | ad-hoc
+interactionMode: detailed | smart | autopilot
+executionMode: inline | serial | parallel
+status: complete
+timestamp: ISO-8601 timestamp
+
+results:                                 # one row per task in execution-list
+  - task-id: <work-id>-T<NN>
+    outcome: completed | blocked | skipped
+    gate-trace:
+      red: { passed: true | false, at: ISO-8601, note: "..." }
+      green: { passed: true | false, at: ISO-8601, note: "..." }
+      refactor: { passed: true | false, at: ISO-8601, note: "..." }
+    retries-used: 0 | 1 | 2
+    reason: null | "[failing assertion snapshot, which gate failed, last error]"   # blocked/skipped only
+    index-checkbox-flipped: true | false   # true only when outcome == completed
+
+aggregators:
+  total: <N>
+  completed: <N>
+  blocked: <N>
+  skipped: <N>
+  in-progress-left: 0                      # must be 0 for task-status coherence (orchestrator gate #4)
+
+regression-detection:
+  baseline-state: green | snapshot-and-continue
+  new-regressions: [test-path or test-id, ...]   # failures beyond the known-failing snapshot
+  snapshot-now-passing: [test-path or test-id, ...] # baseline failures now passing (improvements)
+
+final-index-state:
+  checklist-matches-task-files: true       # docs/tasks/<work-id>/index.md matches task frontmatter status
+  uncompleted-rows: [<task-id>, ...]       # rows still - [] (blocked/skipped)
+```
+
+Also save the Execution Log to `docs/plans/.work/.execute/<execute-id>.md`.
+
+## Validation Rules
+
+- **execute-id:** Required. Format `YYYY-MM-DD-NNN-execute`.
+- **prepare-id, triage-id, work-id, work-branch, input-shape:** Required, inherited (cross-phase consistency).
+- **interactionMode, executionMode:** Both required, identical to the Prepare artifact.
+- **results:** Required. One row per task in `execution-list`. Each row:
+  - `outcome` one of `completed`, `blocked`, `skipped`
+  - `gate-trace` with the three gates; for a `completed` task all three `passed: true`
+  - `reason` recorded for `blocked`/`skipped`; `null` for `completed`
+  - `index-checkbox-flipped` true iff `outcome == completed`
+- **aggregators:** Required. `in-progress-left` must be `0` (task-status coherence — no task left `in-progress`).
+- **regression-detection:** Required. `new-regressions` lists failures beyond the baseline snapshot (per the snapshot-and-continue policy in [task-execution-rules.md](../../task-execution-rules.md)).
+- **final-index-state.checklist-matches-task-files:** Required, must be `true`; else Execute did not leave a coherent state (orchestrator quality gate #4 fails).
+- **status:** Required. `complete`.
+
+## Example (one blocked, rest completed)
+
+```yaml
+execute-id: 2026-08-07-003-execute
+prepare-id: 2026-08-07-002-prepare
+triage-id: 2026-08-07-001-triage
+work-id: 2026-07-10-001
+work-branch: work/redis-session-store
+input-shape: plan-based
+interactionMode: smart
+executionMode: serial
+status: complete
+timestamp: 2026-08-07T15:30:00Z
+results:
+  - task-id: 2026-07-10-001-T01
+    outcome: completed
+    gate-trace:
+      red:    { passed: true, at: 2026-08-07T15:01:00Z, note: "fails on missing client" }
+      green:  { passed: true, at: 2026-08-07T15:05:00Z, note: "all 3 scenarios green" }
+      refactor: { passed: true, at: 2026-08-07T15:06:00Z, note: "thinned wrapper" }
+    retries-used: 0
+    reason: null
+    index-checkbox-flipped: true
+  - task-id: 2026-07-10-001-T02a
+    outcome: blocked
+    gate-trace:
+      red:    { passed: true,  at: 2026-08-07T15:10:00Z, note: "fails on store impl" }
+      green:  { passed: false, at: 2026-08-07T15:14:00Z, note: "TTL test still red after 2 retries" }
+      refactor: { passed: false, at: null, note: "skipped (green not reached)" }
+    retries-used: 2
+    reason: "Green gate: TTL test 'returns null after 1s' fails after 2 retries; TTL not propagated to Redis SET"
+    index-checkbox-flipped: false
+aggregators:
+  total: 2
+  completed: 1
+  blocked: 1
+  skipped: 0
+  in-progress-left: 0
+regression-detection:
+  baseline-state: green
+  new-regressions: []
+  snapshot-now-passing: []
+final-index-state:
+  checklist-matches-task-files: true
+  uncompleted-rows: [2026-07-10-001-T02a]
+```
+
+## Notes
+
+- Task-status coherence (orchestrator quality gate #4) is verified at Review Step 0 and by the `final-index-state` block: every task `completed`/`blocked`/`skipped`, none `in-progress`, and the index checklist matches the task files.
+- `new-regressions` feeds Review's regression check (a non-empty list is a Review Smart pause trigger).
+- The gate trace + `reason` are the primary inputs to Review's learnings-capture (a blocked gate or a refuted assumption becomes a learning candidate).

package/skills/work/references/templates/artifacts/execution-plan.md

@@ -0,0 +1,111 @@
+---
+title: Execution Plan Artifact
+description: Template for the Execution Plan produced by the Prepare phase. Carries the ordered execution-list, selected execution mode, test runner + packageManager, baseline policy, applicable gates, and resume/blocked/skip policy; consumed by Execute.
+type: template
+version: 1.0
+timestamp: "2026-08-07"
+---
+
+# Execution Plan Artifact
+
+The product of the **Prepare** phase is an Execution Plan: an ordered `execution-list` to run, the selected `executionMode`, the resolved test `runner` (+ `packageManager` for Node.js), the `baseline` policy and any known-failing snapshot, and the `applicable-gates` + thresholds (recorded read-only from [task-execution-rules.md](../../task-execution-rules.md)). Execute consumes it.
+
+## Schema
+
+```yaml
+prepare-id: YYYY-MM-DD-NNN-prepare
+triage-id: YYYY-MM-DD-NNN-triage
+work-id: YYYY-MM-DD-NNN
+work-branch: work/<short-description> | null   # inherited from the Work Manifest
+input-shape: plan-based | task-file | ad-hoc
+interactionMode: detailed | smart | autopilot
+executionMode: inline | serial | parallel
+status: complete
+timestamp: ISO-8601 timestamp
+
+test-environment:
+  runner: npm | pnpm | pytest | go | cargo | rspec | phpunit | mvn | gradle | unknown
+  packageManager: npm | pnpm | null     # Node.js only
+  test-command: "[resolved test invocation pattern]"
+
+baseline:
+  state: green | red | snapshot-and-continue
+  known-failing-snapshot: [test-path or test-id, ...]   # only when state == snapshot-and-continue
+
+execution-list:                          # flat for inline/serial; wave-grouped for parallel
+  inline | serial:
+    - <task-id>
+    - <task-id>
+  parallel:
+    waves:
+      - [  <task-id>, ... ]   # Wave 0 (independent)
+      - [  <task-id>, ... ]   # Wave 1 (depends on Wave 0)
+upstream-skipped: false | true           # task-file "Proceed anyway" only
+
+applicable-gates: [red, green, refactor, complete]   # the gates Execute enforces (read-only)
+retry-limit: 2                            # task-scoped; authorized in task-execution-rules.md
+
+policy:                                  # recorded read-only from task-execution-rules.md; not re-derived
+  resume: "completed skipped; blocked/skipped carried; in-progress re-enters; not-started runs"
+  blocked: "green-not-reached-within-retry-limit -> status blocked + reason; checkbox stays -[]"
+  skip: "explicit user confirm only -> status skipped + reason; checkbox stays -[]"
+  complete: "refactor green -> status completed; checkbox -[x]; index tick -[x]"
+  regression: "snapshot-and-continue ignores known-failing-snapshot; green requires no NEW failure"
+
+work-state: ready | nothing-ready         # echoes the Work Manifest if carried through
+```
+
+Also save the Execution Plan to `docs/plans/.work/.prepare/<prepare-id>.md`.
+
+## Validation Rules
+
+- **prepare-id:** Required. Format `YYYY-MM-DD-NNN-prepare`.
+- **triage-id, work-id, work-branch, input-shape:** Required, inherited from Triage (cross-phase consistency).
+- **interactionMode, executionMode:** Both required. `executionMode` must respect the risk floor in [execution-mode-selection.md](../../execution-mode-selection.md) (any HIGH-risk task → `inline`).
+- **test-environment.runner:** Required; `unknown` only allowed when the user was asked to supply the command (Prepare should normally resolve it).
+- **test-environment.packageManager:** Required for Node.js (`npm` | `pnpm`), else `null`.
+- **baseline.state:** Required. `red` without `snapshot-and-continue` is invalid here (Prepare must resolve the policy first).
+- **execution-list:** Required. Preserves the manifest's dependency order; wave-grouping (if `parallel`) respects dependency layers. Empty only when `work-state: nothing-ready`.
+- **applicable-gates, retry-limit, policy:** Required, recorded **read-only** from [task-execution-rules.md](../../task-execution-rules.md) — Execute enforces them; Prepare must not re-encode altered definitions.
+- **status:** Required. `complete`.
+
+## Example (serial, green baseline)
+
+```yaml
+prepare-id: 2026-08-07-002-prepare
+triage-id: 2026-08-07-001-triage
+work-id: 2026-07-10-001
+work-branch: work/redis-session-store
+input-shape: plan-based
+interactionMode: smart
+executionMode: serial
+status: complete
+timestamp: 2026-08-07T14:35:00Z
+test-environment:
+  runner: pnpm
+  packageManager: pnpm
+  test-command: "pnpm test -- <test-path>"
+baseline:
+  state: green
+  known-failing-snapshot: []
+execution-list:
+  - 2026-07-10-001-T01
+  - 2026-07-10-001-T02a
+  - 2026-07-10-001-T02b
+upstream-skipped: false
+applicable-gates: [red, green, refactor, complete]
+retry-limit: 2
+policy:
+  resume: "completed skipped; blocked/skipped carried; in-progress re-enters; not-started runs"
+  blocked: "green-not-reached-within-retry-limit -> status blocked + reason"
+  skip: "explicit user confirm only -> status skipped + reason"
+  complete: "refactor green -> status completed; checkbox -[x]; index tick -[x]"
+  regression: "green requires no NEW failure (snapshot empty for green baseline)"
+work-state: ready
+```
+
+## Notes
+
+- The orchestrator's quality gate #2 cross-checks `interactionMode` and `executionMode` are identical across Prepare/Execute/Review artifacts.
+- `upstream-skipped: true` is set only for the task-file shape when the user chose "Proceed anyway" (Triage Step 2b); the execution-list then contains just that single task.
+- Gate/policy values are **read-only** here: Execute enforces the definitions in [task-execution-rules.md](../../task-execution-rules.md); Prepare must not redefine them (single-source-of-truth).

package/skills/work/references/templates/artifacts/work-input.md

@@ -0,0 +1,78 @@
+---
+title: Work Input Artifact
+description: Template for the Work Input Artifact produced by the Orchestrator. Carries the input shape (plan-id, task-file, or ad-hoc description) and interactionMode; consumed by Triage.
+type: template
+version: 1.0
+timestamp: "2026-08-07"
+---
+
+# Work Input Artifact
+
+The Orchestrator produces a Work Input Artifact as the entry point to the Work workflow. It carries the input shape (one of plan-id, task-file, or ad-hoc description) and the user-selected `interactionMode`. Triage consumes it.
+
+## Schema
+
+```yaml
+type: work-input
+timestamp: ISO-8601 timestamp (e.g., 2026-08-07T14:30:00Z)
+source: user | saved-prompt | document | combination
+status: complete
+interactionMode: detailed | smart | autopilot
+
+# Input shape — exactly one of the following:
+plan-id: YYYY-MM-DD-NNN | null          # plan-based: points at docs/tasks/<plan-id>/index.md
+task-file: docs/tasks/<plan-id>/T<NN>-<name>.md | null   # task-file input (also accepts a task-id like <plan-id>-T03)
+ad-hoc: "<raw work description>" | null  # ad-hoc input
+
+# Optional context carried for ad-hoc:
+goals: [ ... ]
+constraints: [ ... ]
+references: [ ... ]
+```
+
+## Validation Rules
+
+- **type:** Required. Must be `work-input`.
+- **timestamp:** Required. ISO-8601.
+- **source:** Required. One of `user`, `saved-prompt`, `document`, `combination`.
+- **status:** Required. `complete` (the Orchestrator marks it complete once it has the input and the interaction mode).
+- **interactionMode:** Required. One of `detailed`, `smart`, `autopilot`. (If missing, default to `smart`; see [error-handling.md](../../error-handling.md) Category 5.)
+- **Input shape:** Exactly one of `plan-id`, `task-file`, `ad-hoc` must be non-null. If all three are null/empty, the Orchestrator asks: "What would you like to work on? Provide a plan-id, a task file, or describe the task." (Category 3.)
+- **plan-id:** When present, matches `YYYY-MM-DD-NNN` and resolves to a non-empty `docs/tasks/<plan-id>/index.md`. If not, ask to run `/plan <id>` first or switch to ad-hoc.
+- **task-file:** When present, resolves to exactly one task file (or a task-id resolving uniquely). If it matches multiple files, ask the user to disambiguate.
+- **ad-hoc:** When present, a non-empty work description.
+
+## Example
+
+```yaml
+type: work-input
+timestamp: 2026-08-07T09:00:00Z
+source: user
+status: complete
+interactionMode: smart
+plan-id: 2026-07-10-001
+goals: null
+constraints: null
+references: null
+```
+
+Ad-hoc example:
+
+```yaml
+type: work-input
+timestamp: 2026-08-07T09:05:00Z
+source: user
+status: complete
+interactionMode: detailed
+plan-id: null
+task-file: null
+ad-hoc: "Fix the login redirect loop when a session expires mid-request"
+goals: ["Users land on the login page instead of a 500"]
+constraints: ["No new dependencies"]
+references: null
+```
+
+## Notes
+
+- The Orchestrator's Pre-Flight Check ensures `docs/tasks/` and `docs/plans/.work/.{triage,prepare,execute,review}/` exist (self-healing via `mkdir -p`) before handing the Work Input Artifact to Triage.
+- `interactionMode` flows from this artifact into every downstream artifact (Triage → Prepare → Execute → Review); the orchestrator quality gate #2 cross-checks it is identical across all.

package/skills/work/references/templates/artifacts/work-manifest.md

@@ -0,0 +1,119 @@
+---
+title: Work Manifest Artifact
+description: Template for the Work Manifest produced by the Triage phase. Carries the resolved, dependency-ordered task list (one AC per task, one test per task), ready-tasks, related learnings, and any dependency-warning; consumed by Prepare.
+type: template
+version: 1.0
+timestamp: "2026-08-07"
+---
+
+# Work Manifest Artifact
+
+The product of the **Triage** phase is a resolved, dependency-ordered Work Manifest. It normalizes the three input shapes (plan-based, task-file, ad-hoc) into one structure: a list of tasks, each carrying exactly one Acceptance Criterion and one test, ordered by dependency, with status and readiness flags. Prepare consumes it.
+
+## Schema
+
+```yaml
+triage-id: YYYY-MM-DD-NNN-triage
+work-id: YYYY-MM-DD-NNN
+work-branch: work/<short-description> | null      # git branch for this run (Triage Step 2d)
+work-branch-base: <branch-name> | null            # base used when the branch was created
+work-branch-state: created | checked-out | already-on | skipped-by-user | not-a-git-repo
+input-shape: plan-based | task-file | ad-hoc
+interactionMode: detailed | smart | autopilot
+status: complete
+timestamp: ISO-8601 timestamp
+
+# Resolved task list (dependency-ordered; one AC per task)
+tasks:
+  - id: <work-id>-T<NN>
+    title: "[Task title]"
+    unit: U<NN> | U<NN><letter>
+    acceptance-criterion: "[exactly one, verifiable]"
+    files:
+      create: [path/to/file, ...]
+      modify: [path/to/file, ...]
+      test: [path/to/test]          # exactly one
+    priority: P0 | P1 | P2
+    dependencies: [<task-id>, ...]
+    status: not-started | in-progress | completed | blocked | skipped   # current task-file status
+    risk: low | medium | high                  # carried for execution-mode selection
+    ready: true | false                        # deps completed and status not completed
+
+ready-tasks: [<task-id>, ...]                 # subset of tasks runnable this session
+already-complete-tasks: [<task-id>, ...]      # completed tasks (skipped on resume)
+
+related-learnings:                            # per-task; from docs/learn/index.md
+  <task-id>:
+    - docs/learn/XXX.md — [1-line applicability note]
+
+learning-gaps:
+  - gap_name: "[Domain] — [what's missing]"
+    domain: [primary domain]
+    relevance: why this matters for the task
+    suggested_action: "Research external resource" | "Document post-implementation"
+
+dependency-warning: null | proceeded-without-upstream | expanded-to-upstream   # task-file shape only
+work-state: ready | nothing-ready              # nothing-ready if no task is runnable
+```
+
+Also save the manifest to `docs/plans/.work/.triage/<triage-id>.md` for future reference or reuse.
+
+## Validation Rules
+
+- **triage-id:** Required. Format `YYYY-MM-DD-NNN-triage`.
+- **work-id:** Required. For plan-based/task-file, equals the `plan-id` (inherited). For ad-hoc, a freshly allocated `YYYY-MM-DD-NNN` (per [id-generation.md](../../id-generation.md)). The `docs/tasks/<work-id>/` directory must exist (ad-hoc creates it; plan-based already has it).
+- **work-branch:** Required. Format `work/<slug>` (kebab-case, ≤ 50 chars); `null` only when `work-branch-state` is `skipped-by-user` or `not-a-git-repo`. Must be consistent with `work-branch-state` (`created`/`checked-out`/`already-on` require a branch).
+- **work-branch-base:** Required. The base branch used at creation (Triage Step 2d.4); `null` when no branch was created.
+- **work-branch-state:** Required. One of `created`, `checked-out`, `already-on`, `skipped-by-user`, `not-a-git-repo`.
+- **input-shape:** Required. One of `plan-based`, `task-file`, `ad-hoc`.
+- **interactionMode:** Required, propagated from the Work Input Artifact.
+- **status:** Required. `complete`.
+- **tasks:** Required, non-empty unless `work-state: nothing-ready`. Each task must carry:
+  - exactly one `acceptance-criterion` and exactly one `files.test` entry
+  - `files` repository-relative
+  - `dependencies` referencing task-ids that exist (plan-based: in the index; task-file/ad-hoc: in the manifest or parent plan)
+- **ready-tasks:** Required (may be empty). Subset of `tasks` whose dependencies are all `completed` and whose status is not `completed`.
+- **already-complete-tasks:** Required (may be empty). Tasks with `status: completed` — skipped on resume.
+- **related-learnings:** Required (may be empty per task). References `docs/learn/index.md` entries.
+- **dependency-warning:** Required for the task-file shape (`proceeded-without-upstream` or `expanded-to-upstream` record the upstream-dep decision); `null` for other shapes.
+- **work-state:** Required. `nothing-ready` if `ready-tasks` is empty and no task is runnable.
+
+## Example (plan-based)
+
+```yaml
+triage-id: 2026-08-07-001-triage
+work-id: 2026-07-10-001
+work-branch: work/redis-session-store
+work-branch-base: main
+work-branch-state: created
+input-shape: plan-based
+interactionMode: smart
+status: complete
+timestamp: 2026-08-07T14:30:00Z
+tasks:
+  - id: 2026-07-10-001-T01
+    title: "Redis client connects and backs the SessionStore interface"
+    unit: U1
+    acceptance-criterion: "The Redis client connects from REDIS_URL with retry, and SessionStore exports get/save/delete"
+    files: { create: [src/lib/redis-client.ts, src/lib/session-store.ts], modify: [], test: [src/lib/redis-client.test.ts] }
+    priority: P0
+    dependencies: []
+    status: not-started
+    risk: high
+    ready: true
+ready-tasks: [2026-07-10-001-T01]
+already-complete-tasks: []
+related-learnings:
+  2026-07-10-001-T01:
+    - docs/learn/pattern/redis-retry-2026-07-02.md — connection retry pattern reused here
+learning-gaps: []
+dependency-warning: null
+work-state: ready
+```
+
+## Notes
+
+- The manifest is in **dependency order**: no task appears before its dependencies (topological, stable by unit number).
+- The work branch is created in Triage Step 2d, before any task file or index is written; branch setup is idempotent, so a re-run resumes on the same branch. The orchestrator's quality gate verifies branch coherence before Execute.
+- Resume-safe: Prepare/Execute read each task's current `status` from its task file, not from the manifest alone — the manifest is the resolved plan, the task files are the live state.
+- For `task-file` input with the "Proceed anyway" choice, the manifest contains only the single task and `dependency-warning: proceeded-without-upstream`; for "Run upstream first", it contains the unmet upstream tasks plus this task and `dependency-warning: expanded-to-upstream`. Downstream dependents are never included.