> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livepeer.org/llms.txt
> Use this file to discover all available pages before exploring further.
# Repo Gap Analysis
> Implementation-ready audit of surfaces that do not yet align with the ownerless, self-governing repository model.
# Repo Gap Analysis
The implementation backlog for moving the repo closer to the ownerless governance standard. Every surface should be **discoverable, validated, repairable, bounded, and purgeable.**
**Audit dates:** prior baseline 2026-05-14; refresh 2026-05-23 after 10 file-level slice audits; **consolidation pass 2026-05-25** shipped the items below.
## Resolved 2026-05-25 (consolidation pass)
This session closed the following items off the backlog:
* **P0 cron-is-dry-run bug** – fixed in commit `e42946cdf` on `docs-v2-dev-draft` (inverted FLAGS default in all 6 `dispatch-{concern}.yml` scheduled jobs; manual-repair jobs unchanged). Pending merge to `docs-v2`. Unblocks 6+ stale data pipelines (contracts addresses, llms.txt, sitemap-ai.xml, OG/SEO generators).
* **P1 false-flag: decisions-log lags implementation** – verified all 18 decisions present, split across 2 files: `decisions-log.mdx` holds D-ACT-01..10 + D-GOV-07..08; `design/governance/design-overview.md` holds D-GOV-01..06 (locked 2026-04-04). Was a paginated-read artefact, not a real gap.
* **P1 false-flag: `.github/scripts/` empty** – reframed: the folder is **intentionally empty** per locked decision D-ACT-06 (every script migrated to `operations/scripts/` for governance reach). Downgraded to P2 path-drift cleanup for stale references in older docs.
* **P1 ownerless framing refresh post-D-ACT-10** – corrected "8 of 28 surfaces" claim across 6 canonical pages to live state: **4 of 5 unified surfaces ownerless-ready** in `repo-governance-surfaces.json` (canonical post-D-ACT-10; legacy 8-entry `ownerless-governance-surfaces.json` superseded but kept on disk for reference).
* **P3 frameworks/github-actions.mdx v2.1 → v2.2** – synced to the 2026-05-22 4-tier composable refactor + D-ACT-09/10 + D-GOV-07/08; bumped lastVerified to 2026-05-25; refreshed Tier-table counts (6+5=11 workflows, 230 atomics); added paragraph reconciling the "6 actions" framework framing with `automations.mdx`'s "11 active" framing.
* **P4 documentation gap: new dispatcher tranches** – documented the three new veracity dispatchers (`docs-research-packet.js`, `orchestrator-guides-research-review.js`, `docs-page-research-pr-report.js`) under a new "Recently shipped (May 2026)" section in `automations.mdx`; also documented the local-only social-feed dispatcher (`run-solutions-social-fetch.js`) in `contributor-tools.mdx`.
* **Frontmatter compliance sweep on 33 canonical pages** – brought all 16 frameworks + all 17 policies to canonical frontmatter (pageType / audience / purpose / status / lastVerified). All 33 now lint-clean (0 blocking, 0 warnings). Migrated 8 `pageType: overview` instances to canonical enum values across features pages + catalog.
The items below remain open. The cron P0 fix above means the next cron after merge to `docs-v2` should also resolve the **Stale generated governance map** P0 and most data-staleness P0/P1 entries – verify after merge.
**Audit dates:** prior baseline 2026-05-14; refresh 2026-05-23 after 10 file-level slice audits across docs-guide, ai-tools, operations/governance, .github, agent adapters, snippets, v2/internal + per-tab workspaces, per-tab checks.mdx cross-tab comparison, the 14 workspace plans (ORCHS, TERMINOLOGY, CONTRACTS, TOOLING, etc.), workspace history + BACKLOG, and root files.
**Evidence sources (live commands, 2026-05-23):**
```bash icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}}
find operations/scripts \( -name "*.js" -o -name "*.sh" -o -name "*.py" \) -not -path "*/x-archive/*" -not -path "*/archive/*" | wc -l # 321
ls .github/workflows/*.yml | wc -l # 11
find ai-tools/ai-skills -name SKILL.md | wc -l # 35
find v2 -name "*.mdx" -not -path "*/_workspace/*" -not -path "*/x-archived/*" -not -path "*/x-deprecated/*" | wc -l # 1,128
grep -c '"v2/' docs.json # 686
find operations/scripts -name '*.js' | xargs grep -l '@category' | wc -l # 45
find operations/scripts -name '*.js' | xargs grep -l '@domain' | wc -l # 4
node operations/scripts/generators/governance/reports/generate-repo-governance-status.js --check # FAIL (stale)
```
Detailed evidence in `workspace/thread-outputs/repo-consolidation-deep/SLICE-*.md` files (10 slices, \~4,400 lines of file-level inventory).
## Executive findings – what's P0 and P1
| Priority | Gap | Live evidence | Required outcome |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **P0 – FIXED 2026-05-25** | ~~Cron-is-dry-run-by-default bug~~ Fixed in commit `e42946cdf` on `docs-v2-dev-draft` (pending merge to `docs-v2`) | Inverted FLAGS pattern in all 6 `dispatch-{concern}.yml` scheduled jobs. Manual-repair jobs deliberately unchanged. Pre-fix: data files stale (contracts 19d, llms.txt/sitemap-ai.xml 47d) | Merge to `docs-v2`. Verify next scheduled cron writes (next 03:00–07:00 UTC window). See [Automations § Cron-is-dry-run bug](./automations.mdx#cron-is-dry-run-by-default-bug-fixed-2026-05-25) |
| **P0** | Stale generated governance map | `generate-repo-governance-status.js --check` reports `docs-guide/repo-ops/config/repo-governance-map.mdx is stale.` (\~6 weeks behind) | Regenerate map; verify generated-artifact governance |
| **P0** | OpenAPI specs 67 days stale | All 5 specs in `api/` mtime 2026-03-18; fetcher covers 2 of 5; no scheduled workflow | Expand `fetch-openapi-specs.sh` + schedule + gate via `openapi-reference-audit.js --full --strict` |
| **P0** | `docs.json` default version is `v1`, not `v2` | `docs.json` `versions[].default = true` on v1; README + feature-map claim v2 is canonical | Confirm Mintlify dashboard override OR fix `docs.json`; visitors land on v1 by default otherwise |
| **P0** | 6 empty `v2/internal/` stubs filled this session – TAB-SUMMARY.md files unchanged | All 7 TAB-SUMMARY.md files dated 2026-04-08 mark `definitions/ecosystem/references/strategic-alignment/deliverables/outcomes` as FAIL/empty; all 6 now populated 2026-05-22 | Regenerate TAB-SUMMARY files to reflect current state |
| **P1** | **Script JSDoc compliance MUCH better than documented** | Prior baseline said "218 non-compliant"; live 2026-05-23: 327 of 321 active scripts use canonical `@purpose` (100%); only **45 scripts use retired `@category`**, **4 use retired `@domain`** | Backfill the 45-50 remaining scripts; close the gap entirely; update gap-analysis to reflect live data (this refresh does that) |
| **P1** | V2 non-publishable content not fully normalised | V2 cleanup matrix reports 307 rows: 235 `_workspace` targets + 72 `x-deprecated` targets; `gateways` carries 199 of 307 | Execute approved move waves; update `.mintignore` + file-selection helpers |
| **P1** | Gateways canonical/ is BYTE-IDENTICAL to orchestrators canonical/ | `diff` returns 0 lines for `IA.mdx`, `Frameworks.mdx`, `process.mdx`, `ia-data.json`, `REVIEW-REGISTRY.md`. Gateways `REVIEW-REGISTRY.md` literally opens `# Orchestrators Tab Page Inventory` | Either produce gateways-specific canonical artefacts OR formally adopt orchestrators's as shared (with explicit declaration) |
| **P1** | Three decision registries with no cross-index | `D-NAV-01` in CONTENT-WRITING/decisions; `D-ACT-01..10 + D-GOV-01..08` in `.github/workspace/decisions-log.mdx`; `D-DG-01..13` in `docs-guide/decisions/docs-guide-structure.md` | Wire CI check that all 3 reference the unified index at `docs-guide/decisions/registry.md` |
| ~~P1~~ **RESOLVED 2026-05-25** | ~~decisions-log.mdx lags~~ All 18 decisions present, split across 2 files: `decisions-log.mdx` holds D-ACT-01..10 + D-GOV-07..08; `design/governance/design-overview.md` holds D-GOV-01..06 (locked 2026-04-04) | Verified by full grep across both files. Header date is the original 2026-03-31 lock date for D-ACT-01..03; later entries were appended in place | |
| **P1** | `.github/workflows/x-archive/` D-ACT-03 social-data consolidation incomplete | Target name `update-data-feeds.yml` doesn't exist in active set; 7 social-data workflows in `.archived` state | Verify the consolidation moved into `operations/scripts/dispatch/copy/` OR finish the migration |
| **P1** | Validator path drift in `agent-governance-framework.mdx` | Lines 137 + 228 reference `validators/governance/check-agent-docs-freshness.js`; actual is `validators/governance/compliance/check-agent-docs-freshness.js`. `AGENTS.md` line 98 has the correct path | Fix the 2 framework page references |
| **P2** | Pre-refactor docs still reference old `.github/scripts/` paths | `.github/scripts/` is intentionally empty per D-ACT-06 (everything migrated to `operations/scripts/` 2026-04-04); contracts pipeline doc + a handful of other internal references not updated | Update path references in `contracts-pipeline.mdx`, then retire that page (covered by `data-integrations.mdx#contracts-pipeline-deep-dive`) |
| **P1** | Large tracked reports + backup artefacts violate retention | Script footprint audit reports 24 findings: 4 medium + 20 low | Apply report retention policy; remove backup artefacts through governed deletion |
| **P1** | 4-surface component count drift | Feature page 59 / public overview 117 / framework table 118 / registry 132 – no source agrees | Replace every hand-authored count with generator-emitted block from `component-registry.json` |
| **P1** | 18 of 34 local SKILL.md files `status: draft` with empty test logs | Session-lifecycle backbone (`thread`, `research`, `design`, `build`, `iterate`, `close`) never validated in production | Promote one skill per week through 3-pass production validation |
| **P2** | Component archive + count drift | 24 archived JSX files under `snippets/components/x-archive/` with no removal schedule | Triage each: DELETE or KEEP-AS-ALIAS (with `@status deprecated` + removal date) |
| **P2** | Hook scripts violate their own JSDoc spec | `.githooks/pre-commit` + `pre-push` use retired JSDoc tags banned at `docs-guide/policies/script-governance.mdx` lines 195-205 | Update hook scripts to canonical 11-tag JSDoc; they must pass the validator they enforce |
| **P2** | `.githooks/verify.sh` dead enforcement | Defines 7 internal checks; not invoked by active `pre-commit` per SLICE-03 | Wire `verify.sh` back into pre-commit OR retire as dead code |
| **P2** | Archive sprawl in `.github/` | 3 archive lanes: `workflows/deprecated/`, `workflows/x-archive/`, `.github/x-archive/` | Consolidate to one lane per script-framework declaration |
| **P2** | 5 archive naming variants across 11 tabs | `archive/`, `archived/`, `deprecated/`, `x-archived/`, `x-deprecated/` per SLICE-09 | Normalise to `x-archive/` per framework |
| **P2** | Tool PATH discovery still fragile | Non-interactive shell needs Homebrew + NVM on PATH explicitly | Enhance `lpd doctor` output |
## Purge + remediation queue
### 1. Governance artefacts
| Item | Current problem | Implementation | Validation |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `docs-guide/repo-ops/config/repo-governance-map.mdx` | Stale generated output | `PATH="/opt/homebrew/bin:$PATH" node operations/scripts/generators/governance/reports/generate-repo-governance-status.js --write` | Rerun with `--check` |
| ~~Cron-is-dry-run pattern~~ **FIXED 2026-05-25** | Fixed in commit `e42946cdf` on `docs-v2-dev-draft` | Inverted FLAGS in all 6 `dispatch-{brand, copy, discoverability, governance, health, maintenance}.yml` scheduled jobs | Merge to `docs-v2`; verify next scheduled cron writes |
| Validator path drift | `agent-governance-framework.mdx` lines 137 + 228 reference wrong path | Add `/compliance/` to both references | Run `check-agent-docs-freshness.js` from corrected path |
| Stale path references in old docs | Pre-refactor docs reference `.github/scripts/fetch-contract-addresses.js`; `.github/scripts/` is intentionally empty per D-ACT-06 | Update references in `contracts-pipeline.mdx` (then retire that page) | Grep for old path repo-wide; confirm zero stale refs |
| Generated-artefact policy coverage | New surfaces don't automatically register in `generated-artifacts.json` | Add a CI check that flags any new generator script without a matching manifest entry | New validator script |
| `docs-index.json` provenance drift | `generated` field says 2026-04-07; mtime 2026-05-18 | Fix generator to update its own `generated_at` field on every write | Regenerate; verify field matches mtime |
| `codex/skills-manifest.json` provenance drift | `generated_at: 2026-03-22` but mtime 2026-04-08 | Same fix pattern as docs-index.json | Regenerate |
### 2. V2 folder governance
Cleanup matrix totals unchanged from 2026-05-14:
| Metric | Count |
| ------------------------- | --------------------: |
| Total rows | 307 |
| `_workspace` candidates | 235 |
| `x-deprecated` candidates | 72 |
| Core scope | 266 |
| Internal scope | 41 |
| Largest section | `gateways` (199 rows) |
| Next | `internal` (41) |
| Orchestrators | 39 |
**Implementation order:**
1. Update `.mintignore` + shared selection helpers so `_workspace`, `x-deprecated`, `archive`, and known transitional lanes are consistently non-publishable.
2. No-write report; split rows into move waves by section.
3. Start with `gateways` (199 rows; carries most `x-resources` and `x-deprecated` lanes).
4. Use `git mv` or repo move tooling – never hand-copy.
5. Preserve route behaviour: if a page was ever routable, verify redirects or `docs.json` removal explicitly.
6. Regenerate page/catalog indexes after each wave.
7. `lpd test --staged` + targeted link/import validation.
**Acceptance:** no publishable route resolves into `_workspace`, `x-deprecated`, archive, or design lanes; file-selection helpers share the same non-publishable lane contract; matrix rows decrease after each wave.
### 3. Reports, archives, backup artefacts
Script footprint audit: 4 medium + 20 low (no critical/high).
**Specific purge candidates:**
| Path | Issue | Action |
| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `workspace/reports/contracts/recovery-20260403-013442/files/snippets/data/contract-addresses/dep-contractAddressesData.jsx.bak` | Backup file tracked | Cleanup/quarantine then governed deletion |
| `workspace/reports/archive/link-health/*2026-03-09*` | Large historical reports | Replace with concise summary or untrack |
| `workspace/reports/navigation-links/LINK_TEST_REPORT.*` | Large tracked reports | Keep latest concise; regenerate full on demand |
| `workspace/reports/repo-ops/SCRIPT_INVENTORY_FULL.json` | Medium-size generated report | Confirm canonical; if derived, gitignore or summarise |
| `workspace/reports/**/files/**` | Historical full-file captures | Retain only legally/operationally required; otherwise purge |
| `.DS_Store` under root + `snippets/` + `v2/` + `workspace/` | OS metadata | Delete; ensure `.gitignore` coverage |
| `.vscode/livepeer-legacy.code-snippets.bak` (35 KB) | Tracked backup snippet | Classify alias or remove with approval |
| `v2/solutions/daydream/changelog.mdx.bak` | Backup docs artefact | Remove after confirming current changelog source |
| `snippets/data/changelogs/contractAddressesData.jsx` | Legacy orphan duplicate (2026-04-03); live pipeline writes to `snippets/data/contract-addresses/` | Delete |
| `tools/editor-extensions/components 2/`, `markdown-list 2/` | macOS duplicate artefacts | Delete |
| `v2/_workspace/archive/language-pages/{es,fr}` | 1,070 archived locale snapshots never published | Untrack OR archive outside the repo |
| `v2/_workspace/locale-page-archive/` | 24 more locale files | Untrack OR archive |
| 7+ `.zip` files in `_workspace/` (developers, developers1, orchestrators) | Binaries committed in content trees | Untrack |
| 20 byte-identical `audit-tasks-folders--*-audit.md` files in `v2/internal/reports/repo-ops/` | Duplicate aliases | Keep canonical; delete aliases |
| 2 placeholder snapshots: `snippets/data/snapshots/CoinGeckoExchanges.json`, `SolidityEmbed.json` | 178-byte / 170-byte stubs | Wire into fetchers OR delete |
### 4. Scripts and tooling
| Gap | Evidence | Implementation |
| ----------------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Retired JSDoc tags | 45 scripts use `@category`; 4 use `@domain` (live 2026-05-23) | Run `repair-script-inventory.js` on bounded scope; review; enforce in stages |
| Hook scripts violate own JSDoc | `.githooks/pre-commit` + `pre-push` use retired tags | Update to canonical 11-tag schema; hooks must pass the validator they enforce |
| Hook script-index broken | `.githooks/script-index.md` only catalogues 3 of 7 hook scripts | Fix generator filter |
| `pre-commit-no-deletions` unwired | Dead code per its own JSDoc (`@pipeline manual – not yet in pipeline`) | Wire in OR retire |
| `verify.sh` dead enforcement | Defines 7 checks; not invoked by pre-commit | Wire in OR retire |
| `post-commit.disabled` no JSDoc header | Just `# LIVEPEER_NOTION_LOCAL_SYNC_HOOK` | Document re-enable condition OR remove |
| `tools/script-index.md` legacy paths | Per `lpd-cli.mdx` self-note: "Pre-2026-03-21 layout" | Regenerate from `lpd scripts list --json` |
| `agent-write-governance.json` `bridge_mode: "staged"` | Migration incomplete; `repo-governance-surfaces.json` already on `"retired"` | Complete migration |
| Archive sprawl in `operations/scripts/` | Both `archive/` and `x-archive/` exist | Consolidate to one lane per script-framework |
| PATH discovery | Non-interactive shell lacks Homebrew + NVM on PATH | Enhance `lpd doctor` output |
### 5. GitHub Actions
| Gap | Evidence | Implementation |
| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| 3 archive lanes in `.github/` | `workflows/deprecated/` (1 file) + `workflows/x-archive/` (61 files) + `.github/x-archive/` (contents not enumerated) | Consolidate to `workflows/x-archive/` |
| `update-blog-data.yml` orphan | Stays in `deprecated/` | Confirm if compatibility alias OR retire |
| D-ACT-03 social-data consolidation incomplete | Target `update-data-feeds.yml` not in active set; 7 archived `.archived` files | Verify migrated into `operations/scripts/dispatch/copy/` OR finish |
| 2 PR templates side-by-side | `pull_request_template.md` (active) + `pull-request-template-v2.md` (vestigial) | Delete the v2 file |
| `.github/scripts/` intentionally empty | Per D-ACT-06: every `.github/scripts/` script migrated to `operations/scripts/` for governance reach. Folder kept for backward-compat path resolution only | No action – locked decision. Stale references to old paths in older docs should be updated, not the folder reinstated |
| `.github/augment-instructions.md` at active path with archived-header | 206 lines, heaviest adapter | Move to `_retired/` or delete |
| Cron-is-dry-run bug | See Executive findings P0 | See §1 |
| Workflow catalog drift | Feature docs previously referenced old workflow names | Make workflow catalog the source for counts |
| `framework-canonical.md` vs published `docs-guide/frameworks/github-actions.mdx` | Internal working spec ahead by 2 months | Sync published version to match 2026-05-22 refactor |
| Pattern D "Act" stage missing for cron scans | Health + brand opens PRs on manual repair; daily scheduled runs write only to step summaries | Add audit→issue automation to scheduled `-scan.js` dispatchers |
### 6. Components, templates, UI
| Gap | Evidence | Implementation |
| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Component archive unresolved | 24 JSX files under `snippets/components/x-archive/` | Triage: DELETE or KEEP-AS-ALIAS |
| 4-surface component count drift | Feature page 59 / public overview 117 / framework table 118 / registry 132 | Replace hand-authored counts with generator-emitted blocks |
| Wrapper-vs-display category mismatch | 6 components tagged `category: wrappers` but live under `displays/...` (AccordionGroupList, BasicList, CardCarousel, DisplayCard, DynamicTable, +1) | Either move files OR update `@type` in JSDoc |
| Registry generator bug | `snippets-registry.mdx` lines 868-878 mis-label all `displays/*` as "wrappers subtree" | Fix generator label logic |
| All 8 Tier-1 composables in `composables/pages/unclassified/` | Composables tree violates own classification rule | Move to classified subdir per `snippets/guide.mdx` Rule #2 |
| Data files in composables tree | 662 KB `contractAddressesData.jsx` + 3 other data files parked under `composables/` | Move to `snippets/data/` per Rule #1 |
| 4 byte-identical template duplicate pairs | `source-of-truth`, `glossary-consolidated`, `glossary-tab`, `openapi-endpoint-page` | Delete duplicates; fix catalog generator dedupe |
| 11 `.DS_Store` files in `snippets/` | OS metadata | Delete + ensure `.gitignore` coverage |
| `.vscode/livepeer-legacy.code-snippets.bak` (35 KB) tracked | Replaced by `lp-components.code-snippets` + `templates.code-snippets` | Delete |
| `components.code-snippets` (113) + `lp-components.code-snippets` (125) overlap | Two generated snippet files | Declare scope-split OR merge to one |
| Catalog freshness drift | `templates-catalog.mdx` + `ui-templates.mdx` last regen 2026-04-03 (50 days stale) | Add CI workflow that regenerates on `snippets/templates/` + `snippets/components/` change |
| `components-catalog.mdx` embeds raw data block | Author noted `{/* should not be here. */}` | Move data to JSON companion file |
| `--lp-color-text-muted` borderline WCAG AA | Contrast ratio 4.2:1 (below 4.5:1 AA threshold) | Darken default or document per-use exemption |
| Public style-guide leads with deprecated `--accent` aliases | Engineering guide marks them deprecated | Update public guide to canonical `--lp-*` |
### 7. Per-tab content + IA
| Gap | Evidence | Implementation |
| ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Duplicate developer trees | `v2/developers/`, `v2/developers1/`, `v2/developers2/` all exist | Produce IA migration plan first; then execute moves with redirect validation |
| Gateways canonical = orchestrators canonical | Byte-identical `IA.mdx`, `Frameworks.mdx`, `process.mdx`, `ia-data.json`, `REVIEW-REGISTRY.md` | Produce gateways-specific OR formally adopt orchestrators's as shared (declared as such) |
| `v2/developers/_workspace/` has NO canonical/ directory | Only "active" tab without one; uses ad-hoc `developer-tab-fixes/` mirror | Produce canonical/ OR document why ad-hoc structure is permanent |
| orchestrators + gateways `checks.mdx` violate own rules | No frontmatter (fails own Cat 1.1); em-dashes throughout (fails own Cat 2.12) | Add frontmatter; run em-dash remediator on both files |
| gateways `checks.mdx` has no Cat 10 | Completeness gate undefined for the tab | Add Cat 10 (Content Completeness) section |
| Bash-block policy contradicts across tabs | Delegators bans bash blocks; orch/gw/about/dev1 permit | Declare site-wide policy in [Checks Framework](../frameworks/checks-framework.mdx) |
| Frameworks.mdx §1.3 persona enumeration "Pending definition" yet per-tab checks invoke persona rules | Site-wide framework lags per-tab application | Lock persona enumeration; refresh Frameworks.mdx |
| Frameworks.mdx §1.6 InfoType is "Draft" yet Cat 4.7 treats as blocking | Draft framework field is treated as production gate | Promote §1.6 from Draft OR remove Cat 4.7 dependency |
| Tab gate status board contradicts itself | All 5 tabs have `IA Approved ⬜` but 3 have `Content Scan Done ✅` – out of order | Gate-ordering enforcement OR refresh table |
| `Delegators/LPT v2 path confirmed: v2/lpt/`; live tree HAS `v2/delegators/` | tab-status.md says `v2/lpt/` is canonical; that path doesn't exist | Update tab-status.md to reality |
| Large workspaces mixed into content sections | Many section `_workspace`, `_design`, canonical, reviews, archive, deprecated folders | Normalise per `workspace-lifecycle-policy.mdx` TTL rules |
| Internal reports routable in some places | `v2/internal/` includes 36 audit dump files routable from nav | Confirm intended nav scope; collapse audit dumps to single index + retention |
| Tab maps absent at canonical location | Per-page review pipeline Phase 0 requires `v2/{tab}/_workspace/tab-map.mdx`; none exist | Move/symlink ORCHS map from `workspace/plan/active/CONTENTI-PIPLEINE/03-tab-map.md`; produce for other 4 tabs |
| 55 status:draft files repo-wide | 37 in orchestrators (`plans/`, `canonical/check/`, `x-archived/`) | Triage: complete or retire |
| EVERY workspace file has mtime exactly 2026-05-18 | Single batch operation makes mtime unreliable as staleness signal | Use `lastVerified` frontmatter + content date as staleness signal |
### 8. v2/internal + RFP
| Gap | Evidence | Implementation |
| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `v2/internal/rfp/report.mdx` StyledTable self-contradictory | 2026-02-21 status grades unchanged; Part 13 §13.3 (this session) re-grades 5 rows | Update the StyledTable to match Part 13 grades |
| 3 sibling internal pages cite 3 different script counts | `aims.mdx` 58; `governance-pipeline.mdx` 214; `report.md §13.1` 320 | Reconcile to live (321) |
| `governance.mdx` section-owners table uses v1 `v2/pages/01_about/` numbered paths | That IA was removed | Refresh paths |
| `ally-notes.mdx` duplicates own content twice (lines 24-101 ≈ 103-180) | Self-duplication | Deduplicate |
| `personas.mdx` missing 3 of 4 personas | Only Developer has body; Gateway Operator, Orchestrator, Delegator are heading-only stubs | Complete |
| All 7 TAB-SUMMARY.md files dated 2026-04-08 | Mark 6 internal pages as FAIL/empty; all 6 populated 2026-05-22 | Regenerate TAB-SUMMARY files |
### 9. AI features + skills
| Gap | Evidence | Implementation |
| -------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------- |
| `llms.txt` + `sitemap-ai.xml` 47 days stale | Root cause: cron-dry-run | Fix cron-dry-run (Executive P0) |
| `sitemap-ai.xml` only 6 of 10 tabs | developers/orchestrators/delegators/internal/ai-tools entirely absent | Expand fetcher scope |
| 3 AI artefact counts disagree | llms.txt 188 / sitemap-ai.xml 181 / docs-index.json 532 | Pick one source-of-truth OR document why three |
| `robots.txt` doesn't advertise `sitemap-ai.xml` | Only Mintlify auto-sitemap listed | Add the entry |
| `skill.md` aspirational | Documented at `docs.livepeer.org/skill.md`; no repo source | Implement generator OR strike from public docs |
| `.claude/CLAUDE.md` 2.74× AGENTS.md (326 vs 119 lines) | D-DG-11 thin-adapter violation | Trim to ≤200 lines; no policy duplicated from AGENTS.md |
| 18 of 34 SKILL.md `status: draft` | Session-lifecycle backbone never validated in production | Promote 1 per week through 3-pass validation |
| 38 portable-only skills have no local canonical | Dispatchers reference them; the graph is partly fictional | Reconcile or document why |
| `agent-packs/skills/manifest.json` registers 1 of 53 portable skills | Only `browser` registered | Audit + update manifest |
| `docs-copy/` has both `reference/` and `references/` | Two ref directories with different files | Reconcile to one |
| 15 portable wrappers stale v1.0 | Local canonical bodies at v1.3/v1.4 | Regenerate cross-agent-packager exports |
| Templates 32/37/38 appear twice with different content | 41/42 duplicate 37/38 (renumbered without deletion) | Cleanup |
| `ai-tools/registry/ai-tools-inventory.md` lags registry | Inventory mtime 2026-04-05; registry mtime 2026-04-08 | Regenerate inventory |
| `ai-tools/ai-rules/.augment/` phantom-retired subtree (165 lines) | At active path; invisible to freshness validator | Move to `_retired/` |
| Two `AI_GUIDELINES.md` files give contradictory `--no-verify` policy | `.augment/` shadow forbids; live + `_retired` allow with metadata | Reconcile |
| `docs-guide/tooling/ai-tools.mdx` claims 42 templates + 42 skills | Live: 53 templates + 34 local + 53 portable | Replace with generator-emitted block |
| `skill-catalog.json` covers 9 of 34 skills (26%) | Two separate inventory systems with no cross-check | Add CI cross-check |
### 10. Workspace plans
| Gap | Evidence | Implementation |
| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| 3 decision registries with no cross-index | D-NAV-01 + D-ACT-01..10 + D-GOV-01..08 + D-DG-01..13 | Wire CI cross-index check |
| CONTENT-WRITING/READ-EVERY-TIME `collated/` symlinks structurally broken | Non-audience-design symlinks point to `context-packs/` which doesn't exist | Fix or remove symlinks |
| Two parallel orchestrator content tracks (ORCHS vs ORCHESTRATOR-CONTENT-WRITING) | No canonical decision between them | Pick one; archive the other |
| ORCHS IA has 10 sections; ORCHESTRATOR-CONTENT-WRITING/MASTER-STATE.md has 12 (S1-S12) | Same tab, two locked IAs | Reconcile |
| Pool worker (deprecated) still in CLAUDE.md domain terms | TERMINOLOGY-COLLATE locked it as Pool node | Update CLAUDE.md |
| Fee cut direction unresolved across 3 sources | SHIP-CONTENT V-01 vs MASTER-STATE.md vs TERMINOLOGY-COLLATE | Lock in decision-registry |
| CONTRACTS authority paradox | DEPRECATED/ files cited as design-doc authority in REQUIREMENTS.mdx | Resolve |
| 26 files in `ORCHS/x-deprecated/` marked `status: current` or `published` | Lifecycle violation | Status field correction OR file moves |
| CANONICAL-TRUTH-GUIDES marked DELETE but contains active work | Conflict between meta-decision and content | Resolve |
| Folder name issues | `ORCHESTRATOR-CONTENT-WRITING` houses Gateways; `CONTRACTS-CHANGELOG-PIPELINE` header drift; `SCRIPT WORKFLOW AUDIT` has literal space; `CONTENTI-PIPLEINE` misspelled | Rename folders per `naming-conventions.mdx` |
| Per-tab glossary term-count drift (+3 to +10) | glossary-index.md vs per-tab files | Reconcile |
| Gateways scan claims 275 pages (anomaly) | Live count differs | Re-run scan |
### 11. Tab gates stuck at Phase 2
Per `workspace/plan/active/CONTENT-WRITING/decisions/tab-status.md`:
* **0 of 5 tabs has `IA Approved`** – all ⬜
* 3 of 5 tabs have `Content Scan Done` ✅ (Gateways, About, Delegators)
* 0 of 5 tabs have advanced past Phase 2
The project pipeline is stalled. A tab is only "open" for the next phase when its gate is explicitly unlocked by human sign-off recorded in `decision-registry.md`. **Action:** human IA review + lock per tab to unblock downstream phases.
## Implementation plan (refreshed 2026-05-23)
### Phase 1: Stop the bleed (P0)
1. **Fix the cron-is-dry-run bug.** Single edit across 6 `dispatch-{concern}.yml` files. Unblocks contracts, llms.txt, sitemap-ai.xml, OG-images, SEO, glossary regeneration.
2. **Regenerate stale governance map.** Run the generator + commit.
3. **Wire OpenAPI fetcher** to all 5 specs + schedule + validation gate.
4. **Fix `docs.json` default version** (v1 → v2 OR confirm Mintlify dashboard override).
5. **Refresh stale RFP/internal claims** – sibling pages cite 3 different script counts.
6. **Regenerate TAB-SUMMARY.md files** to reflect populated internal stubs.
**Exit criteria:** governance map `--check` passes; data-pipeline staleness drops to ≤1 day; AI artefacts regenerate on every `docs.json` change; visitors land on v2 by default.
### Phase 2: Repair the contracts (P1)
1. Add `/compliance/` to `agent-governance-framework.mdx` validator path references.
2. Update contracts pipeline doc to reference current script location.
3. Wire CI cross-index check across the 3 decision registries.
4. Append D-ACT-05..10 + D-GOV-01..08 entries to `decisions-log.mdx`.
5. Update `framework-canonical.md` published version to match 2026-05-22 refactor.
6. Verify D-ACT-03 social-data consolidation completion (target: `update-data-feeds.yml` exists or scripts under `dispatch/copy/`).
**Exit criteria:** zero stale path references; published frameworks match live state; CI catches future drift.
### Phase 3: Normalise non-publishable lanes (P1)
1. Update `.mintignore` + selection helpers.
2. Execute v2 cleanup matrix by section, starting with `gateways` (199 of 307 rows).
3. Validate route + link + import behaviour after each wave.
4. Record waves in a report under `workspace/reports/repo-ops/`.
**Exit criteria:** cleanup matrix decreases; no routed page in non-publishable lanes; archive naming normalised to `x-archive/`.
### Phase 4: Resolve per-tab canonical contradictions (P1)
1. Decide gateways canonical: produce gateways-specific OR formally adopt orchestrators's as shared (declared).
2. Add Cat 10 to gateways `checks.mdx`.
3. Add frontmatter + run em-dash remediator on orchestrators + gateways `checks.mdx`.
4. Lock bash-block policy site-wide.
5. Lock persona enumeration in `Frameworks.mdx §1.3`.
6. Promote `Frameworks.mdx §1.6` InfoType from Draft.
7. Move/symlink ORCHS tab map to canonical location; produce for other 4 tabs.
**Exit criteria:** per-tab canonical artefacts agree on shared spec; no `checks.mdx` violates its own Cat 1.1 or 2.12; Phase 0 pre-flight passes for at least 1 tab.
### Phase 5: Component + skill backlog (P1)
1. Replace hand-authored component count tables with generator-emitted blocks (4 surfaces).
2. Fix `snippets-registry.mdx` lines 868-878 wrapper/displays label bug.
3. Move 6 wrapper-tagged components OR update their `@type` JSDoc.
4. Triage 24 archived JSX components (DELETE or KEEP-AS-ALIAS).
5. Move all 8 Tier-1 composables out of `composables/pages/unclassified/`.
6. Move 4 data files out of `composables/`.
7. Delete 4 byte-identical template duplicate pairs.
8. Promote 1 draft SKILL.md per week through 3-pass validation (18 in queue).
9. Reconcile portable vs local skill divergence (34 vs 53; 38 portable-only with no local).
10. Trim `.claude/CLAUDE.md` to ≤200 lines.
**Exit criteria:** every count generator-sourced; 0 wrapper-tagged components in displays/; 0 draft skills in production use; thin-adapter compliance per D-DG-11.
### Phase 6: Backfill + retention (P1/P2)
1. Backfill the 45 retired-`@category` + 4 retired-`@domain` scripts.
2. Update `.githooks/pre-commit` + `pre-push` JSDoc to canonical 11-tag.
3. Wire `.githooks/verify.sh` back into pre-commit OR retire.
4. Apply report retention policy.
5. Delete 13-file cleanup queue (`.DS_Store`, `.bak`, `.legacy-duplicate.json`, etc.).
6. Untrack 1,070 archived locale snapshots + 7+ committed `.zip` files.
7. Delete 20 byte-identical audit alias files.
8. Implement `tasks-retention.yml` workflow for `_workspace/` TTL enforcement.
**Exit criteria:** script footprint audit `@category` + `@domain` counts at 0; hook scripts pass the validator they enforce; workspace report bloat reduced; retention TTL enforced.
## Non-acceptance criteria
The following do not satisfy this gap analysis:
* Adding ignore rules without moving, validating, or documenting the underlying source of drift
* Deleting files without dependency checks and required deletion approval
* Hand-editing generated outputs without fixing the generator or canonical source
* Leaving old docs paths as undocumented compatibility aliases
* Treating workspace reports as permanent source of truth
* Running only a superficial command when repo tooling provides a deeper validator
* Marking a fix done without verifying the prior failure mode no longer reproduces
## Next concrete commands
```bash icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}}
# Regenerate stale governance map
PATH="/opt/homebrew/bin:$PATH" node operations/scripts/generators/governance/reports/generate-repo-governance-status.js --write
PATH="/opt/homebrew/bin:$PATH" node operations/scripts/generators/governance/reports/generate-repo-governance-status.js --check
# Refresh v2 folder cleanup matrix
PATH="/opt/homebrew/bin:$PATH" node operations/scripts/audits/governance/reports/generate-v2-folder-governance-cleanup-matrix.js \
--report-md workspace/reports/repo-ops/v2-folder-governance-cleanup-matrix.md \
--report-json workspace/reports/repo-ops/v2-folder-governance-cleanup-matrix.json \
--as-of 2026-05-23
# Refresh script footprint audit (verifies 45 @category + 4 @domain figures)
PATH="/opt/homebrew/bin:$PATH" node operations/scripts/audits/governance/scripts/script-footprint-and-usage-audit.js \
--scope full --output-dir workspace/reports/repo-ops
# Live JSDoc compliance spot-check
find operations/scripts -name '*.js' | xargs grep -l '@category' | wc -l # retired tag count
find operations/scripts -name '*.js' | xargs grep -l '@domain' | wc -l # retired tag count
find operations/scripts -name '*.js' | xargs grep -l '@purpose' | wc -l # canonical tag count
# Confirm pipeline tests pass
node operations/tests/integration/pipeline-smoke-test.js
node operations/tests/integration/pipeline-functional-tests.js
# Validate staged work
lpd test --staged
```
## Related
* **[Adaptive Architecture](./adaptive-architecture.mdx)** – the model this gap analysis remediates against
* **[Automations](./automations.mdx)** – the cron-dry-run bug that gates Phase 1
* **[Feature Map](./feature-map.mdx)** – the canonical inventory cross-link
* **[Ownerless Governance Policy](../policies/ownerless-governance.mdx)** – the 4-part contract that defines "complete"
* **[Workspace Lifecycle Policy](../policies/workspace-lifecycle-policy.mdx)** – TTL rules + `tasks-retention.yml` target
* **[Cleanup + Quarantine Policy](../policies/cleanup-quarantine-policy.mdx)** – deletion-discipline contract
* **`workspace/plan/future/BACKLOG/master-tasks.md`** – BL-001..BL-046 with priorities + status + dates
* **`workspace/thread-outputs/repo-consolidation-deep/`** – 10 file-level slice audits (\~4,400 lines of evidence)
* **`workspace/thread-outputs/repo-consolidation-deep/SLICE-00-MASTER.md`** – master consolidation map (input to this gap analysis)