ldraney/claude-custom
1
0
Fork 0
Code Issues 32 Pull requests Projects Releases Packages Wiki Activity Actions

Refactor session-start-context.sh — project-scoped context loading #143

New issue
Closed
opened 2026-03-21 20:20:41 +00:00 by forgejo_admin · 1 comment
forgejo_admin commented 2026-03-21 20:20:41 +00:00
Contributor
Copy link

Type

Feature

Lineage

plan-pal-e-agency → Phase 20

Repo

forgejo_admin/claude-custom

User Story

As the superuser, when I open Claude Code in ~/basketball-api, I see basketball context (basketball plan TOC, basketball board items, basketball-related briefing). I don't see pal-e-docs CSS phases or mcd-tracker routes. Same token budget, higher signal per token. story:superuser-manage

Context

session-start-context.sh (554 lines) already has project detection infrastructure but doesn't scope context by the detected project. It loads ALL plan TOCs for active projects, queries ALL in-progress phases for dynamic briefing, and aggregates board counts across ALL boards. The project page is dumped as first 40 lines of stripped HTML (unstructured).

Five targeted changes — all within the existing hook architecture, all fail-open:

20a: Fix project detection — Current detection matches git remote against project repo_url, but only 4/20 projects have repo_url set. Instead, extract repo name from git remote -v, curl /repos/{repo-name}, get project_slug from the response. The /repos endpoint has ALL 19 repos with project associations. Fallback: if no match, load everything (current behavior).

20b: Scope plan TOCs — 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 + project). The inject_toc logic at line ~187 needs to check matched_project_slug instead of (or in addition to) projects_with_active_work.

20c: Scope dynamic briefing — Current: semantic search queries all in-progress phase titles with no project filter. New: add &project={detected_slug} to the semantic search URL at line 259. The API already supports the project query param (tested, works). Fallback: if no project detected, query without filter (current behavior).

20d: Scope board items — Current: aggregated counts across all boards ("18 in-progress, 12 todo"). New: show detected project's board items in detail (titles for in_progress, qa, needs_approval items). Other boards as "board-{slug}: N in_progress, M todo" one-liners.

20e: Structured project context — Current: first 40 lines of stripped HTML from project page (lines 461-474). New: fetch TOC via /notes/{page-slug}/toc, look for user-stories anchor. Inject vision paragraph + "User Stories available at get_section(slug, 'user-stories')" reference. Don't inject raw HTML dump.

File Targets

Files the agent should modify:

  • hooks/session-start-context.sh — refactor for project-scoped context

Files the agent should NOT touch:

  • hooks/session-start-board-sync.sh — board sync is separate, works fine
  • hooks/boards-config.sh — board list is correct
  • Any other hooks or settings

Acceptance Criteria

  • Opening Claude Code in ~/basketball-api → project detected as westside-basketball (via repos endpoint)
  • Opening Claude Code in ~/claude-custom → project detected as pal-e-agency
  • Opening Claude Code in ~/pal-e-platform → project detected as pal-e-platform
  • Detected project's plan gets full TOC; other plans get one-liners
  • Dynamic briefing queries include &project={slug} param
  • Detected project's board items shown with titles; other boards shown as counts
  • Project page section replaced with TOC-aware structured context
  • If no project detected (e.g., non-repo directory), loads everything (current behavior, fail-open)
  • If pal-e-docs is unreachable, exits cleanly with no output (fail-open, unchanged)

Test Expectations

  • Manual test: run hook with CWD set to ~/basketball-api — verify output scopes to westside-basketball
  • Manual test: run hook with CWD set to /tmp (no git repo) — verify fallback to full context
  • Manual test: verify no regression when pal-e-docs is unreachable (disconnect network, run hook)

Constraints

  • Maintain fail-open pattern throughout (any error → exit 0 silently)
  • Keep total startup time under 5 seconds (current is ~3s with parallel curl)
  • Don't increase total token output — same ~3000-5000 budget, just more relevant
  • The /repos/{slug} endpoint returns {"slug": "...", "repo_url": "...", "project": {"slug": "...", "name": "..."}}
  • The semantic search endpoint supports ?q=...&limit=N&project=SLUG (tested, works)
  • Clone to temp dir per CLAUDE.md: git clone ~/claude-custom /tmp/claude-custom-{branch}

Checklist

  • PR opened
  • Tests pass
  • No unrelated changes

Related

  • plan-pal-e-agency — parent plan
  • phase-pal-e-agency-20-context-scoped-sessions — parent phase
  • glossary — Enterprise definition
  • phase-pal-e-agency-19-user-stories — user stories now exist on all project pages
