[EL-28] Drive navigation and feature availability from built-in capability manifests

[sodejm]

Catalog ID: EL-28

Public issue: #124

Reviewed baseline: 71abaf4067d4118f28910a22c20524b4e0282b28

Core objective: Replace hard-coded feature discovery with validated,
declarative manifests for trusted built-in modules while keeping executable
code statically bundled and capability-denied by default.

Priority / phase: P2 / Extensibility foundation

Publication status: Published as #124.

Dependency mapping

• Blocks: #16
• Depends On: #11, #101, #106, Define transport-neutral command specifications #41
• Relates To: [EL-29] Define signed declarative plugin manifests, permissions, install, upgrade, and removal #16

UX/UI requirements

• Generate navigation, availability, disabled states, help, and settings links
  from manifest data.
• Explain unavailable capabilities with coded reasons.
• Preserve stable ordering, keyboard navigation, deep-link validation, and
  responsive behavior.
• Never allow manifests to inject markup, styles, scripts, or routes.

Public interfaces

• Define versioned BuiltInCapabilityManifest, NavigationContribution,
  FeatureRequirement, and CapabilityStatus.
• Renderer DTOs contain declarative strings, known icon/slot identifiers, and
  typed routes only.
• Reject unknown schema versions, capabilities, slots, routes, and fields.

Underlying app changes

• Add a trusted built-in manifest registry and capability endpoint.
• Validate manifests during build and startup.
• Statically map trusted implementation identifiers; manifests cannot supply
  module paths.

Acceptance criteria

• Built-in desktop navigation is generated from validated manifests.
• Missing requirements produce visible disabled state and remediation.
• Malformed manifests fail closed without preventing safe core startup.
• Static analysis proves manifests cannot name arbitrary modules, files,
  URLs, or code.
• UI and backend use one capability-resolution contract.
• Schema compatibility and deterministic ordering have regression tests.
• Keyboard, screen-reader, reduced-motion, and zoom behavior remains
  correct.

Security mitigations and rejected anti-patterns

• Applies TM-P01, TM-R01, and TM-I01.
• Reject eval, dynamic require, Python entry-point discovery, arbitrary
  renderer components, manifest HTML/URLs, generic IPC, and
  capability-by-string execution.

Workspace mapping

• Exclusive owned paths: desktop/src/capabilities/**,
  desktop/src/shell/capability-navigation/**,
  src/ancestryllm/api/routes/capabilities/**,
  src/ancestryllm/capabilities/**, and
  desktop/tests/capabilities/**.
• Shared-file rule: Built-in module owners request registration through the
  coordinator; shared dependencies/contracts/lockfiles remain owner-managed.
• Base rule: Branch from updated main after all dependencies merge.
• Branch: feature/electron-el-28-capability-manifests
• Worktree: /Users/justinsoderberg/Development/worktrees/ancestryllm-electron-el-28-capability-manifests
• Validation: make test; make lint; make typecheck; make security;
  pnpm --dir desktop test; pnpm --dir desktop typecheck

[sodejm]

Recommended Codex configuration

• Planning: gpt-5.6-terra with high reasoning
• Implementation: gpt-5.6-sol with high reasoning
• Rationale: This work spans multiple files or subsystem boundaries and needs substantial architecture or performance reasoning, while remaining below the highest security and data-integrity risk tier.
• Delivery: Use test-case-driven development: translate the acceptance criteria into failing or characterization tests first, implement incrementally, then run the applicable tests, lint, typecheck, security, integration, and hosted gates.