nightralph 0.0.0

package/docs/implementation-plans/2026-08-27-issue-tracker-choice/phase_02.md

@@ -0,0 +1,212 @@
+# Issue Tracker Choice -- Phase 2: Tests and Phase 2 Note
+
+**Goal:** Update existing tests for the new `setup()` signature, add tests covering both tracker paths, and write a Phase 2 future work note documenting orchestrator GitHub support.
+
+**Architecture:** Tests follow the existing tapzero pattern with temp directories. The `makeTempProject()` helper gains a `tracker` parameter and an additional template file for GitHub. A new markdown file documents Phase 2 scope (orchestrator changes) for future implementation.
+
+**Tech Stack:** @substrate-system/tapzero, Node fs
+
+**Scope:** 2 phases (this is phase 2 of 2)
+
+**Codebase verified:** 2026-08-27
+
+---
+
+## Acceptance Criteria Coverage
+
+This phase tests:
+
+### issue-tracker-choice.AC1: Tracker choice prompt
+- **issue-tracker-choice.AC1.2 Success:** Choosing "Local Markdown" installs the local markdown issue-tracker template to `docs/agents/issue-tracker.md`
+
+### issue-tracker-choice.AC2: GitHub prerequisite check
+- **issue-tracker-choice.AC2.3 Success:** If `gh` is authenticated, setup installs the GitHub issue-tracker template
+
+### issue-tracker-choice.AC3: AGENTS.md reflects choice
+- **issue-tracker-choice.AC3.1 Success:** After setup with Local Markdown, AGENTS.md issue tracker section says "local markdown files under `.scratch/`"
+- **issue-tracker-choice.AC3.2 Success:** After setup with GitHub Issues, AGENTS.md issue tracker section says "GitHub Issues" with `gh` CLI reference
+
+### issue-tracker-choice.AC4: Template installation
+- **issue-tracker-choice.AC4.1 Success:** The correct `issue-tracker.md` is installed to `docs/agents/` based on tracker choice
+- **issue-tracker-choice.AC4.2 Success:** Non-tracker templates (triage-labels.md, domain.md) are still installed with idempotency checks
+
+---
+
+## Phase 2: Tests and Phase 2 Note
+
+<!-- START_SUBCOMPONENT_A (tasks 1-4) -->
+
+<!-- START_TASK_1 -->
+### Task 1: Update `makeTempProject` helper and existing tests
+
+**Verifies:** issue-tracker-choice.AC4.2
+
+**Files:**
+- Modify: `test/setup.test.ts:12-53` (makeTempProject helper)
+- Modify: `test/setup.test.ts:55-77` (first test -- add tracker to setup call)
+- Modify: `test/setup.test.ts:79-95` (second test -- add tracker to setup call)
+- Modify: `test/setup.test.ts:97-145` (third test -- add tracker to setup call)
+- Modify: `test/setup.test.ts:147-165` (fourth test -- update DOC_TEMPLATES assertion)
+- Modify: `test/setup.test.ts:167-189` (fifth test -- add tracker, adjust for issue-tracker behavior change)
+- Modify: `test/setup.test.ts:191-235` (sixth test -- add tracker)
+
+**Implementation:**
+
+1. **Update `makeTempProject`** -- add the GitHub tracker template to the temp `docsTemplatesDir`. Currently the helper creates template files for each entry in `DOC_TEMPLATES`. Since `issue-tracker.md` is no longer in `DOC_TEMPLATES`, the helper needs to create both tracker templates explicitly:
+   ```typescript
+   // After the DOC_TEMPLATES loop, add tracker templates:
+   writeFileSync(
+       join(docsTemplatesDir, 'issue-tracker.md'),
+       '# Issue tracker: Local Markdown'
+   )
+   writeFileSync(
+       join(docsTemplatesDir, 'issue-tracker-github.md'),
+       '# Issue tracker: GitHub'
+   )
+   ```
+
+2. **Update all existing `setup()` calls** -- add `tracker:'local'` to every existing test's `setup()` call to maintain backward compatibility. The `tracker` field is now required on `SetupOpts`.
+
+3. **Update the DOC_TEMPLATES assertion** -- the fourth test (`setup creates docs/agents/ templates`) checks all `DOC_TEMPLATES` entries exist. Since `issue-tracker.md` is no longer in `DOC_TEMPLATES`, the test should verify `triage-labels.md` and `domain.md` via the `DOC_TEMPLATES` loop, then separately verify `issue-tracker.md` exists.
+
+4. **Update the idempotency test** -- the "does not overwrite existing docs" test (fifth test) checks that `issue-tracker.md` is preserved. But with the new design, `issue-tracker.md` is always overwritten by the tracker choice. Update this test: the file SHOULD be overwritten (to allow tracker switching). Move the idempotency assertion to check `triage-labels.md` or `domain.md` instead, which are still preserved.
+
+**Testing:**
+Tests must verify:
+- issue-tracker-choice.AC4.2: After updating, existing tests still pass -- `triage-labels.md` and `domain.md` are installed with idempotency checks
+
+**Verification:**
+Run: `npm test`
+Expected: All existing tests pass (with updated assertions)
+
+**Commit:** `test: update existing tests for tracker-aware setup`
+<!-- END_TASK_1 -->
+
+<!-- START_TASK_2 -->
+### Task 2: Add tests for local markdown tracker path
+
+**Verifies:** issue-tracker-choice.AC1.2, issue-tracker-choice.AC4.1
+
+**Files:**
+- Modify: `test/setup.test.ts` (append new tests)
+
+**Implementation:**
+
+Add a test: `setup with tracker:'local' installs local issue-tracker.md`
+
+This test should:
+1. Call `makeTempProject()` to get temp dirs
+2. Call `setup({..., tracker:'local'})`
+3. Verify `docs/agents/issue-tracker.md` exists
+4. Verify its content matches the local markdown template (starts with `# Issue tracker: Local Markdown`)
+
+**Testing:**
+Tests must verify:
+- issue-tracker-choice.AC1.2: Local Markdown choice installs the local markdown template
+- issue-tracker-choice.AC4.1: Installed content matches the source template
+
+**Verification:**
+Run: `npm test`
+Expected: New test passes
+
+**Commit:** `test: add local markdown tracker path test`
+<!-- END_TASK_2 -->
+
+<!-- START_TASK_3 -->
+### Task 3: Add tests for GitHub tracker path
+
+**Verifies:** issue-tracker-choice.AC2.3, issue-tracker-choice.AC4.1
+
+**Files:**
+- Modify: `test/setup.test.ts` (append new tests)
+
+**Implementation:**
+
+Add a test: `setup with tracker:'github' installs github issue-tracker.md`
+
+This test should:
+1. Call `makeTempProject()` to get temp dirs
+2. Call `setup({..., tracker:'github'})`
+3. Verify `docs/agents/issue-tracker.md` exists
+4. Verify its content matches the GitHub template (starts with `# Issue tracker: GitHub`)
+
+**Testing:**
+Tests must verify:
+- issue-tracker-choice.AC2.3: GitHub choice installs the GitHub template
+- issue-tracker-choice.AC4.1: Installed content matches the source template for the chosen tracker
+
+**Verification:**
+Run: `npm test`
+Expected: New test passes
+
+**Commit:** `test: add GitHub tracker path test`
+<!-- END_TASK_3 -->
+
+<!-- START_TASK_4 -->
+### Task 4: Add tests for AGENTS.md generation
+
+**Verifies:** issue-tracker-choice.AC3.1, issue-tracker-choice.AC3.2
+
+**Files:**
+- Modify: `test/setup.test.ts` (append new tests)
+
+**Implementation:**
+
+Add two tests:
+
+**Test A:** `setup with tracker:'local' writes AGENTS.md with local description`
+1. Call `makeTempProject()` and `setup({..., tracker:'local'})`
+2. Verify `AGENTS.md` exists in `projectDir`
+3. Read content and verify it contains the string `local markdown files under \`.scratch/\``
+
+**Test B:** `setup with tracker:'github' writes AGENTS.md with github description`
+1. Call `makeTempProject()` and `setup({..., tracker:'github'})`
+2. Verify `AGENTS.md` exists in `projectDir`
+3. Read content and verify it contains the string `GitHub Issues`
+
+**Testing:**
+Tests must verify:
+- issue-tracker-choice.AC3.1: Local setup produces AGENTS.md with local markdown description
+- issue-tracker-choice.AC3.2: GitHub setup produces AGENTS.md with GitHub Issues description
+
+**Verification:**
+Run: `npm test`
+Expected: Both new tests pass
+
+**Commit:** `test: add AGENTS.md generation tests`
+<!-- END_TASK_4 -->
+
+<!-- END_SUBCOMPONENT_A -->
+
+<!-- START_TASK_5 -->
+### Task 5: Write Phase 2 future work note
+
+**Files:**
+- Create: `docs/implementation-plans/2026-08-27-issue-tracker-choice/phase-2-future-work.md`
+
+**Implementation:**
+
+Create a markdown file documenting the scope and approach for Phase 2 -- orchestrator GitHub support. This is a planning document, not code.
+
+The note should cover:
+
+1. **Goal**: Enable `nightralph <provider>` to pull tickets from GitHub Issues instead of `.scratch/` when the project is configured for GitHub tracking.
+
+2. **What changes in the orchestrator** (`src/orchestrator.ts`):
+   - `scanTickets()` currently reads `.scratch/<feature>/issues/` for numbered markdown files. It needs a GitHub-aware variant that queries `gh issue list` with JSON output.
+   - Status parsing: currently reads `Status:` lines from markdown. GitHub variant reads labels.
+   - Blocker parsing: currently reads `Blocked by:` lines. GitHub variant queries issue dependencies via `gh api`.
+   - Status update: currently writes `Status: done` to the file. GitHub variant runs `gh issue close`.
+
+3. **How to detect which tracker is in use**: Read `docs/agents/issue-tracker.md` and check the title line (`# Issue tracker: GitHub` vs `# Issue tracker: Local Markdown`).
+
+4. **New CLI surface**: The `--dir` and `--spec` flags assume local files. GitHub mode would use `--label` or `--milestone` to scope which issues to execute. The feature selection prompt (`resolveIssuesDir` in index.ts) would need a GitHub-aware variant.
+
+5. **Testing considerations**: GitHub orchestrator tests would need either a test repo or mocked `gh` output. The existing wave-based execution model (parallel independent tickets, sequential blocked ones) stays the same -- only the I/O layer changes.
+
+**Verification:**
+Run: `cat docs/implementation-plans/2026-08-27-issue-tracker-choice/phase-2-future-work.md`
+Expected: File exists with the documented scope
+
+**Commit:** `docs: add Phase 2 future work note for orchestrator GitHub support`
+<!-- END_TASK_5 -->