### Type Feature ### Lineage `plan-pal-e-agency` → Phase 20 ### Repo `forgejo_admin/claude-custom` ### User Story As the superuser, when I open Claude Code in `~/basketball-api`, I see basketball context (basketball plan TOC, basketball board items, basketball-related briefing). I don't see pal-e-docs CSS phases or mcd-tracker routes. Same token budget, higher signal per token. `story:superuser-manage` ### Context `session-start-context.sh` (554 lines) already has project detection infrastructure but doesn't scope context by the detected project. It loads ALL plan TOCs for active projects, queries ALL in-progress phases for dynamic briefing, and aggregates board counts across ALL boards. The project page is dumped as first 40 lines of stripped HTML (unstructured). Five targeted changes — all within the existing hook architecture, all fail-open: **20a: Fix project detection** — Current detection matches git remote against project `repo_url`, but only 4/20 projects have `repo_url` set. Instead, extract repo name from `git remote -v`, curl `/repos/{repo-name}`, get `project_slug` from the response. The `/repos` endpoint has ALL 19 repos with project associations. Fallback: if no match, load everything (current behavior). **20b: Scope plan TOCs** — 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 + project). The `inject_toc` logic at line ~187 needs to check `matched_project_slug` instead of (or in addition to) `projects_with_active_work`. **20c: Scope dynamic briefing** — Current: semantic search queries all in-progress phase titles with no project filter. New: add `&project={detected_slug}` to the semantic search URL at line 259. The API already supports the `project` query param (tested, works). Fallback: if no project detected, query without filter (current behavior). **20d: Scope board items** — Current: aggregated counts across all boards ("18 in-progress, 12 todo"). New: show detected project's board items in detail (titles for in_progress, qa, needs_approval items). Other boards as "board-{slug}: N in_progress, M todo" one-liners. **20e: Structured project context** — Current: first 40 lines of stripped HTML from project page (lines 461-474). New: fetch TOC via `/notes/{page-slug}/toc`, look for `user-stories` anchor. Inject vision paragraph + "User Stories available at `get_section(slug, 'user-stories')`" reference. Don't inject raw HTML dump. ### File Targets Files the agent should modify: - `hooks/session-start-context.sh` — refactor for project-scoped context Files the agent should NOT touch: - `hooks/session-start-board-sync.sh` — board sync is separate, works fine - `hooks/boards-config.sh` — board list is correct - Any other hooks or settings ### Acceptance Criteria - [ ] Opening Claude Code in `~/basketball-api` → project detected as `westside-basketball` (via repos endpoint) - [ ] Opening Claude Code in `~/claude-custom` → project detected as `pal-e-agency` - [ ] Opening Claude Code in `~/pal-e-platform` → project detected as `pal-e-platform` - [ ] Detected project's plan gets full TOC; other plans get one-liners - [ ] Dynamic briefing queries include `&project={slug}` param - [ ] Detected project's board items shown with titles; other boards shown as counts - [ ] Project page section replaced with TOC-aware structured context - [ ] If no project detected (e.g., non-repo directory), loads everything (current behavior, fail-open) - [ ] If pal-e-docs is unreachable, exits cleanly with no output (fail-open, unchanged) ### Test Expectations - [ ] Manual test: run hook with CWD set to `~/basketball-api` — verify output scopes to westside-basketball - [ ] Manual test: run hook with CWD set to `/tmp` (no git repo) — verify fallback to full context - [ ] Manual test: verify no regression when pal-e-docs is unreachable (disconnect network, run hook) ### Constraints - Maintain fail-open pattern throughout (any error → exit 0 silently) - Keep total startup time under 5 seconds (current is ~3s with parallel curl) - Don't increase total token output — same ~3000-5000 budget, just more relevant - The `/repos/{slug}` endpoint returns `{"slug": "...", "repo_url": "...", "project": {"slug": "...", "name": "..."}}` - The semantic search endpoint supports `?q=...&limit=N&project=SLUG` (tested, works) - Clone to temp dir per CLAUDE.md: `git clone ~/claude-custom /tmp/claude-custom-{branch}` ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `plan-pal-e-agency` — parent plan - `phase-pal-e-agency-20-context-scoped-sessions` — parent phase - `glossary` — Enterprise definition - `phase-pal-e-agency-19-user-stories` — user stories now exist on all project pages
forgejo_admin commented 2026-03-21 20:28:24 +00:00
Author
Contributor
Copy link

Reading issue for QA review context.

Reading issue for QA review context.
forgejo_admin 2026-03-21 20:30:03 +00:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
217-enhance-skill-review-ticket-verify-arch
86-epilogue-nits-hook-updates-dottie-config
76-add-sessionstart-hook-to-detect-missing
69-fix-block-docs-writes-sh-security-gap-ad
51-phase-3-agent-label-behavior-posttooluse
No results found.
Labels
Clear labels   
domain:backend

   
domain:devops

   
domain:frontend

   
status:approved

QA passed, awaiting merge approval

  
status:in-progress

Dev agent is actively working

  
status:needs-fix

QA found issues, back to dev

  
status:qa

PR submitted, awaiting QA review

  
type:bug

Bug fix

  
type:devops

Infrastructure/CI/config work

  
type:feature

New functionality

No labels
domain:backend
domain:devops
domain:frontend
status:approved
status:in-progress
status:needs-fix
status:qa
type:bug
type:devops
type:feature
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
ldraney/claude-custom#143
No description provided.