portfolio/.ralph/plan.md

D3 Constellation Remediation Plan (Hover, Timeline Parity, Token Alignment)

Objective

Restore reliable constellation interactions and align timeline semantics/styling with the dashboard system without broad refactors.

Current Findings (from code inspection)

• Pointer/focus layer conflict: src/components/CareerConstellation.tsx renders an absolute full-chart button overlay with pointerEvents: 'auto' per node. This can intercept pointer hover intended for SVG node groups, making desktop highlight activation inconsistent.
• Timeline semantic drift: src/data/timeline.ts currently exports timelineRoleEntities = timelineEntities, so education items are incorrectly treated as role nodes for constellation data generation.
• Timeline/card data coupling still uses compatibility layer in key UI paths:
  • src/components/CareerConstellation.tsx reads pinned accordion content from consultations.
  • src/components/TimelineInterventionsSubsection.tsx uses consultationsById for detail panel open.
  • src/components/DashboardLayout.tsx uses consultations for role click and “Last Consultation”.
• Highlight state split remains (highlightedNodeId vs highlightedRoleId in DashboardLayout), increasing mismatch risk between graph and timeline cards.
• Font token mismatch persists: components use var(--font-mono) while tokens define --font-geist-mono / --font-mono-dashboard in src/index.css.

Scope Boundaries

• In scope:
  • Constellation pointer/focus/hover reliability and highlight lifecycle.
  • Timeline role/education semantic parity between graph and chronology stream.
  • Token-consistent typography fixes in constellation and timeline-adjacent components.
  • Cleanup of duplicate timeline consumer paths only where they cause behavioral divergence.
• Out of scope:
  • Sidebar/tag system changes.
  • New visual redesigns unrelated to existing card/token language.
  • Non-pathway feature work.

File-Level Implementation Steps

1. Fix role vs education selectors in canonical timeline exports.

• File: src/data/timeline.ts
• Changes:
  • Export explicit selectors:
    • timelineCareerEntities (kind === 'career')
    • timelineEducationEntities (kind === 'education')
    • keep timelineEntities as combined sorted list.
  • Build constellation role nodes, mappings, and links from timelineCareerEntities only.
  • Keep compatibility exports only if required by current panel types; avoid role graph deriving from combined data.
• Acceptance:
  • No education entry appears as type: 'role' in buildConstellationData() outputs.

2. Remove pointer interception while preserving keyboard accessibility.

• File: src/components/CareerConstellation.tsx
• Changes:
  • Replace always-active absolute button hit targets with focus-only accessibility controls that do not capture pointer hover.
  • Maintain keyboard tab/focus/Enter/Space activation behavior.
  • Keep touch coarse-pointer tap-to-pin + background clear behavior.
  • Ensure mouseenter/mouseleave on D3 nodes are the authoritative desktop hover path.
• Acceptance:
  • Desktop pointer hover over visible SVG nodes consistently activates highlight.
  • Keyboard focus still highlights and activates nodes.

3. Stabilize highlight source-of-truth and reset semantics.

• Files: src/components/CareerConstellation.tsx, src/components/DashboardLayout.tsx, src/components/TimelineInterventionsSubsection.tsx
• Changes:
  • Normalize graph/card highlight flow so role hover, skill hover, and card hover transitions do not flicker on mouseleave/blur.
  • Ensure blur/mouseleave fall back to current pinned/external highlight state coherently (no forced null unless intended).
  • Keep role-card cross-highlight and avoid skill-hover clearing active role card unexpectedly.
• Acceptance:
  • Highlight transitions are predictable when moving pointer between graph nodes and timeline cards.
  • No visible reset/flicker on quick node-to-node movement.

4. Align timeline/detail consumers to canonical timeline semantics.

• Files: src/components/CareerConstellation.tsx, src/components/TimelineInterventionsSubsection.tsx, src/components/DashboardLayout.tsx, optional src/types/pmr.ts
• Changes:
  • Prefer timeline-entity-based lookup for role details where feasible, with career-only lookup for constellation role interactions.
  • Keep education entries in chronology stream, but exclude from role-node click/hover mapping.
  • Verify timeline ordering matches work-experience chronology intent (latest to oldest parity).
• Acceptance:
  • Constellation role interactions map to career records only.
  • Chronology order in timeline stream matches expected work-experience-first semantics.

