@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

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

@@ -2,12 +2,17 @@
 name: catalyst-backlog
 description: >
   Creates and manages Backlog.md tasks for Aurora Catalyst's headless dispatch workflow: the
-  label taxonomy (`tier:`/`lane:`/`path:`/`bc:`), the milestone and its three gates, the
-  field mapping from a triage decision to `backlog` CLI flags, the PRD planning loop, subtask
-  rules, and how to release a `Blocked`
+  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, or ANY mention of backlog, Queued, Blocked, dispatcher, encolar, PRD, subtarea,
-  milestone, `tier:` or `lane:` — even if the user only says "encola esto" or "por qué está bloqueada T-12".
+  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
@@ -33,8 +38,15 @@ metadata:
     - subtarea
     - PRD
     - milestone
+    - depends-on
+    - grafo
+    - 'board:graph'
+    - supervisada
+    - headless
     - 'tier:'
     - 'lane:'
+    - 'mode:'
+    - Registro de ejecución
 ---
 
 ## When to Use
@@ -45,6 +57,9 @@ metadata:
 - 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:
@@ -68,14 +83,14 @@ defines fills that gap.
 | 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:`/`bc:` | `labels` | `-l tier:...,lane:...,path:...,bc:...` | Comma-separated or repeatable `-l` |
+| `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`) | |
+| 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 |
@@ -137,24 +152,16 @@ 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.
 
-**`Branch:` — the parent's real worktree branch (T-15).** A third convention, written on a **parent**
-task by the person who created its worktree branch (`superpowers:using-git-worktrees`, per the root
-`CLAUDE.md`'s Worktree Gate):
-
-```
-Branch: fix/parent-branch-resolution
-```
-
-A parent worked in an interactive session does not live on `task/<id>` — it lives on a
-conventional-commit branch (`feat/…`, `fix/…`, `refactor/…`), the name the Worktree Gate mandates.
-`scripts/backlog/guards.ts`'s `taskBaseBranch`/`resolveTaskBase` resolve a **subtask's** base
-through this chain, in order: (1) the parent's declared `Branch:` line, when it has one; (2) absent
-that, the `task/<parentId>` convention, exactly as before T-15; (3) if neither branch exists on the
-remote, the dispatch guard blocks the subtask, naming both the branch it tried and any remote
-branch whose name mentions the parent's id. Only the **parent's own** `Branch:` line is read — a
-subtask never declares one for itself, and could not forge its parent's even if it tried: the
-convention is parsed off the parent task's own description, which a dispatched subtask worker holds
-no edit grant on.
+**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
@@ -168,11 +175,22 @@ command in, and a rewritten `test` script is code the dispatcher executes moment
 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`) — 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
+- **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
@@ -180,61 +198,76 @@ attempt or the close?**
   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 (`- .claude/` and `- .claude` both).
-  Refused at close on both lanes regardless of declaration.
-- **HARD, by BASENAME** (`SLOT_EXECUTED_BASENAMES`) — `CLAUDE.md`, at any depth and in any casing.
-  Same treatment as the paths above: guard 1c blocks a task that declares it, and the close refuses
-  it on both lanes. A task that needs to touch any `CLAUDE.md` belongs in an interactive session.
-  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.
-- **SOFT** (`HUMAN_REVIEW_PATHS`) — the dispatcher's own sources (`scripts/backlog/`) and the
-  generator package (`packages/cli/`). 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 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 — and `scripts/backlog/` stays refused on that lane regardless,
-  because the wider `scripts/` local-lane extra still catches it.
+  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 under `scripts/backlog/` can change what that run does; and a failed attempt's soft-list edit
-  survives into the retry through the same WIP push described above. What makes these two soft is
-  narrower — no process reads them as INSTRUCTIONS, and the dispatcher itself runs from the main
-  checkout, never the slot.
+  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 `packages/cli/src/templates/` stays refused on both lanes either way — it is the
-close's own regenerated output, never a worker's writing surface.
+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 four labels, no exceptions:
+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 four labels above, it is not an invariant: a task that
+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:
@@ -334,12 +367,72 @@ with no person to ask ends the run with `status: needs-guidance` carrying the qu
 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 |
@@ -350,6 +443,43 @@ one to move on — "no milestone" is the developer's answer, not a default the o
 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:
@@ -357,11 +487,13 @@ 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, files, AC, DoD, allowed new artifacts.
+   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.
+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
@@ -378,19 +510,15 @@ label with the user directly instead.
   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 REAL branch must be ON THE REMOTE before a subtask is queued.** That branch is
-  `Branch:`'s value when the parent declared one (T-15 — the usual case for a parent worked in an
-  interactive session, which lives on `feat/…`/`fix/…`/`refactor/…`, never on `task/<id>`), or
-  `task/<parentId>` otherwise (see this skill's `Branch:` convention above). 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 either way: add the `Branch:` line to the parent's description if its
-  real branch already exists, or create and push `task/<parentId>` — the convention's default —
-  with `git push origin origin/main:refs/heads/task/<parentId>`.
+- **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.
@@ -419,21 +547,40 @@ label with the user directly instead.
 - 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:
+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
-npx --loglevel=error tsx scripts/backlog/worker-edit.ts T-10 --subtask \
+<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,bc:desktop \
+  --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
@@ -444,14 +591,18 @@ 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 `tier:`/`lane:`/`path:`/`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), and the description must 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.
+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
@@ -506,10 +657,16 @@ genuinely task-specific completion hygiene beyond the project defaults; use
    `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. When the comment also lists **rutas de la lista blanda
+   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 soft-list files (`scripts/backlog/`, `packages/cli/`) with no pull request to mark, and
-   those changes are sitting on `task/<id>` waiting for the retry to restore them. Read that diff
+   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
@@ -543,8 +700,184 @@ happened there, but never widen its AC or its `Files to touch` to absorb the new
 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".
 
-A hook that refuses the frozen edits mechanically is planned (see T-8); until it lands, this section
-is the guard.
+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
 
@@ -553,7 +886,7 @@ is the guard.
 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,bc:o-auth \
+  -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"
@@ -575,7 +908,7 @@ backlog milestone add "Desktop application" -d "Electron shell, IPC bridge, UI a
 # 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,bc:desktop \
+  -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"
 
@@ -585,7 +918,7 @@ 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,bc:desktop \
+  -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
@@ -601,4 +934,21 @@ for f in .backlog/tasks/*.md; do grep -q '^milestone:' "$f" || grep -m1 '^id:' "
 # 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
+)"
 ```