nightralph 0.0.18 → 0.0.21

package/README.md

@@ -86,7 +86,11 @@ to add the required skills to your local `.agents/skills/` folder.
 Use the `to-tickets` skill to create issues in local markdown files from
 a prose text description.
 
-The `nightralph` CLI does the `tdd` part of the workflow.
+The `nightralph` CLI does the `tdd` part of the workflow: the agent
+prompt tells the agent to write a failing test per acceptance
+criterion at the seams named in the spec's Testing Decisions, and
+the orchestrator runs the project's test command in the worktree
+before a ticket can be marked `done`.
 
 >
 > [!NOTE]  
@@ -122,6 +126,12 @@ npx nightralph codex --dry-run
 
 # Specify a feature by name
 npx nightralph claude -m claude-opus-4-6 --spec my-feature
+
+# Cap each agent at 30 agentic turns
+npx nightralph claude -m claude-opus-4-6 --max-turns 30
+
+# Start pi at medium thinking and allow one escalated retry
+npx nightralph pi -m openrouter/z-ai/glm-5.3-flash --thinking medium --retries 1
 ```
 
 #### `--spec <name>` option
@@ -139,7 +149,12 @@ Flags:
 | `--spec <name>` | no | auto | Feature name (resolves `.scratch/<name>/`) |
 | `--dry-run` | no | -- | Show wave order and prompt without running |
 | `-X` | no | -- | Stop on merge conflict instead of re-spawning |
-| `--timeout` | no | `300` | Kill agent after N seconds |
+| `--timeout` | no | `3600` | Kill the agent after N seconds. A killed agent is not a failure: its work is kept (see Notes) |
+| `--test-cmd <cmd>` | no | auto | Run in each worktree after the agent exits; non-zero exit rejects the ticket. Auto-detects `npm test`. Pass `""` to disable. Shares the agent's `--timeout`. The command runs in a fresh git worktree, which contains only tracked files, so a project that needs an install step should include it, for example `--test-cmd 'npm ci && npm test'` |
+| `--max-turns <n>` | no | -- | Max agentic turns per ticket. Forwarded verbatim as `--max-turns <n>` to the provider CLI. Only `claude` accepts it; `codex` and `pi` reject it as an unknown option and the agent exits immediately. Applies to every agent spawn, including a re-spawn after a merge conflict. When omitted, `claude` applies no turn limit, so `--timeout` is the only cap. Reaching the limit is an error exit, so the ticket is recorded as failed |
+| `--thinking <level>` | no | -- | Starting thinking level for `pi`, one of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Forwarded as `--thinking <level>`. Omitted = pi's own default. Ignored for other providers. Each retry steps up from here (see `--retries`) |
+| `--retries <n>` | no | `2` | Extra attempts per ticket after a failed run. Each retry starts from a fresh worktree; with `pi` it also raises the thinking level (see Notes). `0` disables retries |
+| `--retry-delay <n>` | no | `30` | Seconds to wait before the first retry; doubles each further retry (30s, 60s, 120s, ...). `0` disables the wait |
 
 
 **Notes**:
@@ -154,19 +169,68 @@ Flags:
   tickets start in the next wave.
 * An agent run only counts as a success when the agent exits 0,
   its worktree branch has new commits relative to the base branch,
-  and the worktree is clean (no uncommitted changes). On success,
-  the ticket's status is updated to `done` in-place. If the agent
-  exits 0 but made no commits or left uncommitted changes, the
-  ticket is left `ready-for-agent` for a retry. Failed tickets
-  (non-zero exit) keep their status and block dependents.
+  and the test command (see `--test-cmd`) exits 0 in that worktree.
+  Uncommitted changes left by the agent are auto-committed before
+  the check. On success, the ticket's status is updated to `done`
+  in-place. If the agent exits 0 but made no commits, or the test
+  command fails, the ticket is left `ready-for-agent` for a retry
+  and the test output is written to `<dir>/../logs/<ticket>.test.log`.
+  Failed tickets (non-zero exit) keep their status and block
+  dependents.
+* A failed attempt is retried, up to `--retries` times, before the
+  ticket is recorded as failed. Non-zero exit, exit 0 with no new
+  commits, and a red test command all count as failures; a timeout
+  does not (see below). Each retry discards the previous worktree
+  and starts from a fresh one. With `pi`, each retry raises the
+  thinking level: without `--thinking` the first retry uses `high`
+  and the second `max`; with `--thinking <level>` each retry steps
+  one level up from the previous attempt, stopping at `max`.
+  `claude` and `codex` are retried at the same settings. Retries
+  are spaced with exponential backoff controlled by `--retry-delay`:
+  the first retry waits `--retry-delay` seconds, the second waits
+  double that, and so on. This lets provider outages clear before
+  burning the next attempt. Retry
+  logs are written to `<dir>/../logs/<ticket>.attempt<n>.log`
+  (and `.attempt<n>.test.log` for the test command) so the first
+  attempt's log is kept.
+* A ticket that exhausts all its retry attempts is excluded from
+  later waves in the same run. It stays `ready-for-agent` on disk
+  so a future run can pick it up, but it will not be re-started
+  within the current invocation. The final summary line includes
+  the count of failed tickets when any failed.
+* An agent still running at `--timeout` is killed. The kill is
+  reported in the status display and in the ticket log. It is not
+  treated as an agent failure: uncommitted changes in the worktree
+  are auto-committed, and the branch goes through the same
+  new-commits check, test gate, and merge as an agent that exited 0.
+  Opus tickets have taken over 12 minutes of API time, which is why
+  the default is an hour rather than the old 15 minutes.
+* Agents are spawned in their own process group (`detached:true`).
+  When the timeout fires or when you press Ctrl-C (SIGINT) or send
+  SIGTERM, the orchestrator kills the entire process group -- not
+  just the agent process -- so dev servers, watchers, and other
+  child processes are cleaned up. SIGINT exits 130 and SIGTERM
+  exits 143 after killing all running agents and restoring the
+  terminal.
+* For fast models that reliably finish tickets in a few minutes,
+  `--timeout 900` is a reasonable cap that catches stuck agents
+  sooner than the one-hour default.
+* `.scratch/` should be listed in your project's `.gitignore`.
+  The orchestrator force-adds `progress.md` so it is tracked despite
+  the ignore rule, but ticket files, logs, and spec files are
+  working state and should not be committed to the project repo.
 * Agent logs are written to `<dir>/../logs/<ticket>.log`.
 * Provider commands are launched non-interactively with default flags
   that grant the agent write access to the worktree, so tickets can
   actually be implemented without a permission prompt:
   * `claude`: `--print --dangerously-skip-permissions`
-  * `codex`: `exec --full-auto`
-  * `pi`: `-p --approve --no-session`
-    (prompt delivered via temp file, not stdin)
+  * `codex`: `exec --dangerously-bypass-approvals-and-sandbox`
+    (codex removed `--full-auto`; the workspace-write sandbox
+    cannot commit in a worktree because its `.git` link points
+    outside the tree)
+  * `pi`: `-p --verbose --approve --no-session --mode json`
+    (prompt delivered via temp file; `--approve` auto-accepts
+    tool-use proposals so the agent runs non-interactively)
 
 
 ## How It Works

package/dist/display.js

@@ -44,6 +44,8 @@ const FILLED_DOT = "\u25CF";
 const EMPTY_DOT = "\u25CB";
 const SEPARATOR_WIDTH = 50;
 const DEFAULT_COLUMNS = 80;
+const MIN_LOG_ROWS = 1;
+const MAX_MESSAGE_BUFFER = 200;
 const ANSI_RE = /\x1b\[[0-9;?]*[A-Za-z]/g;
 function fitLine(line, width) {
   const visible = line.replace(ANSI_RE, "");
@@ -76,16 +78,14 @@ class StatusDisplay {
   config;
   viewportStart = 0;
   resizeListener = null;
-  signalHandler = null;
   constructor(config) {
     this.config = {
-      messageLines: config?.messageLines ?? 10,
       stream: config?.stream ?? process.stdout
     };
   }
   getAvailableRows() {
     const termHeight = this.config.stream.rows ?? 24;
-    const overhead = 2 + this.config.messageLines;
+    const overhead = 2 + MIN_LOG_ROWS;
     const available = termHeight - overhead;
     return Math.max(1, available);
   }
@@ -119,13 +119,6 @@ class StatusDisplay {
         this.resizeListener
       );
     }
-    if (this.signalHandler) {
-      process.removeListener("SIGINT", this.signalHandler);
-      process.removeListener("SIGTERM", this.signalHandler);
-    }
-    this.signalHandler = () => this.cleanup();
-    process.on("SIGINT", this.signalHandler);
-    process.on("SIGTERM", this.signalHandler);
     this.render();
   }
   setTicketStatus(num, status) {
@@ -152,7 +145,7 @@ class StatusDisplay {
   }
   log(message) {
     this.messages.push(message);
-    if (this.messages.length > this.config.messageLines) {
+    if (this.messages.length > MAX_MESSAGE_BUFFER) {
       this.messages.shift();
     }
     this.render();
@@ -161,10 +154,6 @@ class StatusDisplay {
     if (this.resizeListener && this.config.stream.isTTY) {
       this.config.stream.removeListener("resize", this.resizeListener);
     }
-    if (this.signalHandler) {
-      process.removeListener("SIGINT", this.signalHandler);
-      process.removeListener("SIGTERM", this.signalHandler);
-    }
     this.config.stream.write(ansi.cursorShow());
   }
   render() {
@@ -251,18 +240,21 @@ class StatusDisplay {
       renderedTicketCount = (hasMoreAbove ? 1 : 0) + visibleTickets.length + (hasMoreBelow ? 1 : 0);
     }
     output += "-".repeat(Math.min(SEPARATOR_WIDTH, width)) + "\n";
-    const msgLines = Math.max(
+    const termHeight = this.config.stream.rows ?? 24;
+    const logRows = Math.max(
       0,
-      this.config.messageLines - this.messages.length
+      termHeight - 2 - renderedTicketCount
     );
-    for (const msg of this.messages) {
+    const visibleMessages = this.messages.slice(-logRows);
+    for (const msg of visibleMessages) {
       output += `${fitLine(msg, width)}
 `;
     }
-    for (let i = 0; i < msgLines; i++) {
+    const emptyRows = logRows - visibleMessages.length;
+    for (let i = 0; i < emptyRows; i++) {
       output += "\n";
     }
-    this.renderedLines = 2 + renderedTicketCount + this.config.messageLines;
+    this.renderedLines = 2 + renderedTicketCount + logRows;
     this.config.stream.write(output);
   }
 }

package/dist/display.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/display.ts"],
-  "sourcesContent": ["export type TicketStatus =\n    | 'pending'\n    | 'in-progress'\n    | 'done'\n    | 'failed'\n\nexport type DisplayTicket = {\n    readonly num:number\n    readonly filename:string\n    status:TicketStatus\n}\n\nexport type WaveState = {\n    readonly waveNum:number\n    readonly totalWaves:number\n    readonly tickets:Array<DisplayTicket>\n}\n\nexport type DisplayConfig = {\n    readonly messageLines:number\n    readonly stream:NodeJS.WriteStream\n}\n\n/**\n * Progress across the whole run, not just the current wave.\n * `completed` counts tickets done before the wave started;\n * tickets that finish during the wave are added on top.\n */\nexport type RunProgress = {\n    readonly completed:number\n    readonly total:number\n}\n\nexport type Display = {\n    startWave(\n        waveNum:number,\n        totalWaves:number,\n        tickets:ReadonlyArray<{\n            num:number\n            filename:string\n        }>,\n        progress?:RunProgress,\n        remaining?:ReadonlyArray<{\n            num:number\n            filename:string\n        }>,\n    ):void\n    setTicketStatus(num:number, status:TicketStatus):void\n    log(message:string):void\n    cleanup():void\n}\n\nconst ESC = '\\x1b['\n\nexport const ansi = {\n    cursorUp (n:number):string {\n        return `${ESC}${n}A`\n    },\n    cursorTo (col:number):string {\n        return `${ESC}${col}G`\n    },\n    eraseLine ():string {\n        return `${ESC}2K`\n    },\n    eraseLines (n:number):string {\n        let out = ''\n        for (let i = 0; i < n; i++) {\n            out += ansi.eraseLine()\n            if (i < n - 1) out += ansi.cursorUp(1)\n        }\n        return out\n    },\n    cursorHide ():string {\n        return `${ESC}?25l`\n    },\n    cursorShow ():string {\n        return `${ESC}?25h`\n    },\n} as const\n\nexport const color = {\n    green (text:string):string {\n        return `${ESC}32m${text}${ESC}0m`\n    },\n    yellow (text:string):string {\n        return `${ESC}33m${text}${ESC}0m`\n    },\n    red (text:string):string {\n        return `${ESC}31m${text}${ESC}0m`\n    },\n    dim (text:string):string {\n        return `${ESC}2m${text}${ESC}0m`\n    },\n} as const\n\nconst FILLED_DOT = '\u25CF'\nconst EMPTY_DOT = '\u25CB'\nconst SEPARATOR_WIDTH = 50\nconst DEFAULT_COLUMNS = 80\n\n// eslint-disable-next-line no-control-regex\nconst ANSI_RE = /\\x1b\\[[0-9;?]*[A-Za-z]/g\n\n/**\n * Clamp a line to `width` visible columns so it can never wrap.\n * A wrapped line occupies more terminal rows than `render`\n * counts, which leaves stale rows behind on the next erase.\n */\nexport function fitLine (line:string, width:number):string {\n    const visible = line.replace(ANSI_RE, '')\n    if (visible.length <= width) return line\n    return visible.slice(0, width)\n}\n\nexport function renderDot (status:TicketStatus):string {\n    switch (status) {\n        case 'pending':\n            return color.dim(EMPTY_DOT)\n        case 'in-progress':\n            return color.yellow(FILLED_DOT)\n        case 'done':\n            return color.green(FILLED_DOT)\n        case 'failed':\n            return color.red(FILLED_DOT)\n    }\n}\n\nexport class StatusDisplay implements Display {\n    private wave:WaveState|null = null\n    private progress:RunProgress|null = null\n    private remaining:Array<DisplayTicket> = []\n    private messages:Array<string> = []\n    private renderedLines:number = 0\n    private config:DisplayConfig\n    private viewportStart:number = 0\n    private resizeListener:(() => void)|null = null\n    private signalHandler:(() => void)|null = null\n\n    constructor (config?:Readonly<Partial<DisplayConfig>>) {\n        this.config = {\n            messageLines:config?.messageLines ?? 10,\n            stream:config?.stream ?? process.stdout,\n        }\n    }\n\n    private getAvailableRows ():number {\n        const termHeight = this.config.stream.rows ?? 24\n        const overhead = 2 + this.config.messageLines\n        const available = termHeight - overhead\n        return Math.max(1, available)\n    }\n\n    startWave (\n        waveNum:number,\n        totalWaves:number,\n        tickets:Array<Readonly<{ num:number; filename:string }>>,\n        progress?:RunProgress,\n        remaining?:ReadonlyArray<{\n            num:number\n            filename:string\n        }>,\n    ):void {\n        this.wave = {\n            waveNum,\n            totalWaves,\n            tickets:tickets.map(t => ({\n                ...t,\n                status:'pending' as const,\n            })),\n        }\n        this.remaining = (remaining ?? []).map(t => ({\n            ...t,\n            status:'pending' as const,\n        }))\n        this.progress = progress ?? null\n        this.messages = []\n        this.viewportStart = 0\n        this.config.stream.write(ansi.cursorHide())\n\n        if (this.config.stream.isTTY) {\n            if (this.resizeListener) {\n                this.config.stream.removeListener(\n                    'resize', this.resizeListener,\n                )\n            }\n            this.resizeListener = () => this.render()\n            this.config.stream.on(\n                'resize', this.resizeListener,\n            )\n        }\n\n        // Register signal handler to restore cursor on interruption\n        if (this.signalHandler) {\n            process.removeListener('SIGINT', this.signalHandler)\n            process.removeListener('SIGTERM', this.signalHandler)\n        }\n        this.signalHandler = () => this.cleanup()\n        process.on('SIGINT', this.signalHandler)\n        process.on('SIGTERM', this.signalHandler)\n\n        this.render()\n    }\n\n    setTicketStatus (num:number, status:TicketStatus):void {\n        if (!this.wave) return\n\n        const ticket = this.wave.tickets.find(t => t.num === num)\n        if (ticket) {\n            ticket.status = status\n\n            if (status === 'in-progress') {\n                const ticketIndex = this.wave.tickets.indexOf(ticket)\n                const availableRows = this.getAvailableRows()\n                const totalTickets = this.wave.tickets.length\n\n                if (ticketIndex < this.viewportStart) {\n                    this.viewportStart = ticketIndex\n                } else if (ticketIndex >= this.viewportStart + availableRows) {\n                    // offset by 3 to keep context visible below\n                    // the active ticket\n                    this.viewportStart = ticketIndex - availableRows + 3\n                }\n                this.viewportStart = Math.max(\n                    0,\n                    Math.min(this.viewportStart, totalTickets - 1),\n                )\n            }\n\n            this.render()\n        }\n    }\n\n    log (message:string):void {\n        this.messages.push(message)\n        if (this.messages.length > this.config.messageLines) {\n            this.messages.shift()\n        }\n        this.render()\n    }\n\n    cleanup ():void {\n        // Remove resize listener if it exists\n        if (this.resizeListener && this.config.stream.isTTY) {\n            this.config.stream.removeListener('resize', this.resizeListener)\n        }\n        // Remove signal handlers\n        if (this.signalHandler) {\n            process.removeListener('SIGINT', this.signalHandler)\n            process.removeListener('SIGTERM', this.signalHandler)\n        }\n        this.config.stream.write(ansi.cursorShow())\n    }\n\n    private render ():void {\n        if (!this.wave) return\n\n        let output = ''\n\n        if (this.renderedLines > 0) {\n            output += ansi.eraseLines(this.renderedLines + 1)\n        }\n\n        const doneInWave = this.wave.tickets.filter(\n            t => t.status === 'done',\n        ).length\n        const completed = doneInWave + (this.progress?.completed ?? 0)\n        const total = this.progress?.total ?? this.wave.tickets.length\n        const pct = total === 0 ? 0 : Math.round((completed / total) * 100)\n        const width = Math.max(\n            1,\n            (this.config.stream.columns ?? DEFAULT_COLUMNS) - 1,\n        )\n\n        output += `Wave ${this.wave.waveNum}/` +\n            `${this.wave.totalWaves} - ` +\n            `${pct}% complete\\n`\n\n        // Pagination logic\n        const availableRows = this.getAvailableRows()\n        const tickets:ReadonlyArray<DisplayTicket> = [\n            ...this.wave.tickets,\n            ...this.remaining,\n        ]\n        let renderedTicketCount = 0\n\n        if (tickets.length <= availableRows) {\n            // All tickets fit, no pagination\n            for (const ticket of tickets) {\n                const dot = renderDot(ticket.status)\n                const name = fitLine(ticket.filename, width - 2)\n                output += `${dot} ${name}\\n`\n            }\n            renderedTicketCount = tickets.length\n        } else {\n            // Need pagination -- iterative clamp\n            this.viewportStart = Math.max(\n                0,\n                Math.min(\n                    this.viewportStart,\n                    tickets.length - 1,\n                ),\n            )\n\n            let hasMoreAbove = this.viewportStart > 0\n            let tentativeCount =\n                availableRows - (hasMoreAbove ? 1 : 0)\n            let hasMoreBelow =\n                this.viewportStart + tentativeCount <\n                tickets.length\n            let ticketsToShow = Math.max(\n                0,\n                tentativeCount - (hasMoreBelow ? 1 : 0),\n            )\n\n            const maxStart = Math.max(\n                0,\n                tickets.length - Math.max(1, ticketsToShow),\n            )\n            if (this.viewportStart > maxStart) {\n                this.viewportStart = maxStart\n                hasMoreAbove = this.viewportStart > 0\n                tentativeCount = availableRows - (hasMoreAbove ? 1 : 0)\n                hasMoreBelow = (\n                    this.viewportStart +\n                    tentativeCount < tickets.length\n                )\n                ticketsToShow = Math.max(\n                    0,\n                    tentativeCount - (hasMoreBelow ? 1 : 0)\n                )\n            }\n\n            // Show \"more above\" indicator if needed\n            if (hasMoreAbove) {\n                const moreCount = this.viewportStart\n                output += `  ... ${moreCount} more above\\n`\n            }\n\n            // Get visible tickets and render them\n            const visibleTickets = tickets.slice(\n                this.viewportStart,\n                this.viewportStart + ticketsToShow,\n            )\n\n            for (const ticket of visibleTickets) {\n                const dot = renderDot(ticket.status)\n                const name = fitLine(ticket.filename, width - 2)\n                output += `${dot} ${name}\\n`\n            }\n\n            // Show \"more below\" indicator if needed\n            if (hasMoreBelow) {\n                const moreCount = (\n                    tickets.length -\n                    (this.viewportStart + ticketsToShow)\n                )\n                output += `  ... ${moreCount} more below\\n`\n            }\n\n            renderedTicketCount = (hasMoreAbove ? 1 : 0) +\n                visibleTickets.length +\n                (hasMoreBelow ? 1 : 0)\n        }\n\n        output += '-'.repeat(Math.min(SEPARATOR_WIDTH, width)) + '\\n'\n\n        const msgLines = Math.max(\n            0,\n            this.config.messageLines - this.messages.length,\n        )\n        for (const msg of this.messages) {\n            output += `${fitLine(msg, width)}\\n`\n        }\n        for (let i = 0; i < msgLines; i++) {\n            output += '\\n'\n        }\n\n        this.renderedLines = 2 + renderedTicketCount + this.config.messageLines\n        this.config.stream.write(output)\n    }\n}\n\nexport class PlainDisplay implements Display {\n    startWave (\n        waveNum:number,\n        _totalWaves:number,\n        tickets:ReadonlyArray<{ num:number; filename:string }>,\n        progress?:RunProgress,\n        _remaining?:ReadonlyArray<{\n            num:number\n            filename:string\n        }>,\n    ):void {\n        const pct = progress && progress.total > 0 ?\n            ` (${progress.completed}/${progress.total} done)` :\n            ''\n        console.log(\n            `\\nWave ${waveNum}${pct}: ` +\n            tickets.map(t => t.filename).join(', ')\n        )\n    }\n\n    setTicketStatus (_num:number, _status:TicketStatus):void {\n        // no-op: plain mode reports via log()\n    }\n\n    log (message:string):void {\n        console.log(message)\n    }\n\n    cleanup ():void {\n        // no-op\n    }\n}\n\nexport function createDisplay (stream?:NodeJS.WriteStream):Display {\n    const s = stream ?? process.stdout\n    if (s.isTTY) {\n        return new StatusDisplay({ stream:s })\n    }\n\n    return new PlainDisplay()\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["export type TicketStatus =\n    | 'pending'\n    | 'in-progress'\n    | 'done'\n    | 'failed'\n\nexport type DisplayTicket = {\n    readonly num:number\n    readonly filename:string\n    status:TicketStatus\n}\n\nexport type WaveState = {\n    readonly waveNum:number\n    readonly totalWaves:number\n    readonly tickets:Array<DisplayTicket>\n}\n\nexport type DisplayConfig = {\n    readonly stream:NodeJS.WriteStream\n}\n\n/**\n * Progress across the whole run, not just the current wave.\n * `completed` counts tickets done before the wave started;\n * tickets that finish during the wave are added on top.\n */\nexport type RunProgress = {\n    readonly completed:number\n    readonly total:number\n}\n\nexport type Display = {\n    startWave(\n        waveNum:number,\n        totalWaves:number,\n        tickets:ReadonlyArray<{\n            num:number\n            filename:string\n        }>,\n        progress?:RunProgress,\n        remaining?:ReadonlyArray<{\n            num:number\n            filename:string\n        }>,\n    ):void\n    setTicketStatus(num:number, status:TicketStatus):void\n    log(message:string):void\n    cleanup():void\n}\n\nconst ESC = '\\x1b['\n\nexport const ansi = {\n    cursorUp (n:number):string {\n        return `${ESC}${n}A`\n    },\n    cursorTo (col:number):string {\n        return `${ESC}${col}G`\n    },\n    eraseLine ():string {\n        return `${ESC}2K`\n    },\n    eraseLines (n:number):string {\n        let out = ''\n        for (let i = 0; i < n; i++) {\n            out += ansi.eraseLine()\n            if (i < n - 1) out += ansi.cursorUp(1)\n        }\n        return out\n    },\n    cursorHide ():string {\n        return `${ESC}?25l`\n    },\n    cursorShow ():string {\n        return `${ESC}?25h`\n    },\n} as const\n\nexport const color = {\n    green (text:string):string {\n        return `${ESC}32m${text}${ESC}0m`\n    },\n    yellow (text:string):string {\n        return `${ESC}33m${text}${ESC}0m`\n    },\n    red (text:string):string {\n        return `${ESC}31m${text}${ESC}0m`\n    },\n    dim (text:string):string {\n        return `${ESC}2m${text}${ESC}0m`\n    },\n} as const\n\nconst FILLED_DOT = '\u25CF'\nconst EMPTY_DOT = '\u25CB'\nconst SEPARATOR_WIDTH = 50\nconst DEFAULT_COLUMNS = 80\nconst MIN_LOG_ROWS = 1\nconst MAX_MESSAGE_BUFFER = 200\n\n// eslint-disable-next-line no-control-regex\nconst ANSI_RE = /\\x1b\\[[0-9;?]*[A-Za-z]/g\n\n/**\n * Clamp a line to `width` visible columns so it can never wrap.\n * A wrapped line occupies more terminal rows than `render`\n * counts, which leaves stale rows behind on the next erase.\n */\nexport function fitLine (line:string, width:number):string {\n    const visible = line.replace(ANSI_RE, '')\n    if (visible.length <= width) return line\n    return visible.slice(0, width)\n}\n\nexport function renderDot (status:TicketStatus):string {\n    switch (status) {\n        case 'pending':\n            return color.dim(EMPTY_DOT)\n        case 'in-progress':\n            return color.yellow(FILLED_DOT)\n        case 'done':\n            return color.green(FILLED_DOT)\n        case 'failed':\n            return color.red(FILLED_DOT)\n    }\n}\n\nexport class StatusDisplay implements Display {\n    private wave:WaveState|null = null\n    private progress:RunProgress|null = null\n    private remaining:Array<DisplayTicket> = []\n    private messages:Array<string> = []\n    private renderedLines:number = 0\n    private config:DisplayConfig\n    private viewportStart:number = 0\n    private resizeListener:(() => void)|null = null\n\n    constructor (config?:Readonly<Partial<DisplayConfig>>) {\n        this.config = {\n            stream:config?.stream ?? process.stdout,\n        }\n    }\n\n    private getAvailableRows ():number {\n        const termHeight = this.config.stream.rows ?? 24\n        const overhead = 2 + MIN_LOG_ROWS\n        const available = termHeight - overhead\n        return Math.max(1, available)\n    }\n\n    startWave (\n        waveNum:number,\n        totalWaves:number,\n        tickets:Array<Readonly<{ num:number; filename:string }>>,\n        progress?:RunProgress,\n        remaining?:ReadonlyArray<{\n            num:number\n            filename:string\n        }>,\n    ):void {\n        this.wave = {\n            waveNum,\n            totalWaves,\n            tickets:tickets.map(t => ({\n                ...t,\n                status:'pending' as const,\n            })),\n        }\n        this.remaining = (remaining ?? []).map(t => ({\n            ...t,\n            status:'pending' as const,\n        }))\n        this.progress = progress ?? null\n        this.messages = []\n        this.viewportStart = 0\n        this.config.stream.write(ansi.cursorHide())\n\n        if (this.config.stream.isTTY) {\n            if (this.resizeListener) {\n                this.config.stream.removeListener(\n                    'resize', this.resizeListener,\n                )\n            }\n            this.resizeListener = () => this.render()\n            this.config.stream.on(\n                'resize', this.resizeListener,\n            )\n        }\n\n        this.render()\n    }\n\n    setTicketStatus (num:number, status:TicketStatus):void {\n        if (!this.wave) return\n\n        const ticket = this.wave.tickets.find(t => t.num === num)\n        if (ticket) {\n            ticket.status = status\n\n            if (status === 'in-progress') {\n                const ticketIndex = this.wave.tickets.indexOf(ticket)\n                const availableRows = this.getAvailableRows()\n                const totalTickets = this.wave.tickets.length\n\n                if (ticketIndex < this.viewportStart) {\n                    this.viewportStart = ticketIndex\n                } else if (ticketIndex >= this.viewportStart + availableRows) {\n                    // offset by 3 to keep context visible below\n                    // the active ticket\n                    this.viewportStart = ticketIndex - availableRows + 3\n                }\n                this.viewportStart = Math.max(\n                    0,\n                    Math.min(this.viewportStart, totalTickets - 1),\n                )\n            }\n\n            this.render()\n        }\n    }\n\n    log (message:string):void {\n        this.messages.push(message)\n        if (this.messages.length > MAX_MESSAGE_BUFFER) {\n            this.messages.shift()\n        }\n        this.render()\n    }\n\n    cleanup ():void {\n        // Remove resize listener if it exists\n        if (this.resizeListener && this.config.stream.isTTY) {\n            this.config.stream.removeListener('resize', this.resizeListener)\n        }\n        this.config.stream.write(ansi.cursorShow())\n    }\n\n    private render ():void {\n        if (!this.wave) return\n\n        let output = ''\n\n        if (this.renderedLines > 0) {\n            output += ansi.eraseLines(this.renderedLines + 1)\n        }\n\n        const doneInWave = this.wave.tickets.filter(\n            t => t.status === 'done',\n        ).length\n        const completed = doneInWave + (this.progress?.completed ?? 0)\n        const total = this.progress?.total ?? this.wave.tickets.length\n        const pct = total === 0 ? 0 : Math.round((completed / total) * 100)\n        const width = Math.max(\n            1,\n            (this.config.stream.columns ?? DEFAULT_COLUMNS) - 1,\n        )\n\n        output += `Wave ${this.wave.waveNum}/` +\n            `${this.wave.totalWaves} - ` +\n            `${pct}% complete\\n`\n\n        // Pagination logic\n        const availableRows = this.getAvailableRows()\n        const tickets:ReadonlyArray<DisplayTicket> = [\n            ...this.wave.tickets,\n            ...this.remaining,\n        ]\n        let renderedTicketCount = 0\n\n        if (tickets.length <= availableRows) {\n            // All tickets fit, no pagination\n            for (const ticket of tickets) {\n                const dot = renderDot(ticket.status)\n                const name = fitLine(ticket.filename, width - 2)\n                output += `${dot} ${name}\\n`\n            }\n            renderedTicketCount = tickets.length\n        } else {\n            // Need pagination -- iterative clamp\n            this.viewportStart = Math.max(\n                0,\n                Math.min(\n                    this.viewportStart,\n                    tickets.length - 1,\n                ),\n            )\n\n            let hasMoreAbove = this.viewportStart > 0\n            let tentativeCount =\n                availableRows - (hasMoreAbove ? 1 : 0)\n            let hasMoreBelow =\n                this.viewportStart + tentativeCount <\n                tickets.length\n            let ticketsToShow = Math.max(\n                0,\n                tentativeCount - (hasMoreBelow ? 1 : 0),\n            )\n\n            const maxStart = Math.max(\n                0,\n                tickets.length - Math.max(1, ticketsToShow),\n            )\n            if (this.viewportStart > maxStart) {\n                this.viewportStart = maxStart\n                hasMoreAbove = this.viewportStart > 0\n                tentativeCount = availableRows - (hasMoreAbove ? 1 : 0)\n                hasMoreBelow = (\n                    this.viewportStart +\n                    tentativeCount < tickets.length\n                )\n                ticketsToShow = Math.max(\n                    0,\n                    tentativeCount - (hasMoreBelow ? 1 : 0)\n                )\n            }\n\n            // Show \"more above\" indicator if needed\n            if (hasMoreAbove) {\n                const moreCount = this.viewportStart\n                output += `  ... ${moreCount} more above\\n`\n            }\n\n            // Get visible tickets and render them\n            const visibleTickets = tickets.slice(\n                this.viewportStart,\n                this.viewportStart + ticketsToShow,\n            )\n\n            for (const ticket of visibleTickets) {\n                const dot = renderDot(ticket.status)\n                const name = fitLine(ticket.filename, width - 2)\n                output += `${dot} ${name}\\n`\n            }\n\n            // Show \"more below\" indicator if needed\n            if (hasMoreBelow) {\n                const moreCount = (\n                    tickets.length -\n                    (this.viewportStart + ticketsToShow)\n                )\n                output += `  ... ${moreCount} more below\\n`\n            }\n\n            renderedTicketCount = (hasMoreAbove ? 1 : 0) +\n                visibleTickets.length +\n                (hasMoreBelow ? 1 : 0)\n        }\n\n        output += '-'.repeat(Math.min(SEPARATOR_WIDTH, width)) + '\\n'\n\n        const termHeight = this.config.stream.rows ?? 24\n        const logRows = Math.max(\n            0,\n            termHeight - 2 - renderedTicketCount,\n        )\n        const visibleMessages = this.messages.slice(-logRows)\n        for (const msg of visibleMessages) {\n            output += `${fitLine(msg, width)}\\n`\n        }\n        const emptyRows = logRows - visibleMessages.length\n        for (let i = 0; i < emptyRows; i++) {\n            output += '\\n'\n        }\n\n        this.renderedLines = 2 + renderedTicketCount + logRows\n        this.config.stream.write(output)\n    }\n}\n\nexport class PlainDisplay implements Display {\n    startWave (\n        waveNum:number,\n        _totalWaves:number,\n        tickets:ReadonlyArray<{ num:number; filename:string }>,\n        progress?:RunProgress,\n        _remaining?:ReadonlyArray<{\n            num:number\n            filename:string\n        }>,\n    ):void {\n        const pct = progress && progress.total > 0 ?\n            ` (${progress.completed}/${progress.total} done)` :\n            ''\n        console.log(\n            `\\nWave ${waveNum}${pct}: ` +\n            tickets.map(t => t.filename).join(', ')\n        )\n    }\n\n    setTicketStatus (_num:number, _status:TicketStatus):void {\n        // no-op: plain mode reports via log()\n    }\n\n    log (message:string):void {\n        console.log(message)\n    }\n\n    cleanup ():void {\n        // no-op\n    }\n}\n\nexport function createDisplay (stream?:NodeJS.WriteStream):Display {\n    const s = stream ?? process.stdout\n    if (s.isTTY) {\n        return new StatusDisplay({ stream:s })\n    }\n\n    return new PlainDisplay()\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/docs-templates/issue-tracker-github.md

@@ -141,88 +141,18 @@ gh issue view <number>
 
 The user will normally pass the issue number.
 
-## Wayfinding Operations
-
-Used by `/wayfinder` and similar domain-driven agents. GitHub Issues uses native features for navigation:
-
-- **Map**: A pinned issue or GitHub project that lists related issues as task items
-- **Child issues**: Related issues linked via GitHub issue dependencies (see below)
-- **Blocking**: Use GitHub issue dependencies to mark blocking relationships
-- **Frontier**: Query with `gh issue list --state open --assignee "" --label "available"`
-- **Claim**: Assign the issue to yourself with `gh issue edit <number> --add-assignee "@me"`
-- **Resolve**: Close the issue and link to context (PR, gist, decision record) in the final comment
-
-## Blocking and Dependencies
-
-### Mark as blocked
-
-Add the `blocked` label and optionally a comment referencing the blocking issue:
-
-```bash
-gh issue edit <number> --add-label "blocked"
-gh issue comment <number> --body "Blocked by #42"
-```
-
-### Link related issues
-
-Use issue references in comments and body text. GitHub auto-links:
-
-```bash
-# In an issue comment or body, write:
-Relates to #123
-Depends on #456
-Blocks #789
-Fixed in #999
-```
-
-These create bidirectional links visible in the issue UI.
-
-### Check if unblocked
-
-Query the blocking issues referenced in the issue's comments or description. An issue is unblocked when no blocking issues remain open.
-
-## Frontier Query and Workflow
-
-### Find available issues
-
-Query for open, unassigned issues:
-
-```bash
-gh issue list --state open --assignee "" --label "available,p0" --json number,title
-```
-
-### Claim an issue
-
-Assign to yourself when starting work:
-
-```bash
-gh issue edit <number> --add-assignee "@me"
-```
-
-Optionally add `in-progress` label:
-
-```bash
-gh issue edit <number> --add-label "in-progress"
-```
-
-### Resolve an issue
-
-Work through the issue in a PR. When done, close the issue and link the PR:
-
-```bash
-gh issue close <number> --comment "Resolved in PR #999"
-```
-
-Alternatively, create a closing comment with a reference:
-
-```bash
-gh issue comment <number> --body "Fixed in PR #999"
-gh issue close <number>
-```
-
-## Tips
-
-- Use GitHub milestones to group related features
-- Use `gh issue create --web` to open the issue creation form in your browser
-- Use `gh issue edit <number> --web` to open an issue in the browser for complex edits
-- Save frequently-used queries as saved views in the GitHub web UI
+## Tickets are executed within hours, not weeks
+
+Tickets in this tracker are run by an autonomous agent shortly
+after they are written, with a fixed time budget and no
+interview. This changes one upstream rule:
+
+- Do include the file paths, module names, and exported symbols
+  the ticket touches. Put the list under a `## Touches` heading
+  in the issue body. The "avoid specific file paths" guidance in
+  `to-tickets` exists for long-lived human trackers and does not
+  apply here.
+- Keep the `- [ ]` acceptance criteria phrased as observable
+  behavior. The agent writes one failing test per criterion, so
+  each criterion should be testable at a seam named in the spec's
+  Testing Decisions.