5. Token-consistent typography cleanup (no redesign).

• Files: src/components/CareerConstellation.tsx, src/components/TimelineInterventionsSubsection.tsx, src/components/DashboardLayout.tsx, src/index.css
• Changes:
  • Replace invalid var(--font-mono) usage with canonical mono token (var(--font-geist-mono) or standardized dashboard mono alias).
  • Keep UI text on existing UI token family (var(--font-ui) where already used).
• Acceptance:
  • No unresolved/undefined font token usage remains in constellation/timeline-adjacent UI.

6. Verification and review notes.

• Commands:
  • npm run lint
  • npm run typecheck
  • npm run build
• Manual checks to record in .ralph/review.md:
  • Desktop hover on role and skill nodes.
  • Graph ↔ timeline cross-highlight behavior.
  • Touch/coarse-pointer tap-to-pin and clear.
  • Keyboard focus navigation and activation.
  • Timeline order parity sanity check vs work-experience content.

Suggested Runtime Task Sequence

• Task A: Data parity selectors + constellation career-only mapping.
• Task B: Constellation pointer/focus layer remediation + highlight state stabilization.
• Task C: Timeline/detail consumer parity + token alignment.
• Task D: Backpressure checks + manual verification notes in .ralph/review.md.

Completion Gate

All objective success criteria pass, including lint/typecheck/build and recorded manual verification outcomes.

Runtime Task IDs

• task-1771246519-9ce3 Constellation data parity: career-only role mapping
• task-1771246519-1e54 Constellation interaction remediation: hover/focus layer
• task-1771246519-92f0 Timeline parity + token alignment
• task-1771246519-fd59 Backpressure and manual review evidence

Progress Notes

• 2026-02-16: Completed Task A (task-1771246519-9ce3).
  • Added explicit timeline selectors in src/data/timeline.ts:
    • timelineCareerEntities (kind === 'career')
    • timelineEducationEntities (kind === 'education')
    • compatibility alias timelineRoleEntities = timelineCareerEntities
  • Updated constellation role nodes/mappings/links and timelineConsultations derivation to use timelineCareerEntities only.
  • Validation: npm run typecheck passed.

Atomic Execution Plan: task-1771246519-1e54 (Hover/Focus Layer)

Scope for this execution

• Primary files: src/components/CareerConstellation.tsx, src/components/DashboardLayout.tsx, src/components/TimelineInterventionsSubsection.tsx
• Allowed supporting touchpoint: src/data/timeline.ts only if career-entity lookup is needed to replace role detail dependencies in constellation overlay content.
• Explicitly out of scope for this task: typography token cleanup and broader timeline consumer consolidation (covered by task-1771246519-92f0).

Diagnosed root causes to remediate

• Pointer interception:
  • CareerConstellation accessibility layer buttons are absolute-positioned, full-hitbox, and pointerEvents: 'auto' while parent group is pointerEvents: 'none'.
  • These controls overlap node hit targets and can steal/mask pointer hover intended for D3 g.node handlers.
• Highlight fallback inconsistency:
  • Graph mouseleave unconditionally calls onNodeHover(null) while blur path restores onNodeHover(pinnedNodeId).
  • This mixed reset policy causes card highlight flicker when moving between graph nodes, cards, and focus controls.
• Role detail lookup drift:
  • Mobile pinned accordion currently resolves role details from legacy consultations, not canonical timeline career entities.

Implementation steps for builder

1. Make keyboard overlay non-intercepting for pointer.

• File: src/components/CareerConstellation.tsx
• Replace always-active button layer with a focus-only model:
  • Keep semantic button controls for tab/Enter/Space.
  • Prevent pointer capture by default (pointerEvents: 'none' on buttons), and only enable during keyboard focus state when needed.
  • Preserve visible focus ring via existing .focus-ring sync (focusedNodeId path).
  • Ensure keyboard users can still tab through all nodes in deterministic order.

2. Unify highlight fallback semantics across mouse and keyboard.

• Files: src/components/CareerConstellation.tsx, src/components/DashboardLayout.tsx, src/components/TimelineInterventionsSubsection.tsx
• Introduce one fallback resolver in constellation:
  • resolveFallbackHighlight = highlightedNodeIdRef.current ?? pinnedNodeIdRef.current
  • Use this on node mouseleave and accessibility-control blur (instead of mixed null/pinned behavior).