package/docs/implementation-plans/2026-08-27-issue-tracker-choice/test-requirements.md

@@ -0,0 +1,203 @@
+# Test Requirements: Issue Tracker Choice
+
+Maps each acceptance criterion to automated tests or documented human
+verification.
+
+---
+
+## AC1: Tracker choice prompt
+
+### AC1.1: Running `nightralph setup` prompts user to choose between "GitHub Issues" and "Local Markdown"
+
+**Verification:** Human
+
+**Justification:** The prompt is rendered by `@inquirer/prompts` `select`
+inside the CLI handler (`index.ts`). Testing it automatically would
+require either spawning the CLI as a child process with piped stdin or
+mocking inquirer -- both approaches test the scaffolding rather than the
+actual user-facing prompt. The implementation plan notes this is "an
+integration concern -- verified by running the CLI."
+
+**Approach:**
+1. Run `node dist/index.js setup` in a terminal
+2. Verify the prompt displays "Issue tracker format" with two choices:
+   "Local Markdown" and "GitHub Issues"
+3. Verify arrow-key selection works and the chosen value is accepted
+
+---
+
+### AC1.2: Choosing "Local Markdown" installs the local markdown issue-tracker template
+
+**Verification:** Automated test
+
+- **Test type:** Integration
+- **File:** `test/setup.test.ts`
+- **Test name:** `setup with tracker:'local' installs local issue-tracker.md`
+- **Assertions:**
+  1. Call `setup({..., tracker:'local'})` with temp project dirs
+  2. Assert `docs/agents/issue-tracker.md` exists in the project dir
+  3. Assert its content matches the local template source
+     (starts with `# Issue tracker: Local Markdown` or equivalent
+     heading from `src/docs-templates/issue-tracker.md`)
+
+---
+
+## AC2: GitHub prerequisite check
+
+### AC2.1: Choosing "GitHub Issues" runs `gh auth status` and proceeds if authenticated
+
+**Verification:** Automated test (function existence) + Human (CLI wiring)
+
+- **Test type:** Unit
+- **File:** `test/setup.test.ts`
+- **Test name:** `checkGhAuth returns true when gh is authenticated`
+- **Assertions:**
+  1. Import `checkGhAuth` from `../src/setup.js`
+  2. Call `checkGhAuth()` -- on a machine where `gh` is installed and
+     authenticated, assert it returns `true`
+
+**Human verification (CLI wiring):**
+
+The CLI handler in `index.ts` calls `checkGhAuth()` when the user
+selects "GitHub Issues." This wiring is thin glue code. Verifying it
+end-to-end requires running the CLI interactively.
+
+**Approach:**
+1. Ensure `gh auth status` succeeds on the test machine
+2. Run `node dist/index.js setup`, choose "GitHub Issues"
+3. Verify setup proceeds without error and installs the GitHub template
+
+**Note:** `checkGhAuth` is a thin wrapper around `execSync('gh auth status')`.
+The implementation plan explicitly says "unit tests with mocked exec
+would just test the mock." The automated test above is conditional on
+the test machine having `gh` installed. On CI without `gh`, this test
+should be skipped or the AC verified by human run.
+
+---
+
+### AC2.2: If `gh` is not installed or not authenticated, setup prints a message and exits with code 2
+
+**Verification:** Human
+
+**Justification:** The exit-with-code-2 behavior lives in `index.ts`
+(the CLI handler), not in the `setup()` function. Testing `process.exit`
+requires spawning a child process and inspecting its exit code. The
+implementation plan describes this handler as "thin glue" best verified
+by unit tests on the underlying functions plus a manual CLI run.
+
+**Approach:**
+1. Temporarily make `gh auth status` fail (e.g., `gh auth logout` or
+   rename `gh` binary)
+2. Run `node dist/index.js setup`, choose "GitHub Issues"
+3. Verify the output includes "GitHub Issues requires the gh CLI"
+4. Verify the process exits with code 2 (`echo $?` shows `2`)
+5. Restore `gh` auth afterward
+
+---
+
+### AC2.3: If `gh` is authenticated, setup installs the GitHub issue-tracker template
+
+**Verification:** Automated test
+
+- **Test type:** Integration
+- **File:** `test/setup.test.ts`
+- **Test name:** `setup with tracker:'github' installs github issue-tracker.md`
+- **Assertions:**
+  1. Call `setup({..., tracker:'github'})` with temp project dirs
+     (the helper provides both `issue-tracker.md` and
+     `issue-tracker-github.md` in the temp templates dir)
+  2. Assert `docs/agents/issue-tracker.md` exists in the project dir
+  3. Assert its content matches the GitHub template source
+     (starts with `# Issue tracker: GitHub` or equivalent heading
+     from `src/docs-templates/issue-tracker-github.md`)
+
+---
+
+## AC3: AGENTS.md reflects choice
+
+### AC3.1: After setup with Local Markdown, AGENTS.md says "local markdown files under `.scratch/`"
+
+**Verification:** Automated test
+
+- **Test type:** Integration
+- **File:** `test/setup.test.ts`
+- **Test name:** `setup with tracker:'local' writes AGENTS.md with local description`
+- **Assertions:**
+  1. Call `setup({..., tracker:'local'})` with temp project dirs
+  2. Assert `AGENTS.md` exists in the project dir
+  3. Read its content and assert it contains the substring
+     `local markdown files under \`.scratch/\``
+
+---
+
+### AC3.2: After setup with GitHub Issues, AGENTS.md says "GitHub Issues" with `gh` CLI reference
+
+**Verification:** Automated test
+
+- **Test type:** Integration
+- **File:** `test/setup.test.ts`
+- **Test name:** `setup with tracker:'github' writes AGENTS.md with github description`
+- **Assertions:**
+  1. Call `setup({..., tracker:'github'})` with temp project dirs
+  2. Assert `AGENTS.md` exists in the project dir
+  3. Read its content and assert it contains the substring
+     `GitHub Issues` and a reference to `gh`
+
+---
+
+## AC4: Template installation
+
+### AC4.1: The correct `issue-tracker.md` is installed to `docs/agents/` based on tracker choice
+
+**Verification:** Automated test
+
+- **Test type:** Integration
+- **File:** `test/setup.test.ts`
+- **Covered by:** The AC1.2 and AC2.3 tests above (local and GitHub
+  tracker path tests). Each verifies that `docs/agents/issue-tracker.md`
+  receives the content from the correct source template. No separate
+  test needed -- the two tracker-path tests together cover this criterion
+  exhaustively.
+
+---
+
+### AC4.2: Non-tracker templates (triage-labels.md, domain.md) are still installed with idempotency checks
+
+**Verification:** Automated test
+
+- **Test type:** Integration
+- **File:** `test/setup.test.ts`
+- **Covered by:** Two existing tests, updated to pass `tracker:'local'`:
+  1. `setup creates docs/agents/ templates` -- iterates `DOC_TEMPLATES`
+     (now `['triage-labels.md', 'domain.md']`) and asserts each exists.
+     Also separately asserts `issue-tracker.md` exists.
+  2. `setup does not overwrite existing docs` -- pre-creates
+     `triage-labels.md` (or `domain.md`) with custom content, runs
+     setup, asserts the custom content is preserved. (The old test
+     checked `issue-tracker.md` for idempotency, but that file is now
+     always overwritten by tracker choice. The assertion moves to a
+     non-tracker template.)
+  3. `setup is idempotent` -- runs setup twice, asserts all templates
+     still exist after the second run.
+
+---
+
+## Summary
+
+| AC    | Automated | Human | Test file              |
+|-------|-----------|-------|------------------------|
+| AC1.1 |           | Yes   | --                     |
+| AC1.2 | Yes       |       | `test/setup.test.ts`   |
+| AC2.1 | Partial   | Yes   | `test/setup.test.ts`   |
+| AC2.2 |           | Yes   | --                     |
+| AC2.3 | Yes       |       | `test/setup.test.ts`   |
+| AC3.1 | Yes       |       | `test/setup.test.ts`   |
+| AC3.2 | Yes       |       | `test/setup.test.ts`   |
+| AC4.1 | Yes       |       | `test/setup.test.ts`   |
+| AC4.2 | Yes       |       | `test/setup.test.ts`   |
+
+Seven of ten acceptance criteria are fully covered by automated
+integration tests. AC2.1 has partial automated coverage (function
+existence and return value) with human verification for CLI wiring.
+AC1.1 and AC2.2 require human verification because they test interactive
+CLI behavior and process exit codes in the thin handler layer.

