Skip to main content

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.

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)

BucketMeaningTypical action
A — Active coveredRegistry “active” spec has an open [SPEC-ID] issueNone
B — Done closed expectedRegistry “Done” and no open tracking issueNone (desired)
C — Active missingActive spec with no open tracking issueCreate issue (or run npx tsx scripts/bootstrap-github-spec-issues.ts --sync)
D — Enhancements with specDeferred dashboard enhancement ID has matching lite spec file(s)Optional: link from parent spec / board
E — Enhancements without specDashboard lists ID but no specs/{core}/specs/... matchAdd lite spec (PM-*-EN-*-*.md or equivalent) or remove stale ID from dashboard source
F — Not-yet-specified placeholdersStub specs in treeTrack separately; promote to real specs when ready
G — Duplicate open issuesSame [SPEC-ID] on multiple open issuesClose or merge duplicates
Done still openRegistry Done but open tracking issue still existsClose issue or move project item to Done

​
Operational runbook (mismatch -> action)

MismatchAction
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 registryRetitle 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 ProjectRun npm run spec:add-tracking-to-project -- --state open
Issue is on project but status is staleRun 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).