Westside AI Assistant

Validation: Issue #31 -- email_blast tool for NEMO

Verification Checklist

• Forgejo issue #31: closed
• PR #32: merged into main
• Deployment: deployed via :latest tag
• Code artifacts: email_blast tool added to TOOLS list, post() method added to BasketballClient

Scope

Added the email_blast tool to NEMO (the westside AI assistant). This tool allows NEMO to send branded emails via basketball-api's /email/blast endpoint. The tool is registered in the TOOLS list and uses a new post() method on BasketballClient to make write requests.

Production Safety Gate

WARNING: This tool is deployed but requires the NEMO_EMAIL_MODE environment variable gate (#35) before it is safe for production use. Without the gate, NEMO could send real emails without operator confirmation. Issue #35 must be completed before enabling this tool in production.

Disposition

Board item #759 moved to done on board-westside-ai-assistant. Production safety depends on completion of issue #35 (NEMO_EMAIL_MODE gate).

Ticket

westside-ai-assistant#30 — Board item #748. Infra: deploy qwen3.5:4b to cluster Ollama + Nemo env vars.

Environment

Prod cluster. Ollama namespace, westside-ai-assistant namespace, pal-e-deployments repo.

Checks

Verdict

PASS — 4/4 deliverables confirmed. AC #5 blocked by Harbor credentials issue (westside-ai-assistant#33), which is independent of this ticket's scope.

Verdict: NEEDS_REFINEMENT

Template Completeness

Checked against template-issue-bug required sections:

• [x] Type — Bug
• [x] Lineage — discovered during #30 validation
• [x] Repo — listed as forgejo_admin/pal-e-services
• [x] What Broke — detailed with error messages and symptoms
• [x] Repro Steps — clear 4-step reproduction
• [x] Expected Behavior — stated
• [x] Environment — cluster, namespace, Harbor project listed
• [x] Acceptance Criteria — 4 criteria, all testable
• [x] Related — project and blocking issue referenced
• [ ] File Targets — not present (bug template does not require them, but the fix path is ambiguous without them)

Traceability

• [x] story:read-ops label — Admin Read Operations via GroupMe
• [x] story note verified — story-westside-ai-assistant-read-ops exists in project-westside-ai-assistant user-stories section
• [x] arch:A4 label — infrastructure component
• [ ] arch note MISSING — [SCOPE] Create architecture note arch-A4 for the infrastructure component
• [x] Forgejo issue — forgejo_admin/westside-ai-assistant#33, open

File Targets

No specific file paths listed in the issue body. Verified the claimed repo placement:

• [ ] pal-e-services/terraform — ISSUE: westside-ai-assistant does NOT appear anywhere in the pal-e-services terraform codebase. The service was never onboarded into var.services. The harbor-creds secret was provisioned through a different mechanism (likely manual or one-off).
• [x] harbor-creds secret exists in westside-ai-assistant namespace — confirmed via kubectl. Username is robot$westside-ai-assistant+pull, but this robot no longer exists in Harbor.
• [x] ImagePullBackOff confirmed live — pod westside-ai-assistant-dd855f577-c94mp actively failing with 401 Unauthorized.

Repo Placement

MISMATCH. The issue says the fix repo is forgejo_admin/pal-e-services, but westside-ai-assistant is not in pal-e-services var.services. Two possible fix paths:

1. Proper onboarding: Add westside-ai-assistant to pal-e-services var.services, which auto-provisions Harbor project, robot accounts (with duration = -1, no expiry), namespace, and harbor-creds secret. This is the correct long-term fix.
2. Manual re-creation: Create a new robot account in Harbor manually and update the k8s secret. This is a bandaid.

The issue body must clarify which path and update the Repo field accordingly.

Dependencies

• [x] Blocks #29 (Nemo app SDK swap) — documented in issue
• [x] Discovered during #30 validation (Nemo qwen infra) — documented
• [ ] Board item #599 (GroupMe go-live, issue #7) is in_progress — not documented but would also fail on next deploy
• [ ] Board item #759 (email_blast tool, issue #31) is in_progress — not documented but same failure on next deploy
• This is a namespace-wide blocker: ALL westside-ai-assistant deployments fail until resolved

Acceptance Criteria

4 criteria from the issue, all verifiable by an agent:

• [x] "Valid Harbor robot account exists" — verifiable via Harbor API or curl
• [x] "harbor-creds secret updated" — verifiable via kubectl
• [x] "New pod can pull image" — verifiable via kubectl rollout restart + watch
• [x] "No ImagePullBackOff events" — verifiable via kubectl get events

Missing AC: If fix path is pal-e-services onboarding, add AC to verify tofu plan shows the service in state with duration = -1 robots.

Blast Radius

Checked all other namespaces with harbor-creds (basketball-api, westsidekingsandqueens, mcd-tracker, pal-e-docs, pal-e-mail, gcal-scheduler, mcd-tracker-app, pal-e-production, platform-validation). No ImagePull failures found in any other namespace. All other services are provisioned through pal-e-services with duration = -1 robot accounts. Only westside-ai-assistant is affected because it was provisioned outside the standard pipeline. Rollback is straightforward — the old pod with cached image is still running.

Decomposition Assessment

Apply three-thing limit and five-minute rule:

• Single repo fix (pal-e-services terraform vars OR manual Harbor operation)
• 4 acceptance criteria — under the limit
• Estimated agent time: under 5 minutes if fix path is clarified
• No independent subtasks to parallelize

No decomposition needed.

Recommendation

1. [BODY] Fix Repo field: clarify whether fix is (a) onboarding into pal-e-services var.services or (b) manual Harbor robot re-creation. If (a), update file targets to include terraform/terraform.tfvars (or equivalent services var file). If (b), note this is a manual operation with no code PR.
2. [BODY] Add AC: "westside-ai-assistant appears in pal-e-services var.services with duration = -1 robot accounts" (if onboarding path chosen).
3. [BODY] Document that this blocks all in_progress items (#7, #31) — not just #29.
4. [SCOPE] Create architecture note arch-A4 for the infrastructure component.

Verdict: APPROVED

Re-Review of review-749-2026-04-03

Original review returned NEEDS_REFINEMENT with 3 body issues and 1 decomposition recommendation. This re-review verifies the fixes applied to the issue body.

Fixes Applied

• [x] [BODY] app/confirmation.py added to File Targets under new "Files to delete" subsection — was previously only mentioned in Context. Now explicitly listed with rationale: "write confirmation state machine not needed for V1 read-only mode."
• [x] [BODY] requirements.txt / pyproject.toml fixed to just requirements.txt — no pyproject.toml exists in this repo.
• [x] [BODY] Dependency on #30 made explicit in Related section — was previously "infra ticket (qwen3.5:4b in cluster + env vars)", now references #30 directly.

Decomposition Decision

Original review recommended decomposing into 2 sub-tickets (5 file operations, 8 AC). Decision: keep as one ticket. Rationale:

• All 8 AC are testable assertions on one cohesive feature (SDK swap + tool definitions)
• Tool schemas are pre-defined in the ticket — no design ambiguity for the agent
• The "new file" (tools.py) is tightly coupled to the ai.py rewrite — splitting would require the second ticket to re-read and modify ai.py anyway
• The delete (confirmation.py) is trivial — not a separate unit of work

Remaining Scope Item

• [SCOPE] arch-A2 architecture note still missing. This is discovered scope — tracked separately, not a blocker for this ticket.

File Targets Summary (post-fix)

• 3 files to modify: app/ai.py, app/config.py, requirements.txt
• 1 file to create: app/tools.py
• 1 file to delete: app/confirmation.py
• 2 files do-not-touch: app/basketball.py, app/groupme.py

Ticket is ready for dispatch.

Ticket

Forgejo issue: westside-ai-assistant#30 (Nemo qwen infra)
Board item: #748
PR: pal-e-deployments#82 — merged to main as commit 21a33a2
What shipped: Replaced Anthropic model env with Ollama for Nemo AI assistant.

Environment

Production cluster (k3s on archbox). Namespace: westside-ai-assistant. ArgoCD app: westside-ai-assistant.

Checks

Verdict

PARTIAL — ArgoCD synced at the correct revision, but the new pod cannot pull the image due to a 401 Unauthorized error from Harbor. The old pod is still running and serving traffic. The rollout is blocked by a Harbor authentication issue for the westside-ai-assistant/api:latest image.

Discovered Issues

• BLOCKER: Harbor image pull auth failure for westside-ai-assistant namespace. The new ReplicaSet pod gets 401 Unauthorized when pulling from Harbor. Likely missing or expired imagePullSecret in the westside-ai-assistant namespace. Needs a Forgejo issue to fix Harbor pull credentials.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — Feature
• [x] Lineage — standalone, part of westside-email-agent capability
• [x] Repo — forgejo_admin/westside-ai-assistant
• [x] User Story — clear admin-to-NEMO email flow
• [x] Context — thorough, references existing patterns and auth
• [x] File Targets — specific files with modify/do-not-touch
• [x] Acceptance Criteria — 6 testable items
• [x] Test Expectations — 3 unit tests with run command
• [x] Constraints — patterns, auth, prompt guidance
• [x] Checklist — standard 3-item
• [x] Related — arch-email, sop-email-send, project-westside-agency, basketball-api #295

Traceability

• [ ] story:WA-S1 label — NO matching story on project-westside-ai-assistant user-stories section. Project page lists: read-ops, write-ops, safety. "WA-S1" does not exist. [SCOPE] Create user story entry "WA-S1" on project-westside-ai-assistant user-stories section, OR relabel to an existing story (e.g., story:write-ops if email blast is considered a write operation).
• [x] arch:email label — arch-email note exists (id 1102, project westside-basketball, tagged architecture+active). Substantive content covers layouts, components, blast flow.
• [x] Forgejo issue — forgejo_admin/westside-ai-assistant#31, open

File Targets

• [x] app/ai.py — verified: TOOLS list at line 49, SYSTEM_PROMPT at line 24, existing write tools (update_player, assign_player_to_team) with metadata operation=write pattern confirmed. Tool execution handler at line 246+.
• [x] app/basketball.py — verified: BasketballClient class at line 25, only has get() method (line 134). No post() exists yet — matches ticket claim.
• [x] app/confirmation.py — exists, correctly marked NOT to touch.
• [x] app/groupme.py — exists, correctly marked NOT to touch.
• [x] app/config.py — exists, correctly marked NOT to touch.

Repo Placement

OK. Issue filed on forgejo_admin/westside-ai-assistant, all file targets are in that repo. No cross-repo work needed — basketball-api blast endpoint already exists and is deployed.

Dependencies

• [x] basketball-api #295 (blast endpoint) — satisfied. Issue closed, merged (commit fb24245), deployed on origin/main.
• [x] Board item #599 (GroupMe bot go-live) — in_progress. Not a hard blocker (email_blast tool can be built and tested independently), but full end-to-end flow requires bot to be live.

No unresolved dependencies that would block execution.

Acceptance Criteria

6 ACs, all agent-verifiable:

• AC1: email_blast tool in TOOLS with correct schema — grep/read verification
• AC2: Tool tagged as write operation — grep verification of metadata
• AC3: BasketballClient.post() method exists — grep verification
• AC4: SYSTEM_PROMPT includes email capabilities — read verification
• AC5: End-to-end flow (user says X, NEMO proposes, user confirms, blast executes) — testable via unit test mock
• AC6: test_email parameter works — unit test

All criteria are concrete and testable. No ambiguity.

Blast Radius

Low. Changes are additive (new tool + new method). Existing tools and confirmation flow are untouched. The basketball-api blast endpoint already handles auth and validation — this ticket only adds the client-side caller. No sibling services consume NEMO's tool definitions. Rollback is straightforward (revert the two file changes).

Decomposition Assessment

2 files in 1 repo. 6 acceptance criteria. Estimated agent time ~3-4 minutes. All changes are tightly coupled (tool definition + client method + prompt update). No independent subtasks worth parallelizing. No decomposition needed.

Recommendation

1. [SCOPE] Story "WA-S1" does not exist on project-westside-ai-assistant user-stories section. Either create a new user story entry for email/agent-driven-communications capability, or relabel the board item to an existing story (e.g., story:write-ops). This must be resolved before the ticket can move to next_up.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — Feature
• [x] Lineage — Supersedes #27, references Nemo outage
• [x] Repo — forgejo_admin/westside-ai-assistant
• [x] User Story
• [x] Context (excellent — documents current vs new architecture)
• [x] File Targets (modify, create, and do-not-touch lists)
• [x] Tool Schemas (bonus — pre-formatted I/O examples)
• [x] Acceptance Criteria (8 items)
• [x] Test Expectations (4 items + run command)
• [x] Constraints
• [x] Checklist
• [x] Related

Traceability

• [x] story:read-ops label — verified in project-westside-ai-assistant user-stories section
• [x] arch:A2 label — present on board item
• [ ] arch note MISSING — [SCOPE] No arch-A2 note found in pal-e-docs. Create architecture note arch-A2 for AI engine component.
• [x] Forgejo issue — forgejo_admin/westside-ai-assistant#29, open

File Targets

• [x] app/ai.py — verified: exists, contains Anthropic SDK import, anthropic.messages.create(), TOOLS list with api_get + 7 write tools, SYSTEM_PROMPT. Ticket accurately describes what needs replacing.
• [x] app/config.py — verified: exists, contains anthropic_api_key and anthropic_model settings. No ollama settings yet.
• [x] requirements.txt — verified: exists, contains anthropic>=0.52,<1. No pyproject.toml found (requirements.txt only).
• [x] app/tools.py — to be created. Does not exist yet. Appropriate.
• [x] app/basketball.py — verified: exists. Correctly marked as do-not-touch.
• [x] app/groupme.py — verified: exists. Correctly marked as do-not-touch.
• [ ] app/confirmation.py — ISSUE: ticket says "REMOVE" but it's listed under Context, not File Targets. Should be explicitly listed as a file to delete in the File Targets section.

Repo Placement

OK. Issue is filed on westside-ai-assistant, all file changes are within that repo. Single-repo ticket.

Dependencies

• [x] Depends on infra ticket #30 (qwen3.5:4b deployed + env vars set). Correctly documented in Related section.
• [x] Supersedes #27 (read-only SQL tool). Correctly documented.
• [ ] Dependency on infra ticket should be explicit in Constraints or a "Depends on" section — currently only in Related.

Acceptance Criteria

8 AC items for a single repo. This is over the 5-AC guideline but the work is cohesive (one file rewrite + one new file + config changes). The tool schemas provide clear expected I/O which helps verification. However, 8 AC + 4 test expectations + a new file creation pushes the boundary of the 5-minute rule.

Blast Radius

Contained to westside-ai-assistant. The GroupMe webhook handler (app/groupme.py) calls process_message which is being rewritten — but the function signature is preserved (the ticket says "it calls process_message which we're changing internally"). Low external blast radius.

Decomposition

3 files to modify + 1 file to create + 1 file to delete = 5 file operations. 8 AC. Estimated agent work: borderline 5-10 minutes due to new file creation with 4 tool handlers + Ollama HTTP integration. NEEDS DECOMPOSITION into 2 tickets: (1) SDK swap + config (ai.py, config.py, requirements.txt, delete confirmation.py), (2) tool definitions (tools.py + update ai.py TOOLS list). Alternatively, a skilled agent could do it in one pass since the tool schemas are pre-defined.

Recommendation

• [BODY] Add app/confirmation.py to File Targets as "File to delete" — currently only mentioned in Context as "REMOVE".
• [BODY] Fix dependency reference: "requirements.txt / pyproject.toml" should be just "requirements.txt" — no pyproject.toml exists in this repo.
• [DECOMPOSE] 5 file operations, 8 AC — borderline. Recommend decomposition into 2 sub-tickets: (1) SDK swap + config cleanup, (2) purpose-built tools. Route to skill-decompose-ticket if decomposition is desired.
• [SCOPE] Create architecture note arch-A2 for AI engine component.

Verdict: APPROVED

Template Completeness

• [x] Type — Feature
• [x] Lineage — Supersedes #16, references Nemo outage
• [x] Repo — pal-e-deployments + pal-e-platform
• [x] User Story
• [x] Context
• [x] File Targets (modify + check + manual steps)
• [x] Acceptance Criteria (5 items)
• [x] Test Expectations
• [x] Constraints
• [x] Checklist
• [x] Related

Traceability

• [x] story:read-ops label — verified in project-westside-ai-assistant user-stories section (read-ops = "Marcus can query player/team/payment data via GroupMe")
• [x] arch:A4 label — present on board item
• [ ] arch note MISSING — [SCOPE] No arch-A4 note found in pal-e-docs. Create architecture note arch-A4 for infra/deployment component.
• [x] Forgejo issue — forgejo_admin/westside-ai-assistant#30, open

File Targets

• [x] pal-e-deployments/overlays/westside-ai-assistant/prod/deployment-patch.yaml — verified: file exists, contains ANTHROPIC_MODEL env var (line 16) and ANTHROPIC_API_KEY secret ref (lines 21-25). Ticket accurately describes what needs changing (remove ANTHROPIC_MODEL, add OLLAMA_BASE_URL + OLLAMA_MODEL).
• [x] pal-e-platform/terraform/network-policies.tf — verified: ollama NetworkPolicy exists (line 181). The westside-ai-assistant ingress rule was already added in commit 0cc398a (#246) but appears removed in working tree. On main branch the rule exists. Ticket's "verify or add" framing is correct.
• [x] Manual step (kubectl exec ollama pull) — appropriate for a model download, not a file change.

Repo Placement

OK. Issue filed on westside-ai-assistant which is the project context. Actual file changes span pal-e-deployments and potentially pal-e-platform — both are correctly identified. Two PRs expected (one per repo), checklist reflects this.

Dependencies

• [x] Companion ticket #29 (SDK swap) depends on this ticket completing first — correctly documented.
• [x] Supersedes #16 (feature flag approach) — correctly documented.
• [x] No blocking dependencies from the board — this can start immediately.

Acceptance Criteria

5 AC items, all verifiable via kubectl commands. Each criterion maps to a concrete check. The test expectations section provides exact curl command for validation. Solid.

Blast Radius

Low. Deployment patch changes are scoped to westside-ai-assistant namespace only. NetworkPolicy change (if needed) adds an ingress rule to ollama — additive, no risk to existing consumers. The model download is namespace-isolated.

Decomposition

2 file targets across 2 repos + 1 manual step. 5 AC. However, the actual code changes are minimal (env var swap in a YAML patch + verify a NetworkPolicy rule). Estimated <5 minutes. No decomposition needed.

Recommendation

No action needed. Ticket is well-scoped, all file targets verified, traceability complete except arch note (deferred scope item).

• [SCOPE] Create architecture note arch-A4 for infra/deployment component.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — Feature
• [x] Lineage — Standalone, scoped from session discussion
• [x] Repo — forgejo_admin/westside-ai-assistant
• [x] User Story — As Lucas (platform operator), switch providers via env var
• [x] Context — Good background on SDK differences, Ollama cluster-internal URL, qwen2.5:7b already pulled
• [x] File Targets — 5 modify targets + 3 don't-touch targets
• [x] Acceptance Criteria — 6 items
• [x] Test Expectations — 3 unit tests + run command
• [x] Constraints — Minimal provider interface, normalized response, no plugin system
• [x] Checklist — PR opened, tests pass, no unrelated changes
• [x] Related — project-westside-ai-assistant, story-westside-ai-assistant-read-ops

All required sections present. Template is complete.

Traceability

• [x] story:read-ops label — present on board item, listed in project-westside-ai-assistant user-stories table
• [ ] story:read-ops note MISSING — [SCOPE] Create user story note story-westside-ai-assistant-read-ops (referenced on project page but note does not exist in pal-e-docs)
• [x] story:write-ops label — present on board item, listed in project-westside-ai-assistant user-stories table
• [ ] story:write-ops note MISSING — [SCOPE] Create user story note story-westside-ai-assistant-write-ops (referenced on project page but note does not exist in pal-e-docs)
• [x] arch:A2 label — present on board item
• [ ] arch note MISSING — [SCOPE] No arch-A2 note exists. Project page references arch-domain-westside-ai-assistant, arch-dataflow-westside-ai-assistant, and arch-deployment-westside-ai-assistant but none of these exist in pal-e-docs. The A2 label-to-named-note mapping is also unclear.
• [x] Forgejo issue — forgejo_admin/westside-ai-assistant#16, open

File Targets

• [x] app/ai.py — verified: exists, currently Anthropic-only (imports anthropic, uses anthropic.Anthropic client directly, hardcoded to settings.anthropic_api_key and settings.anthropic_model). Provider abstraction needed as described.
• [x] app/config.py — verified: exists, currently has only anthropic_api_key and anthropic_model fields. Needs ai_provider, ollama_url, ollama_model additions.
• [x] app/health.py — verified: exists, readiness check currently hardcoded to bool(settings.anthropic_api_key). Needs provider-aware credential check.
• [x] requirements.txt — verified: exists, currently has anthropic>=0.52,<1 but no openai. Needs openai dependency added.
• [x] tests/test_ai.py — verified: exists, 260+ lines of Anthropic-specific tests. Needs dual-provider test paths.

All 5 file targets verified. Paths are accurate and current codebase state matches what the issue describes.

Repo Placement

OK. Issue filed on forgejo_admin/westside-ai-assistant, all file targets are in this single repo. No cross-repo concerns.

Dependencies

• [x] Board item #642 "Swap Anthropic SDK for Ollama (local qwen2.5:7b)" — done. This ticket logically follows it, restoring dual-provider support.
• [x] No blocking dependencies. No items blocked by this ticket.
• Note: Item #683 "Repo restructure: Nemo agent + modular tool registry" (backlog) would touch app/ai.py — ordering matters but not a blocker since #683 is still in backlog.

Acceptance Criteria

6 AC items, all verifiable by an agent:

• AC 1-2: Environment variable switching — verifiable via unit tests with mocked SDK clients
• AC 3: Tool definition compatibility — verifiable by running both provider paths through tool_use tests
• AC 4: Unchanged confirmation flow — verifiable by existing test suite continuing to pass
• AC 5: Missing credentials error — verifiable via unit test with missing env vars
• AC 6: Default provider — verifiable by checking config default value

All criteria are concrete and testable. No missing criteria detected.

Blast Radius

Low. Changes are contained within the AI engine layer. basketball.py, confirmation.py, and groupme.py are explicitly excluded. The ProviderResponse normalization ensures downstream consumers are unaffected. No sibling services use the same AI provider pattern. Rollback is straightforward: revert the PR.

Decomposition Assessment

5 file targets in 1 repo. 6 AC + 3 test expectations = 9 verification items. All changes are tightly coupled: config drives provider selection, provider drives ai.py, health checks config, tests verify both paths, requirements list dependencies. The constraint explicitly says "two if/else branches, not a plugin system." A single agent can handle this within the 5-minute window. No decomposition needed.

Recommendation

1. [SCOPE] Create user story note story-westside-ai-assistant-read-ops — referenced on project page but does not exist in pal-e-docs
2. [SCOPE] Create user story note story-westside-ai-assistant-write-ops — referenced on project page but does not exist in pal-e-docs
3. [SCOPE] Create architecture notes for this project — project page references arch-domain-westside-ai-assistant, arch-dataflow-westside-ai-assistant, arch-deployment-westside-ai-assistant but none exist. The arch:A2 label on board items has no clear mapping to these named arch notes.

Note: All three [SCOPE] items are project-level gaps affecting every board item on board-westside-ai-assistant, not specific to this ticket. The issue body itself is well-scoped and complete. Once the backing notes are created, this ticket would be READY.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — Feature
• [x] Lineage — Standalone
• [x] Repo — forgejo_admin/westside-ai-assistant
• [x] User Story — As Lucas (platform operator)
• [x] Context — describes inline tools problem and modular pattern
• [x] File Targets — create list, modify list, do-not-touch list
• [x] Acceptance Criteria — 7 criteria
• [x] Test Expectations — 4 test items + run command
• [x] Constraints — TOOL.md format, handler pattern, registry contract
• [x] Checklist — PR, tests, no unrelated changes
• [x] Related — project and story references

Traceability

• [x] story:read-ops label — "Admin Read Operations via GroupMe"
• [x] story note verified — found in project-westside-ai-assistant user-stories section (key: read-ops, note: story-westside-ai-assistant-read-ops)
• [x] arch:A2 label — AI Engine component
• [ ] arch note MISSING — [SCOPE] No note named arch-A2 exists in pal-e-docs. The project page references arch-domain-westside-ai-assistant, arch-dataflow-westside-ai-assistant, arch-deployment-westside-ai-assistant, but none of these notes exist yet either (search returned empty). The A2 component ID is referenced in the story note but has no dedicated architecture note.
• [x] Forgejo issue — forgejo_admin/westside-ai-assistant#18, open

File Targets

• [x] app/ai.py — verified: exists (618 lines), contains inline TOOLS list with 14 tool definitions and _execute_read_tool dispatch function. Ticket correctly identifies this for modification.
• [x] app/basketball.py — verified: exists, correctly listed as do-not-touch
• [x] app/config.py — verified: exists, correctly listed as no-changes-needed
• [x] app/groupme.py — verified: exists, correctly listed as do-not-touch
• [x] app/confirmation.py — verified: exists, correctly listed as dormant/do-not-touch
• [x] New files to create (agents/nemo.md, tools/*/TOOL.md, tools/*/handler.py, app/tool_registry.py, prompts/system.md) — parent directories do not yet exist, creation is valid
• [ ] ISSUE: Ticket says "4 tool categories" with 7 read tools, but ai.py has 14 tools (7 read + 7 write). The write tools (update_player, assign_player_to_team, remove_player_from_team, toggle_player_visibility, create_team, checkin_player, bulk_assign_tryout_numbers) are not addressed in the file targets. If read-only V1 is intentional, the ticket should explicitly state that write tool categories are deferred and the registry should only discover read tools. Otherwise the registry will silently drop 7 tools.

Repo Placement

OK — issue filed on forgejo_admin/westside-ai-assistant, all file targets are within that repo. Single-repo change.

Dependencies

• [ ] Board item #684 (Interaction logging to Postgres) — depends on ai.py internals. This restructure should land first. Not explicitly documented as a dependency. Status: backlog.
• [ ] Board item #685 (Read-only lockdown) — directly affected by this restructure since it modifies the tool set. Should land after this. Not explicitly documented. Status: backlog.
• [ ] Board item #647 (Model provider switch: Anthropic/Ollama) — touches ai.py Anthropic integration. Should be aware of registry pattern. Not explicitly documented. Status: backlog.
• No items currently in_progress that would conflict. No blocking dependencies — this ticket can proceed independently.

Acceptance Criteria

• [x] AC 1 (agents/nemo.md defines personality) — testable: file existence + content check
• [x] AC 2 (4 tool categories with TOOL.md + handler.py) — testable: directory/file existence
• [x] AC 3 (tool_registry.py auto-discovers and generates definitions) — testable: unit test
• [x] AC 4 (ai.py uses registry) — testable: import check + behavior test
• [x] AC 5 (new tool = new directory, no ai.py changes) — testable: verify no dispatch in ai.py
• [ ] AC 6 (all existing read-tool tests still pass) — testable via pytest, BUT test_ai.py (593 lines) imports TOOLS, _TOOL_META, _execute_read_tool directly from app.ai. After restructure, these must still be importable from the same location OR tests must be updated. The ticket does not mention test file modifications.
• [x] AC 7 (system prompt from prompts/system.md + nemo.md) — testable: content assembly check

Blast Radius

• test_ai.py (593 lines) imports TOOLS, _TOOL_META, _execute_read_tool, and other internals from app.ai. Restructuring these requires either (a) preserving re-exports in ai.py or (b) updating test imports. The ticket does not address this.
• .woodpecker.yaml CI pipeline — should not be affected if pytest command stays the same.
• No other repos consume this code (single-service, no SDK). Rollback is straightforward (revert PR).

Decomposition Assessment

Apply the three-thing limit and five-minute rule:

• File count: 12+ new files to create, 1 file to modify (ai.py), potentially 1 more (test_ai.py). All in one repo.
• AC count: 7 acceptance criteria + 4 test expectations = 11 checkpoints.
• Discrete changes: 4 — (1) create tool directory structure with TOOL.md + handler.py, (2) create tool_registry.py, (3) refactor ai.py to use registry, (4) create agents/nemo.md + prompts/system.md. Exceeds three-thing limit.
• Estimated agent time: 5-8 minutes. The file creation is mechanical (move definitions from inline to modular files), but the registry + ai.py integration requires careful wiring.
• Assessment: Borderline. The work is tightly coupled (registry must exist before ai.py can use it, tools must exist before registry can discover them). Parallelization is limited. A single agent pass is feasible but tight. If refinement adds write tools to scope, decomposition would be needed.

Recommendation

1. [BODY] Clarify write tool handling — add explicit statement to Context and File Targets: "Write tools (update_player, assign_player_to_team, remove_player_from_team, toggle_player_visibility, create_team, checkin_player, bulk_assign_tryout_numbers) remain inline in ai.py for now. The registry discovers read tools only. Write tool modularization is deferred to a future ticket." OR include write tool categories in the file targets (which would trigger decomposition).
2. [BODY] Add tests/test_ai.py to "Files the agent should modify" — test imports reference TOOLS, _TOOL_META, _execute_read_tool directly from app.ai. Either document that re-exports must be preserved in ai.py, or list test_ai.py as a modification target for import updates.
3. [SCOPE] Create architecture notes — the project page references arch-domain-westside-ai-assistant, arch-dataflow-westside-ai-assistant, arch-deployment-westside-ai-assistant but none exist in pal-e-docs. The arch:A2 label has no backing note. Create at minimum arch-domain-westside-ai-assistant with component IDs (A1=GroupMe Webhook, A2=AI Engine, A3=Basketball Client, A4=Infrastructure).

Verdict: READY

Scope is solid. All file targets verified against the live codebase. Traceability is complete except for the known arch-A2 note gap (pre-existing, not a blocker for this ticket). Single-repo, single-file change that fits in one agent pass.

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- Standalone, safety scoping for V1 launch
• [x] Repo -- forgejo_admin/westside-ai-assistant
• [x] User Story -- As Marcus (admin), read-only trust
• [x] Context -- V1 read-only rationale, 7 write tools enumerated
• [x] File Targets -- ai.py (modify) + prompts/system.md (conditional), DO NOT TOUCH list correct
• [x] Acceptance Criteria -- 6 criteria, all testable
• [x] Test Expectations -- 3 unit tests + run command
• [x] Constraints -- #18 conditional logic, write code preserved, web app URL required
• [x] Checklist -- standard 3-item
• [x] Related -- project + story references

Traceability

• [x] story:read-ops label -- verified in project-westside-ai-assistant user-stories table (Key: read-ops, story note: story-westside-ai-assistant-read-ops)
• [x] story:safety label -- verified in project-westside-ai-assistant user-stories table (Key: safety, story note: story-westside-ai-assistant-safety)
• [x] arch:A2 label -- AI Engine component
• [ ] arch note MISSING -- [SCOPE] No arch-A2 note exists in pal-e-docs. The project page architecture section uses named notes (arch-domain-westside-ai-assistant, arch-dataflow-westside-ai-assistant, arch-deployment-westside-ai-assistant) but no A-code-mapped note. This is a pre-existing gap flagged in prior reviews (review-647-2026-03-28, review-684-2026-03-28). Not a blocker for this ticket.
• [x] Forgejo issue -- forgejo_admin/westside-ai-assistant#20, state: open

File Targets

• [x] app/ai.py -- verified: EXISTS on main. Contains inline SYSTEM_PROMPT (line 23-28) and TOOLS list with 7 read tools (get_dashboard, list_players, get_player, list_teams, get_roster, get_subscriptions_overview, list_subscriptions) + 7 write tools (update_player, assign_player_to_team, remove_player_from_team, toggle_player_visibility, create_team, checkin_player, bulk_assign_tryout_numbers). All 7 write tool names match the issue exactly.
• [x] prompts/system.md -- verified: DOES NOT EXIST on main (prompts/ directory absent). Issue correctly handles this: "or inline SYSTEM_PROMPT if #18 hasn't merged." Since #18 is still open, agent will modify SYSTEM_PROMPT in ai.py. Correct.
• [x] app/confirmation.py (DO NOT TOUCH) -- verified: EXISTS. Contains store_pending, check_pending, expire_stale, has_pending functions. Issue correctly says keep dormant.
• [x] app/basketball.py (DO NOT TOUCH) -- verified: EXISTS. Contains BasketballClient class with read AND write methods. Issue correctly says keep all functions, only tool exposure changes.

Repo Placement

OK. Issue filed on forgejo_admin/westside-ai-assistant, fix is in the same repo. Single-repo change.

Dependencies

• Board item #683 (Forgejo issue #18: Repo restructure) is in backlog. This ticket explicitly handles the dependency with conditional logic in File Targets and Constraints: "if #18 hasn't merged, modify ai.py inline. If #18 has merged, modify tool_registry.py and prompts/system.md." Currently #18 is open and unmerged, so the ai.py path applies.
• No other blockers identified on the board.
• ai.py imports from confirmation.py (store_pending, check_pending, expire_stale, has_pending). Removing write tools means these imports become unused. The issue does NOT mention cleaning up confirmation imports. This is minor -- dormant imports won't break anything, and the confirmation module is intended for future write support. Acceptable as-is.

Acceptance Criteria

All 6 AC are testable by an agent:

• AC1: Count tool definitions, verify only 7 read tools -- unit testable
• AC2: Check SYSTEM_PROMPT string contains read-only language -- unit testable
• AC3: "What can you do?" produces capability list -- requires AI response mocking but well-specified
• AC4: "Update player height" gets refusal with web app link -- requires AI response mocking
• AC5: basketball.py write functions remain -- file existence check
• AC6: confirmation.py remains -- file existence check

Test Expectations section provides 3 concrete unit tests + pytest command. All verifiable.

Blast Radius

Self-contained to westside-ai-assistant. No sibling services consume this tool registry. The basketball-api write endpoints remain available (only the AI tool exposure is removed). No downstream consumers affected.

Decomposition

1-2 file targets in 1 repo. 6 AC. Estimated agent work well under 5 minutes. No decomposition needed.

Recommendation

• [SCOPE] Create architecture note arch-A2 (or establish A-code mapping to existing arch-domain-westside-ai-assistant). Pre-existing gap, not a blocker for this ticket.

No other action needed. Ticket is READY for dispatch.

Verdict: NEEDS_REFINEMENT

Re-review of board item #684. Previous review (review-684-2026-03-28) returned NEEDS_REFINEMENT with 4 recommendations. None have been addressed -- the Forgejo issue body is unchanged and no comments exist.

Previous Recommendations -- Status

• [SCOPE] Create infra prerequisite ticket (DB creation + NetworkPolicy + k8s secret) -- NOT ADDRESSED. No new issue exists in westside-ai-assistant, pal-e-services, or pal-e-platform for this work. This remains the primary blocker.
• [BODY] Note that migrations/ directory must be created -- NOT ADDRESSED. Issue still says "create migrations/001_interaction_log.sql" without noting the directory is new.
• [BODY] Clarify token counting across tool_use loop -- NOT ADDRESSED. Issue still says "Token counts come from the Anthropic API response" without specifying summing across multiple calls in the tool loop.
• [BODY] Add explicit blocked-by dependency reference -- NOT ADDRESSED. No blocker reference in Constraints.

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- Standalone
• [x] Repo -- forgejo_admin/westside-ai-assistant
• [x] User Story -- well-formed (As Lucas / I want logging / So that I can analyze)
• [x] Context -- thorough, includes CNPG cluster decision and NetworkPolicy mention
• [x] File Targets -- 2 new files, 3 modified files, 3 exclusions
• [x] Acceptance Criteria -- 5 items
• [x] Test Expectations -- 3 unit tests + run command
• [x] Constraints -- asyncpg, fire-and-forget, CNPG, NetworkPolicy
• [x] Checklist -- standard 3-item
• [x] Related -- project-westside-ai-assistant referenced

Traceability

• [x] story:read-ops label -- "Admin Read Operations via GroupMe" (key: read-ops in project-westside-ai-assistant user-stories table)
• [x] story note verified -- found in project-westside-ai-assistant user-stories section
• [x] arch:A2 label -- AI Engine component
• [x] arch note verified -- A2 (AI Engine) documented in arch-domain-westside-ai-assistant and arch-dataflow-westside-ai-assistant notes
• [x] Forgejo issue -- forgejo_admin/westside-ai-assistant#19, state: open

File Targets

• [x] app/ai.py -- verified: exists, contains process_message(). Anthropic SDK response has usage.input_tokens / usage.output_tokens.
• [x] app/config.py -- verified: exists, Settings(BaseSettings) class. Adding database_url is straightforward.
• [x] requirements.txt -- verified: exists with fastapi, uvicorn, httpx, anthropic, pydantic-settings, pytest. No asyncpg present.
• [x] app/logging_db.py -- new file. Parent app/ exists.
• [ ] migrations/001_interaction_log.sql -- ISSUE: migrations/ directory does not exist. Ticket should note directory creation needed.
• [x] Exclusions: app/basketball.py, app/groupme.py, app/confirmation.py -- all verified to exist.

Repo Placement

App code is correctly scoped to forgejo_admin/westside-ai-assistant. However, the Constraints section references infra work belonging to other repos (CNPG DB creation, NetworkPolicy, k8s secret) with no corresponding issues filed.

Dependencies

• [ ] Infra: Postgres database creation -- new DB needed in CNPG pal-e-postgres cluster. No ticket exists. UNRESOLVED.
• [ ] Infra: NetworkPolicy -- westside-ai-assistant namespace needs egress to postgres namespace. Issue #3 (closed) covered basketball-api access only. No ticket for postgres access. UNRESOLVED.
• [ ] Infra: K8s secret -- DATABASE_URL must be wired as k8s secret in pal-e-deployments kustomize overlay. No ticket exists. UNRESOLVED.
• [x] Board item #683 (Repo restructure) -- also in backlog, also touches app/ai.py. Ordering conflict if worked in parallel. Documented awareness sufficient.
• [x] Board item #685 (Read-only lockdown) -- also in backlog, also touches app/ai.py. Same ordering concern. Documented awareness sufficient.

Acceptance Criteria

All 5 AC items are verifiable by an agent via unit tests and file inspection. No missing criteria. AC5 (query logs SQL) is a demonstration query rather than a test command, which is acceptable.

Blast Radius

• app/ai.py is the core engine. Changes are minimal (single await log_interaction() wrapped in try/except). Fire-and-forget constraint is correct.
• No sibling services share this pattern -- only GroupMe bot in the platform.
• Token counting across multiple Anthropic calls in the tool_use loop needs clarification in the ticket (current code makes multiple messages.create() calls during tool loops; total tokens should be summed).

Decomposition Assessment

5 file targets (2 new, 3 modified) in 1 repo. 5 AC. Estimated agent time: ~3-4 minutes. Passes the three-thing limit (3 discrete changes: new logging module, migration SQL, wire into ai.py). Passes the five-minute rule. No independent subtasks that need parallelization.

The infra work (DB creation + NetworkPolicy + k8s secret) is a separate concern that MUST be a separate ticket. The app ticket itself does not need decomposition.

Recommendation

All 4 recommendations from the prior review remain open:

1. [SCOPE] Create a separate Forgejo issue for infra prerequisites: (1) create interaction_log database in CNPG pal-e-postgres cluster, (2) NetworkPolicy update for westside-ai-assistant to reach postgres namespace, (3) k8s secret with DATABASE_URL wired in pal-e-deployments kustomize overlay. This ticket blocks #19. File on appropriate repo (pal-e-services or pal-e-platform).
2. [BODY] Add note in File Targets that migrations/ directory must be created (does not exist yet).
3. [BODY] Clarify in Constraints that token counts must be summed across all Anthropic API calls within a single process_message() invocation (tool_use loop makes multiple calls).
4. [BODY] Add explicit dependency: "Blocked by: infra ticket for Postgres access (DB + NetworkPolicy + k8s secret)" in Constraints section.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — Feature
• [x] Lineage — Standalone
• [x] Repo — forgejo_admin/westside-ai-assistant
• [x] User Story — present, well-formed (As Lucas / I want logging / So that I can analyze)
• [x] Context — thorough, includes CNPG cluster decision and NetworkPolicy mention
• [x] File Targets — 2 new files, 3 modified files, 3 exclusions listed
• [x] Acceptance Criteria — 5 items
• [x] Test Expectations — 3 unit tests + run command
• [x] Constraints — asyncpg, fire-and-forget, token counting, CNPG cluster, NetworkPolicy
• [x] Checklist — standard 3-item
• [x] Related — project-westside-ai-assistant referenced

Traceability

• [x] story:read-ops label — "Admin Read Operations via GroupMe" (key: read-ops in project-westside-ai-assistant user-stories table)
• [x] story note verified — found in project-westside-ai-assistant user-stories section
• [x] arch:A2 label — AI Engine component
• [x] arch note verified — A2 (AI Engine) documented in arch-domain-westside-ai-assistant and arch-dataflow-westside-ai-assistant notes. No standalone arch-A2 note, but the component is covered in the existing architecture notes, which is acceptable for this project's convention.
• [x] Forgejo issue — forgejo_admin/westside-ai-assistant#19, state: open

File Targets

• [x] app/ai.py — verified: exists, contains process_message() function. Logging call should go after Anthropic API response processing. The response object has usage.input_tokens / usage.output_tokens available from the Anthropic SDK.
• [x] app/config.py — verified: exists, contains Settings(BaseSettings) class. Adding database_url: str = "" is straightforward.
• [x] requirements.txt — verified: exists, current deps include fastapi, uvicorn, httpx, anthropic, pydantic-settings, pytest.
• [x] app/logging_db.py — new file to create. Parent directory app/ exists.
• [ ] migrations/001_interaction_log.sql — ISSUE: migrations/ directory does not exist. Agent will need to create the directory. This is fine for a new file target, but the ticket should note the directory must be created.
• [x] Exclusions: app/basketball.py, app/groupme.py, app/confirmation.py — all verified to exist. Good boundary definition.

Repo Placement

OK — issue filed on forgejo_admin/westside-ai-assistant, all app-level file targets are in that repo. However, the Constraints section mentions two pieces of infra work that belong in OTHER repos:

• Create new DB in CNPG cluster (pal-e-postgres) — this is a pal-e-services or pal-e-platform concern (kubectl exec / terraform)
• NetworkPolicy update for westside-ai-assistant → postgres namespace — this is a pal-e-platform concern

These infra prerequisites are mentioned in Constraints but have no corresponding Forgejo issues. The app code will fail to connect until these are done. This is the primary scoping gap.

Dependencies

• Infra: Postgres database creation — new database must be created in CNPG pal-e-postgres cluster before the app can connect. No ticket exists for this.
• Infra: NetworkPolicy — westside-ai-assistant namespace needs egress to postgres namespace. Issue #3 (closed) covered the original NetworkPolicy for basketball-api access, not postgres. No ticket exists for postgres access.
• Infra: K8s secret — DATABASE_URL must be wired as a k8s secret and mounted in the deployment. No ticket exists — would need a pal-e-deployments kustomize overlay update.
• Board item #683 (Repo restructure: Nemo agent + modular tool registry) — also in backlog, also touches app/ai.py. These two tickets will conflict if worked in parallel. Not a blocker but ordering matters.
• Board item #685 (Read-only lockdown) — also in backlog, also touches app/ai.py. Same ordering concern.

Acceptance Criteria

• [x] AC1 (table created via migration SQL) — verifiable: agent can check file exists with correct DDL
• [x] AC2 (every message logged with all fields) — verifiable: unit test can mock asyncpg and assert fields
• [x] AC3 (logging failure doesn't crash bot) — verifiable: unit test can raise in mock and assert no propagation
• [x] AC4 (DATABASE_URL configurable) — verifiable: check Settings class has the field
• [x] AC5 (query logs SQL) — verifiable only in integration, not unit test. The SQL in the AC is a demonstration query, not a test command. Acceptable as a "this should work" criterion.

All AC items are testable by an agent. No missing criteria detected.

Blast Radius

• app/ai.py is the core engine (~350 lines). Changes must be minimal — a single await log_interaction(...) call wrapped in try/except after response processing. The fire-and-forget constraint is correct.
• No sibling services share this pattern — this is the only GroupMe bot in the platform.
• The Anthropic SDK's synchronous messages.create() is used (not async). The logging call is async (asyncpg). This means process_message() is already async, so await log_interaction() works naturally.
• Token counting: The current code does not capture the response.usage object. The agent will need to extract it from the Anthropic response. This is straightforward but the ticket could be more explicit about where in the tool loop to capture tokens (multiple Anthropic calls happen in the tool_use loop).

Decomposition

5 file targets (2 new, 3 modified) in 1 repo. 5 AC. Estimated agent time: ~3-4 minutes. The app-level work fits in a single agent pass.

However, the infra work (DB creation + NetworkPolicy + k8s secret) is a separate concern that MUST be a separate ticket (or tickets). The app ticket should be scoped to app code only, with a documented dependency on the infra ticket(s).

No decomposition of the app ticket itself is needed.

Recommendations

• [SCOPE] Create a separate Forgejo issue for infra prerequisites: (1) create interaction_log database in CNPG pal-e-postgres cluster, (2) NetworkPolicy update for westside-ai-assistant → postgres namespace, (3) k8s secret with DATABASE_URL wired in pal-e-deployments kustomize overlay. This ticket blocks #19.
• [BODY] Add note in File Targets that migrations/ directory must be created (does not exist yet).
• [BODY] Add note in Constraints or Context clarifying where in the tool_use loop to capture token counts — the current code makes multiple Anthropic API calls during tool loops, so total tokens should be summed across all calls in a single process_message() invocation.
• [BODY] Add explicit dependency reference: "Blocked by: infra ticket for Postgres access (DB + NetworkPolicy + k8s secret)" in Constraints section.

Verdict: READY

Round 3 re-review of board item #593. Previous reviews: review-593-2026-03-28 (v1, NEEDS_REFINEMENT, 5 findings), review-593-2026-03-28-v2 (v2, NEEDS_REFINEMENT, 2 findings). Both v2 findings have been addressed in the current issue body.

V2 Findings Resolution

• [x] Finding 1 (image_repo naming): AC1 now says image_repo: "westside-ai-assistant/api" (was /app). Constraints section explicitly documents the convention: "image_repo uses /api suffix (FastAPI convention), NOT /app (SvelteKit convention)."
• [x] Finding 2 (valid_redirect_uris): AC2 now specifies valid_redirect_uris: []. Context section explains why: "The valid_redirect_uris field is required by the variable type but a service-account-only client needs an empty list []."

Template Completeness

• [x] Type — Feature
• [x] Lineage — Standalone, with merge-order dependency on #2 documented
• [x] Repo — forgejo_admin/pal-e-services
• [x] User Story — Marcus as admin, infra provisioning
• [x] Context — includes keycloak variable type + resource extension rationale, valid_redirect_uris empty-list requirement
• [x] File Targets — 3 should-modify, 3 should-not-touch, all verified
• [x] Acceptance Criteria — 6 criteria, all testable
• [x] Test Expectations — tofu validate + plan command with -lock=false
• [x] Constraints — backward-compatibility, no-apply guard, image_repo naming convention
• [x] Checklist — present
• [x] Related — present

Traceability

• [x] story:read-ops — Admin Read Operations via GroupMe
• [x] story:write-ops — Admin Write Operations via GroupMe
• [x] arch:A4 — Deployment architecture component
• [x] Forgejo issue — forgejo_admin/westside-ai-assistant#1, open

File Targets

• [x] terraform/k3s.tfvars — verified: file exists (178 lines). services map at line 104, keycloak_clients map at line 40. basketball-api reference pattern at line 113-120 matches proposed entry structure. All FastAPI services (port 8000) use /api suffix: basketball-api/api, pal-e-docs/api, mcd-tracker/api, pal-e-mail/api.
• [x] terraform/variables.tf — verified: file exists (139 lines). keycloak_clients type at lines 102-125. No service_accounts_enabled or service_account_realm_roles fields present. valid_redirect_uris = list(string) at line 112 is required (no default). Extension scope is accurate.
• [x] terraform/keycloak.tf — verified: file exists (138 lines). keycloak_openid_client resource at lines 91-118 does not set service_accounts_enabled. No keycloak_openid_client_service_account_realm_role resource exists. Provider is mrparkers/keycloak ~5.0, which supports both.
• [x] terraform/services.tf (should NOT touch) — verified: exists
• [x] terraform/main.tf (should NOT touch) — verified: exists
• [x] terraform/cnpg.tf (should NOT touch) — verified: exists

Repo Placement

Correct. Issue filed on westside-ai-assistant repo, work targets forgejo_admin/pal-e-services. Single-repo change. PR goes to pal-e-services, documented in Constraints.

Dependencies

• [x] Issue #2 (kustomize overlay) — board item #594, todo column. Merge-order dependency documented in Lineage: "#2 must also merge before ArgoCD can sync, but the two PRs are to different repos and can be developed in parallel." Correct — no build-time dependency, only deploy-time.
• [x] Issue #3 (NetworkPolicy) — board item #595, todo column. Post-deploy dependency, not blocking this ticket.

Acceptance Criteria

• [x] AC1: services entry — complete. Specifies forgejo_repo, image_repo (correctly /api), port 8000, funnel: true, source_repo, source_path. Matches existing basketball-api pattern.
• [x] AC2: keycloak_clients entry — complete. Specifies confidential, service_accounts_enabled: true, service_account_realm_roles: ["admin"], direct access grants enabled, valid_redirect_uris: []. The empty-list for redirect URIs is explicitly called out in Context.
• [x] AC3: variables.tf type extension — clear. Optional fields with backward-compatible defaults.
• [x] AC4: keycloak.tf resource update — clear. Single attribute addition.
• [x] AC5: new service_account_realm_role resource — clear. Conditionally applied when roles list is non-empty.
• [x] AC6: tofu plan verification — testable. Run command provided in Test Expectations.

All 6 criteria are agent-verifiable. Test command is real and includes -lock=false per convention.

Blast Radius

Low. The services entry uses existing for_each — no structural change. The keycloak_clients variable type extension adds two optional fields with safe defaults (false, []). Verified: no existing client sets service_accounts_enabled or service_account_realm_roles. Existing clients are unaffected. The new keycloak_openid_client_service_account_realm_role resource is conditionally created only when roles are non-empty, so it triggers for westside-ai-bot only.

Decomposition Assessment

3 files in 1 repo, 6 AC. The 6 AC technically touches the >5 threshold, but these are tightly coupled changes to a single variable type + resource + tfvars entry. Splitting would create artificial dependencies. Estimated agent time: <5 minutes. No decomposition needed.

Recommendation

No action needed. All previous findings have been addressed. Scope is solid, file targets verified, traceability complete, acceptance criteria testable, blast radius low. This ticket is ready for dispatch.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — Feature
• [x] Lineage — discovered during review-595-2026-03-28
• [x] Repo — forgejo_admin/pal-e-platform (but WRONG — see Repo Placement)
• [x] User Story — clear who/what/why
• [x] Context — sufficient background
• [x] File Targets — specific path given (but WRONG target — see File Targets)
• [x] Acceptance Criteria — 4 testable criteria
• [x] Test Expectations — commands provided (but wrong tool — tofu vs kustomize)
• [x] Constraints — present
• [x] Checklist — present
• [x] Related — links to parent project and target repo

All template sections present. Content accuracy is the problem, not structure.

Traceability

• [x] story:safety — security posture for basketball-api namespace
• [x] arch:A4 — infrastructure/platform component
• [x] Forgejo issue — forgejo_admin/westside-ai-assistant#9, open

Traceability triangle is complete.

File Targets

• [ ] terraform/network-policies.tf — ISSUE: Wrong layer. This file manages NetworkPolicies for platform namespaces only (monitoring, forgejo, woodpecker, harbor, minio, keycloak, postgres, ollama, cnpg-system). All reference module.*.namespace outputs from terraform modules. basketball-api is an application namespace managed by pal-e-deployments via kustomize/ArgoCD — it has no terraform module in pal-e-platform.

Correct file targets should be in pal-e-deployments:

• bases/standard/kustomization.yaml — uncomment networkpolicy.yaml resource (line 8)
• overlays/basketball-api/prod/kustomization.yaml — uncomment NetworkPolicy patch (lines 54-72) and add westside-ai-assistant namespace to allowlist

Repo Placement

MISMATCH. The issue targets forgejo_admin/pal-e-platform but the correct repo is forgejo_admin/pal-e-deployments. Evidence:

• pal-e-deployments/bases/standard/networkpolicy.yaml — a standard NetworkPolicy base already exists (default-deny ingress, allows tailscale + monitoring)
• pal-e-deployments/overlays/basketball-api/prod/kustomization.yaml lines 54-72 — a commented-out NetworkPolicy overlay patch already exists for basketball-api, including a westsidekingsandqueens allowlist entry
• pal-e-deployments/bases/standard/kustomization.yaml lines 7-8 — the networkpolicy.yaml resource is commented out globally: "TEMPORARY: disabled due to kube-router ipset bug (Forgejo #24)"
• ALL 8 application overlays (basketball-api, pal-e-docs, pal-e-app, westsidekingsandqueens, mcd-tracker, mcd-tracker-app, platform-validation, gcal-scheduler) have their NetworkPolicy patches commented out for the same reason

Dependencies

• [ ] kube-router ipset bug (Forgejo #24) — BLOCKER. ALL application NetworkPolicies are disabled due to this bug. This ticket cannot proceed until #24 is resolved. The fix already exists in pal-e-deployments but is commented out.
• [x] Board item #595 (NetworkPolicy update in pal-e-platform, issue #3) — related but separate. That ticket correctly targets only the keycloak NetworkPolicy allowlist in pal-e-platform. Issue #3 explicitly notes: "Do NOT create a basketball-api NetworkPolicy (that's separate discovered scope)."

Acceptance Criteria

Criteria are reasonable in intent but wrong in implementation details:

• "basketball-api namespace has default-deny ingress NetworkPolicy" — correct goal, wrong location
• "Allowlist includes: westsidekingsandqueens, westside-ai-assistant, monitoring, tailscale" — tailscale and monitoring are already in the base template. The overlay only needs to ADD westsidekingsandqueens and westside-ai-assistant.
• "tofu plan -lock=false shows only basketball-api NetworkPolicy addition" — wrong tool. Should be kustomize build overlays/basketball-api/prod validation
• "Existing services (westside-app) still reach basketball-api after apply" — good criterion but untestable until kube-router bug is fixed

AC are not testable in their current form because they assume the wrong tool and location.

Blast Radius

• If the kube-router ipset bug is fixed, uncommenting bases/standard/kustomization.yaml would enable NetworkPolicies for ALL 8 application namespaces, not just basketball-api. This is a platform-wide change.
• Enabling just basketball-api while others remain open would require a per-overlay approach (uncomment only basketball-api overlay patches while keeping the base commented out), which is inconsistent.
• Rollback is straightforward: re-comment the lines or revert the commit.

Decomposition Assessment

If re-scoped correctly (pal-e-deployments, uncomment existing code), this is a small change — 1-2 files, ~15 lines uncommented, plus adding westside-ai-assistant to the allowlist. Fits within the five-minute rule. No decomposition needed for basketball-api alone.

However, the kube-router blocker and the platform-wide implications suggest this should be part of a larger "enable all application NetworkPolicies" effort after Forgejo #24 is resolved. That larger effort would need decomposition (8 overlays, each needing their own allowlists reviewed).

• Discrete changes: 2 (uncomment base + uncomment/update overlay) — under three-thing limit
• Agent time: <5 minutes if kube-router bug is resolved — fits five-minute rule
• No independent subtasks to parallelize

Recommendation

1. [BODY] Change target repo from forgejo_admin/pal-e-platform to forgejo_admin/pal-e-deployments
2. [BODY] Replace file target terraform/network-policies.tf with: (1) bases/standard/kustomization.yaml — uncomment networkpolicy.yaml resource, (2) overlays/basketball-api/prod/kustomization.yaml — uncomment NetworkPolicy patch and add westside-ai-assistant namespace to allowlist
3. [BODY] Replace test expectations: tofu commands should be kustomize build overlays/basketball-api/prod plus kubectl diff validation
4. [SCOPE] Kube-router ipset bug (Forgejo #24) is a blocker. This ticket is not actionable until that bug is resolved. Should this ticket be deferred, or should resolving the kube-router bug be scoped first?
5. [SCOPE] Enabling basketball-api NetworkPolicy alone while 7 other apps remain open is inconsistent. Should this be re-scoped as "enable all application NetworkPolicies" after the kube-router fix, or is per-app enablement acceptable?

Verdict: READY

Template Completeness

• [x] Type — Feature
• [x] Lineage — Depends on #6, split per review-598-2026-03-28
• [x] Repo — forgejo_admin/westside-ai-assistant
• [x] User Story — As Marcus (admin), confirmation before write execution
• [x] Context — explains split from #6, describes confirmation UX flow
• [x] File Targets — 2 create, 1 modify, 3 do-not-touch
• [x] Acceptance Criteria — 5 criteria covering happy/sad/timeout/replacement paths
• [x] Test Expectations — 5 unit tests + run command
• [x] Constraints — message formats, case-insensitive matching, no background timer
• [x] Checklist — standard 3-item
• [x] Related — project page, write-ops story, safety story

Traceability

• [x] story:write-ops — Marcus can update player info via GroupMe with confirmation before writes
• [x] story:safety — Write operations require confirmation, dangerous ops excluded
• [x] arch:A2 — AI engine component (confirmation is an AI engine sub-module)
• [x] Forgejo issue — forgejo_admin/westside-ai-assistant#8, open

File Targets

• [x] app/confirmation.py (create) — does not exist yet, correct for new file. Functions well-specified: store_pending, check_pending, expire_stale, 5-min TTL, dict keyed by group_id.
• [x] tests/test_confirmation.py (create) — does not exist yet, correct for new file.
• [x] app/ai.py (modify) — does not exist yet but will be created by upstream dependency #6. Modification scope is well-defined: wire confirmation into process_message() flow.
• [x] app/basketball.py (do-not-touch) — consumed as-is, correct.
• [x] app/groupme.py (do-not-touch) — already wired in #6, correct.
• [x] app/config.py (do-not-touch) — no new config needed, correct.

Repo Placement

OK. Issue filed on westside-ai-assistant, all file targets are within westside-ai-assistant. No cross-repo concerns. Single-repo ticket, single-repo work.

Dependencies

• [x] #6 (AI engine core) — HARD dependency, pending. Creates app/ai.py which this ticket modifies. #6 explicitly leaves a "confirmation needed" indicator for writes that this ticket consumes. Clean handoff interface documented in both issues.
• [x] #4 (scaffold) and #5 (basketball client) — transitive dependencies via #6. Not direct concerns for this ticket.

Dependency chain is fully documented in Lineage. This ticket cannot move to next_up until #6 is done.

Acceptance Criteria

All 5 criteria are agent-verifiable via unit tests:

• [x] Write request triggers confirmation prompt (not execution) — testable via mock Anthropic response
• [x] "yes" reply executes pending action — testable via mock basketball client
• [x] Non-"yes" reply cancels — testable via state inspection
• [x] 5-minute expiry — testable with time mocking (freeze_time or similar)
• [x] One pending per group (replacement) — testable via sequential state operations

Test command is real: pytest tests/test_confirmation.py -v. All criteria map to specific test expectations. No ambiguous "works correctly" language.

Blast Radius

Low. Confirmation logic is self-contained in a new module (app/confirmation.py). The only integration point is app/ai.py process_message() flow. basketball-api is consumed read-only — no changes needed there. GroupMe posting is already handled by #6. No similar confirmation state machine patterns exist in sibling services. Rollback is straightforward: revert the PR, writes go back to unconfirmed (which #6 already handles by not executing them).

Decomposition Assessment

Three-thing limit: 3 file targets (2 create + 1 modify), all in 1 repo. Passes.

Five-minute rule: Estimated agent time ~3-4 minutes. The state machine is a simple in-memory dict with 3 functions (store_pending, check_pending, expire_stale) plus TTL logic. The ai.py integration is a well-defined if/else branch in process_message(). Passes.

5 acceptance criteria (borderline on the >5 threshold but all are tightly related to one behavioral flow — confirmation lifecycle). No independent subtasks that would benefit from parallelization.

No decomposition needed.

Recommendation

No action needed.

Verdict: NEEDS_REFINEMENT

Re-review of board item #593 after refinement. Previous review: review-593-2026-03-28 (5 findings, all addressed). This re-review found 2 new issues.

Previous Findings Resolution

• [x] Finding 1: Add file target terraform/variables.tf — ADDRESSED. Now listed in File Targets with correct scope (extend keycloak_clients type).
• [x] Finding 2: Add file target terraform/keycloak.tf — ADDRESSED. Now listed with correct scope (service_accounts_enabled + new role resource).
• [x] Finding 3: Fix AC1 missing forgejo_repo and image_repo — ADDRESSED. Both fields now in AC1.
• [x] Finding 4: Add dependency note to Constraints — ADDRESSED. Lineage section now documents #2 merge ordering.
• [x] Finding 5: Clarify "should NOT touch" re: variables.tf/keycloak.tf — ADDRESSED. Those files removed from should-not-touch, correctly listed in should-modify.

Template Completeness

• [x] Type — Feature
• [x] Lineage — Standalone, with merge-order dependency on #2 documented
• [x] Repo — forgejo_admin/pal-e-services
• [x] User Story — Marcus as admin, infra provisioning
• [x] Context — includes explanation that keycloak variable type + resource need extension
• [x] File Targets — 3 should-modify, 3 should-not-touch, all correct
• [x] Acceptance Criteria — 6 criteria listed
• [x] Test Expectations — tofu validate + plan command with -lock=false
• [x] Constraints — includes backward-compatibility requirement and no-apply guard
• [x] Checklist — present
• [x] Related — present

Traceability

• [x] story:read-ops — Admin Read Operations via GroupMe
• [x] story:write-ops — Admin Write Operations via GroupMe
• [x] arch:A4 — Deployment architecture component
• [x] Forgejo issue — forgejo_admin/westside-ai-assistant#1, open

File Targets

• [x] terraform/k3s.tfvars — verified: file exists, contains services map (line 104) and keycloak_clients map (line 40). basketball-api reference pattern confirmed. All existing FastAPI services (port 8000) use /api suffix in image_repo.
• [x] terraform/variables.tf — verified: file exists. keycloak_clients type at line 102-125 has no service_accounts_enabled or service_account_realm_roles. Extension is needed as described. Note: valid_redirect_uris = list(string) at line 112 is REQUIRED (no default).
• [x] terraform/keycloak.tf — verified: file exists. keycloak_openid_client resource at line 91-118 does not set service_accounts_enabled. No keycloak_openid_client_service_account_realm_role resource exists. Keycloak provider is mrparkers/keycloak, which does support this resource.

Repo Placement

Correct. Issue filed on westside-ai-assistant, work targets forgejo_admin/pal-e-services. Single-repo change.

Dependencies

• [x] Issue #2 (kustomize overlay) — board item #594, backlog. Merge-order dependency documented in Lineage: "#2 must also merge before ArgoCD can sync, but the two PRs are to different repos and can be developed in parallel."
• [x] Issue #3 (NetworkPolicy) — board item #595, backlog. Post-deploy dependency, not blocking.

Acceptance Criteria

• [ ] AC1: services entry — image_repo naming mismatch. Issue says image_repo: "westside-ai-assistant/app" but the established pattern for FastAPI services (port 8000) is /api: basketball-api/api, pal-e-docs/api, mcd-tracker/api, pal-e-mail/api. SvelteKit frontends (port 80) use /app. This is a FastAPI service, so it should be "westside-ai-assistant/api".
• [ ] AC2: keycloak_clients entry — missing valid_redirect_uris. The keycloak_clients variable type requires valid_redirect_uris = list(string) with no default. A service-account-only client doesn't use browser redirects, but the agent must provide a value. The AC should specify valid_redirect_uris: [] (or make the variable optional). Without this, the agent will either guess or hit a validation error.
• [x] AC3: variables.tf type extended — clear, specifies exact field names and defaults.
• [x] AC4: keycloak.tf resource includes service_accounts_enabled — clear.
• [x] AC5: new service_account_realm_role resource — clear, conditionally applied.
• [x] AC6: tofu plan shows expected resources — testable.

Blast Radius

Low for the services entry — existing for_each handles new entries. Medium for keycloak changes — extending the variable type and resource affects all existing clients. The issue's Constraints section correctly requires backward-compatibility via optional() with safe defaults. Verified: no existing client uses service_accounts_enabled, so new optional fields with false/[] defaults are safe. Rollback: revert the tfvars entry.

Decomposition Assessment

3 files in 1 repo, 6 AC. The 6 AC technically exceeds the >5 threshold, but these are tightly coupled changes to a single variable type + resource + tfvars entry. Splitting would create artificial dependencies (can't extend variable type without extending resource and providing values). Estimated agent time: <5 minutes. No decomposition needed.

Recommendation

1. [BODY] Fix AC1: change image_repo: "westside-ai-assistant/app" to image_repo: "westside-ai-assistant/api" — follows established convention that FastAPI services (port 8000) use /api suffix.
2. [BODY] Fix AC2: add valid_redirect_uris: [] to the westside-ai-bot keycloak_clients entry, OR add a note that valid_redirect_uris should be made optional(list(string), []) in the variable type extension. The agent needs an explicit directive since this is a required field.

Verdict: READY

Re-review of board item #594 after refinement. Previous review: review-594-2026-03-28 (NEEDS_REFINEMENT, 4 findings). All 4 findings have been addressed in the updated issue body.

Previous Findings Resolution

• [x] Finding 1 (dependency on #1): Lineage section now explicitly states "#1 (pal-e-services infra) creates the namespace and Harbor project. Both PRs can be developed in parallel but #1 must be applied first for ArgoCD sync and CI dry-run validation."
• [x] Finding 2 (Harbor image URL): File Targets uses harbor.tail5b443a.ts.net/westside-ai-assistant/app. New AC7 added. Constraints section explicitly says "NOT internal URL."
• [x] Finding 3 (secret injection pattern): Context, AC5, and Constraints all now specify individual env[].valueFrom.secretKeyRef (matching basketball-api pattern). Explicitly says "NOT envFrom secretRef."
• [x] Finding 4 (PR placement instruction): Constraints section now says "PR goes to pal-e-deployments repo, not westside-ai-assistant."

Template Completeness

• [x] Type — Feature
• [x] Lineage — Standalone with dependency note on #1
• [x] Repo — forgejo_admin/pal-e-deployments
• [x] User Story — Marcus (admin) wants kustomize overlay so ArgoCD can deploy
• [x] Context — Pattern reference, secret injection convention, basketball-api model
• [x] File Targets — 3 files to create, exclusion list present
• [x] Acceptance Criteria — 7 criteria (expanded from 6, added Harbor URL check)
• [x] Test Expectations — kustomize render command provided
• [x] Constraints — 5 constraints including explicit anti-patterns
• [x] Checklist — PR opened, kustomize renders, no unrelated changes
• [x] Related — project page + convention reference

All required Feature template sections present and filled.

Traceability

• [x] story:read-ops — present on board item
• [x] story:write-ops — present on board item
• [x] arch:A4 — present on board item (infrastructure/deployment component)
• [x] Forgejo issue — forgejo_admin/westside-ai-assistant#2, open

File Targets

• [x] overlays/westside-ai-assistant/prod/kustomization.yaml — NEW file. Parent directory does not exist yet (expected). Reference pattern overlays/basketball-api/prod/kustomization.yaml verified: exists, contains base ref, JSON6902 rename patches, images transformer with harbor.tail5b443a.ts.net URL.
• [x] overlays/westside-ai-assistant/prod/deployment-patch.yaml — NEW file. Reference overlays/basketball-api/prod/deployment-patch.yaml verified: uses individual env[].valueFrom.secretKeyRef entries (not envFrom). Issue correctly specifies 5 plain env vars and 3 secretKeyRef entries from westside-ai-assistant-secrets.
• [x] overlays/westside-ai-assistant/prod/harbor-creds.enc.yaml — NEW file. Reference overlays/basketball-api/prod/harbor-creds.enc.yaml verified: SOPS-encrypted with age key.
• [x] bases/standard/* — exclusion verified. Standard base contains deployment.yaml (name: app, port 8000, /healthz probes), service.yaml (name: app, port 8000), kustomization.yaml. No changes needed.

Repo Placement

Cross-repo placement is documented and acceptable. Issue lives on forgejo_admin/westside-ai-assistant (project tracking), work targets forgejo_admin/pal-e-deployments. Issue body declares ### Repo: forgejo_admin/pal-e-deployments. Constraints section explicitly instructs PR placement. Single-repo change — no additional Forgejo issues needed.

Dependencies

• [x] Board item #593 (Provision infrastructure in pal-e-services) — now documented in Lineage section. Parallel development is possible, #1 must apply first for ArgoCD sync. CI server-side dry-run runs against default namespace context so may pass without the target namespace existing, but conservative documentation is correct.
• [x] Board item #595 (NetworkPolicy update) — independent, not a blocker.
• [x] SOPS age key — required for harbor-creds.enc.yaml encryption. Agent environment must have access. Not a blocker since SOPS key is available on the host.

Acceptance Criteria

7 criteria evaluated — all testable:

• [x] AC1: kustomize render — command provided, verifiable
• [x] AC2: Deployment named westside-ai-assistant with port 8000 — inspect rendered YAML
• [x] AC3: Service named westside-ai-assistant with port 8000 — inspect rendered YAML
• [x] AC4: Plain env vars for 5 config values — specific var names listed, verifiable
• [x] AC5: Secrets via individual secretKeyRef from westside-ai-assistant-secrets — pattern now matches basketball-api convention exactly
• [x] AC6: harbor-creds.enc.yaml is SOPS-encrypted — check for ENC[] markers
• [x] AC7: Image uses external Harbor URL — verifiable in rendered YAML

Blast Radius

• CI pipeline scope: Woodpecker CI iterates all overlays/*/prod/ directories. Malformed overlay would fail entire validation and block all pal-e-deployments PRs. Risk is low — agent follows verified reference pattern.
• No downstream consumers: No existing services reference westside-ai-assistant. No cross-namespace policies point to it yet (#595).
• No existing references: Grep confirms zero mentions of "westside-ai-assistant" in pal-e-deployments repo.

Decomposition Assessment

• File count: 3 new files in 1 repo — within three-thing limit
• AC count: 7 criteria — but 5 are simple YAML inspection checks, substantive work is 3 templated files
• Estimated agent time: ~3 minutes. Templated copy-adapt from verified basketball-api/prod reference.

No decomposition needed.

Recommendation

No action needed. All 4 previous findings addressed. Ticket is ready for dispatch.

Verdict: READY

Template Completeness

• [x] Type — Feature
• [x] Lineage — Depends on #4 (scaffold) and #5 (basketball client). Fixed from v1 review.
• [x] Repo — forgejo_admin/westside-ai-assistant
• [x] User Story — As Marcus (admin), natural language → basketball-api operations
• [x] Context — Scoped to AI engine core only; explicitly references #8 for confirmation flow
• [x] File Targets — 2 creates, 1 modify, 2 do-not-touch
• [x] Acceptance Criteria — 6 items (down from 9 in original)
• [x] Test Expectations — 4 items + run command (down from 7 in original)
• [x] Constraints — SDK, model config, system prompt rules, GroupMe bot post, 1000-char limit
• [x] Checklist — PR, tests, no unrelated changes
• [x] Related — project page, architecture diagram, read-ops story

Traceability

• [x] story:read-ops — read operations story (primary: read tool dispatch)
• [x] story:write-ops — write operations story (tool definitions with write metadata, gated execution)
• [x] story:safety — safety story (write tools defined but not executed, confirmation indicator returned)
• [x] arch:A2 — AI Engine component in arch-dataflow-westside-ai-assistant
• [x] Forgejo issue — forgejo_admin/westside-ai-assistant#6, state: open

File Targets

• [x] app/ai.py (create) — repo only has README.md on main. Valid: #4 scaffolds app/ directory.
• [x] tests/test_ai.py (create) — valid: tests/ created by #4.
• [x] app/groupme.py (modify) — valid: created by #4, wiring callback + bot post.
• [x] app/basketball.py (do-not-touch) — correct: consumed as dependency from #5.
• [x] app/config.py (do-not-touch) — correct: env vars already defined by #4.

All file targets specific and accurate. No ambiguity for the implementing agent.

Repo Placement

OK. Issue filed on forgejo_admin/westside-ai-assistant. All file targets in same repo. No cross-repo work.

Dependencies

• [x] #4 (FastAPI scaffold) — explicit in Lineage. State: open. Creates app/groupme.py, app/config.py, app/__init__.py, tests/__init__.py. Now documented (was missing in v1).
• [x] #5 (Basketball-API client) — explicit in Lineage. State: open. Creates app/basketball.py consumed by this ticket.
• [x] #8 (Confirmation state machine) — downstream dependent on this ticket. Documented in #8's lineage. No circular dependency.

Execution order: #4 → #5 → #6 → #8. All dependencies documented and correctly ordered.

Acceptance Criteria

6 ACs. Testability assessment:

• AC 1 (read query → tool called → GroupMe post) — testable via mocked Anthropic response + mocked GroupMe POST.
• AC 2 (14 tool definitions, 7 reads + 7 writes, with metadata) — testable via tool definition introspection. Requires #5 complete to verify function counts.
• AC 3 (write tools defined but NOT executed, returns confirmation indicator) — testable: mock a write tool_use, assert basketball function NOT called, assert indicator returned.
• AC 4 (conversation history capped at 20 per group) — testable: clear boundary condition.
• AC 5 (plain text responses, no HTML/markdown) — testable: assert no HTML tags or markdown syntax in output.
• AC 6 (truncate at 1000 chars with "...") — testable: boundary condition at 1000/1001 chars.

All criteria are concrete and individually verifiable by an agent.

Blast Radius

• No other services in the platform use the Anthropic SDK — zero shared-library risk.
• AI engine is self-contained. Only integration surface: basketball-api (consumed read-only via basketball.py from #5).
• GroupMe bot posting is net-new — no existing bot behavior to conflict with.
• Rollback: revert the PR, GroupMe callback falls back to logging-only behavior from #4.

Decomposition

• File targets: 2 creates + 1 modify in 1 repo. Under 3-file-across-2-repos threshold.
• Acceptance criteria: 6 items. Marginally above 5-item threshold, but all are cohesive (single-concern: AI engine core).
• Test expectations: 4 items in 1 test file.
• Discrete changes: 3 (system prompt + tool definitions, process_message with read dispatch + conversation history, GroupMe wiring). At the 3-thing limit.
• Estimated agent time: ~5 minutes. Tool definitions are mechanical (mirror basketball.py functions). System prompt is a single string constant. GroupMe wiring is a small modification.

No decomposition needed. The confirmation state machine — the complex, independently testable concern — has been successfully split to #8. Remaining work is cohesive and fits a single agent pass.

Previous Review Issues — Resolution

• [BODY] Missing #4 dependency — RESOLVED. Lineage now reads: "Depends on forgejo_admin/westside-ai-assistant #4 (scaffold) and #5 (basketball client)."
• [DECOMPOSE] 9 ACs exceeding threshold — RESOLVED. Confirmation flow (ACs 2-5 from original) moved to #8. This ticket now has 6 ACs, 4 test expectations, ~5 min estimated time.

Recommendation

No action needed. Ticket is ready for dispatch.

Verdict: READY

Re-review after refinement. Previous review: review-599-2026-03-28 (NEEDS_REFINEMENT, 3 findings). All findings resolved.

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- Depends on #1, #2, #3 (infra), #4 (scaffold), #5 (basketball client), #6 (AI engine), #8 (confirmation flow)
• [x] Repo -- forgejo_admin/westside-ai-assistant + cluster ops
• [x] User Story -- As Marcus (admin) I want the bot registered and deployed so I can start using the AI assistant
• [x] Context -- Go-live ticket, explains GROUPME_BOT_ID rationale (posting credential, stored as secret)
• [x] File Targets -- None (ops/validation ticket, explicitly excludes application code)
• [x] Acceptance Criteria -- 6 items split into Phase 1 (agent, ACs 1-3) and Phase 2 (human, ACs 4-6)
• [x] Test Expectations -- Phase 1 kubectl verification + Phase 2 manual GroupMe validation with clear handoff
• [x] Constraints -- 5 constraints including GroupMe API details, kubectl-only secrets, group lockdown, tofu approval gate
• [x] Checklist -- 5 items including explicit agent handoff step
• [x] Related -- project-westside-ai-assistant, service-onboarding-sop steps 7-10

All template sections present and complete.

Traceability

• [x] story:read-ops -- Marcus can query player/team/payment data via GroupMe
• [x] story:write-ops -- Marcus can update player info via GroupMe with confirmation
• [x] story:safety -- Write ops require confirmation, bot locked to approved group
• [x] arch:A1 -- Domain Model (GroupMe webhook handler receives callbacks)
• [x] arch:A4 -- Deployment (FastAPI pod, Tailscale funnel, k8s secrets, namespace)
• [x] Forgejo issue -- forgejo_admin/westside-ai-assistant#7, open

Traceability complete. All three triangle legs solid.

File Targets

N/A -- ops/validation ticket with no code changes. Issue explicitly states "Files the agent should NOT touch: Application code." Correct for a go-live ops ticket. Agent acts via external APIs (GroupMe Bot API) and cluster tools (kubectl).

Repo Placement

OK. Issue filed on forgejo_admin/westside-ai-assistant. Work is external API calls + kubectl. No cross-repo code changes. Single-repo placement correct.

Dependencies

• [x] #1 (Provision infrastructure in pal-e-services) -- backlog, documented
• [x] #2 (Create kustomize overlay in pal-e-deployments) -- backlog, documented
• [x] #3 (NetworkPolicy update in pal-e-platform) -- backlog, documented
• [x] #4 (FastAPI scaffold + GroupMe webhook handler) -- backlog, documented. Previously missing, now fixed.
• [x] #5 (Basketball-API client with Keycloak auth) -- backlog, documented. Previously missing, now fixed.
• [x] #6 (AI engine core) -- backlog, documented
• [x] #8 (Confirmation state machine for write operations) -- backlog, documented. New dependency added.
• [x] Lucas tofu apply approval -- external human gate, documented in Constraints

All 7 ticket dependencies + 1 human gate documented. Lineage is complete. Issue #9 (discovered: basketball-api NetworkPolicy) is correctly not listed here -- it is a dependency of #5, not #7.

Acceptance Criteria

6 ACs split into two clearly labeled phases:

• Phase 1 -- Agent-executable (ACs 1-3): Bot registration (specific name, callback URL, group_id), k8s secret creation (3 keys matching arch diagram), pod readiness check. All verifiable by agent via API response and kubectl.
• Phase 2 -- Human validation (ACs 4-6): Read test, write test with confirmation, safety test. Clearly marked as manual. Agent hands off after Phase 1.

Previously missing handoff marker now present. Phase separation is explicit in both AC section and Checklist.

Secret Key Alignment

AC 2 lists 3 keys: ANTHROPIC_API_KEY, GROUPME_BOT_ID, KEYCLOAK_CLIENT_SECRET.
Architecture diagram (arch-deployment-westside-ai-assistant) lists 3 keys: ANTHROPIC_API_KEY, GROUPME_BOT_ID, KEYCLOAK_CLIENT_SECRET.
Match confirmed. Previous mismatch (GROUPME_BOT_TOKEN vs GROUPME_BOT_ID) resolved. Context section explains rationale: "GroupMe bots only have a bot_id -- there is no separate token. The bot_id acts as the posting credential."

Blast Radius

• Files/repos touched: 0 files, 0 repos. External API + kubectl only.
• What could break: Incorrect callback URL = bot deaf. Wrong group_id = wrong group. Missing secret key = crash-loop.
• Rollback: Delete bot via GroupMe API, delete k8s secret, pod stops. No persistent state.
• Sibling impact: None. First GroupMe bot in platform. Namespaced secret. No shared infra modified.

Decomposition

• Discrete agent changes: 3 (register bot, create secret, verify pod). Meets three-thing limit.
• Agent ACs: 3. Under the 5-AC threshold.
• Estimated agent time: ~3 minutes. Within five-minute rule.
• Human ACs: 3 (post-handoff, not agent work).

No decomposition needed.

Previous Findings Resolution

Recommendation

No action needed. All three previous findings resolved. Template complete, traceability solid, dependencies documented, ACs testable with clear agent/human handoff, secret keys aligned with architecture diagram. Ready for dispatch when all 7 dependencies are merged.

Deployment

graph TB
    subgraph external["External Services"]
        GROUPME["GroupMe API<br/>Bot callback POST"]
        ANTHROPIC["Anthropic API<br/>Claude tool_use"]
    end

    subgraph cluster["k3s Cluster"]
        subgraph ns_ai["westside-ai-assistant namespace"]
            POD["FastAPI Pod<br/>port 8000"]
            SECRET["k8s Secrets<br/>ANTHROPIC_API_KEY<br/>GROUPME_BOT_ID<br/>KEYCLOAK_CLIENT_SECRET"]
        end
        subgraph ns_bb["basketball-api namespace"]
            BB_POD["basketball-api Pod<br/>port 8000"]
        end
        subgraph ns_kc["keycloak namespace"]
            KC_POD["Keycloak Pod<br/>westside-basketball realm"]
        end
        FUNNEL["Tailscale Funnel<br/>westside-ai-assistant.tail5b443a.ts.net"]
    end

    GROUPME -->|POST /groupme/callback| FUNNEL
    FUNNEL --> POD
    POD -->|HTTP| ANTHROPIC
    POD -->|HTTP internal| BB_POD
    POD -->|client credentials| KC_POD
    SECRET -.->|envFrom| POD

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — Feature
• [x] Lineage — Standalone, scoped from design spec
• [x] Repo — forgejo_admin/pal-e-services
• [x] User Story — Marcus as admin, infra provisioning
• [x] Context — sufficient background
• [x] File Targets — present with should/should-not-touch
• [x] Acceptance Criteria — 4 criteria listed
• [x] Test Expectations — tofu validate + plan command
• [x] Constraints — present
• [x] Checklist — present
• [x] Related — present

Traceability

• [x] story:read-ops — Admin Read Operations via GroupMe
• [x] story:write-ops — Admin Write Operations via GroupMe
• [x] arch:A4 — Deployment architecture component
• [x] Forgejo issue — forgejo_admin/westside-ai-assistant#1, open

File Targets

• [x] terraform/k3s.tfvars — verified: file exists, contains both services map (line 104) and keycloak_clients map (line 40). basketball-api reference entry confirmed at line 113. westside-app client reference confirmed at line 41.
• [ ] terraform/variables.tf — ISSUE: not listed as a file target, but MUST be modified. The keycloak_clients variable type (line 102-125) has no service_accounts_enabled attribute. Adding a service-account client requires adding this attribute to the variable type object.
• [ ] terraform/keycloak.tf — ISSUE: not listed as a file target, but MUST be modified. The keycloak_openid_client resource (line 91-118) does not set service_accounts_enabled. Additionally, there is no keycloak_openid_client_service_account_role resource anywhere in the codebase — this is needed to map the admin role to the service account.

Repo Placement

Correct. Issue is filed on westside-ai-assistant but specifies work in forgejo_admin/pal-e-services, which is the correct repo for infrastructure provisioning. Single-repo change.

Dependencies

• [ ] Issue #2 (Create kustomize overlay in pal-e-deployments) — board item #594, backlog. The services entry's source_path = "overlays/westside-ai-assistant/prod" does not exist yet in pal-e-deployments. ArgoCD will fail to sync until the overlay is created. Merge order: #1 first, #2 second, apply after both merged. Not documented in issue scope.
• [x] Issue #3 (NetworkPolicy update) — board item #595, backlog. Post-deploy dependency, not blocking for this ticket.

Acceptance Criteria

• [ ] AC1: services entry — testable via tofu plan, but missing required fields. The AC says port: 8000, funnel: true, source_repo, source_path but omits forgejo_repo and image_repo, which are REQUIRED fields per the variable definition in variables.tf (lines 130-131).
• [ ] AC2: "Keycloak client westside-ai-bot is confidential, service account enabled" — NOT achievable with current variable type. The keycloak_clients variable has no service_accounts_enabled attribute. The keycloak_openid_client resource does not set it. Variable + resource must both be extended.
• [ ] AC3: "Client has realm role admin mapped" — NOT achievable with current codebase. No keycloak_openid_client_service_account_role resource exists. A new resource block must be added to keycloak.tf, plus a new variable attribute to drive it (e.g., service_account_realm_roles).
• [x] AC4: tofu plan shows expected resources — testable, but will only show correct resources once AC2/AC3 infrastructure is added.

Blast Radius

Low for the services entry — existing for_each pattern handles new entries automatically. Medium for the keycloak changes — modifying the variable type and resource affects ALL existing keycloak clients. The new attributes must use optional() with safe defaults (false / []) to avoid breaking existing client entries. No other service currently uses service accounts, so this is a net-new capability addition to the platform. Rollback is straightforward: revert the tfvars entry.

Decomposition Assessment

The ticket touches 3 files (k3s.tfvars, variables.tf, keycloak.tf) in 1 repo with 4 AC. Once the file targets and AC are corrected, this is still achievable in a single agent pass (<5 min). The three files are tightly coupled (variable definition, resource usage, variable values) and cannot be parallelized. No decomposition needed.

Recommendation

1. [BODY] Add file target: terraform/variables.tf — add service_accounts_enabled = optional(bool, false) and service_account_realm_roles = optional(list(string), []) to the keycloak_clients variable type object.
2. [BODY] Add file target: terraform/keycloak.tf — add service_accounts_enabled = each.value.service_accounts_enabled to the keycloak_openid_client resource block, and add a new keycloak_openid_client_service_account_realm_role resource for service account role mapping.
3. [BODY] Fix AC1: add forgejo_repo: "forgejo_admin/westside-ai-assistant" and image_repo: "westside-ai-assistant/api" to the expected services entry fields.
4. [BODY] Add dependency note to Constraints section: "Depends on issue #2 (kustomize overlay) before tofu apply. Merge order: #1 first, #2 second, apply after both merged."
5. [BODY] Clarify in File Targets "should NOT touch" section: remove any implication that variables.tf and keycloak.tf are off-limits — they must be modified to support service accounts.

Verdict: READY

Template Completeness

• [x] Type — Feature
• [x] Lineage — Standalone, scoped from westside-ai-assistant design spec (2026-03-28)
• [x] Repo — forgejo_admin/westside-ai-assistant
• [x] User Story — As Marcus (admin) I want the AI service to receive GroupMe messages via webhook callback so that every message I send in the approved group reaches the AI engine
• [x] Context — GroupMe bot callback explanation, scope boundary (no AI logic, just log and 200)
• [x] File Targets — 10 files to create, explicit "don't touch" section (no other repos)
• [x] Acceptance Criteria — 7 testable items
• [x] Test Expectations — 4 unit tests + run command (pytest tests/ -v)
• [x] Constraints — Follow basketball-api Dockerfile pattern, internal Harbor URL, port 8000, no AI logic
• [x] Checklist — PR opened, tests pass, Docker builds, no unrelated changes
• [x] Related — project-westside-ai-assistant + arch-domain-westside-ai-assistant referenced

Traceability

• [x] story:read-ops — Marcus can query player/team/payment data via GroupMe (webhook is the entry point for all read queries)
• [x] story:safety — Bot locked to approved group via GROUPME_ALLOWED_GROUP_IDS allowlist, bot self-ignore via sender_type check
• [x] arch:A1 — GroupMe Webhook Handler per arch-domain-westside-ai-assistant domain model
• [x] Forgejo issue — forgejo_admin/westside-ai-assistant#4, open

File Targets

All 10 files are to be created in a greenfield repo. Verified repo state via Forgejo API — only README.md exists. Parent directories (app/, tests/) will be created by the agent.

• [x] app/__init__.py — empty, standard Python package init
• [x] app/main.py — FastAPI app with lifespan, router includes
• [x] app/groupme.py — POST /groupme/callback with group allowlist + bot self-ignore
• [x] app/health.py — GET /healthz (200) + GET /health/ready (config check)
• [x] app/config.py — pydantic BaseSettings with 8 env vars specified
• [x] Dockerfile — multi-stage python:3.12-slim, gunicorn+uvicorn, EXPOSE 8000
• [x] .woodpecker.yaml — test on push/PR, build+push on main, Harbor URL
• [x] requirements.txt — fastapi, uvicorn, gunicorn, httpx, anthropic, pydantic-settings, pytest, pytest-asyncio
• [x] tests/__init__.py — empty
• [x] tests/test_groupme.py — 4 test cases covering valid, bot-ignore, wrong-group, malformed

Targets are specific enough for an agent to act without guessing. basketball-api Dockerfile pattern verified at ~/basketball-api/Dockerfile — multi-stage with python:3.12-slim base confirmed.

Repo Placement

Correct. Issue filed on forgejo_admin/westside-ai-assistant, all file targets within that repo. No cross-repo scope. "Files the agent should NOT touch: No other repos" is explicitly stated.

Dependencies

• [x] No upstream code dependencies — greenfield scaffold, first code in the repo (satisfied)
• [x] basketball-api Dockerfile pattern — exists at ~/basketball-api/Dockerfile (satisfied, reference only)

Downstream items depend on this ticket:

• #597 (Basketball-API client with Keycloak auth) — needs scaffold
• #598 (Anthropic AI engine) — needs scaffold + client
• #599 (GroupMe bot registration + go-live) — needs deployed app

No unresolved dependencies blocking execution.

Acceptance Criteria

All 7 AC are testable and specific:

• [x] POST /groupme/callback returns 200 and logs — verifiable via pytest TestClient + caplog
• [x] Bot messages ignored (sender_type=="bot") — verifiable via pytest with bot payload
• [x] Non-allowlisted groups ignored — verifiable via pytest with wrong group_id
• [x] GET /healthz returns 200 — verifiable via pytest TestClient
• [x] GET /health/ready returns 200 when config loaded — verifiable via pytest TestClient
• [x] Docker image builds successfully — verifiable via docker build
• [x] All tests pass — verifiable via pytest tests/ -v

No ambiguous language. Each criterion maps directly to a verification command.

Blast Radius

• Touches 1 repo (westside-ai-assistant) with 10 new files, 0 modifications
• groupme-sdk (~/groupme-sdk) is outbound-only — no conflict with this inbound webhook handler
• basketball-api has its own GroupMe integration (outbox service) — completely separate concern
• groupme-mcp is a separate MCP tool service — no overlap
• Rollback: trivial — delete the branch or revert the single PR

No blast radius. Isolated greenfield service with no shared state or cross-service dependencies at this stage.

Decomposition Assessment

Three-thing limit: 10 file targets, but all are boilerplate for a single FastAPI scaffold. The "things" are: (1) app scaffold with config, (2) webhook handler + tests, (3) Dockerfile + CI. Borderline 3 discrete changes.

Five-minute rule: Estimated 3-5 minutes for a skilled agent. Patterns are well-specified (follow basketball-api). All files are boilerplate generation, not complex logic.

7 AC exceeds the >5 threshold, but the AC are all facets of the same feature — they cannot be meaningfully split without creating two PRs that depend on each other. Splitting "handler code" from "Dockerfile + CI" would produce PRs that can't be independently validated.

No independent subtasks that could be parallelized — all files must ship in one PR for the scaffold to be functional.

No decomposition needed.

Recommendation

No action needed. Ticket is ready for agent dispatch.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — Feature
• [x] Lineage — Depends on #5 (basketball client)
• [x] Repo — forgejo_admin/westside-ai-assistant
• [x] User Story — As Marcus (admin), natural language → basketball-api ops
• [x] Context — Detailed: Anthropic tool_use, system prompt, confirmation state machine, GroupMe wiring
• [x] File Targets — 3 creates, 1 modify, 2 do-not-touch
• [x] Acceptance Criteria — 9 items
• [x] Test Expectations — 7 items
• [x] Constraints — SDK, model config, system prompt rules, GroupMe bot post, 1000-char limit
• [x] Checklist — PR, tests, no unrelated changes
• [x] Related — project page, architecture, 3 user stories

Traceability

• [x] story:read-ops — read operations story (tool dispatch for reads)
• [x] story:write-ops — write operations story (tool dispatch for writes)
• [x] story:safety — safety story (confirmation flow prevents destructive ops)
• [x] arch:A2 — AI Engine component in arch-domain-westside-ai-assistant
• [x] Forgejo issue — forgejo_admin/westside-ai-assistant#6, state: open

File Targets

• [x] app/ai.py (create) — does not exist yet; repo only has README.md. Valid target since #4 scaffolds the app/ directory.
• [x] tests/test_ai.py (create) — does not exist yet. Valid, tests/ created by #4.
• [x] tests/test_confirmation.py (create) — does not exist yet. Valid, new file.
• [x] app/groupme.py (modify) — does not exist yet; created by #4. Valid target assuming #4 completes first.
• [x] app/basketball.py (do-not-touch) — created by #5. Correct: consumed as dependency.
• [x] app/config.py (do-not-touch) — created by #4. Correct: env vars already defined there.

All targets are specific enough for an agent to act on without guessing. File targets are accurate pending completion of prerequisite tickets #4 and #5.

Repo Placement

OK. Issue filed on forgejo_admin/westside-ai-assistant, all file targets in same repo. No cross-repo work required.

Dependencies

• [x] #5 (Basketball-API client) — explicit dependency in Lineage. State: open. Creates app/basketball.py consumed by this ticket. Pending.
• [ ] #4 (FastAPI scaffold) — implicit dependency, NOT listed in Lineage. State: open. Creates app/groupme.py, app/config.py, app/__init__.py, tests/__init__.py which this ticket requires. Pending, and undocumented.

Execution order must be: #4 → #5 → #6. Both dependencies are in backlog on board-westside-ai-assistant.

Acceptance Criteria

9 ACs. Testability assessment:

• ACs 1-5 (tool dispatch + confirmation flow) — testable via mocked Anthropic responses and mocked basketball client. Well-specified before/after behavior.
• AC 6 (tool definitions match basketball.py exactly, 7 reads + 7 writes) — testable via introspection against basketball.py functions. Requires #5 complete to verify counts.
• AC 7 (requires_confirmation metadata on write tools) — testable via tool definition inspection.
• AC 8 (conversation history capped at 20 per group) — testable, clear boundary condition.
• AC 9 (GroupMe responses are plain text, concise, no HTML/markdown) — testable for "no HTML/markdown" but "concise" is subjective. Suggest tightening: "responses contain no HTML tags or markdown syntax."

Overall: ACs are well-specified and individually testable. Count of 9 triggers decomposition threshold.

Blast Radius

• Files touched: 3 new + 1 modified in a single repo.
• No other services in the platform use the Anthropic SDK — zero shared-library risk.
• The AI engine is self-contained. Only integration surface is basketball-api (consumed read-only via basketball.py client from #5).
• GroupMe bot posting is new — no existing bot behavior to conflict with.
• Rollback: straightforward — revert the PR, GroupMe callback falls back to logging-only behavior from #4.

Decomposition Assessment

Apply the three-thing limit and five-minute rule:

• Discrete changes: 4 (system prompt + tool defs, confirmation state machine, GroupMe wiring, conversation history). Exceeds 3-thing limit.
• Acceptance criteria: 9 items. Exceeds 5-item threshold.
• Test expectations: 7 items across 2 test files.
• Estimated agent time: 8-12 minutes — system prompt authoring + 14 tool definitions + confirmation state machine + GroupMe wiring + 2 test files with 7+ test cases. Exceeds 5-minute rule.

The ticket covers three concerns that could be parallelized:

1. AI engine core — system prompt, 14 tool definitions, process_message(), conversation history, GroupMe response posting (ACs 1, 6, 7, 8, 9)
2. Confirmation state machine — pending action store, 5-min expiry, yes/no handling (ACs 2, 3, 4, 5)

However, both concerns share app/ai.py — confirmation is integral to process_message(). Clean split: Ticket A builds the engine with read-only dispatch (~5 min), Ticket B adds write confirmation on top (~4 min). Ticket B depends on Ticket A.

Recommend decomposition into 2 sequential tickets.

Recommendation

1. [BODY] Add explicit dependency on #4 in Lineage: "Depends on forgejo_admin/westside-ai-assistant #4 (scaffold) and #5 (basketball client)."
2. [DECOMPOSE] 9 ACs + 7 test expectations exceeds both 5-AC and 5-minute thresholds. Recommend splitting into 2 Forgejo issues:
   • Ticket 6a: AI engine core — system prompt, 14 tool definitions, process_message() with read-only dispatch, conversation history (20-msg cap), GroupMe response posting. ACs: 1, 6, 7, 8, 9. Tests: test_ai.py.
   • Ticket 6b: Confirmation state machine — pending action store, 5-min expiry, "yes" executes / "no" cancels, write tools gated on confirmation. ACs: 2, 3, 4, 5. Tests: test_confirmation.py. Depends on 6a.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- Depends on #1, #2, #3 (infra) and #6 (AI engine)
• [x] Repo -- forgejo_admin/westside-ai-assistant + cluster ops
• [x] User Story -- As Marcus (admin) I want the bot registered and deployed so I can start using the AI assistant
• [x] Context -- Go-live ticket, partially manual, all code/infra must be in place first
• [x] File Targets -- None (ops/validation ticket, explicitly states no code changes)
• [x] Acceptance Criteria -- 6 items covering registration, secrets, pod health, and 3 functional tests
• [x] Test Expectations -- 4 manual items + run command (manual validation in GroupMe test group)
• [x] Constraints -- 4 constraints including GroupMe API, kubectl-only secrets, group lockdown, tofu approval gate
• [x] Checklist -- 4 items (bot registered, secrets deployed, pod running, e2e validation)
• [x] Related -- project-westside-ai-assistant, service-onboarding-sop steps 7-10

All template sections present and filled.

Traceability

• [x] story:read-ops -- Marcus can query player/team/payment data via GroupMe and get accurate answers
• [x] story:write-ops -- Marcus can update player info and manage teams via GroupMe with confirmation before writes
• [x] story:safety -- Write ops require confirmation, dangerous ops excluded, bot locked to approved group
• [x] arch:A1 -- Domain Model (GroupMe webhook handler receives callbacks)
• [x] arch:A4 -- Deployment (FastAPI pod, Tailscale funnel, k8s secrets, namespace)
• [x] Forgejo issue -- forgejo_admin/westside-ai-assistant#7, open

Traceability complete. All three project user stories covered. Two architecture components correctly referenced (A1 for the bot callback endpoint, A4 for deployment/secrets infrastructure).

File Targets

N/A -- ops/validation ticket with no code changes. Issue explicitly states "Files the agent should NOT touch: Application code (should be complete from prior tickets)." This is correct for a go-live ops ticket. No file paths to verify.

Targets are appropriately scoped: the agent acts via external APIs (GroupMe Bot API) and cluster tools (kubectl), not file modifications.

Repo Placement

OK. Issue is filed on forgejo_admin/westside-ai-assistant. Work involves external API calls (GroupMe bot registration) and cluster ops (kubectl secret creation, pod validation). No code changes to any repo. The "cluster ops" designation in the Repo field is honest about the scope. Single-repo placement is correct since this is operational, not code work.

Dependencies

• [x] #1 (Provision infrastructure in pal-e-services) -- pending, in backlog
• [x] #2 (Create kustomize overlay in pal-e-deployments) -- pending, in backlog
• [x] #3 (NetworkPolicy update in pal-e-platform) -- pending, in backlog
• [ ] #4 (FastAPI scaffold + GroupMe webhook handler) -- NOT listed in Lineage but REQUIRED. Pod cannot start (AC 3) without application code. Pending, in backlog.
• [ ] #5 (Basketball-API client with Keycloak auth) -- NOT listed in Lineage but REQUIRED. Read/write tests (ACs 4-5) need the API client. Pending, in backlog.
• [x] #6 (Anthropic AI engine with tool definitions) -- pending, in backlog
• [x] Lucas tofu apply approval -- external human gate, documented in Constraints

Two undocumented dependencies found. All dependencies are in backlog -- this ticket is correctly sequenced last but its Lineage section is incomplete.

Acceptance Criteria

6 ACs total. Assessment by category:

• AC 1 (bot registration): Specific -- names the bot name, callback URL, and group_id. Testable via GroupMe API response. Agent-executable.
• AC 2 (k8s secret): Specific -- names the secret, namespace, and all 4 keys. Testable via kubectl get secret. Agent-executable. However, lists GROUPME_BOT_ID which does not appear in the deployment architecture diagram (arch-deployment-westside-ai-assistant). Mismatch needs resolution.
• AC 3 (pod readiness): Specific and testable via kubectl. Agent-executable.
• AC 4 (read test): Specific query with expected behavior. Human-only -- requires sending a GroupMe message and observing response.
• AC 5 (write test): Specific with two-step confirmation flow. Human-only -- requires interactive GroupMe conversation.
• AC 6 (safety test): Specific -- message from different group is ignored. Human-only -- requires sending from a non-allowlisted group.

No ambiguous "works correctly" language. All ACs are testable. However, the issue does not separate agent-executable ACs (1-3) from human-only ACs (4-6). An agent dispatched against this ticket would complete 1-3 then have no way to verify 4-6.

Blast Radius

• Files/repos touched: 0 files, 0 repos. External API + kubectl only.
• What could break: Incorrect callback URL means bot never receives messages. Wrong group_id means bot responds in wrong group. Missing secret keys means pod crash-loops.
• Rollback: Straightforward -- delete bot via GroupMe API, delete k8s secret, pod stops. No persistent state changes.
• Sibling impact: None. First GroupMe bot in platform. Namespaced secret. No shared infrastructure modified.

Decomposition Assessment

Apply the three-thing limit and five-minute rule:

• Discrete changes: 3 (bot registration, secret creation, pod verification). Meets three-thing limit.
• Agent time estimate: ~3 minutes for the agent-executable portion (ACs 1-3). Within five-minute rule.
• Parallelizable subtasks: No -- sequential dependency (register bot to get bot_id/token, create secret with those values, then verify pod).
• Human validation: ACs 4-6 are a separate human phase after agent completes. Not parallelizable with agent work.

No decomposition needed. The agent portion fits in a single pass. The human portion is post-execution validation, not additional agent work. The issue just needs to clearly mark the handoff point.

Recommendation

1. [BODY] Fix incomplete Lineage: add #4 and #5 as dependencies. The pod cannot start (AC 3) without the FastAPI scaffold (#4), and read/write tests (ACs 4-5) require the basketball-api client (#5). Suggested text: "Depends on forgejo_admin/westside-ai-assistant #1, #2, #3 (infra), #4 (scaffold), #5 (API client), and #6 (AI engine)."
2. [BODY] Separate ACs into agent vs. human sections. Add a handoff marker after AC 3: "--- Agent handoff: ACs 1-3 complete. Human validates ACs 4-6 in GroupMe test group. ---"
3. [BODY] Reconcile AC 2 secret keys with deployment architecture diagram. AC 2 lists 4 keys (ANTHROPIC_API_KEY, GROUPME_BOT_ID, GROUPME_BOT_TOKEN, KEYCLOAK_CLIENT_SECRET) but arch-deployment-westside-ai-assistant shows only 3 (ANTHROPIC_API_KEY, GROUPME_BOT_TOKEN, KEYCLOAK_CLIENT_SECRET). Determine whether GROUPME_BOT_ID is a secret or an env config value, and update whichever source is wrong.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — Feature
• [x] Lineage — Standalone, scoped from westside-ai-assistant design spec (2026-03-28)
• [x] Repo — forgejo_admin/pal-e-deployments
• [x] User Story — Marcus (admin) wants kustomize overlay so ArgoCD can deploy the AI assistant
• [x] Context — Explains standard base pattern, references basketball-api/prod as model
• [x] File Targets — 3 files to create, exclusion list present
• [x] Acceptance Criteria — 6 criteria
• [x] Test Expectations — kustomize render + dry-run commands provided
• [x] Constraints — Pattern reference, Harbor URL, port, no secret data in git
• [x] Checklist — PR opened, kustomize renders, no unrelated changes
• [x] Related — project page + convention reference

All required Feature template sections are present and filled.

Traceability

• [x] story:read-ops — present on board item
• [x] story:write-ops — present on board item
• [x] arch:A4 — present on board item (infrastructure/deployment component)
• [x] Forgejo issue — forgejo_admin/westside-ai-assistant#2, open

File Targets

• [x] overlays/westside-ai-assistant/prod/kustomization.yaml — NEW file. Parent directory does not exist yet (expected for new service overlay). Reference pattern at overlays/basketball-api/prod/kustomization.yaml verified: exists, contains base ref, JSON6902 rename patches, images transformer.
• [x] overlays/westside-ai-assistant/prod/deployment-patch.yaml — NEW file. Reference at overlays/basketball-api/prod/deployment-patch.yaml verified: exists, contains env vars via individual env[].valueFrom.secretKeyRef entries, volumes, strategy override.
• [x] overlays/westside-ai-assistant/prod/harbor-creds.enc.yaml — NEW file. Reference at overlays/basketball-api/prod/harbor-creds.enc.yaml verified: exists, SOPS-encrypted with age key.
• [x] bases/standard/* — exclusion verified. Standard base exists at expected path with deployment.yaml (name: app, port 8000, /healthz probes), service.yaml (name: app, port 8000), kustomization.yaml. No changes needed.

Targets are specific enough for an agent to act on. The reference pattern is fully verified.

Repo Placement

Cross-repo issue placement: The Forgejo issue lives on forgejo_admin/westside-ai-assistant but work targets forgejo_admin/pal-e-deployments. The issue body correctly declares ### Repo: forgejo_admin/pal-e-deployments. This is acceptable for project-scoped tracking (issue stays with the project, PR goes to the target repo). However, the issue body lacks an explicit instruction telling the agent to open the PR on pal-e-deployments and cross-reference westside-ai-assistant#2. Single-repo change — no additional Forgejo issues needed.

Dependencies

• [ ] Board item #593 (Provision infrastructure in pal-e-services) — PENDING, not documented in issue. This creates the Harbor project, namespace, and ArgoCD Application. Without it: (a) no Harbor project for the image reference, (b) no namespace for kubectl apply --dry-run=server to validate against, (c) no ArgoCD Application to consume the overlay. The Woodpecker CI pipeline runs server-side dry-run against the live cluster — it will fail if the namespace doesn't exist. This is a hard blocker for AC #6 (CI pipeline passes).
• [x] Board item #595 (NetworkPolicy update in pal-e-platform) — independent of overlay creation. Not a blocker.
• [x] SOPS age key — required for encrypting harbor-creds.enc.yaml. Available on the host but agent must have access. Not documented as a constraint.

Acceptance Criteria

6 criteria evaluated:

• [x] AC1: kubectl kustomize overlays/westside-ai-assistant/prod/ renders valid manifests — testable, command provided
• [x] AC2: Deployment named westside-ai-assistant with port 8000 — verifiable by inspecting rendered YAML
• [x] AC3: Service named westside-ai-assistant with port 8000 — verifiable by inspecting rendered YAML
• [ ] AC4: "Env vars set for all config, secrets referenced via envFrom secretRef" — contradicts established pattern. The basketball-api reference uses individual env[].valueFrom.secretKeyRef entries, not envFrom. The convention-kustomize-overlay doc says "Env vars: Strategic merge patch in deployment-patch.yaml." The AC is ambiguous about which pattern to follow.
• [x] AC5: harbor-creds.enc.yaml is SOPS-encrypted — verifiable by checking for ENC[] markers
• [ ] AC6: Woodpecker CI validation pipeline passes — depends on #593 completing first (namespace must exist for server-side dry-run). The CI pipeline at .woodpecker.yaml validates ALL overlays, so a broken new overlay would block all other PRs too.

Blast Radius

• CI pipeline scope: The Woodpecker CI pipeline iterates all overlays/*/prod/ directories. A malformed new overlay would fail the entire validation step and block all other pal-e-deployments PRs. Risk is low since kustomize render is the first gate and catches most errors before server-side dry-run.
• No downstream consumers: No existing services reference westside-ai-assistant. No cross-namespace network policies point to it yet (that's board item #595).
• Rollback: Straightforward — delete the overlay directory. ArgoCD won't have an Application pointing to it until #593 completes.

Decomposition Assessment

Apply the three-thing limit and five-minute rule:

• File count: 3 new files in 1 repo — within the three-thing limit.
• AC count: 6 acceptance criteria — borderline but 4 are simple YAML inspection checks.
• Estimated agent time: ~3 minutes. This is a templated copy-adapt from a verified reference pattern (basketball-api/prod). The agent copies 3 files, changes names/env vars/image refs. Well within 5-minute rule.
• Independent subtasks: None — the 3 files are tightly coupled (kustomization.yaml references the other two).

No decomposition needed.

Recommendation

1. [BODY] Add dependency: "Depends on westside-ai-assistant#1 (Provision infrastructure in pal-e-services) — namespace and Harbor project must exist before CI server-side dry-run can pass."
2. [BODY] Fix Harbor image URL in Constraints: change harbor-core.harbor.svc.cluster.local to harbor.tail5b443a.ts.net. All existing overlays and the convention-kustomize-overlay doc use the external Tailscale URL. The internal URL would fail image pulls from outside the Harbor namespace.
3. [BODY] Clarify secret injection pattern in AC4: change "secrets referenced via envFrom secretRef" to "secrets referenced via individual env[].valueFrom.secretKeyRef entries (matching basketball-api pattern)." The envFrom approach is valid Kubernetes but diverges from the established codebase convention.
4. [BODY] Add agent instruction to Constraints: "Open PR on forgejo_admin/pal-e-deployments. Reference westside-ai-assistant#2 in PR body."

Data Flow

sequenceDiagram
    participant M as Marcus (GroupMe)
    participant G as GroupMe API
    participant W as westside-ai-assistant
    participant A as Anthropic API
    participant B as basketball-api
    participant K as Keycloak

    M->>G: Types message in group
    G->>W: POST /groupme/callback
    W->>W: Validate group_id, ignore bot messages
    W->>A: messages + tools (tool_use)
    A->>W: tool_use response (e.g. get_player)
    W->>K: Client credentials grant (if token expired)
    K->>W: Access token
    W->>B: GET /admin/players (Bearer token)
    B->>W: Player data JSON
    W->>A: tool_result with player data
    A->>W: Final text response
    W->>G: POST bot message to group
    G->>M: Bot reply appears in chat

Domain Model

erDiagram
    GroupMe_Message {
        string sender_name
        string text
        string group_id
        string sender_type
    }
    AI_Engine {
        string system_prompt
        list tool_definitions
        dict conversation_history
        dict pending_confirmations
    }
    Basketball_Client {
        string base_url
        string keycloak_token
        datetime token_expiry
    }
    Tool_Call {
        string tool_name
        dict parameters
        bool requires_confirmation
        string status
    }
    GroupMe_Message ||--o| AI_Engine : "parsed by"
    AI_Engine ||--o{ Tool_Call : "generates"
    Tool_Call ||--o| Basketball_Client : "executed by"

Story

As Marcus (admin), I'm protected from accidental data changes — writes require confirmation, dangerous operations (email, billing, contracts) are excluded, and the bot only operates in the approved GroupMe group.

Acceptance Criteria

• Bot ignores messages from any group not in the allowlist
• Bot ignores its own messages (no infinite loops)
• Email, billing, contract, and token-generation operations are not available as tools
• All write operations require explicit "yes" confirmation
• Pending confirmations expire after 5 minutes
• Bot authenticates via Keycloak service account, not user credentials

Architecture References

arch: A1 (GroupMe Webhook — group allowlist, self-ignore), A2 (AI Engine — tool exclusions, confirmation flow)

Story

As Marcus (admin), I can update player info, assign players to teams, and toggle visibility through GroupMe chat — with a confirmation prompt before any write executes.

Acceptance Criteria

• "Update Jaylen's height to 6'1" triggers confirmation prompt
• Replying "yes" executes the update and confirms success
• Replying anything else cancels the pending action
• "Add Jaylen to Kings" assigns player to team after confirmation
• "Make Jaylen public" toggles visibility after confirmation
• Confirmation expires after 5 minutes with no response

Architecture References

arch: A2 (AI Engine — confirmation state machine), A3 (Basketball Client — write endpoints)

Story

As Marcus (admin), I can ask natural language questions in the approved GroupMe group and get accurate answers about players, teams, rosters, payment status, and program stats — without opening the web UI.

Acceptance Criteria

• "How many players are registered?" returns accurate count from dashboard stats
• "What's Jaylen's height?" returns the correct player field
• "Show me the Kings roster" returns team roster
• "Who hasn't paid?" returns players with overdue subscriptions
• Responses are concise and formatted for GroupMe (no HTML, no markdown tables)

Architecture References

arch: A1 (GroupMe Webhook), A2 (AI Engine), A3 (Basketball Client)

Verdict: READY

Re-review of board item #759. Previous review (review-759-2026-04-03) was NEEDS_REFINEMENT with one finding: story:WA-S1 label had no matching entry on project-westside-ai-assistant. Fixed by relabeling to story:write-ops.

Template Completeness

• [x] Type — Feature
• [x] Lineage — standalone, westside-email-agent capability
• [x] Repo — forgejo_admin/westside-ai-assistant
• [x] User Story — clear admin-to-NEMO email flow
• [x] Context — thorough, references existing patterns and auth
• [x] File Targets — specific files with modify/do-not-touch
• [x] Acceptance Criteria — 6 testable items
• [x] Test Expectations — 3 unit tests with run command
• [x] Constraints — patterns, auth, prompt guidance
• [x] Checklist — standard 3-item
• [x] Related — arch-email, sop-email-send, project-westside-agency, basketball-api #295

Traceability

• [x] story:write-ops label — "Marcus can update player info and manage teams via GroupMe with confirmation (future — not V1)"
• [x] story note verified — found in project-westside-ai-assistant user-stories section (key: write-ops)
• [x] arch:email label — email architecture component
• [x] arch note verified — arch-email note exists in pal-e-docs (id 1102, project westside-basketball, tagged architecture+active)
• [x] Forgejo issue — forgejo_admin/westside-ai-assistant#31, open

File Targets

• [x] app/ai.py — verified: TOOLS list at line 51+, SYSTEM_PROMPT at line 24, write tools with metadata operation=write pattern confirmed, tool execution handler present
• [x] app/basketball.py — verified: BasketballClient class with _request(method, path, json=...) helper. Has get() and specific write methods but no generic post(). Ticket accurately describes adding post() to mirror get().
• [x] app/confirmation.py — exists, correctly marked NOT to touch
• [x] app/groupme.py — exists, correctly marked NOT to touch
• [x] app/config.py — exists, correctly marked NOT to touch

Repo Placement

OK. Issue filed on forgejo_admin/westside-ai-assistant, all file targets are in that repo. No cross-repo work needed — basketball-api blast endpoint already exists and is deployed.

Dependencies

• [x] basketball-api #295 (blast endpoint) — satisfied, issue closed, merged, deployed
• [x] Board item #599 (GroupMe bot go-live) — in_progress. Not a hard blocker; email_blast tool can be built and tested independently

No unresolved dependencies that would block execution.

Acceptance Criteria

6 ACs, all agent-verifiable:

• AC1: email_blast tool in TOOLS with correct schema — grep/read verification
• AC2: Tool tagged as write operation — grep verification of metadata
• AC3: BasketballClient.post() method exists — grep verification
• AC4: SYSTEM_PROMPT includes email capabilities — read verification
• AC5: End-to-end flow (user says X, NEMO proposes, user confirms, blast executes) — testable via unit test mock
• AC6: test_email parameter works — unit test

All criteria are concrete and testable. No ambiguity.

Blast Radius

Low. Changes are additive (new tool + new method). Existing tools and confirmation flow are untouched. basketball-api blast endpoint handles auth and validation — this ticket only adds the client-side caller. No sibling services consume NEMO's tool definitions. Rollback is straightforward (revert two file changes).

Decomposition Assessment

2 files in 1 repo. 6 acceptance criteria. Estimated agent time ~3-4 minutes. All changes are tightly coupled (tool definition + client method + prompt update). No independent subtasks worth parallelizing. No decomposition needed.

Recommendation

No action needed. Previous finding (story label mismatch) has been resolved. Ticket is ready for execution.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — Feature
• [x] Lineage — Standalone, scoped from westside-ai-assistant design spec (2026-03-28)
• [x] Repo — forgejo_admin/pal-e-platform
• [x] User Story — As Marcus (admin), wants AI assistant to reach basketball-api and keycloak
• [x] Context — Explains NetworkPolicy cross-namespace restriction and connection refused symptom
• [x] File Targets — terraform/network-policies.tf specified with modify/don't-touch lists
• [x] Acceptance Criteria — 4 items
• [x] Test Expectations — tofu validate + tofu plan -lock=false
• [x] Constraints — Only modify network-policies.tf, follow existing pattern, no tofu apply
• [x] Checklist — PR opened, plan output, no unrelated changes
• [x] Related — project-westside-ai-assistant, service-onboarding-sop

All required sections present. Template is structurally complete.

Traceability

• [x] story:read-ops — AI assistant reads data from basketball-api
• [x] story:write-ops — AI assistant writes data via basketball-api
• [x] arch:A4 — infrastructure/platform component
• [x] Forgejo issue — forgejo_admin/westside-ai-assistant#3, open

Traceability triangle is complete.

File Targets

• [x] terraform/network-policies.tf — verified: file exists at /home/ldraney/pal-e-platform/terraform/network-policies.tf, contains 9 NetworkPolicy resources for platform namespaces (monitoring, forgejo, woodpecker, harbor, minio, keycloak, postgres, ollama, cnpg-system)
• [ ] "basketball-api ingress policy" — DOES NOT EXIST. There is no netpol_basketball_api resource in this file. basketball-api is an application namespace, not a platform namespace. It has no default-deny ingress policy anywhere in pal-e-platform, pal-e-services, or pal-e-deployments. Traffic to basketball-api is already unrestricted by default.
• [x] "keycloak ingress policy" — verified: kubernetes_manifest.netpol_keycloak exists (line 133). Currently allows ingress from tailscale, basketball-api, and monitoring. Adding westside-ai-assistant here is valid and follows the existing pattern.

File targets are partially incorrect. The issue assumes a basketball-api NetworkPolicy exists when it does not.

Repo Placement

Cross-repo filing: Forgejo issue is on forgejo_admin/westside-ai-assistant but work targets forgejo_admin/pal-e-platform. The ### Repo section correctly identifies the target repo. This is acceptable — the issue is scoped from the westside-ai-assistant project and the PR will be opened on pal-e-platform. No multi-repo split needed for the corrected scope (keycloak policy only).

Dependencies

• [x] Board item #593 (Provision infrastructure in pal-e-services) — logically runs first to create the westside-ai-assistant namespace. However, NetworkPolicy namespace selectors are declarative (label-based), so the policy can reference a namespace that doesn't exist yet. No hard blocker, but logical ordering should be documented.
• [x] Board item #594 (Create kustomize overlay in pal-e-deployments) — independent, no dependency.

No unresolved blockers. Dependencies are not documented in the issue body but are soft (no execution blocker).

Acceptance Criteria

• AC1: "westside-ai-assistant namespace listed in basketball-api NetworkPolicy allowlist" — UNTESTABLE. No basketball-api NetworkPolicy exists. Agent cannot satisfy this criterion. Must be removed or rewritten.
• AC2: "westside-ai-assistant namespace listed in keycloak NetworkPolicy allowlist" — Testable. Agent adds a namespaceSelector line to netpol_keycloak ingress list following existing pattern.
• AC3: "tofu plan -lock=false shows only NetworkPolicy changes" — Testable. Agent runs cd terraform && tofu plan -lock=false and includes output in PR.
• AC4: "No other namespaces added or removed" — Testable via plan diff inspection.

3 of 4 AC are testable. AC1 must be corrected.

Blast Radius

• 1 file touched: terraform/network-policies.tf
• 1 resource modified: kubernetes_manifest.netpol_keycloak
• Impact if buggy: worst case, keycloak ingress policy syntax error blocks all keycloak traffic. Rollback is straightforward (revert the single line addition).
• No similar gap elsewhere — basketball-api has no default-deny policy, so no parallel fix needed. If defense-in-depth is desired for basketball-api, that is a separate scope decision.
• westside-app (westsidekingsandqueens) already reaches basketball-api without any NetworkPolicy entry, confirming basketball-api is open.

Decomposition Assessment

• Discrete changes: 1 (add one namespaceSelector line to keycloak policy). Well under the 3-change limit.
• Estimated agent time: ~2 minutes. Well under the 5-minute rule.
• No independent subtasks to parallelize.
• No decomposition needed once scope is corrected.

Recommendation

1. [BODY] Remove reference to "basketball-api ingress policy" from File Targets. Replace with: terraform/network-policies.tf — add westside-ai-assistant namespace to keycloak ingress policy (kubernetes_manifest.netpol_keycloak, line ~148).
2. [BODY] Remove AC1 ("westside-ai-assistant namespace listed in basketball-api NetworkPolicy allowlist"). Replace with: "basketball-api has no default-deny ingress policy — no change needed for basketball-api connectivity."
3. [BODY] Update Context to clarify: only the keycloak policy needs modification. basketball-api is already reachable from any namespace.
4. [SCOPE] Decision needed: should a default-deny NetworkPolicy be created for basketball-api? If yes, that is a separate ticket. Currently basketball-api accepts ingress from all namespaces (no defense-in-depth).

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — Feature
• [x] Lineage — depends on #4 (scaffold)
• [x] Repo — forgejo_admin/westside-ai-assistant
• [x] User Story — clear who/what/why for Marcus as admin
• [x] Context — explains Keycloak client credentials flow, caching, and typed functions
• [x] File Targets — specific files to create and modify, plus do-not-touch boundaries
• [x] Acceptance Criteria — 6 testable conditions
• [x] Test Expectations — 4 unit tests plus run command
• [x] Constraints — httpx, internal URL, Keycloak token URL, client-only
• [x] Checklist — PR, tests, no unrelated changes
• [x] Related — project page and architecture doc linked

Traceability

• [x] story:read-ops — read operations for program data
• [x] story:write-ops — write operations for program data
• [x] arch:A3 — Basketball-API Client component in domain model
• [x] Forgejo issue — forgejo_admin/westside-ai-assistant#5, open

File Targets

• [x] app/basketball.py — to be created. Repo currently only has README.md (scaffold from #4 not yet implemented). Path is consistent with #4's app/ convention. Parent dir will exist after #4 completes.
• [x] requirements.txt — to be modified. Does not exist yet; depends on #4 creating it. Dependency documented in Lineage.
• [x] Do-not-touch boundaries clearly stated (basketball-api repo, app/groupme.py).

Targets are specific enough for an agent, but the agent will need the exact HTTP paths for each basketball-api endpoint (see Acceptance Criteria below).

Repo Placement

OK. Issue filed on forgejo_admin/westside-ai-assistant, work targets that repo. basketball-api is consumed, not modified — correctly noted in Constraints. Single-repo scope.

Dependencies

• [x] #4 (FastAPI scaffold + GroupMe webhook handler) — pending. Board item #596, column: backlog, state: open. This ticket cannot execute until #4 merges. Documented in Lineage.
• [ ] Keycloak client provisioning — UNDOCUMENTED. The ticket references a westside-ai-bot client in the westside-basketball realm with admin role and service-accounts-enabled. No board item or Forgejo issue covers creating this Keycloak client. Either #1 (Provision infrastructure in pal-e-services) includes it, or a separate ticket is needed. The issue body should state which ticket provisions the Keycloak client.

Acceptance Criteria

6 AC items are testable and specific. However, the AC references function names that don't precisely match basketball-api's actual endpoint paths. An agent implementing blindly from the AC would guess URLs incorrectly. Specific issues:

• Missing tenant context: Multiple basketball-api endpoints require tenant_id or tenant_slug parameters (e.g., GET /api/teams?tenant_id=X, GET /tenants/{tenant_slug}/roster, POST /api/roster/{tenant_slug}/check-in/{player_id}). The AC and Context sections don't mention how the client resolves tenant identity — hardcoded slug, env var, or per-call parameter.
• assign_tryout_number is a bulk operation: The actual endpoint POST /tryouts/admin/{tenant_slug}/assign-numbers bulk-assigns numbers to ALL unassigned players. The function name implies single-player assignment.
• Inconsistent route prefixes: get_roster lives at GET /tenants/{tenant_slug}/roster, checkin_player at POST /api/roster/{tenant_slug}/check-in/{player_id}, and assign_tryout_numbers at POST /tryouts/admin/{tenant_slug}/assign-numbers. These are three different route prefix patterns vs. the /api/ and /admin/ patterns used by most other endpoints.

Blast Radius

Low. This is a new client module in a new repo. No existing code is modified. basketball-api is consumed read-only. The only risk is incorrect endpoint URLs causing runtime failures, which is why the endpoint mapping gaps matter. Rollback is trivial (revert one file).

Decomposition Assessment

1 file to create, 1 file to modify, 6 AC, 4 test expectations, single repo. All work is in one module (app/basketball.py) plus one test file. Fits within the three-thing limit (1 client class, 1 test file, 1 requirements update). Estimated agent time: 3-4 minutes. No decomposition needed.

Recommendation

1. [BODY] Add a Constraints bullet documenting tenant resolution strategy: hardcoded slug, env var, or per-call parameter.
2. [BODY] Add an endpoint reference table in Context or Constraints listing each function's exact HTTP method + full URL path. Verified paths from basketball-api codebase:
   • GET /admin/dashboard (admin role)
   • GET /admin/players (admin role)
   • GET /api/players/{player_id} (any auth)
   • GET /api/teams?tenant_id={tenant_id} (admin role)
   • GET /tenants/{tenant_slug}/roster (admin or coach role)
   • GET /api/subscriptions/overview
   • GET /api/subscriptions
   • PUT /api/players/{player_id} (any auth)
   • POST /api/teams/{team_id}/players (admin role)
   • DELETE /api/teams/{team_id}/players/{player_id} (admin role)
   • PATCH /admin/players/{player_id}/visibility (admin role)
   • POST /api/teams (admin role)
   • POST /api/roster/{tenant_slug}/check-in/{player_id} (any auth)
   • POST /tryouts/admin/{tenant_slug}/assign-numbers (admin role, BULK)
3. [BODY] Rename assign_tryout_number to assign_tryout_numbers (plural) and note it is a bulk trigger, not a per-player operation.
4. [BODY] Add Lineage note clarifying which ticket provisions the Keycloak client westside-ai-bot (likely #1 or needs its own ticket).

Verdict: READY

Re-review Context

Previous review: review-597-2026-03-28 (verdict: NEEDS_REFINEMENT, 4 recommendations). All 4 recommendations have been addressed in the updated issue body. This re-review verifies the fixes and performs a fresh deep-verification pass against the basketball-api codebase.

Template Completeness

• [x] Type — Feature
• [x] Lineage — depends on #4 (scaffold), Keycloak client provisioned by #1
• [x] Repo — forgejo_admin/westside-ai-assistant
• [x] User Story — clear who/what/why for Marcus as admin
• [x] Context — Keycloak client credentials flow, caching, typed functions, tenant slug hardcoded
• [x] File Targets — specific files to create and modify, plus do-not-touch boundaries
• [x] Acceptance Criteria — 5 testable conditions
• [x] Endpoint Reference Table — NEW. Full HTTP method + path for all 14 operations
• [x] Test Expectations — 4 unit tests plus run command
• [x] Constraints — httpx, internal URL, Keycloak token URL, tenant slug, bulk note, client-only
• [x] Checklist — PR, tests, no unrelated changes
• [x] Related — project page and architecture doc linked

Traceability

• [x] story:read-ops — read operations for program data
• [x] story:write-ops — write operations for program data
• [x] arch:A3 — Basketball-API Client component in domain model
• [x] Forgejo issue — forgejo_admin/westside-ai-assistant#5, open

Previous Recommendations — Resolution

• [x] [BODY] Tenant resolution strategy — RESOLVED. Context says "Tenant slug is hardcoded to 'westside-kings-queens'". Constraints repeats it. Endpoint table bakes the slug into paths.
• [x] [BODY] Endpoint reference table — RESOLVED. Full table added with 7 reads and 7 writes, all with HTTP method + path.
• [x] [BODY] Rename assign_tryout_number to plural — RESOLVED. Now bulk_assign_tryout_numbers with explicit BULK note in Constraints.
• [x] [BODY] Clarify Keycloak client provisioning — RESOLVED. Lineage now says "Keycloak client provisioned by #1."

File Targets

• [x] app/basketball.py — to be created. Depends on #4 scaffold creating the app/ directory. Documented in Lineage.
• [x] tests/test_basketball.py — to be created. Test file for the client module.
• [x] requirements.txt — to be modified. httpx should already be present from #4.
• [x] Do-not-touch boundaries clearly stated (basketball-api repo, app/groupme.py).

Endpoint Table Deep Verification

Verified all 14 endpoints against the basketball-api codebase (~/basketball-api/src/basketball_api/):

Reads (all correct):

• [x] GET /admin/dashboard — admin router prefix /admin + route /dashboard. No query params needed (auto-resolves tenant).
• [x] GET /admin/players — admin router prefix /admin + route /players. No query params needed.
• [x] GET /players/{player_id} — players router mounted at both /api/players and /players (SPA alias). Path works via SPA alias. Requires any auth.
• [x] GET /admin/teams — admin router prefix /admin + route /teams. Auto-resolves tenant. Returns teams+players for draft board.
• [x] GET /tenants/westside-kings-queens/roster — roster router prefix /tenants + route /{tenant_slug}/roster. Correct.
• [x] GET /api/subscriptions/overview — subscriptions router prefix /api/subscriptions + route /overview. Correct.
• [x] GET /api/subscriptions — subscriptions router prefix /api/subscriptions + route "". Correct.

Writes (all paths correct, minor query-param nit):

• [x] PUT /players/{player_id} — SPA alias mount works. Requires any auth.
• [x] POST /teams/{team_id}/players — SPA alias mount works. Requires admin + ?tenant_id= query param. Body is {"player_ids": [...]} (list, not single). See Nit 1.
• [x] DELETE /teams/{team_id}/players/{player_id} — SPA alias mount works. Requires admin + ?tenant_id= query param. See Nit 1.
• [x] PATCH /admin/players/{player_id}/visibility — admin router. Correct.
• [x] POST /api/teams — teams router. Body includes tenant_id field. Correct.
• [x] POST /api/roster/westside-kings-queens/check-in/{player_id} — tryouts router (no prefix). Correct.
• [x] POST /tryouts/admin/westside-kings-queens/assign-numbers — tryouts router (no prefix). Correct. BULK operation documented.

Nits (non-blocking)

These are minor details an agent can resolve at implementation time. They do not block the ticket.

1. Query param on team player operations: POST /teams/{team_id}/players and DELETE /teams/{team_id}/players/{player_id} both require a ?tenant_id= query parameter in the basketball-api code. Since the client hardcodes the tenant slug, the implementing agent needs to resolve the tenant's numeric ID or pass the slug. The existing endpoint accepts str for tenant_id, so passing the slug string should work. Not blocking because the agent will discover this from the basketball-api OpenAPI spec or error responses.
2. Path prefix inconsistency: Some write paths use /teams/ and /players/ (SPA alias mounts) while others use /api/teams and /api/players. Both work — the SPA aliases are registered at lines 82-83 of main.py. Cosmetic only.
3. assign_player_to_team body schema: The actual endpoint accepts {"player_ids": [...]} (a list), not a single player_id. The function name assign_player_to_team (singular) is fine as a client wrapper that takes a single ID and wraps it in a list. The agent can handle this.

Repo Placement

OK. Issue filed on forgejo_admin/westside-ai-assistant, work targets that repo. basketball-api is consumed, not modified. Single-repo scope.

Dependencies

• [x] #4 (FastAPI scaffold + GroupMe webhook handler) — board item #596, column: backlog. This ticket cannot execute until #4 merges. Documented in Lineage.
• [x] #1 (Provision infrastructure) — provisions the Keycloak client westside-ai-bot. Now documented in Lineage.
• [x] #9 (basketball-api default-deny NetworkPolicy) — discovered scope item on the board. The AI assistant pod needs network access to basketball-api. This is an infra dependency that must be resolved before runtime validation, but not before code implementation.

Acceptance Criteria

5 AC items are testable and specific. All can be verified by an agent via unit tests with mocked HTTP responses. The test expectations align with the AC. Run command is clear: pytest tests/test_basketball.py -v.

Blast Radius

Low. New client module in a new repo. No existing code modified. basketball-api consumed read-only. Rollback is trivial (revert one file). NetworkPolicy item (#9) already tracked separately for runtime access.

Decomposition

2 files to create, 1 file to modify, 5 AC, 4 test expectations, single repo. All work is in one module (app/basketball.py) plus one test file and a requirements line. Fits within the three-thing limit (1 client class, 1 test file, 1 requirements update). Estimated agent time: 4-5 minutes. No decomposition needed.

Recommendation

No action needed. All previous NEEDS_REFINEMENT items resolved. Three nits identified (query params, path prefix inconsistency, body schema) are non-blocking implementation details the agent will resolve at build time.

Verdict: READY

Re-review of board item #595 after refinement. Previous review: review-595-2026-03-28 (NEEDS_REFINEMENT). All 4 recommendations from the previous review have been addressed.

Template Completeness

• [x] Type — Feature
• [x] Lineage — Standalone, scoped from westside-ai-assistant design spec (2026-03-28)
• [x] Repo — forgejo_admin/pal-e-platform
• [x] User Story — As Marcus (admin), wants AI assistant to reach Keycloak for client credentials flow
• [x] Context — Clearly explains that only keycloak NetworkPolicy needs modification; basketball-api has no NetworkPolicy and is already reachable
• [x] File Targets — terraform/network-policies.tf with modify/don't-touch lists; correctly scoped to keycloak only
• [x] Acceptance Criteria — 4 items, all keycloak-scoped
• [x] Test Expectations — tofu validate + tofu plan -lock=false
• [x] Constraints — Only modify keycloak policy, follow existing pattern, no tofu apply, no new NetworkPolicy resources
• [x] Checklist — PR opened, plan output, no unrelated changes
• [x] Related — project-westside-ai-assistant, service-onboarding-sop

All required sections present and complete. Template is structurally sound.

Traceability

• [x] story:read-ops — AI assistant reads data (needs Keycloak token)
• [x] story:write-ops — AI assistant writes data (needs Keycloak token)
• [x] arch:A4 — infrastructure/platform component
• [x] Forgejo issue — forgejo_admin/westside-ai-assistant#3, open

Traceability triangle is complete.

File Targets

• [x] terraform/network-policies.tf — verified: file exists at /home/ldraney/pal-e-platform/terraform/network-policies.tf (221 lines), contains 9 NetworkPolicy resources
• [x] kubernetes_manifest.netpol_keycloak — verified: exists at lines 133-154. Currently allows ingress from tailscale (line 148), basketball-api (line 149), and monitoring (line 150)
• [x] Pattern reference — verified: basketball-api entry at line 149 is the exact pattern to replicate: { from = [{ namespaceSelector = { matchLabels = { "kubernetes.io/metadata.name" = "basketball-api" } } }] },
• [x] "Files the agent should NOT touch" — correctly lists all other terraform files and explicitly forbids creating a basketball-api NetworkPolicy

All file targets verified. Line references accurate.

Repo Placement

OK. Cross-repo filing is intentional and documented: Forgejo issue is on forgejo_admin/westside-ai-assistant (the consuming project), PR targets forgejo_admin/pal-e-platform (the platform repo). The ### Repo section correctly identifies the target. No multi-repo split needed.

Dependencies

• Board item #593 (Provision infrastructure in pal-e-services) — logically runs first to create the westside-ai-assistant namespace, but NetworkPolicy namespaceSelector is declarative (label-based). The policy can reference a namespace that doesn't exist yet. No hard blocker.
• Board item #594 (Create kustomize overlay in pal-e-deployments) — independent, no dependency.
• Board item #605 (Discovered: basketball-api default-deny NetworkPolicy) — tracked as separate discovered scope. No dependency on this ticket.

No unresolved blockers. Soft ordering (namespace creation before policy apply) is inherent in the pipeline, not a blocking dependency.

Acceptance Criteria

• AC1: "westside-ai-assistant namespace listed in keycloak NetworkPolicy namespaceSelector" — Testable. Agent adds one line to the ingress list.
• AC2: "tofu plan -lock=false shows only the keycloak NetworkPolicy change" — Testable. Agent runs command and includes output in PR.
• AC3: "No other namespaces added or removed" — Testable via plan diff inspection.
• AC4: "No new NetworkPolicy resources created" — Testable via plan diff inspection.

All 4 AC are testable and verifiable by an agent. No missing criteria.

Blast Radius

• 1 file touched: terraform/network-policies.tf
• 1 resource modified: kubernetes_manifest.netpol_keycloak
• 1 line added (namespaceSelector entry)
• Impact if buggy: worst case, keycloak ingress policy syntax error blocks all keycloak traffic. Rollback is a single-line revert.
• No westside-ai-assistant references exist anywhere in pal-e-platform today (confirmed via grep). This is a clean addition.
• Discovered scope (basketball-api default-deny) tracked separately as board item #605 / Forgejo issue #9.

Decomposition Assessment

• File targets: 1 file, 1 resource, 1 line addition
• Acceptance criteria: 4 (under the 5 threshold)
• Estimated agent time: ~2 minutes
• No independent subtasks to parallelize

No decomposition needed.

Previous Review Resolution

• [x] [BODY] "Remove basketball-api ingress policy from File Targets" — RESOLVED. File Targets now reference only keycloak policy. "Files the agent should NOT touch" explicitly says not to create a basketball-api NetworkPolicy.
• [x] [BODY] "Remove AC1 referencing basketball-api allowlist" — RESOLVED. All AC are keycloak-scoped.
• [x] [BODY] "Update Context to clarify only keycloak needs modification" — RESOLVED. Context now states: "basketball-api does NOT have a NetworkPolicy... Only the keycloak NetworkPolicy needs modification."
• [x] [SCOPE] "Decision needed on basketball-api default-deny" — RESOLVED. Tracked as discovered scope: board item #605, Forgejo issue #9.

Recommendation

No action needed. Ticket is ready for dispatch.

Vision

Nemo — an AI assistant that lives in GroupMe, enabling program admins (Marcus) to manage the Westside basketball program through natural language. Backed by Anthropic Haiku 4.5 with tool_use against basketball-api. Read-only V1, with a graduation path to write access based on interaction log analysis. Child project of Westside Basketball.

User Stories

Future stories: Coach-level assistant with scoped permissions (spike #22).

Architecture

1. Domain Model — GroupMe message → Nemo AI engine → basketball-api tool call → response
2. Data Flow — GroupMe callback POST → Anthropic Haiku tool_use → cluster-internal HTTP → GroupMe bot post
3. Deployment — FastAPI pod in k8s, Tailscale funnel, Keycloak service account (westside-ai-bot, admin role)

Key decisions:

• GroupMe bot callback (not polling) — real-time conversational response
• Anthropic Haiku 4.5 (cheapest model, ~$0.25/M input) — Ollama/qwen2.5:7b as zero-cost fallback (provider switch ticket #16)
• Cluster-internal basketball-api calls — no external network hop
• Keycloak service account with admin role — client credentials flow
• Modular tool registry (ticket #18) — tools as directories, auto-discovered, enabled/disabled via frontmatter
• Read-only V1 — write tools exist in codebase but disabled. Graduation via interaction log analysis.

Board

board-westside-ai-assistant

Status

Deployed and responding. Pod running in k8s, Haiku responding to GroupMe messages. Keycloak auth to basketball-api being validated. Test GroupMe group: "Westside AI Assistant - Test" (ID: 114069292).

Achieved: M1 (bot responds to messages). M2 in validation (read queries against basketball-api).

In progress: Repo restructure (#18), read-only lockdown (#20), interaction logging (#19/#21).

Backlog: Provider switch (#16), coach-level expansion (spike #22), secrets backup (pal-e-platform #253).

Milestones

• M1 (achieved): Bot receives message in test group and responds conversationally
• M2 (validating): Bot answers a read query ("list all players") correctly via basketball-api
• M3 (future): Bot executes a confirmed write ("update height") end-to-end
• M4 (future): Coach-level assistant in team GroupMe groups with scoped permissions

Repos

Infrastructure

• Namespace: westside-ai-assistant
• Funnel: https://westside-ai-assistant.tail5b443a.ts.net
• Harbor: westside-ai-assistant/api
• Keycloak client: westside-ai-bot (confidential, service account, admin role)
• GroupMe bot: "Westside Assistant" (bot_id: 96060d69c3efb7a4aca500cc7d, group: 114069292)
• Model: claude-haiku-4-5-20251001 (configurable via ANTHROPIC_MODEL env var)
• Ollama fallback: qwen2.5:7b pulled and ready in cluster Ollama pod