nightralph 0.0.0

package/dist/test/setup.test.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../test/setup.test.ts", "../../src/setup.ts"],
+  "sourcesContent": ["import { test } from '@substrate-system/tapzero'\nimport {\n    mkdtempSync, mkdirSync, writeFileSync, existsSync,\n    lstatSync, readlinkSync, readFileSync,\n} from 'node:fs'\nimport { join } from 'node:path'\nimport { tmpdir } from 'node:os'\nimport {\n    setup, SKILL_DIRS, DOC_TEMPLATES, checkGhAuth,\n} from '../src/setup.js'\n\nfunction makeTempProject ():{\n    projectDir:string;\n    bundledSkillsDir:string;\n    docsTemplatesDir:string;\n} {\n    const base = mkdtempSync(\n        join(tmpdir(), 'nightralph-test-')\n    )\n    const projectDir = join(base, 'project')\n    mkdirSync(projectDir, { recursive:true })\n\n    const bundledSkillsDir = join(base, 'bundled')\n    mkdirSync(bundledSkillsDir, { recursive:true })\n\n    writeFileSync(\n        join(bundledSkillsDir, 'upstream.json'),\n        JSON.stringify({\n            repo:'test/repo',\n            commit:'abc123',\n        })\n    )\n\n    for (const skill of SKILL_DIRS) {\n        const dir = join(bundledSkillsDir, skill)\n        mkdirSync(dir, { recursive:true })\n        writeFileSync(\n            join(dir, 'SKILL.md'),\n            `# ${skill}`\n        )\n    }\n\n    const docsTemplatesDir = join(base, 'docs-templates')\n    mkdirSync(docsTemplatesDir, { recursive:true })\n    for (const tmpl of DOC_TEMPLATES) {\n        writeFileSync(\n            join(docsTemplatesDir, tmpl),\n            `# ${tmpl}`\n        )\n    }\n    writeFileSync(\n        join(docsTemplatesDir, 'issue-tracker.md'),\n        '# issue-tracker.md'\n    )\n    writeFileSync(\n        join(docsTemplatesDir, 'issue-tracker-github.md'),\n        '# issue-tracker-github.md'\n    )\n\n    return { projectDir, bundledSkillsDir, docsTemplatesDir }\n}\n\ntest('setup copies skills to .agents/skills', t => {\n    const {\n        projectDir, bundledSkillsDir, docsTemplatesDir,\n    } = makeTempProject()\n\n    setup({\n        bundledSkillsDir,\n        docsTemplatesDir,\n        projectDir,\n        tracker:'local',\n    })\n\n    for (const skill of SKILL_DIRS) {\n        const dest = join(\n            projectDir, '.agents', 'skills', skill\n        )\n        t.ok(\n            existsSync(dest),\n            `${skill}/ should exist in .agents/skills`\n        )\n        t.ok(\n            existsSync(join(dest, 'SKILL.md')),\n            `${skill}/SKILL.md should be copied`\n        )\n    }\n})\n\ntest('setup does NOT create .claude/skills by default', t => {\n    const {\n        projectDir, bundledSkillsDir, docsTemplatesDir,\n    } = makeTempProject()\n\n    setup({\n        bundledSkillsDir,\n        docsTemplatesDir,\n        projectDir,\n        tracker:'local',\n    })\n\n    const claudeSkills = join(\n        projectDir, '.claude', 'skills'\n    )\n    t.ok(\n        !existsSync(claudeSkills),\n        '.claude/skills should not exist without --claude'\n    )\n})\n\ntest('setup --claude creates symlinks in .claude/skills', t => {\n    const {\n        projectDir, bundledSkillsDir, docsTemplatesDir,\n    } = makeTempProject()\n\n    setup({\n        bundledSkillsDir,\n        docsTemplatesDir,\n        projectDir,\n        claude:true,\n        tracker:'local',\n    })\n\n    for (const skill of SKILL_DIRS) {\n        const agentsDest = join(\n            projectDir, '.agents', 'skills', skill\n        )\n        t.ok(\n            existsSync(agentsDest),\n            `${skill}/ should exist in .agents/skills`\n        )\n\n        const claudeDest = join(\n            projectDir, '.claude', 'skills', skill\n        )\n        t.ok(\n            existsSync(claudeDest),\n            `${skill}/ should exist in .claude/skills`\n        )\n\n        if (!existsSync(claudeDest)) {\n            t.fail(`symlink missing for ${skill}`)\n            continue\n        }\n\n        const stat = lstatSync(claudeDest)\n        t.ok(\n            stat.isSymbolicLink(),\n            `.claude/skills/${skill} should be a symlink`\n        )\n\n        const target = readlinkSync(claudeDest)\n        const expected = join(\n            '..', '..', '.agents', 'skills', skill\n        )\n        t.equal(\n            target,\n            expected,\n            `symlink should point to ${expected}`\n        )\n    }\n})\n\ntest('setup creates docs/agents/ templates', t => {\n    const {\n        projectDir, bundledSkillsDir, docsTemplatesDir,\n    } = makeTempProject()\n\n    setup({\n        bundledSkillsDir,\n        docsTemplatesDir,\n        projectDir,\n        tracker:'local',\n    })\n\n    for (const tmpl of DOC_TEMPLATES) {\n        const dest = join(\n            projectDir, 'docs', 'agents', tmpl\n        )\n        t.ok(\n            existsSync(dest),\n            `docs/agents/${tmpl} should be created`\n        )\n    }\n})\n\ntest('setup does not overwrite non-tracker docs', t => {\n    const {\n        projectDir, bundledSkillsDir, docsTemplatesDir,\n    } = makeTempProject()\n    const triagePath = join(\n        projectDir, 'docs', 'agents', 'triage-labels.md'\n    )\n    mkdirSync(join(projectDir, 'docs', 'agents'), {\n        recursive:true,\n    })\n    writeFileSync(triagePath, 'custom triage content')\n\n    setup({\n        bundledSkillsDir,\n        docsTemplatesDir,\n        projectDir,\n        tracker:'local',\n    })\n\n    const content = readFileSync(triagePath, 'utf8')\n    t.equal(\n        content,\n        'custom triage content',\n        'should preserve existing triage-labels.md'\n    )\n})\n\ntest('setup is idempotent', t => {\n    const {\n        projectDir, bundledSkillsDir, docsTemplatesDir,\n    } = makeTempProject()\n    const opts = {\n        bundledSkillsDir,\n        docsTemplatesDir,\n        projectDir,\n        claude:true,\n        tracker:'local' as const,\n    }\n\n    setup(opts)\n    setup(opts)\n\n    for (const skill of SKILL_DIRS) {\n        const agentsDest = join(\n            projectDir, '.agents', 'skills', skill\n        )\n        t.ok(\n            existsSync(agentsDest),\n            `${skill}/ should still exist after second run`\n        )\n\n        const claudeDest = join(\n            projectDir, '.claude', 'skills', skill\n        )\n        if (!existsSync(claudeDest)) {\n            t.fail(`symlink missing for ${skill}`)\n            continue\n        }\n        const stat = lstatSync(claudeDest)\n        t.ok(\n            stat.isSymbolicLink(),\n            `${skill} symlink should still be valid`\n        )\n    }\n\n    for (const tmpl of DOC_TEMPLATES) {\n        const dest = join(\n            projectDir, 'docs', 'agents', tmpl\n        )\n        t.ok(\n            existsSync(dest),\n            `docs/agents/${tmpl} should still exist`\n        )\n    }\n})\n\ntest('checkGhAuth exists and is callable', t => {\n    t.equal(\n        typeof checkGhAuth,\n        'function',\n        'checkGhAuth should be a function'\n    )\n})\n\ntest('setup with tracker:local copies local markdown template', t => {\n    const {\n        projectDir, bundledSkillsDir, docsTemplatesDir,\n    } = makeTempProject()\n\n    setup({\n        bundledSkillsDir,\n        docsTemplatesDir,\n        projectDir,\n        tracker:'local',\n    })\n\n    const trackerPath = join(\n        projectDir, 'docs', 'agents', 'issue-tracker.md'\n    )\n    t.ok(\n        existsSync(trackerPath),\n        'docs/agents/issue-tracker.md should exist'\n    )\n    const content = readFileSync(trackerPath, 'utf8')\n    t.ok(\n        content.includes('# issue-tracker.md'),\n        'should copy local markdown template'\n    )\n})\n\ntest('setup with tracker:github copies github template', t => {\n    const {\n        projectDir, bundledSkillsDir, docsTemplatesDir,\n    } = makeTempProject()\n\n    setup({\n        bundledSkillsDir,\n        docsTemplatesDir,\n        projectDir,\n        tracker:'github',\n    })\n\n    const trackerPath = join(\n        projectDir, 'docs', 'agents', 'issue-tracker.md'\n    )\n    t.ok(\n        existsSync(trackerPath),\n        'docs/agents/issue-tracker.md should exist'\n    )\n    const content = readFileSync(trackerPath, 'utf8')\n    t.ok(\n        content.includes('# issue-tracker-github.md'),\n        'should copy github template'\n    )\n})\n\ntest('setup creates AGENTS.md with local markdown text', t => {\n    const {\n        projectDir, bundledSkillsDir, docsTemplatesDir,\n    } = makeTempProject()\n\n    setup({\n        bundledSkillsDir,\n        docsTemplatesDir,\n        projectDir,\n        tracker:'local',\n    })\n\n    const agentsMdPath = join(projectDir, 'AGENTS.md')\n    t.ok(\n        existsSync(agentsMdPath),\n        'AGENTS.md should exist'\n    )\n    const content = readFileSync(agentsMdPath, 'utf8')\n    t.ok(\n        content.includes('local markdown files'),\n        'should mention local markdown'\n    )\n})\n\ntest('setup creates AGENTS.md with GitHub Issues text', t => {\n    const {\n        projectDir, bundledSkillsDir, docsTemplatesDir,\n    } = makeTempProject()\n\n    setup({\n        bundledSkillsDir,\n        docsTemplatesDir,\n        projectDir,\n        tracker:'github',\n    })\n\n    const agentsMdPath = join(projectDir, 'AGENTS.md')\n    t.ok(\n        existsSync(agentsMdPath),\n        'AGENTS.md should exist'\n    )\n    const content = readFileSync(agentsMdPath, 'utf8')\n    t.ok(\n        content.includes('GitHub Issues'),\n        'should mention GitHub Issues'\n    )\n})\n\ntest(\n    'tracker template overwrites when switching trackers',\n    t => {\n        const {\n            projectDir, bundledSkillsDir,\n            docsTemplatesDir,\n        } = makeTempProject()\n\n        setup({\n            bundledSkillsDir,\n            docsTemplatesDir,\n            projectDir,\n            tracker:'local',\n        })\n\n        const trackerPath = join(\n            projectDir, 'docs', 'agents',\n            'issue-tracker.md'\n        )\n        const localContent = readFileSync(\n            trackerPath, 'utf8'\n        )\n        t.ok(\n            localContent.includes('# issue-tracker.md'),\n            'should have local template initially'\n        )\n\n        setup({\n            bundledSkillsDir,\n            docsTemplatesDir,\n            projectDir,\n            tracker:'github',\n        })\n\n        const githubContent = readFileSync(\n            trackerPath, 'utf8'\n        )\n        t.ok(\n            githubContent.includes('# issue-tracker-github.md'),\n            'should overwrite with GitHub template'\n        )\n        t.ok(\n            !githubContent.includes('# issue-tracker.md'),\n            'should not contain local template anymore'\n        )\n    }\n)\n", "import {\n    cpSync,\n    existsSync,\n    mkdirSync,\n    readdirSync,\n    readFileSync,\n    symlinkSync,\n    writeFileSync,\n} from 'node:fs'\nimport { join } from 'node:path'\nimport { execSync } from 'node:child_process'\n\nexport const SKILL_DIRS = [\n    'grill', 'grilling', 'domain-modeling',\n    'to-spec', 'to-tickets', 'tdd',\n] as const\n\nexport const DOC_TEMPLATES = [\n    'triage-labels.md',\n    'domain.md',\n] as const\n\nexport function checkGhAuth ():boolean {\n    try {\n        execSync('gh auth status', { stdio:'ignore' })\n        return true\n    } catch {\n        return false\n    }\n}\n\nexport type TrackerKind = 'github'|'local'\n\nexport type SetupOpts = {\n    bundledSkillsDir:string\n    docsTemplatesDir:string\n    projectDir:string\n    claude?:boolean\n    tracker:TrackerKind\n}\n\nconst TRACKER_TEMPLATES:Record<TrackerKind, string> = {\n    local:'issue-tracker.md',\n    github:'issue-tracker-github.md',\n}\n\nexport function setup (opts:SetupOpts):void {\n    const {\n        bundledSkillsDir,\n        docsTemplatesDir,\n        projectDir,\n        claude,\n        tracker,\n    } = opts\n    const agentsSkillsDir = join(\n        projectDir, '.agents', 'skills'\n    )\n\n    const upstream = JSON.parse(\n        readFileSync(\n            join(bundledSkillsDir, 'upstream.json'),\n            'utf8'\n        )\n    ) as { repo:string; commit:string }\n\n    console.log('Installing skills to .agents/skills/\\n')\n\n    for (const skill of SKILL_DIRS) {\n        const src = join(bundledSkillsDir, skill)\n        const dest = join(agentsSkillsDir, skill)\n        mkdirSync(dest, { recursive:true })\n        cpSync(src, dest, { recursive:true })\n        const files = readdirSync(src)\n        console.log(\n            `  ${skill}/ (${files.join(', ')})`\n        )\n    }\n\n    if (claude) {\n        const claudeSkillsDir = join(\n            projectDir, '.claude', 'skills'\n        )\n        mkdirSync(claudeSkillsDir, { recursive:true })\n\n        for (const skill of SKILL_DIRS) {\n            const linkPath = join(claudeSkillsDir, skill)\n            const target = join(\n                '..', '..', '.agents', 'skills', skill\n            )\n            if (existsSync(linkPath)) continue\n            symlinkSync(target, linkPath)\n        }\n\n        console.log(\n            '\\nCreated symlinks in .claude/skills/'\n        )\n    }\n\n    const docsAgentsDir = join(\n        projectDir, 'docs', 'agents'\n    )\n    mkdirSync(docsAgentsDir, { recursive:true })\n\n    console.log('')\n    for (const tmpl of DOC_TEMPLATES) {\n        const dest = join(docsAgentsDir, tmpl)\n        if (existsSync(dest)) {\n            console.log(\n                `  docs/agents/${tmpl} (already exists)`\n            )\n            continue\n        }\n        const src = join(docsTemplatesDir, tmpl)\n        writeFileSync(dest, readFileSync(src, 'utf8'))\n        console.log(`  docs/agents/${tmpl} (created)`)\n    }\n\n    const trackerSrc = join(\n        docsTemplatesDir, TRACKER_TEMPLATES[tracker]\n    )\n    const trackerDest = join(docsAgentsDir, 'issue-tracker.md')\n    writeFileSync(trackerDest, readFileSync(trackerSrc, 'utf8'))\n    console.log(\n        `  docs/agents/issue-tracker.md (${tracker})`\n    )\n\n    const trackerLine = tracker === 'github' ?\n        'Issues are tracked via GitHub Issues using the `gh` ' +\n        'CLI.' :\n        'Issues are tracked as local markdown files under ' +\n        '`.scratch/`.'\n\n    const agentsMd = [\n        '## Agent skills',\n        '',\n        '### Issue tracker',\n        '',\n        `${trackerLine} See \\`docs/agents/issue-tracker.md\\`.`,\n        '',\n        '### Triage labels',\n        '',\n        'Default label vocabulary. See ' +\n        '`docs/agents/triage-labels.md`.',\n        '',\n        '### Domain docs',\n        '',\n        'Single-context layout. See `docs/agents/domain.md`.',\n        '',\n    ].join('\\n')\n\n    writeFileSync(join(projectDir, 'AGENTS.md'), agentsMd)\n    console.log('\\n  AGENTS.md (updated)')\n\n    console.log(\n        `\\nSource: ${upstream.repo} @ ${upstream.commit}`\n    )\n}\n"],
+  "mappings": "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",
+  "names": ["mkdirSync", "writeFileSync", "existsSync", "readFileSync", "join", "join", "mkdirSync", "writeFileSync", "existsSync", "readFileSync"]
+}

