pal-e-docs

Phase 20: Context-Scoped Session Loading

phase-pal-e-agency-20-context-scoped-sessions Phase

active phase
Project
Goal: When the superuser opens Claude Code, the session loads context scoped to the detected project. Same token budget, higher signal per token. The superuser doesn't see pal-e-docs CSS phases when working on basketball.
Owner: Dev agent (hook refactoring)
Repo: forgejo_admin/claude-custom
Depends on: Phase 19 (user stories must exist on project pages)

Scope

What exists (session-start-context.sh, 554 lines):
  • Platform detection (Forgejo/GitHub) — working
  • Project detection via project repo_url match — working but weak (only 4/20 projects have repo_url)
  • All SOPs loaded — not scoped
  • Plan TOCs filtered by board activity — partially scoped (by active work, not by cwd project)
  • Dynamic briefing queries ALL in-progress phases — not scoped
  • Board item counts aggregated across ALL boards — not scoped
  • Project page injected as first 40 lines of stripped HTML — unstructured, may miss user stories
  • Personality injected — working, keep as-is
What changes:
20a: Fix project detection — use repos endpoint
  • Current: matches git remote against project repo_url (only 4 projects have this set)
  • New: extract repo name from git remote, curl /repos/{repo-name}, get project_slug
  • All 19 repos have project associations via the repos endpoint
  • Fallback: if no match, load everything (current behavior, fail-open)
20b: Scope plan TOCs by detected project
  • Current: full TOC for any project with in_progress board items
  • New: full TOC for detected project's plan ONLY. Other active plans get one-liner (title + slug)
20c: Scope dynamic briefing by project
  • Current: semantic search queries ALL in-progress phase titles, no project filter
  • New: add &project={detected_slug} param to semantic search queries (API already supports this)
  • Fallback: if no project detected, query all (current behavior)
20d: Scope board items by project
  • Current: aggregated counts across all boards ("18 in-progress, 12 todo")
  • New: detected project's board items shown in detail (in_progress, qa, needs_approval). Other boards as one-line counts.
20e: Replace raw project page dump with structured context
  • Current: first 40 lines of stripped HTML from project page (unstructured, may miss user stories)
  • New: fetch TOC via /notes/{page-slug}/toc, confirm user-stories anchor exists, note it for the LLM. Inject project vision (first content block) + user stories reference. No section API exists in REST — keep it lightweight.
NOT changing: Personality injection, SOP index, core SOPs (agent-spawn-conventions, agent-workflow), template reference, bug/TODO tracking instructions. These are platform-wide and stay as-is.

Deliverables

# Deliverable Forgejo Issue Status
20a-e Refactored <code>session-start-context.sh</code> — project-scoped context loading <code>claude-custom #143</code> — PR #144 merged DONE
  • glossary — Enterprise definition (context loading at the right time)
  • phase-pal-e-agency-19-user-stories — prerequisite (stories must exist to load)
  • phase-pal-e-agency-18-enterprise-definitions — vocabulary
  • plan-pal-e-agency — parent plan
  • hook-catalog — SessionStart hooks