nightralph 0.0.0

package/src/skills/to-tickets/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: to-tickets
+description: Break a plan, spec, or the current conversation into a set of tracer-bullet tickets, each declaring its blocking edges, published to the configured tracker (edges as text in one file per ticket locally, or native blocking links on a real tracker).
+disable-model-invocation: true
+---
+
+# To Tickets
+
+Break a plan, spec, or conversation into a set of **tickets**: tracer-bullet vertical slices, each declaring the tickets that **block** it.
+
+The issue tracker and triage label vocabulary should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`.
+
+## Process
+
+### 1. Gather context
+
+Work from whatever is already in the conversation context. If the user passes a reference (a spec path, an issue number or URL) as an argument, fetch it and read its full body and comments.
+
+### 2. Explore the codebase (optional)
+
+If you have not already explored the codebase, do so to understand the current state of the code. Ticket titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching.
+
+Look for opportunities to prefactor the code to make the implementation easier. "Make the change easy, then make the easy change."
+
+### 3. Draft vertical slices
+
+Break the work into **tracer bullet** tickets.
+
+<vertical-slice-rules>
+
+- Each slice cuts a narrow but COMPLETE path through every layer (schema, API, UI, tests): vertical, NOT a horizontal slice of one layer
+- A completed slice is demoable or verifiable on its own
+- Each slice is sized to fit in a single fresh context window
+- Any prefactoring should be done first
+
+</vertical-slice-rules>
+
+Give each ticket its **blocking edges**: the other tickets that must complete before it can start. A ticket with no blockers can start immediately.
+
+**Wide refactors are the exception to vertical slicing.** A **wide refactor** is one mechanical change (rename a column, retype a shared symbol) whose **blast radius** fans across the whole codebase, so a single edit breaks thousands of call sites at once and no vertical slice can land green. Don't force it into a tracer bullet; sequence it as **expand–contract**. First expand: add the new form beside the old so nothing breaks. Then migrate the call sites over in batches sized by blast radius (per package, per directory), each batch its own ticket blocked by the expand, keeping CI green batch to batch because the old form still exists. Finally contract: delete the old form once no caller remains, in a ticket blocked by every migrate batch. When even the batches can't stay green alone, keep the sequence but let them share an integration branch that all block a final integrate-and-verify ticket; green is promised only there.
+
+### 4. Quiz the user
+
+Present the proposed breakdown as a numbered list. For each ticket, show:
+
+- **Title**: short descriptive name
+- **Blocked by**: which other tickets (if any) must complete first
+- **What it delivers**: the end-to-end behaviour this ticket makes work
+
+Ask the user:
+
+- Does the granularity feel right? (too coarse / too fine)
+- Are the blocking edges correct: does each ticket only depend on tickets that genuinely gate it?
+- Should any tickets be merged or split further?
+
+Iterate until the user approves the breakdown.
+
+### 5. Publish the tickets to the configured tracker
+
+Publish the approved tickets. **How** depends on the tracker `/setup-matt-pocock-skills` configured; the tickets are the same either way, only the shape of the blocking edges changes:
+
+- **Local files** → write one file per ticket under `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01` in dependency order (blockers first). Each file's "Blocked by" lists the numbers/titles it depends on. Use the per-ticket file template below: one ticket per file, never a single combined file.
+- **A real issue tracker (GitHub, Linear, …)** → publish one issue per ticket in dependency order (blockers first) so each ticket's blocking edges can reference real identifiers. Use the platform's native blocking / sub-issue relationship where it has one; otherwise set each ticket's "Blocked by" to the blocking issues. Apply the `ready-for-agent` triage label unless instructed otherwise; the tickets are agent-grabbable by construction.
+
+Work the **frontier**: any ticket whose blockers are all done. For a purely linear chain that means top to bottom.
+
+Do NOT close or modify any parent issue.
+
+<local-ticket-template>
+
+# <NN>: <Ticket title>
+
+**What to build:** the end-to-end behaviour this ticket makes work, from the user's perspective, not a layer-by-layer implementation list.
+
+**Blocked by:** the numbers/titles of the tickets that gate this one, or "None (can start immediately)".
+
+**Status:** ready-for-agent
+
+- [ ] Acceptance criterion 1
+- [ ] Acceptance criterion 2
+
+</local-ticket-template>
+
+<issue-template>
+
+## Parent
+
+A reference to the parent issue on the tracker (if the source was an existing issue, otherwise omit this section).
+
+## What to build
+
+The end-to-end behaviour this ticket makes work, from the user's perspective, not layer-by-layer implementation.
+
+## Acceptance criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Blocked by
+
+- A reference to each blocking ticket, or "None (can start immediately)".
+
+</issue-template>
+
+In either form, avoid specific file paths or code snippets: they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it and note briefly that it came from a prototype. Trim to the decision-rich parts, not a working demo, just the important bits.

package/src/skills/to-tickets/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "To Tickets"
+  short_description: "Split a plan into tracer-bullet tickets"
+policy:
+  allow_implicit_invocation: false

package/src/skills/upstream.json

@@ -0,0 +1,5 @@
+{
+  "repo": "mattpocock/skills",
+  "commit": "6654f6b",
+  "pulledAt": "2026-08-26"
+}

package/tasks/prd-integration-test-coverage.md

@@ -0,0 +1,243 @@
+# PRD: Integration Test Coverage
+
+## Introduction
+
+The nightralph test suite has solid unit coverage for parsing,
+wave scheduling, and setup scaffolding, but nothing validates that
+the CLI commands actually work end-to-end. The CLI layer
+(`src/index.ts`) is completely untested, the `setup` and execute
+commands are never tested in composition, and `spawnAgent` is only
+exercised through trivial mock scripts. This PRD defines the
+integration tests needed to close those gaps and give confidence
+that `npx nightralph setup` followed by
+`npx nightralph claude -m <model>` works on real issue docs.
+
+## Goals
+
+- Validate the full CLI path via subprocess (`node dist/index.js`)
+- Prove that `setup` output feeds correctly into the execute command
+- Test `findFeatureDirs` and `resolveIssuesDir` with realistic
+  directory layouts
+- Test `dryRun` output (wave order, deadlock warnings, prompt preview)
+- Test the unknown-blocker warning/stripping logic in `runExecute`
+- All new tests use mock agent scripts -- no real `claude` invocation
+
+## User Stories
+
+### US-001: Subprocess CLI smoke test for execute
+
+**Description:** As a developer, I want a test that spawns
+`node dist/index.js <provider>` as a child process so that I know
+the yargs wiring, argument parsing, and file resolution work
+end-to-end.
+
+**Acceptance Criteria:**
+
+- [ ] Test spawns the built CLI with `--dir`, `--spec`, and
+      `--timeout-secs` pointing at a temp directory with ticket files
+- [ ] Uses the existing `mock-agent-pass.js` as the provider argument
+- [ ] Asserts exit code 0
+- [ ] Asserts ticket files on disk are updated to `**Status:** done`
+- [ ] Asserts log files are created in the expected location
+- [ ] Typecheck/lint passes
+
+### US-002: Subprocess CLI test for `--dry-run`
+
+**Description:** As a developer, I want a test that runs the CLI
+with `--dry-run` so that I know the dry-run path works through yargs
+and produces the expected output.
+
+**Acceptance Criteria:**
+
+- [ ] Test spawns the built CLI with `--dry-run`, `--dir`, and
+      `--spec`
+- [ ] Captures stdout
+- [ ] Asserts output contains "Wave 1:" with the expected ticket
+      filenames
+- [ ] Asserts output contains "AGENT INSTRUCTIONS" (prompt preview)
+- [ ] Asserts ticket files on disk are NOT modified
+- [ ] Typecheck/lint passes
+
+### US-003: Subprocess CLI test for `--model` flag
+
+**Description:** As a developer, I want to verify that `--model`
+(or `-m`) is passed through to the spawned agent process so that
+running `npx nightralph claude -m claude-sonnet-4-6` actually
+forwards the model argument.
+
+**Acceptance Criteria:**
+
+- [ ] Create a new mock agent script (`mock-agent-echo-args.js`)
+      that writes `process.argv` to stdout, then exits 0
+- [ ] Test spawns the CLI with `-m test-model` using this mock agent
+- [ ] Asserts the log file contains `--model` and `test-model` in
+      the captured argv
+- [ ] Typecheck/lint passes
+
+### US-004: `findFeatureDirs` returns correct structure
+
+**Description:** As a developer, I want direct tests for
+`findFeatureDirs` so that feature directory discovery is validated
+independently.
+
+**Acceptance Criteria:**
+
+- [ ] Export `findFeatureDirs` from `src/index.ts` (or extract to a
+      shared module) so it can be imported in tests
+- [ ] Test: returns empty array when `.scratch/` does not exist
+- [ ] Test: returns empty array when `.scratch/` has directories
+      without `issues/` subdirs
+- [ ] Test: returns entries with correct `name`, `dir`, and `spec`
+      paths for valid feature dirs
+- [ ] Test: ignores non-directory entries in `.scratch/`
+- [ ] Typecheck/lint passes
+
+### US-005: `resolveIssuesDir` with explicit flags
+
+**Description:** As a developer, I want to verify that when both
+`--dir` and `--spec` are provided, `resolveIssuesDir` returns them
+directly without scanning `.scratch/`.
+
+**Acceptance Criteria:**
+
+- [ ] Export `resolveIssuesDir` (or extract to a shared module)
+- [ ] Test: returns `{ dir, spec }` exactly as given when both
+      flags are provided
+- [ ] No filesystem scanning occurs (the temp dir has no `.scratch/`)
+- [ ] Typecheck/lint passes
+
+### US-006: Setup-then-execute composition test
+
+**Description:** As a developer, I want a test that runs `setup`,
+then creates issue files in the expected `.scratch/` layout, then
+runs `execute` -- proving the two commands compose correctly.
+
+**Acceptance Criteria:**
+
+- [ ] Test calls `setup()` with `tracker:'local'` in a temp project dir
+- [ ] Creates `.scratch/<feature>/issues/` with 2 ticket files and
+      a `spec.md`
+- [ ] Spawns the CLI as a subprocess pointing at that project dir
+      (using the mock agent)
+- [ ] Asserts tickets are marked done
+- [ ] Asserts logs are written to `.scratch/<feature>/logs/`
+- [ ] Asserts `docs/agents/issue-tracker.md` exists (from setup)
+- [ ] Asserts `.agents/skills/` directories exist (from setup)
+- [ ] Typecheck/lint passes
+
+### US-007: Unknown blocker warning and stripping
+
+**Description:** As a developer, I want to verify that `runExecute`
+warns about blockers referencing nonexistent ticket numbers and
+strips them so execution proceeds.
+
+**Acceptance Criteria:**
+
+- [ ] Test creates a ticket with `**Blocked by:** 99` where ticket
+      99 does not exist
+- [ ] Spawns the CLI as a subprocess
+- [ ] Asserts stderr/stdout contains a warning mentioning
+      blocker `99`
+- [ ] Asserts the ticket still completes (blocker was stripped)
+- [ ] Typecheck/lint passes
+
+### US-008: Dry-run deadlock detection
+
+**Description:** As a developer, I want the dry-run to report
+deadlocked tickets (circular dependencies) so users can fix their
+ticket graph before running real agents.
+
+**Acceptance Criteria:**
+
+- [ ] Test creates two tickets that block each other (1 blocks 2,
+      2 blocks 1)
+- [ ] Spawns the CLI with `--dry-run`
+- [ ] Asserts output contains "Deadlocked tickets" with both
+      filenames
+- [ ] Typecheck/lint passes
+
+### US-009: CLI exits with error when no tickets found
+
+**Description:** As a developer, I want to verify the CLI handles
+the empty-directory edge case gracefully.
+
+**Acceptance Criteria:**
+
+- [ ] Test points `--dir` at an empty directory
+- [ ] Asserts stdout contains "No ticket files found"
+- [ ] Asserts exit code 0 (graceful, not a crash)
+- [ ] Typecheck/lint passes
+
+### US-010: CLI exits with error for missing dir/spec
+
+**Description:** As a developer, I want the CLI to fail clearly
+when `--dir` or `--spec` point to nonexistent paths.
+
+**Acceptance Criteria:**
+
+- [ ] Test passes `--dir /nonexistent/path` with a valid `--spec`
+- [ ] Asserts exit code is non-zero
+- [ ] Asserts stderr contains "not found"
+- [ ] Test passes valid `--dir` with `--spec /nonexistent/spec.md`
+- [ ] Asserts exit code is non-zero
+- [ ] Asserts stderr contains "not found"
+- [ ] Typecheck/lint passes
+
+## Functional Requirements
+
+- FR-1: All new integration tests must use subprocess spawning
+  (`node dist/index.js`) to exercise the full CLI path including
+  yargs parsing
+- FR-2: All tests must use mock agent scripts, never the real
+  `claude` CLI
+- FR-3: A new mock agent script `mock-agent-echo-args.js` must be
+  created to validate argument forwarding
+- FR-4: `findFeatureDirs` and `resolveIssuesDir` must be exported
+  (or extracted to a testable module) for direct unit tests
+- FR-5: Tests must create and clean up temp directories -- no
+  shared mutable state between tests
+- FR-6: The composition test (US-006) must call `setup()` as a
+  library function, then spawn the CLI for execute, proving the
+  two stages connect
+- FR-7: All tests must pass `npm test` (build + run)
+
+## Non-Goals
+
+- No tests that invoke the real `claude` CLI or require
+  authentication
+- No tests for the interactive `@inquirer/prompts` select flows
+  (these require TTY)
+- No tests for `checkGhAuth()` (depends on external `gh` CLI state)
+- No performance or load testing
+- No changes to the existing unit test files
+
+## Technical Considerations
+
+- The CLI must be built (`npm run build`) before subprocess tests
+  run -- the test script already does this
+- Subprocess tests should set a short `--timeout-secs` (e.g. 10)
+  to avoid hanging
+- `findFeatureDirs` currently uses `process.cwd()` -- it will need
+  a `cwd` parameter to be testable, or the tests can set `CWD` via
+  subprocess env
+- The test file should be `test/integration.test.ts` to keep it
+  separate from the existing unit tests
+- Mock agent scripts live in `test/` alongside existing
+  `mock-agent-pass.js` and `mock-agent-fail.js`
+
+## Success Metrics
+
+- Running `npm test` exercises the full CLI path through subprocess
+- The `--model` flag is provably forwarded to the agent process
+- The setup -> execute composition is tested in a single test
+- Dry-run output is validated (wave order, deadlocks, prompt preview)
+- Edge cases (empty dir, missing paths, unknown blockers) are covered
+
+## Open Questions
+
+- Should `findFeatureDirs` accept a `cwd` parameter, or should
+  tests set `process.cwd()` via subprocess working directory? The
+  subprocess approach avoids changing the function signature but
+  is less direct for unit testing.
+- Should the integration tests live in `test/integration.test.ts`
+  or `test/cli.test.ts`?