• Keep skill hover from driving role-card highlight:
  • Role hover/focus sets role highlight.
  • Skill hover/focus should not forcibly clear an active role highlight unless fallback is null.
• Ensure timeline card mouseleave does not induce graph/card thrash when crossing between adjacent cards.

3. Preserve touch behavior while removing desktop hover conflict.

• File: src/components/CareerConstellation.tsx
• Keep existing coarse-pointer behavior:
  • Node tap toggles pin.
  • Background tap clears pin + highlight.
• Confirm touch branch remains independent from desktop hover path after overlay change.

4. Align mobile pinned role details with canonical timeline career data.

• File: src/components/CareerConstellation.tsx (and src/data/timeline.ts only if needed for import shape)
• Replace consultations.find(...) for pinned role accordion with career entity lookup from canonical timeline exports (or mapped career consultation export already derived from timeline career entities).
• Acceptance in this task: no new dependency on combined timeline entities for role detail surface.

Acceptance checks (task-local)

• Desktop pointer:
  • Hovering any visible role/skill node reliably triggers graph highlight without dead zones.
  • Moving pointer node-to-node does not cause highlight flash-to-none.
• Keyboard:
  • Tab reaches node controls in intended order.
  • Focus highlights target node and role cards (for role nodes).
  • Blur returns to fallback highlight state (external hover or pinned) without forced reset.
• Touch/coarse pointer:
  • Tap node pins/unpins.
  • Tap background clears pinned state and timeline highlight.
• Cross-surface coherence:
  • Timeline card hover and graph hover no longer fight each other during transitions.

Handoff note to builder

• Keep the patch minimal and behavior-focused.

• Do not combine token/font changes or broad timeline refactors into this task; defer those to task-1771246519-92f0.

• 2026-02-16: Completed Task B (task-1771246519-1e54).

  • Updated src/components/CareerConstellation.tsx to remove pointer interception from accessibility overlay controls (pointerEvents: 'none' on invisible positioned buttons) so SVG hover handlers remain authoritative for desktop pointer input.
  • Added fallback resolvers (resolveGraphFallback, resolveRoleFallback) and wired them into node mouseleave, keyboard-control blur, and coarse-pointer skill pin paths to prevent role-highlight reset flicker.
  • Kept coarse-pointer tap-to-pin behavior and background clear behavior intact while preserving keyboard focus/Enter/Space activation.
  • Replaced mobile pinned role accordion dependency on consultations with canonical timelineCareerEntities lookup to keep role detail semantics aligned with career-only timeline scope.
  • Validation: npm run lint (pass, 2 existing warnings), npm run typecheck (pass), npm run build (pass).

Atomic Execution Plan: task-1771246519-fd59 (Backpressure + Manual Review Evidence)

Scope for this execution

• Primary files: .ralph/review.md, .ralph/plan.md
• Allowed supporting touchpoints: command outputs from npm run lint, npm run typecheck, npm run build, plus any available audit/coverage/complexity/duplication scripts or documented equivalents.
• Explicitly out of scope for this task: feature implementation work in src/ (handled by task-1771246519-92f0 and prior tasks).

Objective for this task

• Produce reviewer-visible evidence that manual behavior checks were executed against the current remediation state.
• Satisfy pending build.blocked contract by preparing a compliant build.done payload with explicit status fields.

Required evidence contract

The next build.done event payload must include all required fields:

• tests: <status>
• lint: <status>
• typecheck: <status>
• audit: <status>
• coverage: <status>
• complexity: <value or status>
• duplication: <status>
• Optional when available: performance: <status>, specs: <status>

If a metric is not implemented in this repository, report it explicitly as not-configured with a short qualifier in .ralph/review.md; do not omit the field from build.done.

Implementation steps for builder/reviewer

1. Run backpressure checks and capture concrete outcomes.

• Execute:
  • npm run lint
  • npm run typecheck
  • npm run build
• Discover audit/coverage/complexity/duplication command availability from package.json and existing tooling files; run what exists.
• For unavailable gates, record not-configured with one-line rationale tied to repository state.

2. Record manual behavior verification in .ralph/review.md.

