@aurorajs.dev/catalyst-cli 1.0.2 → 2.0.0

package/dist/templates/monorepo/.claude/skills/catalyst-backlog/SKILL.md

@@ -0,0 +1,954 @@
+---
+name: catalyst-backlog
+description: >
+  Creates and manages Backlog.md tasks for Aurora Catalyst's headless dispatch workflow: the
+  label taxonomy (`tier:`/`lane:`/`path:`/`mode:`/`bc:`), the milestone and its three gates, the
+  field mapping from a triage decision to `backlog` CLI flags, the dependency-detection step at
+  creation, the supervised-mode floor, the PRD planning loop, subtask
+  rules, the dependency view (`pnpm backlog:graph`) and its graph-holder task, and how to release a
+  `Blocked`
+  task. Trigger: creating a task for a Medium/Complex request, queueing or releasing a task,
+  planning a PRD, archiving a document under `.backlog/docs/`, writing the «Registro de ejecución»
+  block when a task moves to `Done`, or ANY
+  mention of backlog, Queued, Blocked, dispatcher, encolar, PRD, subtarea,
+  milestone, `--depends-on`, grafo, `board:graph`, supervisada, headless, `tier:`, `lane:` or `mode:`
+  — even if the user only says "encola esto" or "por qué está bloqueada T-12".
+  The bare words "task"/"tarea" are deliberately NOT triggers: they appear in almost every prompt in
+  this repo, so a trigger on them fires always and therefore says nothing.
+  Does NOT cover the dispatched worker's own system prompts (see
+  `worker-system-prompt.md` and `frontier-worker-addendum.md`, beside this file) or the
+  reconciler's internals (see
+  `scripts/backlog/README.md`) — this skill is for the orchestrator CREATING and MANAGING
+  tasks, not for the dispatched worker or the dispatcher process itself.
+license: MIT
+metadata:
+  author: aurora
+  version: '1.0'
+  # Literal substrings the UserPromptSubmit hook matches (`.claude/skills-triggers-index.json` is
+  # GENERATED from this list by `.claude/scripts/generate-skills-index.ts`). Every entry must be
+  # unambiguous: `task`, `tarea` and `planificación` were dropped because they appear in nearly
+  # every prompt here, and `tier`/`lane` carry the colon so they match the LABEL rather than the
+  # English words.
+  triggers:
+    - backlog
+    - Queued
+    - Blocked
+    - dispatcher
+    - encolar
+    - subtarea
+    - PRD
+    - milestone
+    - depends-on
+    - grafo
+    - 'board:graph'
+    - supervisada
+    - headless
+    - 'tier:'
+    - 'lane:'
+    - 'mode:'
+    - Registro de ejecución
+---
+
+## When to Use
+
+- Creating a task for a Medium or Complex request (Task-Weight Triage's mandatory rule — every
+  Medium/Complex request gets one, Minor only if the user defers it).
+- Queueing a `To Do` task (`Queued`) or naming one in a session ("trabajemos T-12").
+- Planning a PRD: a request larger than one change, decomposed into pieces.
+- Creating subtasks under a decomposed Complex task.
+- Releasing a `Blocked` task after answering its question.
+- Closing a task: the «Registro de ejecución» block goes into its notes — written by the orchestrator
+  when it opens the PR (supervisada), or by the reconciler when the PR merges (headless). Section 12.
+- Archiving a document under `.backlog/docs/` that nothing live cites any more. Section 14.
+
+Two worker-facing files live beside this one, both passed by the dispatcher via
+`--append-system-prompt-file`, and neither is for the orchestrator that creates tasks:
+
+- `worker-system-prompt.md` — the WHOLE context a local-lane executor gets (it runs `--bare`).
+- `frontier-worker-addendum.md` — a template, rendered per launch, appended on top of the full
+  harness a frontier-lane orchestrator already loads: only the facts an interactive session would
+  have made false.
+
+This SKILL.md is for the orchestrator CREATING and MANAGING tasks on the board.
+
+## 1. Field mapping table
+
+Triage output → `backlog task create`/`task edit` fields. There is no CLI field for "files to
+touch" or "a scoped test command" (see the Note below the table) — the convention this skill
+defines fills that gap.
+
+| Triage output | Field | Flag | Notes |
+| --- | --- | --- | --- |
+| Outcome, one line, no implementation detail | `title` | positional argument | |
+| The WHY: problem, trigger, user value; **and** the `Test command:` / `Files to touch:` lines | `description` | `-d`/`--desc` | See the Note below |
+| feature / bug / chore / docs / spike / enhancement | `type` | `--type` | |
+| Urgency | `priority` | `--priority High\|Medium\|Low` | |
+| `tier:`/`lane:`/`path:`/`mode:`/`bc:` | `labels` | `-l tier:...,lane:...,path:...,mode:...,bc:...` | Comma-separated or repeatable `-l` |
+| The effort this task belongs to — the norm, settled by the gates in section 2.2 | `milestone` | `-m <milestone-id>` | Pass the ID `backlog milestone list` prints (`m-3`), never a retyped title — the field does not validate. See section 2 |
+| Design docs, API specs, manuals | `documentation` | `--doc <path-or-url>` (repeatable) | |
+| GitHub issues/PRs/tickets/URLs | `references` | `--ref <path-or-url>` (repeatable) | |
+| What will be true when done | `acceptanceCriteria` | `--ac <text>` (repeatable) | One atomic, testable item per criterion |
+| Task-specific completion hygiene, beyond the project defaults | `definitionOfDone` (task-specific only) | `--dod <text>` (repeatable) | Do not copy project defaults here — see DoD defaults below |
+| Subtask's parent | — | `-p`/`--parent <taskId>` | Not a milestone id |
+| Ordering between decomposed pieces | `dependencies` | `--depends-on <taskIds>` (`task edit`) | Run the dependency-detection step (section 4.1) before writing this flag — it proposes the candidates and their evidence |
+| Implementation plan | `plan` | `--plan <text>` | **Only** for already-started work created directly in an active status (e.g. `In Progress`) — never at `To Do` creation, and never used by this skill's own creation flow |
+| Progress notes during execution | `notes` | `--notes` (append with `--append-notes`) | Written while working the task, never at creation. A DISPATCHED worker writes them through the dispatcher's wrapper (`scripts/backlog/worker-edit.ts`), its only board command; the orchestrator in an interactive session uses `backlog task edit` directly |
+| PR-style completion summary | `finalSummary` | `--final-summary` (`task edit`) | Written at `Done`, not at creation |
+
+**Note — no native "files to touch"/"test command" fields.** The `backlog` CLI has no flag for
+either, so both are conventions inside `description`, each on its own labelled line, and both are
+parsed back out mechanically by `scripts/backlog/task-view.ts`:
+
+```
+Test command: pnpm --filter backend test -- session.spec.ts
+
+Files to touch:
+- backend/src/@app/o-auth/session/application/refresh.handler.ts
+- backend/src/@app/o-auth/session/application/refresh.handler.spec.ts
+```
+
+`Files to touch:` also accepts an inline comma list on the same line. That list is load-bearing,
+not decoration: it is the allowlist the local lane's close-time scope check runs the real diff
+against, and the list the security-path guard inspects before a task is ever dispatched to
+`lane:local`. Do not invent a new label or field for either — extending `description` is the
+existing declarative surface, not a new one.
+
+Entries are **repo-relative paths**, and the scope check reads three shapes:
+
+| Entry | Covers |
+| --- | --- |
+| `backend/src/@app/o-auth/session/application/refresh.handler.ts` | exactly that file |
+| `backend/src/@app/o-auth/session/` | everything under that directory (note the trailing `/`) |
+| a declared source file | its sibling `.spec.ts` / `.test.ts` too, without declaring it |
+
+The sibling-test rule exists because TDD is mandatory for a dispatched task: declaring
+`refresh.handler.ts` and then blocking the attempt for writing `refresh.handler.spec.ts` would
+punish the executor for obeying the harness. Declare a directory only when the task really owns the
+whole module — the allowlist is the only thing standing between a weak executor and scope creep.
+
+**`Test command:` is MANDATORY on both lanes** — guard 1 blocks a task that declares none, naming
+the missing line, and the close's pre-PR gate refuses to pass an attempt whose "scoped tests pass"
+Definition-of-Done item is still unticked (the close ticks it only when a test actually ran and
+passed). It is executed by the close, so it is restricted to one grammar — the repo's own
+convention and nothing else:
+
+```
+pnpm [--filter <pkg> | --dir <relative-path>] [run] <test | cli:test | test:*> [args…]
+```
+
+The line may also contain no shell metacharacter (`;`, `&`, `|`, backticks, `$(...)`, `<`, `>`), and
+a `--filter` value must be a plain package name, never another flag. Naming `pnpm` is not enough:
+`pnpm dlx <package>` is the same arbitrary-package fetch-and-execute `npx` is refused for, and
+`pnpm add`/`install`/`exec` reach just as far outside this repository. `--dir` is the alternative
+selector, and it exists for `packages/cli`, which is deliberately not a workspace member (root
+`CLAUDE.md`, D8) so `--filter` matches nothing there; its value must be a RELATIVE path with no `..`
+segment. The command is spawned directly, never through a shell. A line that breaks any rule fails
+the close with `test command no permitido` — it is not silently skipped.
+
+The same validated line becomes the executor's ONLY `Bash` permission for running tests
+(`Bash(<command>:*)`, granted per launch), so a task that declares no command leaves its worker
+unable to run one — which is why TDD needs it.
+
+Both lines are read at LAUNCH time and travel with the task from there, so editing them while a
+worker runs changes nothing about how that attempt is verified.
+
+**A subtask's base is always `task/<parentId>` (T-14).** The root `CLAUDE.md`'s Worktree Gate
+mandates that same `task/T-nn` naming for ANY task on the board, interactive or dispatched (T-52),
+so a subtask's base branch is a pure deduction from its parent's id — never something a parent
+declares. `scripts/backlog/guards.ts`'s `taskBaseBranch`/`resolveTaskBase` name that base and check
+it exists on the remote; if it does not, the dispatch guard blocks the subtask, naming both the
+branch it tried and any remote branch whose name mentions the parent's id. (T-15 briefly widened
+this to a `Branch:` description convention that let a parent declare a different real branch, for
+the case where an interactive-session parent lived on `feat/…`/`fix/…`/`refactor/…` — T-52 retired
+it once the Worktree Gate itself started mandating `task/T-nn`, since the override then had nothing
+left to override; the convention was measured to have zero declarations, active or archived.)
+
+A **`lane:local` task with no `Files to touch:` line is blocked by guard 1**, not dispatched: an
+empty allowlist is not "no restriction" — the close's local-lane scope check would report every
+changed file as undeclared, and the security-path guard would have nothing to inspect.
+
+**A task that must change a dependency is not dispatchable at all — on either lane.** `package.json`
+(root or any workspace one), `pnpm-lock.yaml` and `node_modules/` are on the close's HARD path list
+(`guards.ts`'s `SLOT_EXECUTED_PATHS`), so declaring one in `Files to touch:` does not authorise it:
+they define the environment the close then runs Prettier, the barrels lint and the task's own test
+command in, and a rewritten `test` script is code the dispatcher executes moments later. Do the
+dependency change in an interactive session, where a person reads the install and its diff; queue
+the work that USES it afterwards.
+
+**The lists themselves are read in code, not copied here (design.md decision 4d).** The one source
+of truth for which files are refused, and by which mechanism, is `scripts/backlog/guards.ts`'s
+constants — `SUPERVISED_ONLY_PATHS`, `SLOT_EXECUTED_PATHS`, `SLOT_EXECUTED_BASENAMES`,
+`CLAUDE_DIR_SEGMENTS`, `HUMAN_REVIEW_PATHS`, `SECURITY_PATH_PATTERNS`, `LOCAL_FORBIDDEN_PATHS` — and
+`close.ts`'s `MIRROR_OUTPUT_PREFIXES` for the mirror output. Read the constant itself before
+declaring `Files to touch:` against one of these categories, rather than trusting a paraphrase here:
+a copy would go stale the next time a list changes, and it is exactly the AI creating a task that a
+stale copy would mislead.
+
+**Two path lists, split by one criterion (T-31): does the file execute inside the slot during the
+attempt or the close?**
+
+- **HARD** (`SLOT_EXECUTED_PATHS`, plus `SLOT_EXECUTED_BASENAMES` for the one entry matched by
+  basename instead of by path — the instruction file every later reader treats as law, which lives
+  at the root of every scope) — the harness's own settings and local overlay, its hook and script
+  directories, the version-control hooks the close's own commit runs, the package
+  manifest/lockfile/dependency tree the close runs Prettier, the barrels lint and the test command
+  with, the board directory the attempt is judged against, and the two script directories the close
+  SPAWNS from inside the slot: `scripts/packager/` (the mirror regeneration runs it, and it globs
+  and spawns whatever `.mjs` files it finds in its own directory) and `scripts/harness-rules/` (the
+  barrels lint runs `tsx scripts/harness-rules/lint-barrels.ts`). **Declaring one of these in `Files
+  to touch:` blocks the task in the QUEUE** (guard 1c, `slot-executed-path`) — a real session before
+  a slot is ever spent, not a discovery at close. Declaring a DIRECTORY whose subtree contains one
+  blocks it just the same, with or without a trailing slash. Refused at close on both lanes
+  regardless of declaration. The basename entry blocks the same way (guard 1c) for two measured
+  reasons: `lane:local`'s close runs an AI reviewer over the attempt's own diff from inside the slot,
+  and it reads the instruction file it finds there (the executor writing its own examiner's brief);
+  and on EITHER lane a failed attempt's whole slot tree is pushed to `task/<id>` and restored by the
+  retry, so what one attempt writes there is what the next attempt's executor boots reading — and a
+  failed close opens no pull request, so no PR mark would be applied.
+- **HARD, by POLICY** (`SUPERVISED_ONLY_PATHS`) — guard 1e blocks a task that declares one, and the
+  close refuses them on both lanes. The cause is unlike every other entry here: nothing in the slot
+  executes these files, and the harness does not deny the write — the DECISION is architectural. The
+  list holds the framework both applications compile against (widening a decorator or a port there
+  changes every consumer at once, and no test inside the changed package can show that — measured on
+  T-94, 2026-09-16: the framework change was written, the consumer could not compile it, and a whole
+  frontier slot ended in `needs-guidance`) and the dispatcher's own sources (a change there alters
+  the machinery every LATER task is judged by, and it ships to every scaffolded application, where no
+  solution task has any business touching it — a scaffolded application has no generator package of
+  its own to reach instead). By the time such a change is a marked pull request its shape is already
+  settled, which is why the SOFT list below is the wrong instrument even though it looks close.
+  **Do not split a task to smuggle a refused change past this** — the point is that a person decides
+  the shape, not that the change be made in smaller pieces. Queue what is genuinely application-side,
+  and take the rest to an interactive session.
+- **SOFT** (`HUMAN_REVIEW_PATHS`) — the generator package. Admitted, not blocked: the task
+  dispatches normally, and the close marks its pull request `harness-review` for a person to read
+  before merging. When the close FAILS instead, there is no pull request to mark, so the `Blocked`
+  comment names those files — on every failure shape, including the session-level ones
+  (`needs-guidance`, a timeout, an exhausted budget, a crash) and a `board-check` failure, none of
+  which reach the close's scope check at all. On a failure with no scope check behind it the comment
+  carries TWO lists, because the leftover tree is classified exactly as the scope check would
+  classify it: the soft-list paths (read them) and any HARD-list, by-policy or mirror-output path the
+  attempt left behind (remove them — the retry restores that tree into the slot). On `lane:local` a
+  soft path still has to be DECLARED in `Files to touch:` to pass — the undeclared-file check is
+  unchanged.
+
+  **Soft does not mean inert**, and when writing a task it is worth knowing why: admitting the diff
+  is what lets the close run the task's own declared `Test command:` inside the slot, so a soft-list
+  edit can change what that run does — the allowlist admits the generator package's own test script,
+  which spawns the slot's own copy of that suite; and a failed attempt's soft-list edit survives into
+  the retry through the same WIP push described above. What makes this soft is narrower — nothing
+  reads it as INSTRUCTIONS, and the dispatcher itself runs from the main checkout, never the slot.
+
+The mirror output stays refused on both lanes either way (checked first, ahead of either list above)
+— it is the close's own regenerated output, never a worker's writing surface.
+
+## 2. Task taxonomy
+
+### 2.1 Labels
+
+Every task carries all five labels, no exceptions:
+
+| Label | Legal values | Notes |
+| --- | --- | --- |
+| `tier:` | `minor` \| `medium` \| `complex` | Task-Weight Triage's tier |
+| `lane:` | `local` \| `frontier` | **`tier:complex` always implies `lane:frontier`**, regardless of where the task is later queued — the local lane accepts `tier:minor` only (Phase 0 measured one Minor task, not a Medium; see design.md decision (n)) |
+| `path:` | `direct` \| `sdd` | Resolves the frontier lane's orchestrator model: `direct` → Sonnet, `sdd` → Opus |
+| `mode:` | `headless` \| `supervised` | Whether the task may run with no person present. Declared, never inferred: a task with no `mode` has an incomplete triage, and guard 1 blocks it "sin triage" the same as a missing `tier`/`lane`/`path` — it does not default to either value. See section 2.3 for what forces `supervised` and what only raises it as a signal |
+| `bc:` | free text | The bounded context this task's work lives in; not enumerated — there is no fixed BC list |
+
+A **Complex task queued on `lane:local` is a dispatcher guard failure** (`Blocked`, not a silent
+downgrade) — never label a Complex task `lane:local` to "make it fit."
+
+`mode:headless` is a PERMISSION (the task may run without a person; a person can still work it in a
+session — no guard looks at a task that never enters `Queued`). `mode:supervised` is a PROHIBITION:
+guard 0 moves a `Queued` task carrying it straight to `Blocked`, before any other guard even runs,
+with a comment naming the exact exit — see section 10.
+
+### 2.2 Milestone
+
+**A milestone is the norm on a task — proposed every time, never forced.** It is what makes the
+board filterable: without it, two dozen tasks are one undifferentiated list and nobody can tell
+which effort a task serves. Unlike the five labels above, it is not an invariant: a task that
+genuinely belongs to no effort ships with the field EMPTY, and that is an honest record.
+
+`milestone` and `bc:` answer different questions, which is why both exist:
+
+- `bc:` says WHERE the code lives.
+- `milestone` says WHICH effort the task belongs to.
+
+They diverge often. T-19 carries `bc:harness`, because the file it edits lives there, yet it
+belongs to the cross-context relations effort. Filtering by `bc:` buries it among ten dispatcher
+tasks. The milestone is the axis `bc:` cannot provide.
+
+**Granularity.** A milestone groups a CAPABILITY, not a change. It lives for weeks and holds
+several tasks. Test before creating one: if it would hold one or two tasks, it is not a milestone —
+it is the task. One milestone per task is the same disorder under a new name, and a filter with as
+many values as rows filters nothing.
+
+**Which milestone — three gates, in order. The first that matches decides:**
+
+| Gate | Condition | Action |
+| --- | --- | --- |
+| 1 | The task is a subtask (`-p <parent>`) | Inherit the parent's milestone. Mechanical, never asked |
+| 2 | The user named the milestone, OR the session already works inside one (a piece of that PRD, that effort's change directory or worktree) | Assign it, and CITE the evidence in one line |
+| 3 | Anything else | PROPOSE to the user — and accept "none" as a valid answer |
+
+The default is gate 3. Gate 2 does not mean "the orchestrator knows" — a model always believes it
+knows, and that belief cannot be audited. Gate 2 requires a QUOTABLE fact: a sentence the user
+wrote, a change directory, a branch name. No quotable fact, no gate 2.
+
+**How to propose (gate 3).** ONE question. Run `backlog milestone list`, then offer three kinds of
+answer: the active milestones, a NAMED proposal for a new one ("create `Desktop application`?" —
+never the empty "shall we create one?"), and **no milestone at all**. Then STOP and wait: a question
+means stop (root `CLAUDE.md`, Core rules).
+
+**Only the developer decides "no milestone".** The orchestrator proposes; it never ships a task with
+an empty milestone on its own judgement. "This belongs to no effort" is a claim about where the
+project is going, and the person holding that direction is the one who can make it.
+
+**There is no catch-all milestone, and none is to be created.** A `Miscellaneous` bucket existed on
+this board for one afternoon and was removed on 2026-09-09: a catch-all collapses gate 3, because
+every uncertain task lands in it and the filter is back to one undifferentiated list under a longer
+name. It also lies — it reports as "sorted" a task nobody sorted. An empty field says the same thing
+truthfully, and leaves the task visible as an orphan.
+
+**Finding the orphans.** A task with no milestone stays visible — the board grouped by milestone
+puts it in its own group (`backlog board -m`; the binary labels it "No milestone" / "Unassigned
+tasks"). That visibility is half the reason there is no catch-all bucket: an empty field surfaces as
+an orphan, while a `Miscellaneous` row would report it as sorted.
+
+`backlog task list` cannot express the same filter — measured 2026-09-09, `-m ""` is ignored and
+lists the whole board, and `-m none` looks for a milestone actually named "none". For a script, read
+the front matter:
+
+```bash
+for f in .backlog/tasks/*.md; do grep -q '^milestone:' "$f" || grep -m1 '^id:' "$f"; done
+```
+
+**Always assign by ID, never by a typed title.** The front matter stores the milestone's ID
+(`milestone: m-1`), the way `dependencies` stores `T-11` rather than a task's title. Passing the
+EXACT title works too — the CLI resolves it and stores the ID — but the resolution is exact-match
+only, and a miss is silent.
+
+Measured 2026-09-09 on this repo, assigning to a board whose milestones are `m-0`..`m-3`:
+
+| `task edit -m <value>` | Front matter afterwards |
+| --- | --- |
+| `m-3` | `m-3` — resolved |
+| `Miscellaneous` (exact title) | `m-3` — resolved |
+| `Miscelaneous` (one letter short) | `Miscelaneous` — PHANTOM |
+| `misc` (partial) | `misc` — PHANTOM |
+| `xyzzy` | `xyzzy` — PHANTOM |
+
+No error, no warning, exit code 0. A phantom is a value that exists on the task and nowhere else,
+so it groups nothing and `milestone list` never counts it.
+
+Do not confuse this with the FILTER: `backlog task list -m "Cross-context"` IS fuzzy
+("closest match, case-insensitive") and finds the milestone from a fragment. Reading is forgiving;
+writing is not. The asymmetry is the trap.
+
+The order is therefore fixed:
+
+1. For a NEW milestone, run `backlog milestone add "<Title>" -d "<one line>"` FIRST, and read the
+   ID it prints.
+2. Assign the task with that ID (`-m m-3`).
+3. `milestone add` has no `--id` flag — the ID is generated, exactly like a task's. The readable
+   title lives in the milestone filename, in `milestone list`, in the filter, and in `backlog board
+   -m`, which groups the board by milestone in the TUI (`board export -m` ignores the flag and
+   exports the status board instead).
+
+**Do not try to make the ID readable.** Measured 2026-09-09: editing a milestone file's `id:` to a
+slug and renaming the file to match makes the CLI stop seeing the milestone entirely — it vanished
+from `milestone list`. `m-N` is the identity format the tool requires, not a cosmetic default.
+Hand-writing a title into a task's front matter fails the same way: the next `task edit` normalizes
+it back to the ID.
+
+**Headless** (`BACKLOG_DISPATCH_ACTIVE=1`): gates 1 and 2 cover the normal case. Reaching gate 3
+with no person to ask ends the run with `status: needs-guidance` carrying the question, exactly like
+every other gate that needs a human. Never invent a milestone, and never ship the task with an empty
+one to move on — "no milestone" is the developer's answer, not a default the orchestrator may take.
+
+### 2.3 The supervised-mode floor
+
+Choosing `mode:` is part of decomposing the work between the developer and the orchestrator, not
+something this skill derives on its own — that derivation is a separate, later effort (the
+supervisor PRD's Phase 0, which aggregates the «Registro de ejecución» blocks of section 12). What
+this skill does set is a FLOOR under it.
+
+**The floor.** At creation, check the task's declared `Files to touch:` against every path the
+dispatcher refuses on both lanes — `SUPERVISED_ONLY_PATHS`, `SLOT_EXECUTED_PATHS`,
+`SLOT_EXECUTED_BASENAMES`, any path with a `.claude` segment (`CLAUDE_DIR_SEGMENTS`), and the
+packager's mirror output (see section 1's path lists — read the constants, do not keep a second
+copy of their contents). A match forces `mode:supervised`, and the orchestrator states so to the
+developer in ONE line naming the path as evidence, for example:
+
+> T-nn va supervisada: toca `packages/core-back/`.
+
+`mode:headless` on such a task is not a preference to weigh — it is a contradiction the queue would
+only report later as `Blocked`, after the label was already wrong.
+
+**Above the floor, the orchestrator raises signals; it never applies them.** The developer decides
+the value together with the orchestrator while decomposing the work. Signals worth raising:
+
+- a criterion that needs a human eye (a visual review);
+- a decision reserved to a person;
+- a read or migration of the shared database;
+- a foreseen new architectural artifact;
+- a large `.origin` reconciliation after a regen;
+- a cause that may differ from the one the task describes.
+
+**What does NOT rule out headless on its own:** the generator package (soft-listed, not
+supervised-only), a security path on `lane:frontier` (it goes through `/security-review` instead of
+a person), and `tier:complex` (it forces `lane:frontier`, not a person).
+
+## 3. The task rule
+
+- **Minor**: execute now, no task. Create one only if the user explicitly asks to defer it.
+- **Medium or Complex**: always create a task in `To Do`, before any code change, regardless of
+  who will end up working it (a person in a session, or a dispatched worker).
+
+### 3.1 Four rules for what goes into it
+
+**A harness task needs an incident, not a reading.** A task labelled `bc:harness` cites the attempt
+that failed (`.backlog/.dispatch/<id>/intento-N`) or the `Blocked` task that surfaced it. A review
+finding with no incident goes to `scripts/backlog/README.md` → "Accepted risks" as one line, never
+to the board. Reason: measured 2026-09-11 — every closed harness task spawned one to four children
+from review findings alone (T-31 → T-35/36/37/38; T-8 → T-20; T-9 → T-57/58).
+
+**A description a human reads in 30 seconds.** Three labelled blocks, ten lines maximum before the
+mechanical `Test command:` / `Files to touch:` lines: `Problema:` (what breaks, for whom),
+`Evidencia:` (the incident or measurement, with a path), `Hecho cuando:` (one sentence; the
+acceptance criteria carry the detail). Reason: the board owner could no longer understand their own
+tasks — AI-written tasks had become AI-only reading.
+
+**Tasks and PRs are written in Spanish.** Title, description, acceptance criteria, notes and final
+summary of a task, and the title and body of the PR that closes it, are Spanish — the board and the
+PR are where a person reads and decides. Identifiers, paths and commands stay as they are, and the
+two mechanical lines `Test command:` / `Files to touch:` are never translated: `task-view.ts` parses
+them. Code, commit messages, OpenSpec specs and skills stay in English.
+
+**An adjacent fix found in session may ride in the same PR.** Interactive path only: the fix is
+surfaced to the owner and approved, it touches the same subject and files, and it changes no
+acceptance criterion of the task (a task's scope is frozen once it leaves `To Do`). When any of the
+three fails, it goes to the task's notes, and it becomes a task only with an incident behind it
+(first rule above). A dispatched worker never widens: the close measures its diff against
+`Files to touch:` and the forbidden-path lists, and anything outside them blocks the attempt.
+
+## 4. When the orchestrator creates it
+
+| Path | Creation point |
+| --- | --- |
+| SDD (`path:sdd`) | At `/opsx:propose` — the change references the task, and the proposal carries the task id |
+| Direct (`path:direct`), Medium | Before the first code change |
+
+A subtask (SDD decomposition, or a PRD piece) follows the same rule as its own path once
+created.
+
+### 4.1 Dependency detection at creation
+
+Before writing `--depends-on`, compare the new task's `Files to touch:` with every OPEN task's own
+(`To Do`, `Queued`, `In Progress`, `Blocked`) at three levels — the same file; a declared directory
+that contains a declared file; and an overlap of EFFECT, where one task changes what another task's
+output is derived from (a generator template change against a task that regenerates its output). It
+is a judgement step, not a guard: a directory as wide as a whole application tree overlaps with
+almost every task, so a mechanical refusal would block work that is genuinely parallel. Propose
+`--depends-on` for each overlap found, with one line of evidence per link — the shared file, or the
+directory-and-file pair.
+
+**Direction follows what can still be edited.** A task in `Queued` or `In Progress` has its
+dependencies frozen (section 11), so the dependency goes on the NEW task, never on the frozen one.
+When the order has to be the other way — the frozen task should run after the new one — record the
+need as a `--comment` on the frozen task instead of trying to edit its dependencies.
+
+**Listing command.** Reads only, no board write; run it against the MAIN checkout regardless of
+where the session is working. It survives file names with spaces and accents (the board's task
+files have them) because the file name is never re-split:
+
+```bash
+for f in .backlog/tasks/*.md; do
+  status=$(sed -n 's/^status: //p' "$f")
+  case "$status" in
+    "To Do"|Queued|"In Progress"|Blocked) ;;
+    *) continue ;;
+  esac
+  id=$(sed -n 's/^id: //p' "$f")
+  echo "== $id [$status] =="
+  awk '/^Files to touch:/{flag=1; sub(/^Files to touch:[ ]*/, ""); if (length($0)) print; next}
+       /^<!-- SECTION:DESCRIPTION:END -->/{flag=0} flag' "$f"
+done
+```
+
+`--depends-on` REPLACES the whole list on the target task, so repeat any dependency already there
+when adding a new one.
+
+## 5. The PRD planning loop
+
+A request larger than one change becomes a PRD, not a single task:
+
+1. Create a backlog document (`backlog doc create`) and a milestone (`backlog milestone add`) with
+   the user.
+2. Decompose the PRD into pieces. For EACH piece, dry-run the head: Intent Gate, Task-Weight
+   Triage, feature/bug, direct/SDD, lane, mode (section 2.3's floor and signals), files, AC, DoD,
+   allowed new artifacts.
+3. Create every piece as a `To Do` task linked to that milestone by ID (`-m m-4`) — **including
+   Minor pieces**, not just Medium/Complex ones. A PRD is the clearest case of gate 2 in section
+   2.2, not an exception to it: the PRD is simply the case where the answer is already obvious.
+4. Wire cross-piece ordering with `--depends-on`, before either task is queued, using the
+   dependency-detection step of section 4.1 to find the overlaps between the pieces themselves.
+5. The human reviews the full decomposition before any piece is queued.
+
+Triage at this stage is an estimate. A dispatched worker that finds a piece's tier wrong moves it
+to `Blocked` proposing the correction (see release flow below) rather than silently reclassifying
+or executing under the wrong label; in an interactive session, the orchestrator corrects the
+label with the user directly instead.
+
+## 6. Subtask rules
+
+- Create with `-p`/`--parent <taskId>` — never pass a milestone ID to `-p`; the two flags are
+  different fields.
+- **A subtask inherits its parent's milestone** (section 2.2, gate 1). Read the parent's
+  `milestone:` and pass the same ID to `-m`. This is mechanical: never ask which milestone a
+  subtask belongs to, and never let a subtask sit in a different one from its parent.
+- A subtask's branch is created from its **parent's branch**, not from `main`.
+- Its PR targets the **parent's branch**, not `main` — the parent's own PR is what reaches `main`.
+- **The parent's `task/<parentId>` branch must be ON THE REMOTE before a subtask is queued.** It is
+  both the ref the subtask branches from and the ref its close diffs and opens its PR against, so a
+  dispatch guard (`missing-parent-branch`) refuses the subtask and moves it to `Blocked` when that
+  branch is absent — naming the branch it tried and any remote candidate mentioning the parent's id.
+  The refusal lands BEFORE a slot is taken, which is the point: T-4.1 measured the old behaviour,
+  where the branch was missing, the attempt ran to completion on `origin/main` anyway, and the close
+  then failed `scope-check-failed` against a ref dispatch never created — one whole frontier run
+  spent on work nobody could merge. Fix it by creating and pushing `task/<parentId>` with
+  `git push origin origin/main:refs/heads/task/<parentId>`.
+- This bites hardest on the shape the bullet below prescribes: after an INTERACTIVE decomposition the
+  parent goes straight back to `To Do`, so it has no branch at all. A `path:sdd` parent may never be
+  dispatched, and therefore may never grow one on its own.
+- The parent's state is **derived**, never written by hand (`scripts/backlog/parent.ts`'s
+  precedence rule: any child `Blocked` wins; any child `Queued`/`In Progress`, or a `Done`+`To Do`
+  mix, means `In Progress`; all children `Done` plus the parent's own PR merged means `Done`; all
+  `To Do` means `To Do`).
+- **A `tier:complex` parent whose children are all `Done` and whose own PR has NOT merged yet gets
+  enqueued for exactly ONE automated close attempt** (T-8, 2026-09-08, decision "Option B"),
+  instead of parking at `In Progress` forever: the maintenance pass moves it to `Queued` on the
+  frontier lane, and the dispatch hands it a FIXED brief (`scripts/backlog/prompt.ts`'s
+  `buildParentCloseAttemptPrompt`, never the task's own task-derived description) — run the
+  change's verification-gate tasks over the diff `task/<parentId>` now accumulates from every
+  merged subtask, tick `tasks.md` with evidence, write NO new implementation. A confirmed
+  `judgment-day` finding reports `status: needs-guidance` instead of being fixed there, which the
+  close turns into `Blocked` with the full verdict as the comment (section 10 releases it exactly
+  like any other `Blocked` task). A clean run finishes normally and the ALREADY-WIRED close opens
+  `task/<parentId>` -> `main`. This runs exactly once: `scripts/backlog/parent.ts`'s derivation
+  never re-enqueues a Complex parent whose close attempt has already been ENQUEUED — a durable
+  marker `maintenance.ts`'s `recomputeParent` writes the INSTANT rule 4 first fires, not
+  `task.attempts > 0` (T-8 defect 3, 2026-09-08 hardening: a guard block, an abort, or a
+  reconciler crash before the worker ever started used to leave `attempts` at `0` forever, so the
+  same "all Done, not merged" children re-derived `Queued` on every later pass) — so a live retry
+  or a `Blocked` review is never clobbered back to `Queued` by the next maintenance pass. A
+  non-Complex parent, or one with no children, is unaffected.
+- After an SDD design phase splits a Complex task into subtasks: **headless**, the parent moves to
+  `Blocked` asking a person to review the split before queueing; **in an interactive session**,
+  the parent returns straight to `To Do` — the human already approved the split in conversation.
+- **The automated parent close (the bullet above) stops at the merged PR.** It runs the
+  verification gates and opens `task/<parentId>` -> `main`; it never runs `/opsx:archive`, syncs
+  specs, or runs `/business-rules:promote` — those are a PERSON's step after the merge. This is the
+  sixth manual responsibility on this board, beside: creating the task with its triage, moving it
+  to `Queued`, reviewing and merging its PR, answering a `Blocked` question, and applying a pending
+  migration (see `scripts/backlog/README.md`'s "Lane profiles" — a dispatched slot never migrates
+  the shared database on boot).
+
+**Headless decomposition** (no person present) does not go through `backlog task create` at all —
+that command, and the backlog MCP write tools, are both denied to a dispatched worker. Its only
+board write is the same wrapper it uses to report progress, `scripts/backlog/worker-edit.ts`, in a
+second mode.
+
+**The path is never written by hand.** `workerEditCommand` (`scripts/backlog/worker-edit.ts`)
+composes an ABSOLUTE path to the wrapper in the MAIN checkout, and `launch.ts`'s `backlogRulesForTask`
+grants exactly that string — a worker that types the relative form below resolves it against its own
+SLOT (a different copy of the file, with no `BACKLOG_CWD` behind it) and the permission matcher
+denies it before it ever runs. A dispatched worker never composes this path itself either: the
+frontier system-prompt addendum (`frontier-worker-addendum.md`) hands it the already-bound command
+through the `{{WORKER_EDIT_COMMAND}}` placeholder. The shape below stands for that bound command —
+substitute the real one your launch granted, never the bare relative path:
+
+```bash
+<mainCheckoutPath>/scripts/backlog/worker-edit.ts T-10 --subtask \
+  --title "IPC bridge" \
+  --desc-file .claude/worktrees/dispatch-b/subtask-desc.txt \
+  --labels tier:medium,lane:frontier,path:direct,mode:headless,bc:desktop \
+  --ac "Renderer can invoke a main-process handler and receive its result" \
+  --priority Medium --type feature --depends-on T-9
+```
+
+(the real command also carries the `npx --loglevel=error tsx` prefix `workerEditCommand` adds — the
+line above is trimmed to the part that changes per launch)
+
+**Never quote a multi-line `--desc` with `$'…\n…'` (ANSI-C quoting).** T-6 measured four `--subtask`
+invocations out of five DENIED by the Bash permission matcher for exactly that shape — `$'` reads to
+it as a `$` expansion, not a quoted literal, so the command is refused before it ever reaches this
+wrapper. Write the description to a file with the Write tool, inside the worker's own slot, and pass
+`--desc-file <path>` instead (relative, no `..` segment, must exist) — `--desc` and `--desc-file` are
+mutually exclusive.
+
+`<parentId>` is always the worker's own dispatched task — the wrapper refuses a `--parent` flag in
+the argv for the same reason it refuses `-s`/`--status`: the parent is what `BACKLOG_TASK_ID`
+already names, not something the argv gets to reassert. `--title` and `--labels` are mandatory, plus
+exactly one of `--desc`/`--desc-file`; `--labels` must carry exactly one each of
+`tier:`/`lane:`/`path:`/`mode:`/`bc:` with legal values (`tier:complex` still forces `lane:frontier`,
+and **`lane:local` forces `tier:minor`** — T-6 measured this the other way open: only the complex
+case was refused, so a `tier:medium` subtask reached `lane:local`, guard 1 let it through, and
+`resolveLane` only threw later, after a slot was already taken). `mode:` joins the other three's
+exactly-one check for the same reason: a headless split that mints a subtask with no `mode`, or two,
+would otherwise reach the board and let guard 1 block it as an incomplete triage later, after the
+split already happened — the wrapper refuses it before `backlog task create` ever runs instead. The
+description must also carry a `Test command:` line the same allowlist (`resolveTestCommand`)
+accepts — plus a `Files to touch:` line when the subtask is `lane:local`. A subtask that fails any of
+that is refused before `backlog task create` ever runs, exit code 2, same as every other refusal
+this wrapper reports.
+
+If the task's `References:` or description names an EXISTING OpenSpec change under
+`openspec/changes/<name>` — the usual case for a subtask of a split Complex task — `path:sdd` on
+that subtask means `/opsx:apply <name>` on its slice of that change's `tasks.md`, never a second
+`/opsx:propose`: the change already exists, and re-proposing it would fork the design the split
+already agreed on.
+
+After creating the subtasks this way, the worker reports `status: needs-guidance` with the split
+summary — never `completed` — because the parent's move to `Blocked` for a person to review the
+split (the rule two bullets up) is not something the worker itself can trigger; it is what the
+dispatcher's close does once it sees the report.
+
+## 7. Allowed new artifacts
+
+Every task carries an "allowed new artifacts" field, **empty by default**. Leave it empty unless
+the task explicitly anticipates a new architectural artifact (new directory, new category of
+anything, new convention — see the root `CLAUDE.md`'s Architectural Artifact Gate). Anything a
+worker discovers it needs beyond what this field names is NOT a green light to create it: the
+worker stops and asks (session), or moves the task to `Blocked` describing the need (headless) —
+it never creates the artifact itself.
+
+## 8. Entrada-de-prompt gate criterion
+
+One criterion decides whether a prompt naming a task enters its session: **does it express
+intent to work the task now**, or does it only ask about it?
+
+- "trabajemos T-12", "continúa T-12", "haz T-12" → intent to work it → the task moves to
+  `In Progress` directly (never through `Queued`).
+- "¿por qué está bloqueada T-12?", "¿qué hace T-12?" → a question → the task's state is
+  unchanged, no session gate fires.
+
+Before starting a session on a named task, check its current state: `Done` or `Blocked` warns and
+refuses to start; `In Progress` under a live lock warns about the conflict instead of starting a
+competing session.
+
+## 9. DoD defaults
+
+Project-level Definition of Done defaults live in `.backlog/config.yml`'s `definition_of_done`
+list (today: scoped tests pass with the declared command, Prettier and barrels lint pass, every
+AC is checked with evidence, PR opened to `main` or the parent branch). These apply automatically
+to every new task — do not copy them into `--dod` when creating a task. Use `--dod` only for
+genuinely task-specific completion hygiene beyond the project defaults; use
+`--no-dod-defaults` only when a task truly should skip the project defaults (exceptional).
+
+## 10. Releasing a `Blocked` task
+
+1. Read the task's comment — it states the cause and the open question (design.md decision (m):
+   `Blocked` is the ONLY human column, so the comment always carries enough to act on).
+2. Answer the question: correct a mislabeled tier, resolve an ambiguity, approve a decomposition,
+   or fix whatever stopped the push. A `missing-parent-branch` block asks for one concrete action and
+   nothing else: create and push `task/<parentId>` (see section 6), then re-queue. A
+   `slot-executed-path` block (guard 1c, T-31 — see section 1's hard/soft split) also asks for one
+   concrete action: take the named HARD-list file out of `Files to touch:` and do that part of the
+   work in an interactive session, where a person reads the diff — it can never be dispatched, on
+   either lane — then re-queue what remains. A `supervised-mode` block (guard 0) has exactly two
+   exits, named in its own comment: work the task in a session (move it to `To Do`), or, if the label
+   was wrong, edit BOTH labels in the SAME command — `backlog task edit <id> --remove-label
+   mode:supervised --add-label mode:headless` — then re-queue; `--add-label` alone APPENDS rather
+   than replacing, which would leave both `mode:` labels on the task. There is nothing to fix in the
+   work itself.
+   When the comment also lists **rutas de la lista blanda
+   tocadas por el intento**, that is not the block's cause: it is the record that the failed attempt
+   changed a soft-list file (section 1's `HUMAN_REVIEW_PATHS`) with no pull request to mark, and
+   that change is sitting on `task/<id>` waiting for the retry to restore it. Read that diff
+   before re-queueing. A second list, **rutas prohibidas que el intento dejó en el slot**, is the
+   same record's other half and needs the opposite action: those paths are refused on both lanes, the
+   retry would restore them into the slot from `task/<id>`, so remove them from the branch (or drop
+   the branch) before re-queueing.
+3. Record the answer as a comment (`--comment`), then move the task:
+   - `Queued` — the dispatcher retries on the **same branch**, with the prior comment and any
+     reviewer findings carried into the retry prompt automatically.
+   - `To Do` — a person will work it in a session instead.
+
+Never re-queue a task whose `Blocked` question was never answered — that reproduces the same
+failure with a fresh context and no new information.
+
+## 11. Scope freeze after `Queued`
+
+A task's scope is a contract the moment it enters `Queued`: the dispatcher snapshots description,
+AC and DoD at launch and the close fails the attempt if the board says something else (`board-check`),
+and a worker can only tick AC, write notes and plan, and create subtasks. The same discipline binds
+the orchestrator and the person in a session — T-1 accumulated thirteen follow-ups as notes before
+they became tasks, which is exactly the drift this rule prevents.
+
+| State | Frozen (never edit) | Still open |
+| --- | --- | --- |
+| `To Do` | nothing | everything — this is where scope is shaped |
+| `Queued`, `In Progress`, `Done` | title, description (incl. `Test command:` / `Files to touch:`), AC add/remove, DoD, labels, parent, dependencies | `--notes` / `--append-notes`, `--comment`, `--check-ac`, `--plan`, the status |
+| `Blocked` | nothing while the person answers its question: correcting a mislabeled tier or a wrong path is the release flow of section 10 | everything |
+
+Anything new that the work uncovers — a defect, a gap, an improvement, a measurement worth acting on —
+becomes its OWN task, created in `To Do` with `--ref <original-id>` and, when the ordering matters,
+`--depends-on`. Record the discovery as a note or comment on the original task if it explains what
+happened there, but never widen its AC or its `Files to touch` to absorb the new work: the original
+attempt's evidence stops matching its contract, the local lane's scope check has nothing stable to
+judge, and a `Done` stops meaning "this contract was met".
+
+Nothing refuses a frozen edit AT EDIT TIME — `backlog task edit` on a `Queued`/`In Progress`/`Done`
+task accepts a title, description or AC change mechanically. The guard is downstream: the
+dispatcher snapshots the board at launch, and the close's `board-check` step re-reads the task and
+compares it against that snapshot before trusting anything else — a mismatch diverts the attempt
+(`board-check-failed`) rather than letting it proceed against a contract the worker never saw.
+
+## 12. The «Registro de ejecución» block at close
+
+Every task carries, in its notes, a fixed-field record of HOW its execution went, present by the time
+it moves to `Done`. The purpose is not narrative. Phase 0 of the supervisor PRD (`.backlog/docs/doc-6`)
+AGGREGATES these records to derive the headless/supervisada rule, so every field is written to be
+counted, not to be read.
+
+The block is IDENTICAL on both paths — only the author changes:
+
+| Path | Who writes it | Where the data comes from |
+| --- | --- | --- |
+| headless | the reconciler's maintenance pass (`scripts/backlog/maintenance.ts`), at the `Done` transition it makes when the PR merges | `.backlog/.dispatch/<id>/intento-N` and the PR |
+| supervisada | the orchestrator, when it opens the PR — before the merge | the session itself and the PR |
+
+### 12.1 The template
+
+Prose in this skill is English; the block itself is **Spanish**, like every task and PR on this
+board. Copy it verbatim — the PRD's §6 holds the same template, and the two must not drift.
+
+```markdown
+## Registro de ejecución
+
+- **Modo:** headless | supervisada — <motivo de la elección>
+- **Resultado del intento 1:** Done | reintento | Blocked (<causa>)
+- **Rondas de corrección:** <número> — revisor: code-review | judgment-day | supervisor | humano | ninguno
+- **Arreglos posteriores al merge:** <PR que referencian la tarea tras su merge> | ninguno conocido al cierre
+- **Intervenciones humanas:** <número> — tipo: respuesta a Blocked | corrección de triaje | rescate de rama | otra | ninguna
+- **Fallos de entorno:** cuota | LM Studio | red | ninguno
+- **Tiempo de ciclo:** <Queued → Done, p. ej. 4h 12m (2026-09-13 20:06 → 2026-09-14 00:18)>
+- **Fuente:** <.backlog/.dispatch/T-nn/intento-N | PR #nnn | sin evidencia>
+```
+
+### 12.2 Five rules that make it countable
+
+1. **Eight fields, always all eight, always in this order.** A missing line is a parse failure, not
+   an empty value. A reader that has to guess whether a field is absent or zero cannot aggregate.
+2. **One field per LINE, never wrapped.** The aggregation that reads these is a one-line parser, and
+   a wrapped value hides everything after the first line from it — the same constraint that already
+   bites the OpenSpec and business-rules parsers.
+3. **The three "empty" values are NOT interchangeable.** This is the rule that protects the
+   aggregate; confusing them manufactures data that was never measured:
+
+   | Value | Meaning | Example |
+   | --- | --- | --- |
+   | `ninguno` / `ninguna` | Measured. It did not happen. | `**Fallos de entorno:** ninguno` |
+   | `desconocido` | No data exists. Never estimate one. | `**Tiempo de ciclo:** desconocido` |
+   | `sin evidencia` | `Fuente` only: no attempt directory and no PR. | `**Fuente:** sin evidencia` |
+
+4. **Two fields have a known limit at close time. Do not let them invent a value.**
+   - `Arreglos posteriores al merge` cannot be known when the task closes: those PRs do not exist
+     yet. Write `ninguno conocido al cierre`. A later PR that references the task updates the line.
+   - `Tiempo de ciclo` needs two stamps, and today nothing records a status transition. Backlog.md's
+     `onStatusChange` does receive `OLD_STATUS` and `NEW_STATUS` (`.backlog/config.yml` routes that
+     event to the dispatcher, and `scripts/backlog/entry.ts` acts only on `→ Queued`), but no stamp
+     file survives it, and the task front matter carries only `created_date` and `updated_date`. So
+     the field is `desconocido` unless the attempt directory dates both ends.
+5. **`Fallos de entorno` stays separate from the task's own fitness.** A quota cut, an LM Studio
+   health failure or a network drop says nothing about whether the task suited the lane. Merging the
+   two is what makes the headless/supervisada decision ambiguous in the first place.
+
+### 12.3 How it is written
+
+The block goes in with `--append-notes` — notes stay open after the scope freeze of section 11, so
+this is the one field a task may still receive while `Queued`, `In Progress` or `Done`.
+
+**Nobody moves a task to `Done` by hand.** On BOTH paths the reconciler makes that transition when
+the `task/T-nn` PR merges (`maintenance.ts` step 3; `recomputeParent` for a parent). That decides
+when each author writes:
+
+- **headless** — the reconciler composes the block from the attempt directories and appends it
+  immediately BEFORE the `Done` transition. A failed write never blocks the transition; it leaves one
+  comment on the task instead, and a person fills the block in by hand from the template above.
+- **supervisada** — the orchestrator appends the block when it opens the PR, the last moment it still
+  owns the task, and updates the `Arreglos posteriores al merge` line if a later PR references the
+  task. Do NOT pass `-s Done`: the merge moves the task.
+
+The `## Registro de ejecución` heading, on a line of its own inside the notes section, is the
+sentinel: the block is written ONCE per task. A pass that finds the heading leaves the notes alone,
+so an orchestrator's block always wins over the reconciler's.
+
+**The reconciler's fallback for a supervisada task.** If the orchestrator's block is missing at
+merge, the reconciler writes one anyway. It measures one fact: `attempts === 0`, meaning the
+dispatcher never launched the task. That block reads `Modo: supervisada — desconocido`,
+`Intervenciones humanas: desconocido — tipo: desconocido`, `Fuente: PR #nnn`, and `desconocido` in
+every field only the session could know. It is countable but nearly empty — Phase 0 needs the
+orchestrator's own block, so write it.
+
+**Known limit.** A task dispatched at least once and then finished in session has `attempts > 0`,
+so the reconciler's fallback records it as `headless`. The orchestrator that finishes it MUST write
+its own block, which the sentinel then preserves.
+
+## 13. The dependency view
+
+`pnpm backlog:graph` renders every OPEN task (`To Do`, `Queued`, `In Progress`, `Blocked`) as a flat
+list, not a tree — dependencies form a DAG, and a tree would repeat a task that has two parents. Two
+sections, each task on one self-contained line: `LISTAS — sin dependencias abiertas` (no recorded
+open wait), and `EN ESPERA` (waits for at least one, naming every one it waits for). "Recorded" is
+two things merged, deduplicated: a task's declared `dependencies`, AND its own open subtasks — a
+parent waits for every open subtask exactly like an open dependency, a `Done` subtask is no wait,
+and a subtask never waits for its own parent this way. No link is ever guessed from which files two
+tasks touch. The waiting section is a topological order, so a task never appears before what it
+waits for. It reads the board fresh at call time, in the main checkout, and edits nothing — this is
+the interface an AI consumer reads, never the graph-holder task described below, which can lag it by
+one maintenance pass. `pnpm backlog:graph --write` also refreshes that task immediately, instead of
+waiting for it.
+
+**Check the exit code, not just the text.** The command reports a partial board read on stderr
+BEFORE printing the view — a task waiting on one that could not be read would otherwise render
+under "LISTAS" with no caveat in sight — and ends with a non-zero exit code whenever it has anything
+to report: an unrecognized argument (refused before anything runs), a partial board read, more than
+one `board:graph` holder, or a failed underlying read/write. `0` means "printed / refreshed /
+nothing to do" and nothing else, with or without `--write`. An AI consumer that only reads stdout can
+miss all of this — check the exit code.
+
+**The view shows RECORDED links only.** A task listed under "LISTAS" has no declared open dependency
+and no open subtask — that is not the same as having no conflict with other work in progress. The
+view informs about order; it does not authorize queueing any task. Section 4.1's detection step is
+what the view's accuracy actually depends on.
+
+**The graph-holder task.** One task on the board, found by the label `board:graph` (never by a task
+id — this tooling ships to scaffolded applications, whose boards number tasks differently), carries
+the rendered view as its own description, so the order is visible on the terminal board — which
+shows tasks and nothing else; neither a card nor its detail popup shows a dependency anywhere else.
+Pin it with a low `--ordinal`, label it `mode:supervised`, and give it no `Test command:` — it is
+never queued, worked or closed, and a `Queued` holder carrying `mode:supervised` would be refused by
+guard 0 ALONE: guard evaluation is first-wins, so guard 1's separate "no test command" reason never
+even runs against it. Zero holders on a board is a valid state — the feature is simply off. Two or
+more is an ambiguity, reported by the refresh: the VIEW is written to none of them, but each holder
+that does not already show it gets a plain-text notice instead, naming every id and saying to keep
+the label on only one — removing it from all but one brings the view back on the next refresh.
+
+**The refresh REPLACES THE WHOLE DESCRIPTION, without reading it first.** Whichever text a holder's
+description carries — the view, the ambiguity notice, or anything a person wrote by hand — the next
+refresh overwrites all of it outright, on both `pnpm backlog:graph --write` and the maintenance
+pass. This is accepted behaviour: `board:graph` declares that a task's description is machine-owned
+from now on, so never put the label on a task whose description is worth keeping (see
+`scripts/backlog/README.md`'s "Accepted risks").
+
+**Refresh timing.** The maintenance pass refreshes the holder on every one of its three triggers (a
+status-change callback, the `launchd` timer, and the periodic `gh` poll), as one step between
+recomputing every parent's derived state and committing the board — so a status change shows at
+once, and a task created or a dependency edited within one timer interval shows on the next pass. It
+writes only when the rendered text differs from the holder's current description, so a pass over an
+unchanged board produces no edit and no commit; it is skipped whole over an incomplete board read,
+since a view derived from part of the board would show a waiting task as ready; and a failure in the
+refresh is reported and never stops the rest of the pass — closing merged tasks, recomputing
+parents, and committing the board all proceed regardless.
+
+## 14. Archiving a document
+
+A document under `.backlog/docs/` is usually the deliverable of one task (a ledger, an inventory, a
+PRD). It is archived when **nothing live cites it any more** — not when its task reaches `Done`. Live
+means an open task, an active milestone, code, a skill, or an active OpenSpec change; a `Done` task
+and an archived OpenSpec change do not count. The task's status is the wrong test: a spike can be
+`Done` while the milestone it spawned still names its inventory as the source of the work ahead.
+
+```bash
+# Who still cites it? Tracked files only, so ignored files are never read.
+git grep -l -- "<file name or doc id>" -- ':!.backlog/docs'
+```
+
+Archive = move it to `.backlog/archive/docs/T-nn/`, the folder named after the task that produced it
+(capital `T`), with `git mv`. Backlog has no `doc archive` command, and the location is load-bearing:
+`backlog doc list` and the browser panel read `.backlog/docs/` recursively, so a subfolder INSIDE
+`docs/` keeps the document listed; they do not read `.backlog/archive/`. Then rewrite the old path in
+the `.backlog/completed/` tasks that cite it, so their `documentation`/`references` still resolve.
+Archived OpenSpec changes that cite the old path stay as they are — a frozen record.
+
+A document written by hand needs the Backlog front matter (`id: doc-N`, `title`, `type`,
+`created_date`) to be listed at all; the file name does not register it. An archived document leaves
+id allocation together with the listing: with `doc-9` archived, the next `backlog doc create` issued
+`doc-9` again (measured 2026-09-19). Cite a document by its PATH, never by its id alone.
+
+## Commands
+
+```bash
+# Create a Medium direct task, To Do, before the first code change
+backlog task create "Fix session expiry redirect" \
+  --desc $'Users are bounced to /login with no message when the session token expires mid-request.\n\nTest command: pnpm --filter backend test -- session.spec.ts\n\nFiles to touch:\n- backend/src/@app/o-auth/session/application/refresh.handler.ts\n- backend/src/@app/o-auth/session/application/refresh.handler.spec.ts' \
+  --type bug --priority High \
+  -l tier:medium,lane:frontier,path:direct,mode:headless,bc:o-auth \
+  --ac "Expired-token requests redirect to /login with a visible message" \
+  --ac "A refreshed token never triggers this redirect" \
+  --ref "https://github.com/aurora/aurora-catalyst/issues/123"
+
+# Queue it for the dispatcher
+backlog task edit T-42 -s Queued
+
+# From a worktree slot, the CLI must read/write the MAIN checkout's board state (design.md
+# decision (l): backlog state lives only there) — point it there with BACKLOG_CWD
+BACKLOG_CWD=/Users/carlos/Projects/aurora/aurora-catalyst backlog task view T-42 --plain
+
+# Create a PRD document (opens the editor for content; use `doc update --content` to set it
+# non-interactively) and a milestone, then a decomposed piece (including a Minor one)
+backlog doc create "Desktop application" -t specification
+backlog doc update doc-1 --content "$(cat prd-desktop-app.md)"
+backlog milestone add "Desktop application" -d "Electron shell, IPC bridge, UI adaptation, packaging"
+# -> prints: Created milestone "Desktop application" (m-4).  Use THAT id below, not the title:
+# an inexact title is stored verbatim as a phantom milestone, silently (section 2.2).
+# Both convention lines are guard-1 blockers: "Test command:" on EITHER lane, and
+# "Files to touch:" additionally on lane:local.
+backlog task create "Electron shell setup" -m m-4 \
+  -l tier:minor,lane:local,path:direct,mode:headless,bc:desktop \
+  --desc $'Bootstrap the Electron main process so the renderer can be loaded.\n\nTest command: pnpm --filter aurora-desktop test\n\nFiles to touch:\n- desktop/src/main.ts\n- desktop/src/window.factory.ts' \
+  --ac "App window opens and loads the renderer"
+
+# Record a dependency between two decomposed pieces
+backlog task edit T-12 --depends-on T-11
+
+# Create a subtask under a decomposed Complex task
+# A subtask inherits the parent's milestone — same id, no question asked
+backlog task create "IPC bridge" -p T-10 -m m-4 \
+  -l tier:medium,lane:frontier,path:direct,mode:headless,bc:desktop \
+  --ac "Renderer can invoke a main-process handler and receive its result"
+
+# Gate 3 of section 2.2: no milestone is obvious. List them, PROPOSE, then assign the id the
+# user picks — or leave `-m` off entirely if they answer "none".
+# Reading is fuzzy, writing is not: `-m misc` would store the string "misc" as a phantom.
+backlog milestone list
+backlog task list -m "Cross-context" --plain   # the FILTER accepts a fragment
+
+# Tasks with no milestone: visible as their own group in `backlog board -m` (TUI).
+# `task list` has no equivalent filter, so for a script read the front matter:
+for f in .backlog/tasks/*.md; do grep -q '^milestone:' "$f" || grep -m1 '^id:' "$f"; done
+
+# Release a Blocked task: read the comment, answer it, then re-queue on the same branch
+backlog task view T-42 --plain
+backlog task edit T-42 --comment "Corrected tier to Medium per the worker's proposal." -s Queued
+
+# Supervisada close: append the «Registro de ejecución» block (section 12) when the PR opens.
+# No -s Done: the reconciler moves the task when the PR merges. Quoted heredoc: the block has
+# backticks and «».
+backlog task edit T-42 --append-notes "$(cat <<'REGISTRO'
+## Registro de ejecución
+
+- **Modo:** supervisada — toca `.claude/`, que ningún carril del despachador puede escribir
+- **Resultado del intento 1:** Done
+- **Rondas de corrección:** 0 — revisor: ninguno
+- **Arreglos posteriores al merge:** ninguno conocido al cierre
+- **Intervenciones humanas:** 1 — tipo: otra
+- **Fallos de entorno:** ninguno
+- **Tiempo de ciclo:** desconocido
+- **Fuente:** PR #181
+REGISTRO
+)"
+```