package/docs/README.md

@@ -0,0 +1,12 @@
+# Docs
+
+## Some Links
+
+* [`nightshift`](https://github.com/Shaurya-Sethi/nightshift/) -- a Rust CLI
+  designed specifically for the Pocock skills.
+* [tracer bullets](https://www.aihero.dev/tracer-bullets) -- a metaphor that
+  I like, a good programming style
+* [chainlink](https://github.com/dollspace-gay/chainlink) -- a CLI issue
+  tracker for AI Agents
+* [mattpocock/skills](https://github.com/mattpocock/skills) -- the skills that
+  this CLI targets.

package/docs/agents/domain.md

@@ -0,0 +1,36 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists: it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because..._

package/docs/agents/issue-tracker.md

@@ -0,0 +1,30 @@
+# Issue tracker: Local Markdown
+
+Issues and specs for this repo live as markdown files in `.scratch/`.
+
+## Conventions
+
+- One feature per directory: `.scratch/<feature-slug>/`
+- 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)
+- Comments and conversation history append to the bottom of the file under a `## Comments` heading
+
+## When a skill says "publish to the issue tracker"
+
+Create a new file under `.scratch/<feature-slug>/` (creating the directory if needed).
+
+## When a skill says "fetch the relevant ticket"
+
+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`.

package/docs/agents/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.

package/docs/implementation-plans/2026-08-27-issue-tracker-choice/phase-2-future-work.md

@@ -0,0 +1,144 @@
+# Phase 2: Future Work -- Orchestrator GitHub Support
+
+## Goal
+
+Enable `nightralph <provider>` to pull tickets from GitHub Issues instead of `.scratch/` when the project is configured for GitHub tracking. This allows teams to use GitHub Issues as a native issue tracking system while leveraging nightralph's orchestrator for workflow execution.
+
+## Overview
+
+Phase 1 established the choice between local markdown and GitHub Issues for issue tracking. Phase 2 extends the orchestrator (`src/orchestrator.ts`) to support GitHub-backed issues, enabling end-to-end integration from issue discovery through status updates.
+
+## Changes Required in the Orchestrator
+
+### Tracker Detection
+
+The orchestrator needs to detect which tracker is in use by reading the title line from `docs/agents/issue-tracker.md`:
+
+- If title is `# Issue tracker: GitHub`, use GitHub mode
+- If title is `# Issue tracker: Local Markdown`, use local mode (current behavior)
+
+### Scan Tickets (`scanTickets()` function)
+
+Currently, `scanTickets()` reads `.scratch/<feature>/issues/` for numbered markdown files.
+
+**GitHub variant:**
+- Query `gh issue list --json number,title,body,labels,state --label <feature>` to retrieve issues
+- Parse JSON output into ticket objects
+- Handle pagination if needed
+
+**Local variant:**
+- Keep existing implementation (reads markdown files)
+
+### Status Parsing
+
+Currently, the orchestrator reads `Status:` lines from markdown files.
+
+**GitHub variant:**
+- Map GitHub labels to status: look for labels like `status-pending`, `status-in-progress`, `status-done`, `status-blocked`
+- Extract status from issue label set
+
+**Local variant:**
+- Keep existing implementation (reads markdown Status: field)
+
+### Blocker Parsing
+
+Currently, the orchestrator reads `Blocked by:` lines from markdown files.
+
+**GitHub variant:**
+- Query issue dependencies via `gh api repos/{owner}/{repo}/issues/{issue_number}/blocking_issues_and_pull_requests`
+- Extract blocker relationships from API response
+
+**Local variant:**
+- Keep existing implementation (reads markdown Blocked by: field)
+
+### Status Updates
+
+Currently, when a wave completes, the orchestrator writes `Status: done` to the markdown file.
+
+**GitHub variant:**
+- Run `gh issue close <issue_number>` to close the issue
+- Optionally add a comment or label to mark completion
+
+**Local variant:**
+- Keep existing implementation (writes to markdown file)
+
+## CLI Surface Changes
+
+The `--dir` and `--spec` flags assume local file-based issues. GitHub mode requires different scoping mechanisms:
+
+### New Flags for GitHub Mode
+
+- `--label <label>` -- filter issues by GitHub label (e.g., `nightralph`, `phase-1`)
+- `--milestone <milestone>` -- filter issues by GitHub milestone
+- `--assignee <user>` -- filter issues assigned to a specific user
+
+### Feature Selection
+
+The `resolveIssuesDir` function in `index.ts` currently prompts for a local feature directory. A GitHub-aware variant would:
+
+1. Query `gh issue list --label nightralph --json labels` to discover available labels
+2. Prompt user to select which label(s) to execute
+3. Optional: support milestone selection if `--milestone` is not specified
+
+## Testing Considerations
+
+### Test Strategy
+
+GitHub orchestrator tests need to handle the challenge of testing against external API calls:
+
+**Option 1: Mocked `gh` Output**
+- Mock the `gh` command output using standard test mocking patterns
+- Provide fixed JSON fixtures for different issue scenarios
+- Tests run fast and require no network access
+
+**Option 2: Test Repository**
+- Set up a dedicated test GitHub repository
+- Run integration tests against real GitHub Issues
+- More realistic but slower and requires GitHub API rate-limit budget
+
+**Option 3: Hybrid Approach**
+- Unit tests with mocked `gh` output for core logic
+- Optional integration tests with test repository for end-to-end validation
+- Recommended for this project
+
+### Execution Model Remains Unchanged
+
+The wave-based execution model (parallel independent tickets, sequential blocked ones) stays the same. GitHub mode only changes the I/O layer for reading and writing issue state.
+
+## Implementation Phases
+
+### Phase 2a: Tracker Detection
+- Add function to detect active tracker from `docs/agents/issue-tracker.md`
+- Route `scanTickets()` based on detection
+
+### Phase 2b: GitHub Scan and Parse
+- Implement `scanTicketsFromGitHub()` function
+- Add status and blocker parsing for GitHub labels and API calls
+- Add error handling for `gh` CLI availability and authentication
+
+### Phase 2c: GitHub Status Updates
+- Implement status update logic for GitHub Issues
+- Handle issue closing and labeling
+
+### Phase 2d: CLI and UX
+- Add `--label` and `--milestone` flags
+- Implement GitHub-aware feature selection prompt
+- Add documentation for GitHub workflow
+
+### Phase 2e: Testing
+- Write unit tests with mocked `gh` output
+- Optional: add integration tests with test repository
+- Verify backward compatibility with local markdown mode
+
+## Dependencies
+
+- `gh` CLI must be installed and authenticated
+- GitHub repository must be configured in current git remote
+- Existing test infrastructure (@substrate-system/tapzero, temp directories)
+
+## Backward Compatibility
+
+- Local markdown mode continues to work without changes
+- Projects using local markdown issue tracking are unaffected
+- The orchestrator can serve projects with either tracker type
+- No breaking changes to existing CLI surface for local mode

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

@@ -0,0 +1,292 @@
+# Issue Tracker Choice -- Implementation Plan
+
+**Goal:** Add an inquirer prompt to `nightralph setup` that lets users choose between GitHub Issues and Local Markdown as their issue tracker, with `gh` prerequisite checking and correct template installation.
+
+**Architecture:** The setup function gains a `tracker` field on `SetupOpts` (`'github' | 'local'`). The CLI handler in `index.ts` prompts for the choice via `@inquirer/prompts` `select`, runs `gh auth status` when GitHub is chosen, then passes the result to `setup()`. The `setup()` function copies the correct `issue-tracker*.md` template and writes an AGENTS.md that reflects the choice.
+
+**Tech Stack:** TypeScript, yargs, @inquirer/prompts (already installed), Node child_process for `gh` CLI check
+
+**Scope:** 2 phases from context bundle (phases 1-2)
+
+**Codebase verified:** 2026-08-27
+
+---
+
+## Acceptance Criteria Coverage
+
+This phase implements and tests:
+
+### issue-tracker-choice.AC1: Tracker choice prompt
+- **issue-tracker-choice.AC1.1 Success:** Running `nightralph setup` prompts user to choose between "GitHub Issues" and "Local Markdown"
+- **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.1 Success:** Choosing "GitHub Issues" runs `gh auth status` and proceeds if authenticated
+- **issue-tracker-choice.AC2.2 Failure:** If `gh` is not installed or not authenticated, setup prints a message and exits with code 2
+- **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 1: Setup Prompt, Template, and AGENTS.md
+
+<!-- START_SUBCOMPONENT_A (tasks 1-2) -->
+
+<!-- START_TASK_1 -->
+### Task 1: Create GitHub issue tracker template
+
+**Files:**
+- Create: `src/docs-templates/issue-tracker-github.md`
+
+**Implementation:**
+
+Create the GitHub issue tracker template at `src/docs-templates/issue-tracker-github.md`. Optionally reference the Matt Pocock template at `~/.claude/plugins/cache/claude-plugins-official/mattpocock-skills/1.2.3/skills/engineering/setup-matt-pocock-skills/issue-tracker-github.md` for conventions (this path is machine-local and not a required input -- the template can be written from scratch using `gh` CLI documentation). Adapt to match nightralph's conventions (simpler, no GitLab, no PR triage surface).
+
+The template should document:
+- Title: `# Issue tracker: GitHub`
+- How to create/read/list/comment/close issues via `gh` CLI
+- How to apply and remove labels
+- The "publish to issue tracker" instruction (create a GitHub issue)
+- The "fetch the relevant ticket" instruction (`gh issue view`)
+- Wayfinding operations using GitHub sub-issues or task lists
+- Blocking via GitHub native issue dependencies
+- Frontier query, claim (assign), and resolve (close) operations
+
+The file is copied verbatim by the build system (`cp -r ./src/docs-templates/* ./dist/docs-templates`), so no build changes are needed.
+
+**Verification:**
+Run: `ls src/docs-templates/issue-tracker-github.md`
+Expected: File exists
+
+**Commit:** `feat: add GitHub issue tracker template`
+<!-- END_TASK_1 -->
+
+<!-- START_TASK_2 -->
+### Task 2: Build and verify template is included
+
+**Files:**
+- None modified (build system verification)
+
+**Verification:**
+Run: `npm run build`
+Expected: Build succeeds, `dist/docs-templates/issue-tracker-github.md` exists
+
+Run: `ls dist/docs-templates/`
+Expected: Shows `domain.md`, `issue-tracker-github.md`, `issue-tracker.md`, `triage-labels.md`
+
+**Commit:** No commit needed -- build verification only.
+<!-- END_TASK_2 -->
+
+<!-- END_SUBCOMPONENT_A -->
+
+<!-- START_SUBCOMPONENT_B (tasks 3-5) -->
+
+<!-- START_TASK_3 -->
+### Task 3: Add `checkGhAuth` function to setup.ts
+
+**Verifies:** issue-tracker-choice.AC2.1, issue-tracker-choice.AC2.2
+
+**Files:**
+- Modify: `src/setup.ts:1-10` (add import for `execSync`)
+
+**Implementation:**
+
+Add a new exported function `checkGhAuth` to `src/setup.ts`. This function:
+1. Calls `execSync('gh auth status', { stdio:'ignore' })` in a try/catch
+2. Returns `true` if the command succeeds (exit 0)
+3. Returns `false` if it throws (command not found or auth failure)
+
+Keep it as a pure check -- no console output, no process.exit. The caller (`index.ts`) decides what to do with the result.
+
+Add `execSync` to the imports from `node:child_process`.
+
+**Testing:**
+Tests must verify:
+- issue-tracker-choice.AC2.1: `checkGhAuth` returns true when `gh` is authenticated
+- issue-tracker-choice.AC2.2: `checkGhAuth` returns false when `gh` is not available
+
+Note: this is a thin wrapper around exec. The function's behavior depends on the system state (`gh` installed/authenticated). Integration testing is appropriate -- unit tests with mocked exec would just test the mock. Testing guidance: verify the function exists and has the right signature; actual auth checking is tested via the CLI integration.
+
+**Verification:**
+Run: `npx tsc --noEmit`
+Expected: No type errors
+
+**Commit:** `feat: add checkGhAuth helper`
+<!-- END_TASK_3 -->
+
+<!-- START_TASK_4 -->
+### Task 4: Refactor setup.ts for tracker-aware template copying
+
+**Verifies:** issue-tracker-choice.AC1.2, issue-tracker-choice.AC2.3, issue-tracker-choice.AC4.1, issue-tracker-choice.AC4.2
+
+**Files:**
+- Modify: `src/setup.ts:12-21` (DOC_TEMPLATES constant)
+- Modify: `src/setup.ts:23-28` (SetupOpts type)
+- Modify: `src/setup.ts:80-103` (template copying section and end of function)
+
+**Implementation:**
+
+1. **Update `DOC_TEMPLATES`** -- remove `'issue-tracker.md'` from the array. It becomes tracker-specific and is handled separately. The constant becomes:
+   ```typescript
+   export const DOC_TEMPLATES = [
+       'triage-labels.md',
+       'domain.md',
+   ] as const
+   ```
+
+2. **Add tracker type and update `SetupOpts`** -- add a string literal union type and a `tracker` field:
+   ```typescript
+   export type TrackerKind = 'github' | 'local'
+
+   export type SetupOpts = {
+       bundledSkillsDir:string
+       docsTemplatesDir:string
+       projectDir:string
+       claude?:boolean
+       tracker:TrackerKind
+   }
+   ```
+
+3. **Add tracker template mapping** -- define which source template maps to which tracker choice:
+   ```typescript
+   const TRACKER_TEMPLATES:Record<TrackerKind, string> = {
+       local:'issue-tracker.md',
+       github:'issue-tracker-github.md',
+   }
+   ```
+
+4. **Add tracker template copy logic** -- after the existing `DOC_TEMPLATES` loop (line 98), add logic to copy the tracker-specific template. The destination is always `issue-tracker.md` in `docs/agents/`. Unlike other templates, this one overwrites existing content (so re-running setup with a different tracker choice takes effect):
+   ```typescript
+   const trackerSrc = join(
+       docsTemplatesDir, TRACKER_TEMPLATES[tracker]
+   )
+   const trackerDest = join(docsAgentsDir, 'issue-tracker.md')
+   writeFileSync(trackerDest, readFileSync(trackerSrc, 'utf8'))
+   console.log(
+       `  docs/agents/issue-tracker.md (${tracker})`
+   )
+   ```
+
+5. **Add AGENTS.md writing** -- after template copying, write AGENTS.md with tracker-appropriate content. AGENTS.md is fully regenerated on each setup run (not patched); any custom sections a user added will be overwritten. This is acceptable because the file is small and deterministic -- users who need custom content should edit it after setup. Define the issue tracker description based on the choice:
+   ```typescript
+   const trackerLine = tracker === 'github' ?
+       'Issues are tracked via GitHub Issues using the `gh` CLI.' :
+       'Issues are tracked as local markdown files under `.scratch/`.'
+
+   const agentsMd = [
+       '## Agent skills',
+       '',
+       '### Issue tracker',
+       '',
+       `${trackerLine} See \`docs/agents/issue-tracker.md\`.`,
+       '',
+       '### Triage labels',
+       '',
+       'Default label vocabulary. See `docs/agents/triage-labels.md`.',
+       '',
+       '### Domain docs',
+       '',
+       'Single-context layout. See `docs/agents/domain.md`.',
+       '',
+   ].join('\n')
+
+   writeFileSync(join(projectDir, 'AGENTS.md'), agentsMd)
+   console.log('\n  AGENTS.md (updated)')
+   ```
+
+**Testing:**
+Tests must verify:
+- issue-tracker-choice.AC1.2: `setup({..., tracker:'local'})` creates `docs/agents/issue-tracker.md` with local markdown content
+- issue-tracker-choice.AC2.3: `setup({..., tracker:'github'})` creates `docs/agents/issue-tracker.md` with GitHub content
+- issue-tracker-choice.AC4.1: The installed template content matches the source template for the chosen tracker
+- issue-tracker-choice.AC4.2: `triage-labels.md` and `domain.md` are still installed with idempotency
+
+**Verification:**
+Run: `npx tsc --noEmit`
+Expected: No type errors
+
+**Commit:** `feat: tracker-aware template copying and AGENTS.md generation`
+<!-- END_TASK_4 -->
+
+<!-- START_TASK_5 -->
+### Task 5: Update index.ts with tracker prompt and gh check
+
+**Verifies:** issue-tracker-choice.AC1.1, issue-tracker-choice.AC2.1, issue-tracker-choice.AC2.2, issue-tracker-choice.AC3.1, issue-tracker-choice.AC3.2
+
+**Files:**
+- Modify: `src/index.ts:7` (add `checkGhAuth` to setup import)
+- Modify: `src/index.ts:8` (add `TrackerKind` type import)
+- Modify: `src/index.ts:20-38` (setup command handler)
+
+**Implementation:**
+
+1. **Update imports** -- add `checkGhAuth` and `TrackerKind` to the import from `./setup.js`
+
+2. **Make setup handler async** -- change the handler callback from sync to async
+
+3. **Add tracker prompt** -- before calling `setup()`, prompt the user with `select`:
+   ```typescript
+   const tracker = await select<TrackerKind>({
+       message:'Issue tracker format',
+       choices:[
+           {
+               name:'Local Markdown',
+               value:'local' as const,
+               description:'Issues as .md files in .scratch/',
+           },
+           {
+               name:'GitHub Issues',
+               value:'github' as const,
+               description:'Issues via gh CLI',
+           },
+       ],
+   })
+   ```
+
+4. **Add gh auth check** -- if tracker is `'github'`, call `checkGhAuth()`. If it returns false, print a message and exit:
+   ```typescript
+   if (tracker === 'github') {
+       if (!checkGhAuth()) {
+           console.error(
+               'GitHub Issues requires the gh CLI, ' +
+               'authenticated.\n' +
+               'Install: https://cli.github.com\n' +
+               'Then run: gh auth login'
+           )
+           process.exit(2)
+       }
+   }
+   ```
+
+5. **Pass tracker to setup** -- add `tracker` to the options object passed to `setup()`
+
+**Testing:**
+Tests must verify:
+- issue-tracker-choice.AC1.1: The prompt is presented (this is an integration concern -- verified by running the CLI)
+- issue-tracker-choice.AC2.1: GitHub path calls `checkGhAuth`
+- issue-tracker-choice.AC2.2: Setup exits with code 2 when gh is not authenticated
+
+Note: The CLI handler is thin glue -- its behavior is best tested via the unit tests on `setup()` and `checkGhAuth()` individually, plus a manual run of the CLI.
+
+**Verification:**
+Run: `npm run build`
+Expected: Build succeeds
+
+Run: `node dist/index.js setup --help`
+Expected: Shows setup command help (the `--claude` flag)
+
+**Commit:** `feat: add tracker choice prompt to setup command`
+<!-- END_TASK_5 -->
+
+<!-- END_SUBCOMPONENT_B -->
+
+---
+
+**Note:** After completing Phase 1, `npm test` will fail because existing tests call `setup()` without the new required `tracker` field. This is expected. Phase 2 Task 1 updates all existing test calls. Use `npx tsc --noEmit` and `npm run build` to verify Phase 1 correctness.