Project Tracking

# project-tracking — Command Reference

> Executable command blocks for `project-tracking/SKILL.md`. The SKILL.md holds the
> decision logic (what each step does, when to confirm); this file holds the literal
> `gh` / GraphQL invocations. Referenced by step ID, e.g. "run `[track-init §1]`".
> Replace `{owner}`, `{repo}`, `{project_number}`, and `{...-id}` placeholders with the
> values resolved in pre-flight and the engram config.

---

## Pre-flight — detect repo

```bash
# Detect owner/repo from git remote
git remote get-url origin
# Parse: https://github.com/owner/repo.git → owner=owner, repo=repo
# Parse: git@github.com:owner/repo.git → same
```

## Issue-Type detection (shared by plan-epic, plan-migrate)

```bash
gh api graphql -f query='query { repository(owner:"OWNER", name:"REPO") { issueTypes(first:10) { nodes { id name } } } }'
```

Empty / unsupported → fall back to label-only mode, warn once per session.

---

## track-init

### `[track-init §0]` — detect token capabilities

```bash
gh auth status 2>&1                          # is gh logged in at all?
gh project list --owner {owner} --limit 1 2>&1   # can the token reach Projects V2?
```

Classify the failure by what the output says — do NOT assume it's always the token:

| Symptom in output | Cause | Action |
|-------------------|-------|--------|
| `gh auth status` says "not logged in" / no token | gh not authenticated | Run `[track-init §0-auth]` |
| `github_pat_...` token + permission error | Fine-grained PAT (no Projects V2 on personal accounts) | Run `[track-init §0-manual]`, lead with Exit A |
| Classic token but `missing required scope 'project'` / `read:project` | Token lacks the `project` scope | `gh auth refresh -s project` then re-run §0 |
| `HTTP 5xx`, `timeout`, `rate limit`, network error | GitHub / network, not the token | Stop. Tell the user it's a transient GitHub/network error; retry §0 later. Do NOT touch the token |
| REST works (issues OK) but Projects/GraphQL says `FORBIDDEN` / `Resource not accessible` | `gh` is using a token from a misconfigured env var (wrong type, or the right token under a name `gh` never reads) | Run `[track-init §0-token-env]` |
| Empty list, no error | Token is fine, account just has no boards yet | Proceed to Step 1 (create board automatically) |

### `[track-init §0-auth]` — gh is not authenticated

```
The gh CLI isn't logged in (gh auth status reported no token).
Authenticate first, then I'll retry detection:
  gh auth login        # GitHub.com → choose token or browser
After it succeeds, tell me "listo" and I re-run detection (§0).
```

### `[track-init §0-token-env]` — configure the token gh actually reads

Symptom: issues work (REST) but any Projects/board operation returns
`FORBIDDEN` / `Resource not accessible by personal access token`. Projects v2
is **GraphQL-only**, so a token that is fine for REST can still be blocked here.
Two independent things have to be right — token TYPE and the env var NAME.

**1. The token must be a Classic PAT.** Fine-grained PATs (`github_pat_...`) do
not reliably reach Projects v2 over GraphQL on personal accounts — REST works,
GraphQL is blocked, which is exactly why the failure looks intermittent. Use a
Classic PAT (`ghp_...`) with scopes `repo` + `project`.

**2. The token must live in a variable gh reads.** `gh` reads an auth token
from **exactly two** env vars, in this order of precedence:

```
GH_TOKEN   >   GITHUB_TOKEN
```

Any other name (`GITHUB_CLASSIC_TOKEN`, `MY_PAT`, …) is a **dead variable** — gh
never looks at it, so the token is present but ignored. Worse: an env var token
**overrides `gh auth login`** ("takes precedence over previously stored
credentials"), so the wrong token in `GITHUB_TOKEN` silently wins over a correct
`gh auth login`.

**The fix (canonical):** put the Classic PAT in **`GH_TOKEN`** — the
highest-precedence name. Unset or correct any other GitHub token var so a stale
one can't win.

```bash
# Windows (PowerShell, persists for the user):
[Env