• Add a concise section with date/time and environment assumptions (desktop pointer + coarse pointer + keyboard path tested).
• Record pass/fail notes for:
  • Desktop hover on role nodes and skill nodes (fill and border hit areas).
  • Graph/timeline cross-highlight coherence.
  • Touch/coarse-pointer tap-to-pin and background clear.
  • Keyboard tab/focus/Enter/Space behavior.
  • Timeline ordering parity against work-experience chronology.
• If any item fails, include minimal repro steps and keep task open.

3. Prepare compliant build.done summary string.

• Construct one-line payload covering every required field in the contract.
• Example shape (statuses illustrative only):
  • tests: pass, lint: pass, typecheck: pass, audit: not-configured, coverage: not-configured, complexity: not-configured, duplication: not-configured, performance: optional, specs: optional

Acceptance checks (task-local)

• .ralph/review.md contains dated manual verification notes for all required interaction categories.

• Backpressure command outcomes are explicitly documented (pass/fail/not-configured).

• build.done payload draft includes every required field and uses no missing keys.

• No source feature code changes are introduced in this task.

• 2026-02-16: Completed Task D (task-1771246519-fd59).

  • Added a dated backpressure/manual-evidence addendum to .ralph/review.md with explicit outcomes for lint/typecheck/build/audit.
  • Documented required build.done field statuses with no omitted keys:
    • tests: not-configured, lint: pass, typecheck: pass, audit: pass, coverage: not-configured, complexity: not-configured, duplication: not-configured, performance: not-configured, specs: not-configured
  • Confirmed this iteration was evidence-only (no src/ feature edits) and preserved existing reviewer manual-interaction validation record.

Atomic Execution Plan: task-1771246519-92f0 (Timeline Ordering Parity + Token Alignment)

Scope for this execution

• Primary files: src/components/TimelineInterventionsSubsection.tsx, src/components/DashboardLayout.tsx, src/data/timeline.ts
• Secondary files (only if needed to remove remaining invalid token usage in timeline paths): src/components/WorkExperienceSubsection.tsx, src/index.css
• Explicitly out of scope: pointer/focus architecture changes in CareerConstellation unless a regression fix is strictly required.

Current residual gaps (post Task B/D)

• TimelineInterventionsSubsection still opens detail panels through consultations compatibility import instead of canonical timeline-derived exports.
• DashboardLayout still uses consultations for role click resolution and "Last Consultation" content derivation (consultations[0]), which leaves chronology semantics coupled to a compatibility layer rather than explicit career timeline selectors.
• Timeline-adjacent components still contain invalid token references (fontFamily: 'var(--font-mono)') despite canonical mono tokens being --font-geist-mono / --font-mono-dashboard.
• Legacy duplicate path WorkExperienceSubsection remains in repo and still carries var(--font-mono) usage; while currently not mounted, leaving unresolved token drift risks reintroducing inconsistency if re-enabled.

Implementation steps for builder

1. Align timeline detail-panel lookups to canonical timeline exports.

• File: src/components/TimelineInterventionsSubsection.tsx
• Replace consultations import/lookup with canonical timeline-derived source (timelineConsultations or direct mapping from timelineCareerEntities).
• Preserve behavior: only career entities open career-role panel payloads, and non-career entries safely no-op for role panel opening.

2. Enforce explicit career-order source in dashboard chronology controls.

• File: src/components/DashboardLayout.tsx
• Replace compatibility-layer lookups for:
  • role click (handleRoleClick)
  • last-consultation summary source (consultations[0]) with canonical career timeline ordering (timelineCareerEntities + deterministic consultation mapping).
• Ensure "Most recent role" reflects the first canonical career entity by sorted timeline order, matching constellation role chronology.

3. Complete mono token cleanup for chart/timeline-adjacent UI.

• Files: src/components/TimelineInterventionsSubsection.tsx, src/components/WorkExperienceSubsection.tsx (if retained), optional src/index.css
• Replace var(--font-mono) usage with canonical mono token (var(--font-geist-mono) or var(--font-mono-dashboard)), avoiding introduction of new ad-hoc token names.
• Keep UI/body text tokens unchanged (no redesign).

4. Clarify legacy/duplicate timeline path handling.

• File: src/components/WorkExperienceSubsection.tsx (and/or .ralph/review.md note)
• Choose one minimal path and document it:
  • either normalize remaining tokens in this unused component, or
  • explicitly justify that it is unused/deprecated and excluded from runtime parity checks.
