> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Spec tracking reconciliation — triage playbook

> Purpose: Interpret output from scripts/audit/reconcile-spec-tracking.ts and align actions with GITHUB_PROJECT_SPEC_TRACKING_PLAN.md.

**Purpose:** Interpret output from `scripts/audit/reconcile-spec-tracking.ts` and align actions with [GITHUB\_PROJECT\_SPEC\_TRACKING\_PLAN.md](GITHUB_PROJECT_SPEC_TRACKING_PLAN.md).

## Commands

```bash theme={null}
# Markdown to terminal
npm run spec:reconcile-tracking

# Save a snapshot (optional path)
npm run spec:reconcile-tracking -- --output reports/SPEC_TRACKING_RECONCILE.md
```

**Requirements:** `gh` CLI authenticated with `repo` scope. Listing open `spec-tracking` issues uses `gh issue list`.

## Buckets (what they mean)

| Bucket                                 | Meaning                                                          | Typical action                                                                          |
| -------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **A — Active covered**                 | Registry “active” spec has an open `[SPEC-ID]` issue             | None                                                                                    |
| **B — Done closed expected**           | Registry “Done” and no open tracking issue                       | None (desired)                                                                          |
| **C — Active missing**                 | Active spec with **no** open tracking issue                      | Create issue (or run `npx tsx scripts/bootstrap-github-spec-issues.ts --sync`)          |
| **D — Enhancements with spec**         | Deferred dashboard enhancement ID has matching lite spec file(s) | Optional: link from parent spec / board                                                 |
| **E — Enhancements without spec**      | Dashboard lists ID but no `specs/{core}/specs/...` match         | Add lite spec (`PM-*-EN-*-*.md` or equivalent) or remove stale ID from dashboard source |
| **F — Not-yet-specified placeholders** | Stub specs in tree                                               | Track separately; promote to real specs when ready                                      |
| **G — Duplicate open issues**          | Same `[SPEC-ID]` on multiple open issues                         | Close or merge duplicates                                                               |
| **Done still open**                    | Registry Done but open tracking issue still exists               | Close issue or move project item to Done                                                |

## Operational runbook (mismatch -> action)

| Mismatch                                                                             | Action                                                                                                                  |
| ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| Missing canonical issue for active spec (`Bucket C`)                                 | Run `npm run bootstrap:spec-issues -- --sync --active-only` and re-run verify                                           |
| Open issue exists but title does not exactly match registry                          | Retitle to canonical `[SPEC-ID] Registry Name` (or close duplicate and keep canonical issue)                            |
| Multiple open issues with same `[SPEC-ID]`                                           | Keep one canonical issue; close the rest; then run `npm run spec:close-stale-tracking`                                  |
| PM alias issue (`PM-EN-*`) exists but canonical enhancement spec ID is `PM-##-EN-##` | Keep canonical `PM-##-EN-##` issue in `spec-tracking`; remove alias from `spec-tracking` (or close alias as superseded) |
| Issue is correct but missing from GitHub Project                                     | Run `npm run spec:add-tracking-to-project -- --state open`                                                              |
| Issue is on project but status is stale                                              | Run `npm run spec:sync-project-status`                                                                                  |

## PM enhancement IDs (Bucket E)

Many PM deferred rows use `PM-EN-*` codes with **per-enhancement** lite files (e.g. `PM-08-EN-12-...md`), not a single `PM-##-ENHANCEMENTS.md`. If Bucket E lists a `PM-EN-*` row, confirm whether the ID is still valid in `specs/DEFERRED_DASHBOARD.md` / parent spec text; add or rename a lite spec so `reconcile-spec-tracking`’s filename heuristics match, or adjust dashboard wording.

## GitHub Projects prerequisites

* **Bootstrap + project add:** refresh token with project scope, e.g. `gh auth refresh -s project`, and set `GH_PROJECT_NUMBER`.
* **Backfill issues onto the board:** `npm run spec:add-tracking-to-project` (issues that already existed are skipped by bootstrap `--sync` and are not auto-added until you run this).
* **sync-project-status:** `npm run spec:sync-project-status` needs `read:project` (and permission to update project items). Without these, run bootstrap only (issues still created) or use `--dry-run` on sync. Live sync requires `GH_PROJECT_NUMBER`.

## Bootstrap reliability

`bootstrap-github-spec-issues.ts` creates issues sequentially. A transient GitHub error (e.g. HTTP 502) can stop the run partway through; re-run with `--sync` to continue (existing titles are skipped).

## Related

* `npm run spec:validate-enhancement-catalogs` — structural checks on `*-ENHANCEMENTS.md` catalogs.
* `specs/FEATURE_CATALOGUE.md` — per-spec rollup with enhancement catalog links.
* `npm run spec-tracking:verify -- --scope active` — strict coverage gate (no missing canonical active issues).