Studio Hathor · Pre-Production Project Management

Purpose#

Admin lane console for the real @hathor/pre-production project-health scorer. The operator enters a task board as one line per task (taskId | category | status), and the lane returns the health score out of 100, blocked-task count, category breakdown, and any human-readable deductions. Blocked tasks cost a share of 20 points proportional to the board, and lopsided category distribution costs a flat 10. Admin-scoped and fail-closed.

Entry points#

• Direct URL / bookmark — /studio/hathor/pre-production-project-management; alternates.canonical is set.
• Quick-action from siblings — e.g. Hathor Pre-Production and Hathor World Version Branching link here; this page links to Visual Storyboarding.
• Studio overview — see ../../studio-overview.md.

Layout regions#

page.tsx renders inside <ShellLayout active="studio">:

• Workspace (StudioHathorPreProductionProjectManagementWorkspace, data-hathor-pre-production-project-management-workspace):
  • <h1> WorkspaceHeading — "Hathor Pre-Production Project Management Workspace"
  • Summary <p data-hathor-pre-production-project-management-summary>
  • Project Health Lane: catalog state, then the task-board form, pending state, result, or inline error.
• Route Map panel (<section data-hathor-pre-production-project-management-route-map>, data-hathor-ppm-route-count="5", <h2>Route Map</h2>): 5 entries from STUDIO_HATHOR_PRE_PRODUCTION_PROJECT_MANAGEMENT_ROUTE_MAP, each carrying data-hathor-ppm-route-map-entry and data-route-path.
• Quick-action lane (data-hathor-ppm-quick-actions, data-hathor-ppm-quick-action-count="2"): Visual Storyboarding and Back to Studio workspace index. Each link carries data-hathor-ppm-quick-action.

States#

• Loading — <p data-hathor-ppm-loading role="status" aria-live="polite"> "Loading project-health engine…" while the GET catalog request is in flight.
• Unauthorized — data-hathor-ppm-unauthorized role="alert" notice on 401/403 (admin-scope required).
• Error — data-hathor-ppm-error role="alert" notice on a non-OK catalog response, malformed catalog payload, or network failure.
• Ready (form) — data-hathor-ppm-categories role="status" aria-live="polite" + data-hathor-ppm-form data-hathor-ppm-form-state="idle" aria-busy="false" with the task textarea and submit button.
• Pending scoring — data-hathor-ppm-form-state="pending", aria-busy="true", disabled textarea, disabled submit button, data-hathor-ppm-submit-state="pending", and "Scoring…" button copy.
• Result — data-hathor-ppm-result role="status" aria-live="polite" with data-hathor-ppm-score, data-hathor-ppm-counts, data-hathor-ppm-breakdown, and either data-hathor-ppm-issues containing per-issue data-hathor-ppm-issue entries or data-hathor-ppm-no-issues.
• Validation error — data-hathor-ppm-parse-error role="alert" for live line-format parsing and data-hathor-ppm-assess-error role="alert" for submit-time client validation, BFF 400 detail responses, malformed 200 result payloads, or transport failure.

Interactions#

• data-hathor-ppm-tasks (textarea, aria-label="task board") — edit one task per line as taskId | category | status; disabled while scoring is pending.
• data-hathor-ppm-submit ("Score project health" / "Scoring…") — parses the task board and POSTs it to the assess endpoint; on 200 with a valid result it renders score/counts/issues/breakdown, otherwise sets data-hathor-ppm-assess-error from detail or the fail-closed fallback.
• Route Map entries — verify against STUDIO_HATHOR_PRE_PRODUCTION_PROJECT_MANAGEMENT_ROUTE_MAP (5 entries), with stable data-route-path ordering.
• Quick-action links — Visual Storyboarding (data-hathor-ppm-quick-action="visual-storyboarding" → /studio/hathor/visual-storyboarding), Back to Studio (data-hathor-ppm-quick-action="studio-index" → /studio).

Data & contracts#

• Reads: GET /v1/admin/hathor/pre-production-project-management (catalog: categories).
• Writes: POST /v1/admin/hathor/pre-production-project-management/assess with { tasks: [{ taskId, category, status }] }.
• Realtime: none.
• Caching: client fetch on mount, cache: 'no-store', buildBffAuthHeaders(), AbortController on unmount.
• Auth: admin-scoped, fail-closed (401/403 → unauthorized state); route is behind the signed-in + studio proxy gate.
• Client parsing: GET catalog requires categories: string[]; POST success requires numeric score, numeric totalTasks, numeric blockedTasks, string-array issues, and numeric tasksByCategory entries before rendering a result.

Cross-references#

• Parent: ../../studio-overview.md
• Shell: ../../../shell/04-auth-session.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioHathorPreProductionProjectManagementWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioHathorPreProductionProjectManagementRouteMap.ts
• Sibling routes: ./studio-hathor-visual-storyboarding.md, ./studio-hathor-pre-production.md, ./studio-hathor-world-version-branching.md

Automated coverage#

• apps/oshun/web/e2e/studio-hathor-pre-production-project-management.spec.ts covers: anonymous redirect, Hathor-admin shell entry, live project-health category catalog, default blocked-board score, edited healthy-board score, edited lopsided-board score, browser bearer propagation, scoped axe, 44 px controls, route map, quick actions, client-only malformed line validation with zero POSTs, BFF detail surfacing, malformed success payload handling, transport failure, catalog loading/503/malformed states, non-admin fail-closed state, pending scoring lockout, mobile no-overflow containment, and direct BFF auth/schema gates.
• Focused component tests: StudioHathorPreProductionProjectManagementWorkspace.test.tsx and StudioHathorPreProductionProjectManagementWorkspace.integration.test.tsx.
• Focused BFF route test: apps/oshun/bff/src/__tests__/admin-hathor-pre-production-project-management-route.test.ts.

Open questions / known gaps#

• Hathor is unconfirmed-v1 per WALKTHROUGH/matrix/routes.csv; confirm whether the dedicated /studio/hathor/* admin lanes ship V1 or are internal-only. Confirmed in V1 via V1/TODOS.md §34 and the 2026-05-29 surface inventory.
• The route-map sub-routes are listed but their concrete page.tsx files are not present; confirm whether they remain route-map placeholders or need dedicated deep-link pages.
• Manual assistive-technology pass remains pending; automated scoped axe and touch-target assertions pass for this route.