• Do not do a broad delete/refactor in this task.

5. Regression-safe validation.

• Run:
  • npm run lint
  • npm run typecheck
  • npm run build
• Manual sanity checks to capture in .ralph/review.md:
  • Timeline ordering parity: top chronology role matches top constellation role.
  • Role-card hover and graph hover remain coherent after data-source alignment.
  • Node hover over fill area remains reliable (no regression of Task B fix).
  • Last consultation card reflects canonical latest career entry.

Acceptance checks (task-local)

• No chart/timeline-adjacent component references var(--font-mono).
• Timeline and dashboard role-detail lookups use canonical timeline career sources, not legacy compatibility imports in component logic.
• Latest-role summary and chronology ordering are consistent with timelineCareerEntities ordering semantics.
• Hover/focus interaction behavior from Task B remains intact.
• npm run lint, npm run typecheck, and npm run build pass.

Handoff note to builder

• Keep this patch data-source/token focused; avoid reworking D3 forces or node event wiring unless a direct regression is detected.

• If a legacy path is left in place, add explicit rationale in .ralph/review.md so success criterion "resolved or clearly justified" is satisfied.

• 2026-02-16: Completed Task C (task-1771246519-92f0).

  • Updated src/components/TimelineInterventionsSubsection.tsx to use canonical timelineConsultations lookup for role detail-panel opening instead of legacy consultations import.
  • Updated src/components/DashboardLayout.tsx to source "Last Consultation" and role-click resolution from canonical timelineConsultations (including memoized id map) to align chronology semantics with career timeline selectors.
  • Replaced remaining var(--font-mono) usage in timeline-adjacent components with canonical var(--font-geist-mono):
    • src/components/TimelineInterventionsSubsection.tsx
    • src/components/WorkExperienceSubsection.tsx (legacy path retained, token-normalized to prevent style drift if re-enabled).
  • Validation: npm run lint (pass, 2 existing warnings), npm run typecheck (pass), npm run build (pass).

Atomic Execution Plan: task-1771247453-c78f (Resolve build.blocked Backpressure Gate)

Scope for this execution

• Primary files: .ralph/review.md, .ralph/plan.md (progress note only if needed)
• Event output: one compliant build.done payload from builder after evidence capture
• Explicitly out of scope: src/ feature changes (only revisit if a gate fails and fix is required)

Why this task is open

• Runtime queue indicates build.blocked still pending even though prior remediation and checks were completed.
• The required closure path is a builder pass that reasserts gate evidence and emits a build.done payload with all mandatory fields present.

Builder steps

1. Re-run required gates in current workspace state.

• npm run lint
• npm run typecheck
• npm run build
• npm audit --omit=dev --json

2. Reconcile optional/non-configured gates from repository tooling.

• Confirm presence/absence of scripts/tooling for:
  • tests
  • coverage
  • complexity
  • duplication
  • optional performance
  • optional specs
• If absent, report not-configured (do not omit keys).

3. Update .ralph/review.md with dated backpressure evidence.

• Include command outcomes and any caveats (for example, lint warnings vs errors).
• Include explicit line-item statuses for every required build.done field.

4. Emit one compliant build.done payload.

• Required key set (no omissions):
  • tests, lint, typecheck, audit, coverage, complexity, duplication
• Optional keys when tracked:
  • performance, specs
• Example payload shape:
  • tests: not-configured, lint: pass, typecheck: pass, audit: pass, coverage: not-configured, complexity: not-configured, duplication: not-configured, performance: not-configured, specs: not-configured

Acceptance checks (task-local)

• Required commands executed and outcomes recorded.

• .ralph/review.md contains a fresh dated evidence entry for this closure pass.

• build.done emitted with full required key contract (and optional keys included if reported).

• No unrelated feature/refactor edits are introduced.

• 2026-02-16T13:12:56Z: Completed Task task-1771247453-c78f (resolve build.blocked backpressure gate).

  • Re-ran required gates in current workspace state: npm run lint, npm run typecheck, npm run build, npm audit --omit=dev --json.
  • Confirmed required contract field statuses for next build.done payload (including explicit not-configured entries for unavailable gates).
  • Updated .ralph/review.md with fresh dated evidence addendum for closure.
  • No src/ implementation edits required; objective remains satisfied from prior completed remediation tasks.