@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

package/dist/templates/monorepo/scripts/backlog/close.ts

@@ -25,7 +25,6 @@
  *     recorded call order, never the reverse (design.md decision (k)).
  */
 import {
-  type DeclaredBranchLookup,
   HUMAN_REVIEW_PATHS,
   LOCAL_FORBIDDEN_PATHS,
   matchesAnyPathPattern,
@@ -34,8 +33,13 @@ import {
   SECURITY_PATH_PATTERNS,
   SLOT_EXECUTED_BASENAMES,
   SLOT_EXECUTED_PATHS,
+  SUPERVISED_ONLY_PATHS,
   taskBaseBranch,
 } from './guards.js';
+import { STREAM_OUTCOME } from './render.js';
+// Type-only on `reviewer.ts`'s own side (`import type { MechanicalStepResult } from './close.js'`),
+// so this value import creates no runtime cycle — see this section's own header comment.
+import { REVIEWER_VERDICT } from './reviewer.js';
 import {
   ACCEPTANCE_CRITERIA_HEADING,
   DEFINITION_OF_DONE_HEADING,
@@ -66,6 +70,15 @@ export interface CheckScopeInput {
   lane: Lane;
   changedFiles: readonly string[];
   declaredFiles: readonly string[];
+  /**
+   * The subset of `changedFiles` NOT yet committed on this branch (T-79) — `collectChangedFileSets`'s
+   * working-tree half: dirty, untracked, or written under a watched gitignored path. Omitted (or
+   * `undefined`) keeps every mirror-output path in `changedFiles` judged exactly as before this field
+   * existed — the right default for a caller with only a flat, already-merged file list and no way to
+   * tell a prior close's own committed output apart from this attempt's. See `isMirrorViolation`'s
+   * doc comment for why only a DIRTY mirror path may be judged once this is given.
+   */
+  workingTreeFiles?: readonly string[];
 }
 
 export interface ScopeCheckResult {
@@ -108,15 +121,85 @@ function isDeclared(file: string, declaredFiles: readonly string[]): boolean {
 }
 
 /**
- * Every file this attempt reaches under the packager's OWN output root — see `MIRROR_OUTPUT_PREFIX`
- * below. Anchored (a prefix, not a substring) so only the real output root matches, and
- * case-INSENSITIVE like every sibling matcher in this module: this repo is developed on a
- * case-insensitive filesystem, where `Packages/CLI/src/Templates/…` names the same file on disk,
- * and a case-sensitive check let that spelling slip past the mirror-first precedence into the soft
- * branch and be merely marked (T-31 round 2).
+ * Every file this attempt reaches under one of the packager's OWN output roots — see
+ * `MIRROR_OUTPUT_PREFIXES` below. Anchored (a prefix, not a substring) so only the real output
+ * roots match, and case-INSENSITIVE like every sibling matcher in this module: this repo is
+ * developed on a case-insensitive filesystem, where `Packages/CLI/src/Templates/…` names the same
+ * file on disk, and a case-sensitive check let that spelling slip past the mirror-first precedence
+ * into the soft branch and be merely marked (T-31 round 2).
  */
 function isMirrorOutput(file: string): boolean {
-  return file.toLowerCase().startsWith(MIRROR_OUTPUT_PREFIX.toLowerCase());
+  const lower = file.toLowerCase();
+  return MIRROR_OUTPUT_PREFIXES.some((prefix) => lower.startsWith(prefix));
+}
+
+/**
+ * T-79: a mirror-output file is a violation for THIS attempt only when it is also DIRTY —
+ * uncommitted, in `workingTreeFiles` (`collectChangedFileSets`'s working-tree half: untracked,
+ * modified, or written under a watched gitignored path). A mirror-output file present ONLY in the
+ * committed diff (`<base>...HEAD`) can never be the worker's own doing: the executor is forbidden
+ * from running `git` at all (`collectAttemptDiff`'s doc comment), so nothing it writes is ever
+ * committed by anything other than a close. On a retry, `<base>...HEAD` is cumulative across every
+ * PRIOR attempt's commits — a PREVIOUS close's own `mirror-regen` step (below) regenerates the
+ * scaffold and its output travels in that close's own commit (`runMirrorRegen`'s doc comment: "the
+ * mirror travels in the attempt's own commit"). Re-checking that already-produced output against the
+ * NEXT attempt's scope is the T-78 incident this closes: the close blocking the retry with its own
+ * prior output, over files the retrying attempt never touched.
+ *
+ * `workingTreeFiles === null` keeps every direct `checkScope` caller that has no working-tree
+ * distinction to offer (most of this module's own tests, and any future caller with only a flat
+ * changed-files list) on today's behaviour: every mirror path is judged, exactly as before this
+ * fix — the safe default when "was this committed by a close, or written by hand" cannot be told
+ * apart at all.
+ *
+ * A worker's OWN hand-write under the mirror prefix is unaffected and still a hard violation
+ * (acceptance criterion #2) ON THE ATTEMPT THAT MAKES IT: it is dirty then, since nothing commits it
+ * until AFTER scope-check has already run and, on a violation, blocked the attempt before mirror-regen
+ * or any commit ever happens.
+ *
+ * Known, accepted residual (not closed by this fix, and deliberately out of `close.ts`'s own scope):
+ * "committed ⇒ produced by a close" is true, but NOT equivalent to "committed ⇒ produced by
+ * `mirror-regen`". `divert` (`executeClose`) calls `saveWork` on EVERY mechanical failure, including
+ * `scope-check`'s own — and `saveWork`'s WIP commit `git add -A`s the WHOLE working tree
+ * unconditionally, sweeping in a hand-written mirror violation right alongside everything else, the
+ * same run it was rejected on. A RETRY on that same branch then sees the violation as committed, not
+ * dirty, and this function exempts it — a worker's hand-write laundered through its own rejection.
+ * Reaching this requires a human to re-queue a `Blocked` task without reading why it blocked (the
+ * `scope-check-failed` reason names the exact file); closing it fully means either `saveWork` itself
+ * excludes files `scope-check` just rejected, or a `mirror-regen` commit is marked apart from a WIP
+ * one — both changes belong to `saveWork`'s own "preserve work before blocking" contract in
+ * `dispatch.ts`, outside this task's declared files.
+ */
+function isMirrorViolation(file: string, workingTreeFiles: ReadonlySet<string> | null): boolean {
+  return isMirrorOutput(file) && (workingTreeFiles === null || workingTreeFiles.has(file));
+}
+
+/**
+ * `pnpm cli:build`'s BUILD output — distinct from `MIRROR_OUTPUT_PREFIXES`
+ * (`packages/cli/src/templates/{backend,frontend,monorepo}/`, the packager's committed SOURCE
+ * mirror, checked above): this is `packages/cli/dist/templates/`, a gitignored COPY of that same
+ * scaffold that `tsc`/`esbuild`
+ * rewrite on every build. It is read only when a generated project is scaffolded — never executed
+ * inside the slot (T-75).
+ *
+ * Before this exemption, a file here reached `forbiddenPaths` by ACCIDENT: `matchesAnyPathPattern`
+ * and `matchesBasename` compare by substring/basename, so
+ * `packages/cli/dist/templates/monorepo/package.json` contains the hard entry `package.json`, and
+ * `packages/cli/dist/templates/monorepo/CLAUDE.md` matches `SLOT_EXECUTED_BASENAMES` — even though
+ * neither file is the repo's own `package.json` or `CLAUDE.md`. Measured incident: T-73's close
+ * failed `scope-check-failed` on ~55 such files despite a correct diff, 1930 green tests and an
+ * APPROVED review.
+ *
+ * Scoped to `templates/` alone, not to all of `packages/cli/dist/`: `packages/cli/bin/run.js` loads
+ * the REST of `dist/` (`IGNORED_SCAN_PATHS`'s doc comment, T-49), so that part must stay watched. A
+ * file under this prefix still falls through to the soft `packages/cli/` match
+ * (`HUMAN_REVIEW_PATHS`) below, same as any other `packages/cli/` file — exempted from the HARD list
+ * only, never dropped from the diff or from human review.
+ */
+const CLI_DIST_TEMPLATES_PREFIX = 'packages/cli/dist/templates/';
+
+function isCliDistTemplateOutput(file: string): boolean {
+  return file.toLowerCase().startsWith(CLI_DIST_TEMPLATES_PREFIX.toLowerCase());
 }
 
 /** The two kinds of path a changed-file set holds, each file in exactly ONE of them. */
@@ -137,17 +220,24 @@ export interface PathClassification {
  * The paths this LANE refuses outright. The frontier lane refuses the hard list; the local lane
  * refuses the same list plus its own three extras (`LOCAL_FORBIDDEN_PATHS`) and every security path,
  * since a local worker runs with the developer's own credentials.
+ *
+ * `SUPERVISED_ONLY_PATHS` is refused on BOTH, and so appears in both arms: guard 1e already blocks a
+ * task that DECLARES one before a slot is spent, but a task that only DISCOVERS the need mid-attempt
+ * declared nothing for that guard to read — the frontier lane does not judge a diff against
+ * `Files to touch:` at all. Without this the change would reach a pull request, which is exactly
+ * what the list exists to prevent (see its doc comment in `guards.ts`).
  */
 function forbiddenPathsFor(lane: Lane): readonly string[] {
   return lane === LANE.LOCAL
-    ? [...SECURITY_PATH_PATTERNS, ...LOCAL_FORBIDDEN_PATHS]
-    : SLOT_EXECUTED_PATHS;
+    ? [...SECURITY_PATH_PATTERNS, ...LOCAL_FORBIDDEN_PATHS, ...SUPERVISED_ONLY_PATHS]
+    : [...SLOT_EXECUTED_PATHS, ...SUPERVISED_ONLY_PATHS];
 }
 
 /**
  * Every file in `files` placed in exactly one bucket, in design.md decision 5's fixed order: the
- * mirror-output prefix first, then the lane's refused paths (plus `SLOT_EXECUTED_BASENAMES`, matched
- * by file name at any depth), then — only for what neither claimed — the soft list.
+ * mirror-output prefix first, then (T-75) the `packages/cli/dist/templates/` build-output
+ * exemption, then the lane's refused paths (plus `SLOT_EXECUTED_BASENAMES`, matched by file name at
+ * any depth), then — only for what neither claimed — the soft list.
  *
  * The ONE place that order lives, because two callers need the same answer for two different
  * purposes and round 3 shipped them as two independent readings that disagreed (T-31 round 4):
@@ -155,21 +245,27 @@ function forbiddenPathsFor(lane: Lane): readonly string[] {
  * turns it into a RECORD (what did this attempt leave behind, whatever the verdict). Sharing the
  * classification is what makes "the record classifies the tree the way the check would" true by
  * construction instead of by two prose comments agreeing.
+ *
+ * `workingTreeFiles` (T-79) is the dirty/untracked half of the same attempt's changes — see
+ * `isMirrorViolation`'s doc comment for why only THAT half may judge a mirror-output path.
  */
 function classifyChangedPaths(
   files: readonly string[],
   forbiddenPaths: readonly string[],
+  workingTreeFiles: ReadonlySet<string> | null,
 ): PathClassification {
   const forbiddenFiles: string[] = [];
   const humanReviewFiles: string[] = [];
   for (const file of files) {
     if (isMirrorOutput(file)) {
-      forbiddenFiles.push(file);
+      if (isMirrorViolation(file, workingTreeFiles)) {
+        forbiddenFiles.push(file);
+      }
       continue;
     }
     if (
-      matchesAnyPathPattern(file, forbiddenPaths) ||
-      matchesBasename(file, SLOT_EXECUTED_BASENAMES)
+      !isCliDistTemplateOutput(file) &&
+      (matchesAnyPathPattern(file, forbiddenPaths) || matchesBasename(file, SLOT_EXECUTED_BASENAMES))
     ) {
       forbiddenFiles.push(file);
       continue;
@@ -188,8 +284,8 @@ function classifyChangedPaths(
  * declared is not enough for the second list: a task may not authorise itself into the harness's
  * own machinery — `.backlog/` included, since declaring the board would authorise a worker to edit
  * the criteria it is judged against. A SOFT-list file is admissible on this lane too, but only when
- * DECLARED and caught by no `LOCAL_FORBIDDEN_PATHS` extra (design.md decision 6): `scripts/` still
- * catches `scripts/backlog/`, which is soft everywhere else.
+ * DECLARED and caught by no `LOCAL_FORBIDDEN_PATHS` extra (design.md decision 6) — today only
+ * `packages/cli/`, which none of those extras reach.
  *
  * Frontier: no declared-files allowlist (see `guards.ts`'s `SLOT_EXECUTED_PATHS` doc comment) —
  * only the hard list, checked against the real diff regardless of declaration.
@@ -206,7 +302,12 @@ function classifyChangedPaths(
  * about a path, and round 3 shipped them as separate readings that did not.
  */
 export function checkScope(input: CheckScopeInput): ScopeCheckResult {
-  const classified = classifyChangedPaths(input.changedFiles, forbiddenPathsFor(input.lane));
+  const workingTreeFiles = input.workingTreeFiles ? new Set(input.workingTreeFiles) : null;
+  const classified = classifyChangedPaths(
+    input.changedFiles,
+    forbiddenPathsFor(input.lane),
+    workingTreeFiles,
+  );
   // The declared-files allowlist is the local lane's own rule and the one part of the verdict that is
   // not a property of the PATH: it asks what the task promised, which a record of leftovers cannot.
   const undeclared =
@@ -232,24 +333,18 @@ export function checkScope(input: CheckScopeInput): ScopeCheckResult {
  * remote-tracking form below.
  *
  * Delegates to `guards.ts`'s `taskBaseBranch` — the ONE place this naming convention lives, per
- * T-14 (2026-09-08) and T-15 (2026-09-09, the declared-branch chain). This function used to compute
- * `task/<parentId>` on its own, and `slots.ts`'s branch resolution used to compute its OWN answer
- * independently; T-4.1 measured the two silently disagreeing on a subtask whose parent branch was
- * not yet pushed (`slots.ts` fell back to `origin/main`, this function kept assuming
- * `task/<parentId>` regardless), producing a `scope-check-failed` diffing against a ref dispatch
- * never created. `guards.ts`'s pre-launch guard (`checkParentBranchOnRemote`) now refuses that
- * dispatch before a slot is ever taken, so this function no longer needs to check the remote itself
- * — by the time a close runs, the branch is guaranteed to exist — but it MUST keep consulting the
- * same naming function `slots.ts` does, so the two can never diverge again.
- *
- * `tasksById` defaults to `{}` (no parent lookup in hand) rather than being required: every EXISTING
- * caller that predates the declared-branch chain keeps resolving `task/<parentId>`, exactly as
- * before — never a silently wrong answer, since an absent lookup reads the same as a parent that
- * declared nothing. The two REAL close call sites (`dispatch.ts`'s `buildCloseRunners`) pass the
- * board's actual `tasksById`.
+ * T-14 (2026-09-08). This function used to compute `task/<parentId>` on its own, and `slots.ts`'s
+ * branch resolution used to compute its OWN answer independently; T-4.1 measured the two silently
+ * disagreeing on a subtask whose parent branch was not yet pushed (`slots.ts` fell back to
+ * `origin/main`, this function kept assuming `task/<parentId>` regardless), producing a
+ * `scope-check-failed` diffing against a ref dispatch never created. `guards.ts`'s pre-launch guard
+ * (`checkParentBranchOnRemote`) refuses that dispatch before a slot is ever taken, so this function
+ * no longer needs to check the remote itself — by the time a close runs, the branch is guaranteed to
+ * exist — but it MUST keep consulting the same naming function `slots.ts` does, so the two can never
+ * diverge again.
  */
-export function resolveBaseBranch(task: Task, tasksById: DeclaredBranchLookup = {}): string {
-  return taskBaseBranch(task, tasksById);
+export function resolveBaseBranch(task: Task): string {
+  return taskBaseBranch(task);
 }
 
 /**
@@ -259,8 +354,8 @@ export function resolveBaseBranch(task: Task, tasksById: DeclaredBranchLookup =
  * A subtask still measures against its PARENT's branch — diffing a child against `main` would
  * report every file the parent already changed as this child's scope violation.
  */
-export function resolveBaseRef(task: Task, tasksById: DeclaredBranchLookup = {}): string {
-  return `origin/${resolveBaseBranch(task, tasksById)}`;
+export function resolveBaseRef(task: Task): string {
+  return `origin/${resolveBaseBranch(task)}`;
 }
 
 // ── Scope check over the REAL diff ─────────────────────────────────────────────
@@ -312,7 +407,7 @@ function parsePorcelainPaths(output: string): string[] {
 
 /**
  * Runs the close's mechanical scope verification against the slot's real changes and feeds them to
- * `checkScope`. Two git reads, unioned, because either one alone leaves a hole:
+ * `checkScope`. Three git reads, unioned, because any one alone leaves a hole:
  *
  *   - `git diff --name-only -z <base>...HEAD` covers what the attempt COMMITTED. Three dots, not
  *     two: `...` compares against the merge base, so commits that landed on `base` after the
@@ -331,6 +426,10 @@ function parsePorcelainPaths(output: string): string[] {
  *     successful attempt leaves everything in the working tree — checking HEAD alone would let a
  *     scope violation through by simply not committing it, and an untracked new file never appears
  *     in a `git diff` under any flags.
+ *   - the same `status` call, scoped to `IGNORED_SCAN_PATHS` and with `--ignored` added, covers what
+ *     neither of the two above can see at all: a write under a path the repo's OWN `.gitignore`
+ *     hides (T-49). Deliberately NOT a blanket `--ignored` over the whole tree — see
+ *     `IGNORED_SCAN_PATHS`'s doc comment for the 138184-entry volume that was measured and rejected.
  *
  * A `git` failure fails the check rather than passing it: an unverifiable diff is exactly the case
  * design.md decision (i) refuses to trust ("the 4-bit probe produced scope creep while reporting
@@ -342,12 +441,53 @@ export interface CollectChangedFilesInput {
 }
 
 /**
- * Every repo-relative path this attempt produced: what it COMMITTED (`<base>...HEAD`) plus what it
- * left dirty or untracked. Exported because the mechanical triad scopes its Prettier and barrels
- * runs to exactly this set — running them repo-wide fails every attempt on someone else's diff.
- * Throws on a git failure; the callers turn that into a mechanical failure with the reason.
+ * Where a THIRD, gitignore-aware git read is scoped (T-49). Neither the `diff` half above nor the
+ * plain `status` half carries `--ignored`, so a write under a gitignored path never reached
+ * `changedFiles` at all — measured incident: `packages/cli/.gitignore` hides `dist/`, and
+ * `packages/cli/bin/run.js` LOADS `dist/`, not `src/`, so a worker that wrote its payload there and
+ * ran it left a clean diff: no scope-check hit, no human-review mark, no trace in a `Blocked`
+ * comment.
+ *
+ * The obvious fix — add `--ignored` to the plain `status` call, repo-wide — was measured and
+ * rejected (2026-09-10, this checkout): `git status --porcelain -z --untracked-files=all --ignored`
+ * with no pathspec returned 138184 entries, almost all of it pre-existing `node_modules/` content
+ * installed at slot PROVISIONING (every dispatched attempt gets a `pnpm install` before it starts,
+ * per the root `CLAUDE.md`'s dispatched-worker section) and therefore not written by the attempt at
+ * all — plus `backend/.env` and `backend/.keys` surfacing as "changed" simply for existing. That
+ * volume, repeated on every close of every task, and those two paths landing in a changed-files list
+ * at all, is worse than the hole it closes.
+ *
+ * A pathspec-scoped `--ignored` read avoids both: `git status --ignored -- packages/cli/dist` reads
+ * ONLY that gitignored subtree, so the reachable answer stays "did this attempt touch the one
+ * directory the incident named", never "list everything gitignored in the repo". `node_modules/`
+ * stays deliberately OUT of this list: it is already `SLOT_EXECUTED_PATHS`-hard, and the one attack
+ * this scan exists to catch there — a worker `git add -f`-ing a tampered dependency — already
+ * surfaces in the plain `diff`/`status` halves above, since a forced add overrides the ignore rule
+ * that hides it. Scoping this list to it too would buy nothing but the 138184-entry regression just
+ * measured.
  */
-export function collectChangedFiles(input: CollectChangedFilesInput): string[] {
+const IGNORED_SCAN_PATHS: readonly string[] = ['packages/cli/dist'];
+
+/**
+ * `collectChangedFiles`'s two halves, kept APART (T-79) rather than merged: `committed` is what
+ * `<base>...HEAD` reports, cumulative across every attempt this branch ever had; `workingTree` is
+ * dirty, untracked, or written under a watched gitignored path — necessarily THIS attempt's own
+ * doing, since the executor never commits anything itself. `checkScope`'s mirror-output judgment
+ * (`isMirrorViolation`) needs exactly this split; nothing else in this module does, which is why
+ * `collectChangedFiles` below stays the merged, single-list answer every other caller already reads.
+ */
+export interface ChangedFileSets {
+  committed: string[];
+  workingTree: string[];
+}
+
+/**
+ * The three git reads `collectChangedFiles` used to run inline, now shared with `checkScope`'s
+ * working-tree split (T-79) so both halves come from the SAME three calls instead of running git
+ * twice per close step. See `collectChangedFiles`'s doc comment (below) for why each of the three
+ * reads exists; this function only changes how their results are GROUPED, not what they ask git.
+ */
+export function collectChangedFileSets(input: CollectChangedFilesInput): ChangedFileSets {
   // No `trim()` on the entries. `-z` already means "nothing is escaped", and trimming would rewrite
   // exactly the paths that flag exists to preserve: a filename with a leading or trailing space, a
   // tab or a newline would be compared against the path lists and the declared allowlist under a
@@ -361,7 +501,30 @@ export function collectChangedFiles(input: CollectChangedFilesInput): string[] {
   const dirty = parsePorcelainPaths(
     input.runGit(['status', '--porcelain', '-z', '--untracked-files=all']),
   );
-  return [...new Set([...committed, ...dirty])];
+  const ignored = parsePorcelainPaths(
+    input.runGit([
+      'status',
+      '--porcelain',
+      '-z',
+      '--untracked-files=all',
+      '--ignored',
+      '--',
+      ...IGNORED_SCAN_PATHS,
+    ]),
+  );
+  return { committed, workingTree: [...new Set([...dirty, ...ignored])] };
+}
+
+/**
+ * Every repo-relative path this attempt produced: what it COMMITTED (`<base>...HEAD`), what it left
+ * dirty or untracked, and what it wrote under a gitignored path this module knows to watch
+ * (`IGNORED_SCAN_PATHS`, T-49). Exported because the mechanical triad scopes its Prettier and barrels
+ * runs to exactly this set — running them repo-wide fails every attempt on someone else's diff.
+ * Throws on a git failure; the callers turn that into a mechanical failure with the reason.
+ */
+export function collectChangedFiles(input: CollectChangedFilesInput): string[] {
+  const sets = collectChangedFileSets(input);
+  return [...new Set([...sets.committed, ...sets.workingTree])];
 }
 
 /** `runScopeCheck`'s return, widened with the soft-list files `dispatch.ts`'s `openPr` runner reads (T-31). */
@@ -370,9 +533,9 @@ export interface ScopeCheckStepResult extends MechanicalStepResult {
 }
 
 export function runScopeCheck(input: RunScopeCheckInput): ScopeCheckStepResult {
-  let changedFiles: string[];
+  let sets: ChangedFileSets;
   try {
-    changedFiles = collectChangedFiles({ base: input.base, runGit: input.runGit });
+    sets = collectChangedFileSets({ base: input.base, runGit: input.runGit });
   } catch (error) {
     return {
       ok: false,
@@ -382,7 +545,15 @@ export function runScopeCheck(input: RunScopeCheckInput): ScopeCheckStepResult {
     };
   }
 
-  const result = checkScope({ lane: input.lane, changedFiles, declaredFiles: input.declaredFiles });
+  const changedFiles = [...new Set([...sets.committed, ...sets.workingTree])];
+  const result = checkScope({
+    lane: input.lane,
+    changedFiles,
+    declaredFiles: input.declaredFiles,
+    // T-79: only a DIRTY mirror-output path is judged as this attempt's violation — a committed-only
+    // one is a prior close's own `mirror-regen` output. See `isMirrorViolation`'s doc comment.
+    workingTreeFiles: sets.workingTree,
+  });
   if (!result.ok) {
     return {
       ok: false,
@@ -416,13 +587,17 @@ export interface CollectLeftoverFilesInput extends CollectChangedFilesInput {
  * Round 3 filtered the tree through the soft list alone, which reported a mirror-output path — the
  * one prefix refused on both lanes — as a soft-list file the close admits, and said nothing at all
  * about `.claude/settings.json`. Both halves now come from `classifyChangedPaths`, the same function
- * `checkScope` reads, so the record and the verdict cannot classify a path differently.
+ * `checkScope` reads, so the record and the verdict cannot classify a path differently — including
+ * (T-79) the same working-tree split, so a PRIOR close's committed mirror output is not named here
+ * as a leftover to clean up either; see `isMirrorViolation`'s doc comment.
  *
  * Throws on a `git` failure; `executeClose` records that as "none found" rather than failing a close
  * that has already failed.
  */
 export function collectLeftoverFiles(input: CollectLeftoverFilesInput): PathClassification {
-  return classifyChangedPaths(collectChangedFiles(input), forbiddenPathsFor(input.lane));
+  const sets = collectChangedFileSets(input);
+  const changedFiles = [...new Set([...sets.committed, ...sets.workingTree])];
+  return classifyChangedPaths(changedFiles, forbiddenPathsFor(input.lane), new Set(sets.workingTree));
 }
 
 // ── mirror-regen: keeping the CLI scaffold mirror in step with the attempt ────
@@ -434,12 +609,24 @@ export function collectLeftoverFiles(input: CollectLeftoverFilesInput): PathClas
  *
  * Measured defect (PR #96, dispatched task T-3): the attempt edited `backend/src/@app/iam/**` and
  * `frontend/src/app/domains/admin/apps/iam/**`, both mirrored roots, and the PR failed that gate.
- * The worker could not fix it — this prefix is refused on both lanes regardless of the T-31 split
- * (`packages/cli/` itself is soft, but its OWN generated mirror never is: `checkScope` checks this
- * prefix first, before either path list) — and no close step regenerated the mirror either, so ANY
- * dispatched task touching a mirrored root could never pass CI on its own. This step closes that.
+ * The worker could not fix it — these prefixes are refused on both lanes regardless of the T-31
+ * split (`packages/cli/` itself is soft, but its OWN generated mirror never is: `checkScope` checks
+ * these prefixes first, before either path list) — and no close step regenerated the mirror either,
+ * so ANY dispatched task touching a mirrored root could never pass CI on its own. This step closes
+ * that.
+ *
+ * Deliberately these THREE directories, not the whole `packages/cli/src/templates/` tree (T-93):
+ * the sibling `packages/cli/src/templates/codegen/` is 944 KB of hand-written `.eta` templates —
+ * the CLI's OWN source, not packager output — and `cli-template-drift-check.yml`'s own drift check
+ * excludes it by name for that same reason. Treating it as mirror output made a legitimate
+ * hand-written `.eta` edit a hard scope violation on every attempt that declared it (T-76
+ * intento-1) even though nothing the packager writes ever lands there.
  */
-const MIRROR_OUTPUT_PREFIX = 'packages/cli/src/templates/';
+const MIRROR_OUTPUT_PREFIXES = [
+  'packages/cli/src/templates/backend/',
+  'packages/cli/src/templates/frontend/',
+  'packages/cli/src/templates/monorepo/',
+] as const;
 
 /**
  * The packager's own output root, subtracted from the mirrored-root list. The drift-check filter
@@ -591,7 +778,9 @@ export function runMirrorRegen(input: RunMirrorRegenInput): MirrorRegenResult {
     return mirrorRegenFailure(`git no se pudo ejecutar tras regenerar el espejo: ${String(error)}`);
   }
 
-  const mirrorFiles = afterRegen.filter((file) => file.startsWith(MIRROR_OUTPUT_PREFIX));
+  const mirrorFiles = afterRegen.filter((file) =>
+    MIRROR_OUTPUT_PREFIXES.some((prefix) => file.startsWith(prefix)),
+  );
   return { ok: true, regenerated: true, mirrorFiles };
 }
 
@@ -644,12 +833,6 @@ export interface BuildPrCreateArgsInput {
    * behaviour this function had before `composePrBody` existed.
    */
   taskText?: string;
-  /**
-   * The board's task lookup, for `resolveBaseBranch`'s `--base` resolution — a subtask's parent may
-   * have DECLARED a real branch (T-15). Omitted falls back to `resolveBaseBranch`'s own default
-   * (`task/<parentId>`), the pre-T-15 behaviour.
-   */
-  tasksById?: DeclaredBranchLookup;
   /** `lanes.json`'s `attempts` cap, shown alongside the attempt number in the composed body. */
   maxAttempts?: number;
   /**
@@ -1048,7 +1231,7 @@ export function buildPrCreateArgs(input: BuildPrCreateArgsInput): string[] {
     'pr',
     'create',
     '--base',
-    resolveBaseBranch(input.task, input.tasksById),
+    resolveBaseBranch(input.task),
     '--head',
     input.branch,
     '--title',
@@ -1128,6 +1311,40 @@ export interface MechanicalCheck {
   label: string;
   command: string;
   args: string[];
+  /**
+   * Non-zero exit statuses this check treats as advisory, not a failure — the check's OWN
+   * pass/fail contract. Absent (every check but lint-barrels) means any non-zero status still
+   * fails, unchanged from before this field existed. Declared per check, not read from the exit
+   * code by the evaluation loop, so a future check never inherits a tolerance it did not ask for.
+   */
+  advisoryStatuses?: readonly number[];
+}
+
+export interface MechanicalCheckOutcome {
+  /** False only when the status is neither zero nor declared advisory — this fails the attempt. */
+  ok: boolean;
+  /** True when a non-zero status passed because the check declared it advisory. */
+  advisory: boolean;
+}
+
+/**
+ * Turns a check's raw exit status into pass/fail, honouring the check's OWN advisory contract
+ * instead of hardcoding a status number here. Exit 0 always passes; any other status passes ONLY
+ * when the check declares it advisory (today: lint-barrels' exit 2 — HR-BARRELS-004's
+ * `informational` tier, the same contract `.husky/pre-commit` already honours). A status the
+ * check does not name still fails, so a check added later inherits no tolerance silently.
+ */
+export function evaluateMechanicalCheckResult(
+  check: MechanicalCheck,
+  status: number,
+): MechanicalCheckOutcome {
+  if (status === 0) {
+    return { ok: true, advisory: false };
+  }
+  if (check.advisoryStatuses?.includes(status)) {
+    return { ok: true, advisory: true };
+  }
+  return { ok: false, advisory: false };
 }
 
 export interface PlanMechanicalChecksInput {
@@ -1274,6 +1491,10 @@ export function planMechanicalChecks(input: PlanMechanicalChecksInput): Mechanic
       label: 'lint-barrels',
       command: 'pnpm',
       args: [LINT_BARRELS_SCRIPT, '--', ...barrelsFiles],
+      // HR-BARRELS-004's `informational` severity maps to exit 2 (`computeExitCode`,
+      // scripts/harness-rules/lint-barrels.ts) — the same status `.husky/pre-commit` already lets
+      // through. Only THIS check owns that tolerance; prettier and the test step declare none.
+      advisoryStatuses: [2],
     });
   }
 
@@ -1691,6 +1912,218 @@ export function formatBlockComment(details: BlockDetails): string {
   return sanitizeCommentBody([head, question, pointers, forbidden, softList, action].join(''));
 }
 
+// ── The «Registro de ejecución» block (T-68; `catalyst-backlog/SKILL.md` §12) ────────────────
+//
+// Every task carries, once, an eight-field record of how its headless dispatch went, appended to
+// its notes at the `Done` transition. `close.ts`'s own `planClose`/`executeClose` never set `Done`
+// (this module never does) — `maintenance.ts` does, from TWO places: step 3 (a leaf task, merged PR
+// -> `Done`) and `recomputeParent` (a parent whose children are all `Done` and whose own PR merged —
+// §12 says "every task", a parent included). Both gather the raw facts (`Task.attempts`, each
+// attempt's classified stream outcome, each attempt's `review.md` verdict, the current notes text
+// scoped to the notes section for the idempotence check) and hand them here. Composing the block
+// from those facts is PURE, exactly like `planClose` above — `close.test.ts` asserts it directly,
+// with no filesystem or `backlog` CLI involved.
+//
+// §12.2 rule 3's three "empty" values are NOT interchangeable, and this is where that distinction
+// is enforced: `desconocido` marks a field this function had no real signal for; `ninguno`/`ninguna`
+// is reserved for a field it actually measured and found absent. An LM Studio or network failure is
+// real but structurally untraceable by the time this runs — `entry.ts`'s `onLocalModelMissing`
+// writes only a `Blocked` COMMENT (never a file under `.backlog/.dispatch/`), and that comment is
+// routinely overwritten by every later transition — so "Fallos de entorno" can positively detect
+// only a budget cutoff (`STREAM_OUTCOME.BUDGET`) and reads `desconocido`, never `ninguno`, when it
+// finds none: this measures ONE of three possible causes, not all three.
+//
+// `attempts === 0` means the dispatcher never launched a single attempt for this task — the root
+// `CLAUDE.md`'s Worktree Gate forces EVERY task onto a `task/T-nn` branch, supervisada (interactive)
+// sessions included, so step 3/`recomputeParent` close such a task the moment its PR merges, exactly
+// like a headless one. That absence of any attempt IS a measurement, not a headless task with zero
+// attempts: this composer records it as `Modo: supervisada`, `Intervenciones humanas: desconocido`
+// (the dispatcher has no visibility into a supervisada session's own human steps), and points
+// `Fuente` at the merged PR — the only trace left with no attempt directory to point at instead.
+//
+// The idempotence sentinel (`hasExecutionRecordBlock`, below) applies identically to a supervisada
+// task: if a person already appended their own block to its notes by hand, this composer never
+// runs at all — the caller's `readNotes`/`hasExecutionRecordBlock` check short-circuits first.
+
+export const EXECUTION_RECORD_HEADING = '## Registro de ejecución';
+
+/**
+ * A WHOLE LINE, not a substring: `notes.includes(EXECUTION_RECORD_HEADING)` also matched a report
+ * that merely MENTIONS the heading in prose ("texto ## Registro de ejecución aquí"), which is real
+ * text a worker's own notes can legitimately contain. `EXECUTION_RECORD_HEADING` carries no regex
+ * metacharacter (`#` and letters only), so it is safe to anchor directly.
+ */
+const EXECUTION_RECORD_HEADING_LINE = new RegExp(`^${EXECUTION_RECORD_HEADING}$`, 'm');
+
+/**
+ * §12.3's sentinel: `true` once `notes` already carries the heading on its OWN line — the
+ * maintenance pass's own idempotence check. `notes` must already be scoped to the notes SECTION
+ * (`task-view.ts`'s `notesRegion`) by the caller: this function has no way to tell a heading
+ * legitimately written in the notes apart from one that merely appears in the description or a
+ * comment the CLI's `--plain` view happens to also carry.
+ */
+export function hasExecutionRecordBlock(notes: string | null | undefined): boolean {
+  return typeof notes === 'string' && EXECUTION_RECORD_HEADING_LINE.test(notes);
+}
+
+const UNKNOWN_FIELD = 'desconocido';
+const POST_MERGE_FIXES_AT_CLOSE = 'ninguno conocido al cierre';
+// §12.2 rule 4: no status-transition timestamp survives anywhere today (the task front matter
+// keeps only `created_date`/`updated_date`, and Backlog.md's `onStatusChange` payload is gone the
+// instant the callback returns) — `desconocido` unconditionally, rather than an attempt directory's
+// own mtime, which shifts every time ANY file inside it is written and would silently misreport the
+// exact window it claims to measure.
+const CYCLE_TIME_UNKNOWN = UNKNOWN_FIELD;
+
+export interface ExecutionRecordInput {
+  /** The task's `lane:` label at close time — decides the "Modo" motivo. */
+  lane: Lane | undefined;
+  /** `Task.attempts` — the number of `intento-N` directories this task's dispatch record holds. */
+  attempts: number;
+  /**
+   * Each attempt's classified terminal outcome (`render.ts`'s `StreamOutcome`), attempt 1 first,
+   * `null` where the stream could not be read. Shorter than `attempts` — or entirely empty — when
+   * the caller could not read every attempt; a missing entry reads as "unknown", never as success.
+   */
+  attemptOutcomes: readonly (string | null)[];
+  /**
+   * Each attempt's `review.md` verdict (`reviewer.ts`'s `ReviewerVerdict`, parsed by
+   * `parseReviewerVerdict` — reused, never reimplemented), attempt 1 first, `null` where the
+   * attempt has no `review.md` at all. Only the local lane's close ever runs the reviewer, so this
+   * is empty (or all-`null`) for every frontier-lane task — its own worker runs whatever gates it
+   * runs, invisible to the dispatcher, and "Rondas de corrección"/"revisor" must say so honestly
+   * (`desconocido`) rather than guess from the lane label, which a quota cutoff or a crash makes
+   * wrong (a retry with no review at all is not a correction ROUND).
+   */
+  reviewVerdicts: readonly (string | null)[];
+  /** `.backlog/.dispatch/<id>/intento-<N>` of the LAST attempt, or `null` with no attempt at all. */
+  sourcePath: string | null;
+  /**
+   * Only consulted when `attempts === 0` (`sourceLine`'s own JSDoc) — Fuente's PR-based fallback
+   * for a task the dispatcher never launched. Three states, matched to §12.2 rule 3's own three
+   * "empty" values:
+   *  - a `number`: the PR is known — `Fuente` reads `PR #<n>`.
+   *  - `'read-failed'`: the caller already confirmed a PR exists (step 3/`recomputeParent` only
+   *    ever reach this with a CONFIRMED merged PR) but could not read its number — `Fuente` reads
+   *    `desconocido`, never `sin evidencia`: the PR is real, only the read failed.
+   *  - `null` (default): no PR is known to exist at all — `Fuente` reads `sin evidencia`, rule 3's
+   *    OWN definition ("no attempt directory AND no PR").
+   */
+  prNumber?: number | 'read-failed' | null;
+}
+
+/**
+ * "Rondas de corrección" + its "revisor", from MEASURED `review.md` data only (§12.2 rule 3) — never
+ * from the retry count (a quota cutoff or a crash retries with no review at all) or from the lane
+ * label (the frontier lane's close never runs a reviewer the dispatcher can see). `desconocido` for
+ * BOTH halves when no attempt has a `review.md` at all — there is nothing to count.
+ */
+function correctionRounds(verdicts: readonly (string | null)[]): { rounds: string; revisor: string } {
+  if (!verdicts.some((verdict) => verdict !== null)) {
+    return { rounds: UNKNOWN_FIELD, revisor: UNKNOWN_FIELD };
+  }
+  const failCount = verdicts.filter((verdict) => verdict === REVIEWER_VERDICT.FAIL).length;
+  return { rounds: String(failCount), revisor: 'code-review' };
+}
+
+/**
+ * "Resultado del intento 1": the first attempt's OWN outcome when it is known — carrying its real
+ * cause into the record (AC1's "Blocked cause if there was one") — degrading to the template's
+ * cause-free `reintento` when only the retry COUNT is known (a later, close-level failure that
+ * never touched the stream, e.g. a scope violation), and to `desconocido` with no attempt at all.
+ */
+function firstAttemptResult(attempts: number, firstOutcome: string | null): string {
+  if (attempts <= 0) {
+    return UNKNOWN_FIELD;
+  }
+  if (firstOutcome !== null && firstOutcome !== STREAM_OUTCOME.COMPLETED) {
+    return `Blocked (${firstOutcome})`;
+  }
+  return attempts === 1 ? 'Done' : 'reintento';
+}
+
+/** See this section's own header comment for why absence here is `desconocido`, never `ninguno`. */
+function environmentFailures(outcomes: readonly (string | null)[]): string {
+  return outcomes.includes(STREAM_OUTCOME.BUDGET) ? 'cuota' : UNKNOWN_FIELD;
+}
+
+/**
+ * `attempts === 0` is read as "the dispatcher never launched this task": the root `CLAUDE.md`'s
+ * Worktree Gate puts supervisada (interactive) sessions on `task/T-nn` branches too, precisely so
+ * the reconciler closes them the same way. Its motivo is recorded nowhere the dispatcher can read,
+ * hence `desconocido`.
+ *
+ * Not an exact equivalence: `entry.ts` sets `In Progress` and writes the lock BEFORE
+ * `beginAttempt` creates `intento-1`, so a crash in that window leaves a dispatched task at zero
+ * attempts (documented beside `countAttempts` in `attempt.ts`). Step 1's PID-based dead-lock sweep
+ * blocks such a task before step 3 can close it, which is what keeps this reading safe — not the
+ * count itself.
+ */
+function neverDispatched(attempts: number): boolean {
+  return attempts === 0;
+}
+
+/** "Modo": `supervisada` once `neverDispatched`, `headless — lane:<lane>` otherwise (unchanged). */
+function modeLine(attempts: number, lane: Lane | undefined): string {
+  if (neverDispatched(attempts)) {
+    return `supervisada — ${UNKNOWN_FIELD}`;
+  }
+  return lane ? `headless — lane:${lane}` : `headless — ${UNKNOWN_FIELD}`;
+}
+
+/**
+ * "Intervenciones humanas": `attempts - 1` retries, each measured through a human-released `Blocked`
+ * (§10) — unchanged for a dispatched task. `desconocido` once `neverDispatched`: the dispatcher has
+ * no visibility at all into a supervisada session's own human interventions (§12.2 rule 3 — this is
+ * "no data", never a measured "ninguna" nobody actually measured).
+ */
+function humanInterventionsLine(attempts: number): string {
+  if (neverDispatched(attempts)) {
+    return `${UNKNOWN_FIELD} — tipo: ${UNKNOWN_FIELD}`;
+  }
+  const rounds = Math.max(0, attempts - 1);
+  return `${rounds} — tipo: ${rounds > 0 ? 'respuesta a Blocked' : 'ninguna'}`;
+}
+
+/**
+ * "Fuente": the last attempt directory for a dispatched task (unchanged). For a `neverDispatched`
+ * task the attempt directory never existed, so the PR is the only trace left — see
+ * `ExecutionRecordInput.prNumber`'s own JSDoc for the three states this reads.
+ */
+function sourceLine(
+  attempts: number,
+  sourcePath: string | null,
+  prNumber: number | 'read-failed' | null | undefined,
+): string {
+  if (!neverDispatched(attempts)) {
+    return sourcePath ?? 'sin evidencia';
+  }
+  if (typeof prNumber === 'number') {
+    return `PR #${prNumber}`;
+  }
+  if (prNumber === 'read-failed') {
+    return UNKNOWN_FIELD;
+  }
+  return 'sin evidencia';
+}
+
+/** Composes the eight-field block (§12.1's template), fixed order, one field per line (§12.2 rule 2). */
+export function buildExecutionRecordBlock(input: ExecutionRecordInput): string {
+  const { rounds, revisor } = correctionRounds(input.reviewVerdicts);
+  return [
+    EXECUTION_RECORD_HEADING,
+    '',
+    `- **Modo:** ${modeLine(input.attempts, input.lane)}`,
+    `- **Resultado del intento 1:** ${firstAttemptResult(input.attempts, input.attemptOutcomes[0] ?? null)}`,
+    `- **Rondas de corrección:** ${rounds} — revisor: ${revisor}`,
+    `- **Arreglos posteriores al merge:** ${POST_MERGE_FIXES_AT_CLOSE}`,
+    `- **Intervenciones humanas:** ${humanInterventionsLine(input.attempts)}`,
+    `- **Fallos de entorno:** ${environmentFailures(input.attemptOutcomes)}`,
+    `- **Tiempo de ciclo:** ${CYCLE_TIME_UNKNOWN}`,
+    `- **Fuente:** ${sourceLine(input.attempts, input.sourcePath, input.prNumber)}`,
+  ].join('\n');
+}
+
 export interface PlanCloseSuccessInput {
   outcome: 'success';
   lane: Lane;