package/docs/skills.md

@@ -0,0 +1,58 @@
+# Skill/CLI Drift
+
+Prevent version drift by bundling the CLI & skill definitions.
+
+## Background
+
+We see [nightshift](https://github.com/Shaurya-Sethi/nightshift/), which uses
+the [Pocock skills](https://github.com/mattpocock/skills/). And reading the
+docs for each, we see that the CLI has already drifted from the current version
+of the skills.
+
+The Pocock workflow is
+
+```
+grill -> to-spec -> to-tickets -> tdd
+```
+
+The upstream
+[`grill-with-docs`](https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/SKILL.md)
+skill is exposed as `/grill`. It is a composite that calls the upstream
+`grilling` and `domain-modeling` sub-skills, which are also bundled.
+
+`to-tickets` will create many issues fwiu. We need to be able to start many
+`tdd` sessions, preferably in parallel as much as possible.
+
+## Issues
+
+The `nightshift` CLI I think is hardcoded to GH issues, and we want
+local markdown. Need the Pocock skills to create local markdown.
+
+### Solution
+
+Seed `docs/agents/issue-tracker.md` via `npx` runnable script.
+
+Should include a script that can be executed with `npmx`, like
+`npmx nightralph setup`.
+
+#### Example `issue-tracker.md`
+
+This is an example config for `docs/agents/issue-tracker.md`:
+
+```
+# Issue Tracker Config
+
+Where issues live: local markdown files under .scratch/ in this repo.
+
+---
+
+## Conventions
+
+- One feature per directory: .scratch/<feature-name>/
+- Implementation issues are stored as one file per ticket at
+  `.scratch/<feature-name>/issues/NN-<name>.md`.
+- When publishing to the issue tracker: Write markdown files under
+  `.scratch/<feature-name>/issues/`.
+- When fetching a ticket: Read the file at the referenced path
+  under `.scratch/`.
+```

package/docs/test-plans/2026-08-27-issue-tracker-choice.md

@@ -0,0 +1,95 @@
+# Issue Tracker Choice -- Human Test Plan
+
+## Prerequisites
+
+- Node.js installed; project built (`npm run build` produces `dist/`)
+- `npm test` passes (66 assertions in setup.test.ts, 54 in
+  orchestrator.test.ts)
+- `gh` CLI installed and authenticated (`gh auth status` succeeds) for
+  GitHub Issues tests
+- A throwaway directory or git branch to avoid polluting a real project
+
+## Phase 1: Interactive Prompt Verification (AC1.1)
+
+| Step | Action | Expected |
+|------|--------|----------|
+| 1 | Open a terminal, `cd` to a clean temp directory | Working directory is empty or has a basic package.json |
+| 2 | Run `node <path-to-nightralph>/dist/index.js setup` | An interactive prompt appears: "Issue tracker format" |
+| 3 | Observe the choices listed | Two choices appear: "Local Markdown" (with description "Issues as .md files in .scratch/") and "GitHub Issues" (with description "Issues via gh CLI") |
+| 4 | Press up/down arrow keys | Highlighted selection moves between the two choices |
+| 5 | Highlight "Local Markdown" and press Enter | Prompt accepts the selection. Setup proceeds, printing "Installing skills to .agents/skills/" and listing installed files |
+| 6 | Verify `docs/agents/issue-tracker.md` was created | File exists, content starts with the local markdown template heading |
+| 7 | Verify `AGENTS.md` was created | File exists, contains "local markdown files under `.scratch/`" |
+
+## Phase 2: GitHub Issues -- Authenticated Path (AC2.1, AC2.3)
+
+| Step | Action | Expected |
+|------|--------|----------|
+| 1 | Confirm `gh auth status` succeeds (exit code 0) | Output shows authenticated user and active account |
+| 2 | Remove any previous setup output (`rm -rf .agents docs AGENTS.md`) | Clean state |
+| 3 | Run `node <path-to-nightralph>/dist/index.js setup` | Prompt appears |
+| 4 | Select "GitHub Issues" and press Enter | No error message. Setup proceeds normally |
+| 5 | Verify `docs/agents/issue-tracker.md` was created | File exists, content matches the GitHub template (heading references GitHub) |
+| 6 | Verify `AGENTS.md` contains "GitHub Issues" and a reference to `gh` | The issue tracker section reads: "Issues are tracked via GitHub Issues using the `gh` CLI." |
+
+## Phase 3: GitHub Issues -- Unauthenticated Path (AC2.2)
+
+| Step | Action | Expected |
+|------|--------|----------|
+| 1 | Make `gh auth status` fail. Option A: run `gh auth logout`. Option B: temporarily rename the `gh` binary (`which gh`, then `mv` it) | `gh auth status` now fails or `gh` is not found |
+| 2 | Remove any previous setup output | Clean state |
+| 3 | Run `node <path-to-nightralph>/dist/index.js setup` | Prompt appears |
+| 4 | Select "GitHub Issues" and press Enter | Error message printed: "GitHub Issues requires the gh CLI, authenticated." followed by install/login instructions |
+| 5 | Check exit code: `echo $?` | Exit code is `2` |
+| 6 | Verify no `docs/agents/issue-tracker.md` was created | File does not exist -- setup aborted before template installation |
+| 7 | Restore `gh` authentication (`gh auth login`) or rename the binary back | `gh auth status` succeeds again |
+
+## End-to-End: Full Tracker Switching Scenario
+
+**Purpose:** Validates that a user can set up with one tracker, then
+re-run setup to switch to the other, and all artifacts reflect the new
+choice.
+
+| Step | Action | Expected |
+|------|--------|----------|
+| 1 | Clean temp directory | Empty |
+| 2 | Run `node <path>/dist/index.js setup`, select "Local Markdown" | Setup completes. `AGENTS.md` mentions local markdown, `issue-tracker.md` has local template content |
+| 3 | Run `node <path>/dist/index.js setup` again, select "GitHub Issues" (requires authenticated `gh`) | Setup completes without error |
+| 4 | Read `docs/agents/issue-tracker.md` | Content now matches the GitHub template -- local template content is gone |
+| 5 | Read `AGENTS.md` | Now says "GitHub Issues using the `gh` CLI" -- no mention of "local markdown files" |
+| 6 | Verify `docs/agents/triage-labels.md` and `docs/agents/domain.md` still exist | Non-tracker templates preserved across re-runs |
+
+## End-to-End: --claude Flag with Tracker Choice
+
+**Purpose:** Validates that the `--claude` flag works correctly alongside
+tracker selection.
+
+| Step | Action | Expected |
+|------|--------|----------|
+| 1 | Clean temp directory | Empty |
+| 2 | Run `node <path>/dist/index.js setup --claude`, select "Local Markdown" | Setup completes. Skills installed to both `.agents/skills/` and `.claude/skills/` |
+| 3 | Verify `.claude/skills/<skill>` entries are symlinks | Each is a symlink pointing to `../../.agents/skills/<skill>` |
+| 4 | Verify `docs/agents/issue-tracker.md` has local template content | Tracker choice unaffected by --claude flag |
+| 5 | Run setup again with --claude, select "GitHub Issues" | Symlinks remain valid. `issue-tracker.md` now has GitHub content |
+
+## Human Verification Required
+
+| Criterion | Why Manual | Steps |
+|-----------|-----------|-------|
+| AC1.1: Prompt displays two choices | Tests the interactive `@inquirer/prompts` `select` UI, which requires a real TTY. Mocking would test the mock, not the prompt. | Phase 1, steps 2-5 |
+| AC2.1: CLI wiring calls `checkGhAuth` on "GitHub Issues" selection | The automated test confirms the function exists; the CLI handler glue (`index.ts` lines 46-55) is thin code best verified by running | Phase 2, steps 3-4 |
+| AC2.2: Unauthenticated `gh` prints error and exits with code 2 | `process.exit(2)` lives in the CLI handler; testing requires a child process with inspected exit code | Phase 3, steps 4-5 |
+
+## Traceability
+
+| Acceptance Criterion | Automated Test | Manual Step |
+|----------------------|----------------|-------------|
+| AC1.1: Prompt with two choices | -- | Phase 1, steps 2-5 |
+| AC1.2: Local Markdown installs local template | `setup with tracker:local copies local markdown template` | Phase 1, step 6 |
+| AC2.1: checkGhAuth when authenticated | `checkGhAuth exists and is callable` (partial) | Phase 2, steps 3-4 |
+| AC2.2: Unauthenticated exits with code 2 | -- | Phase 3, steps 4-6 |
+| AC2.3: GitHub Issues installs GitHub template | `setup with tracker:github copies github template` | Phase 2, step 5 |
+| AC3.1: AGENTS.md local markdown text | `setup creates AGENTS.md with local markdown text` | Phase 1, step 7 |
+| AC3.2: AGENTS.md GitHub Issues text | `setup creates AGENTS.md with GitHub Issues text` | Phase 2, step 6 |
+| AC4.1: Correct template per choice | AC1.2 + AC2.3 tests + tracker-switching test | Switching scenario, steps 2-5 |
+| AC4.2: Non-tracker templates + idempotency | `setup creates docs/agents/ templates` + `setup does not overwrite non-tracker docs` + `setup is idempotent` | Switching scenario, step 6 |