Encore OS — Documentation

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

Commands

# 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).

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).

Why our spec templates look this way Canonical Spec Workflow

Start Here

Module Engineering Snapshots

Canonical AI Governance

Architecture

Integrations

Development

Decision Guides

Database

Module Reference

Testing

Migration

Operations

Governance & Security

Platform Internals

Spec tracking reconciliation — triage playbook

Commands

Buckets (what they mean)

Operational runbook (mismatch -> action)

PM enhancement IDs (Bucket E)

GitHub Projects prerequisites

Bootstrap reliability

​Commands

​Buckets (what they mean)

​Operational runbook (mismatch -> action)

​PM enhancement IDs (Bucket E)

​GitHub Projects prerequisites

​Bootstrap reliability

​Related

Commands

Buckets (what they mean)

Operational runbook (mismatch -> action)

PM enhancement IDs (Bucket E)

GitHub Projects prerequisites

Bootstrap reliability

Related