package/dist/docs-templates/issue-tracker.md

@@ -8,6 +8,7 @@ Issues and specs for this repo live as markdown files in `.scratch/`.
 - The spec is `.scratch/<feature-slug>/spec.md`
 - Implementation issues are one file per ticket at `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01`, never a single combined tickets file
 - Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
+- Dependencies are recorded as a `**Blocked by:**` line near the top of each issue file, listing the numbers of the tickets that must complete first, or `None`
 - Comments and conversation history append to the bottom of the file under a `## Comments` heading
 
 ## When a skill says "publish to the issue tracker"
@@ -18,13 +19,18 @@ Create a new file under `.scratch/<feature-slug>/` (creating the directory if ne
 
 Read the file at the referenced path. The user will normally pass the path or the issue number directly.
 
-## Wayfinding operations
-
-Used by `/wayfinder`. The **map** is a file with one **child** file per ticket.
-
-- **Map**: `.scratch/<effort>/map.md` (the Notes / Decisions-so-far / Fog body).
-- **Child ticket**: `.scratch/<effort>/issues/NN-<slug>.md`, numbered from `01`, with the question in the body. A `Type:` line records the ticket type (`research`/`prototype`/`grilling`/`task`); a `Status:` line records `claimed`/`resolved`.
-- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked when every file it lists is `resolved`.
-- **Frontier**: scan `.scratch/<effort>/issues/` for files that are open, unblocked, and unclaimed; first by number wins.
-- **Claim**: set `Status: claimed` and save before any work.
-- **Resolve**: append the answer under an `## Answer` heading, set `Status: resolved`, then append a context pointer (gist + link) to the map's Decisions-so-far in `map.md`.
+## Tickets are executed within hours, not weeks
+
+Tickets in this tracker are run by an autonomous agent shortly
+after they are written, with a fixed time budget and no
+interview. This changes one upstream rule:
+
+- Do include the file paths, module names, and exported symbols
+  the ticket touches. Put them on a `**Touches:**` line directly
+  under `**Blocked by:**`. The "avoid specific file paths" guidance
+  in `to-tickets` exists for long-lived human trackers and does not
+  apply here.
+- Keep the `- [ ]` acceptance criteria phrased as observable
+  behavior. The agent writes one failing test per criterion, so
+  each criterion should be testable at a seam named in the spec's
+  Testing Decisions.