pal-e-agency

Verdict: PASS

Ticket

ldraney/appstoreconnect-tofu#15 — Implement 10 remaining IaC resources for beta (ch13) and App Store submission (ch14) in the appstoreconnect-tofu provider.

Board item #1982 on board-platform-playbook (8 points). Merged via PR #16 (ch13, 4 resources) and PR #17 (ch14, 6 resources).

Environment

Local validation against ldraney/appstoreconnect-tofu main branch. HEAD: 9c31bb2 (Add Chapter 14 App Store submission resources). Go build and test suite. This is a Terraform provider source repo (Go code), not a Terraform configuration repo — tofu plan does not apply; validation is via go build and go test.

Tiers Executed

• Tier 1 (Local): Pull main, go build ./..., go test ./... -count=1
• Tier 2 (Staging): N/A — no staging deployment for a provider binary
• Tier 3 (Prod): Verified repo state on origin/main — both PRs merged, issue closed, all files present in HEAD tree

Checks

#	Criterion	How Verified	Result	Evidence
1	All 10 resources have client methods with tests	ls pkg/appstoreconnect/*.go + go test ./...	PASS	10 new client files present (4 ch13 + 6 ch14), 17 total test files in pkg/appstoreconnect/, all tests pass
2	All 10 resources have Terraform resource/data source with schema tests	ls resource_*.go data_source_*.go + provider.go registration	PASS	15 resources and 15 data sources registered in provider.go (5 original + 10 new each)
3	go build and go test ./... pass	go build ./... (exit 0), go test ./... -count=1	PASS	Build: exit code 0 (no errors). Tests: both packages ok (root 0.006s, pkg/appstoreconnect 0.040s)
4	README resource table updated	grep README.md	PASS	All 15 resources listed with endpoints and priority levels (P3 for ch13, P4 for ch14)
5	Codegen resourceDef entries added so types regenerate from spec	grep cmd/openapi-gen/main.go	PASS	resourceDef entries present for all 10 new resource types plus 3 new enum definitions

Regression Check

go build ./... compiles the entire provider (original 6 resources + 10 new) without errors. go test ./... passes all tests across both packages. No regressions detected — original resources (app, bundle_id, profile, device, beta_group, certificates) continue to function.

Discovered Issues

Local workspace contamination (non-blocking): The local working tree at /home/ldraney/appstoreconnect-tofu had all 60+ new files from PRs #16 and #17 staged for deletion (git rm). This appears to be leftover from a prior agent workspace operation. The repo on Forgejo (origin/main at 9c31bb2) is correct — all files exist in the HEAD commit tree. Resolved by git stash during validation. No Forgejo issue needed — this is a local workspace artifact, not a code defect.

Architecture: SDK

Thin Python SDKs that prove external APIs work via pytest integration tests. Each SDK wraps a single external service's REST API with a typed client class.

Pattern

• Language: Python 3.12+
• Dependencies: requests only — no heavy frameworks
• Build: hatchling
• Lint: ruff
• Tests: pytest (unit + integration against live API)
• CI: Woodpecker on Forgejo
• Registry: Forgejo PyPI

Structure

{service}-sdk/
  src/{service}_sdk/
    __init__.py      # Package exports
    client.py        # Client class wrapping REST endpoints
    models.py        # Dataclasses for API responses
    exceptions.py    # Typed exceptions
  tests/
    test_client.py   # Integration tests (live API)
  openapi.json       # API spec (if available)
  pyproject.toml     # hatchling + ruff + pytest config
  .woodpecker.yml    # CI: lint, test, publish

Instances

SDK	Service	Status
minio-sdk	MinIO S3	Complete (62/62 tests passing)
recraft-sdk	Recraft image generation	Planned

Relationship to MCP

SDKs are consumed by MCP servers. The SDK proves the API works; the MCP server wraps the SDK for Claude Code integration. SDK → MCP is always the dependency direction.

Verdict: PASS

Ticket

svc#192 — Register ISS dev environment as terraform-managed ArgoCD service. Merged via PR #195. Board item #1892 on board-iss.

Environment

Production k3s cluster (archbox). Namespace: iss-dev. ArgoCD app: iss-dev. Tailscale funnel: iss-dev.tail5b443a.ts.net. Tofu apply ran via Woodpecker pipeline #275 (manual trigger on main).

Checks

#	Criterion	How Verified	Result	Evidence
1	Tofu apply succeeded cleanly	Woodpecker pipeline #275 status	PASS	Pipeline #275: status=success, event=manual, branch=main. Steps: clone=success, apply=success, cross-pillar-review=success.
2	Tofu plan shows no iss-dev drift	tofu plan -lock=false -var-file=k3s.tfvars	PASS	Plan: 0 to add, 6 to change (all unrelated: ArgoCD instance label drift on mdview/iss-dev/gcal-scheduler, Keycloak sensitive value formatting), 0 to destroy. No iss-dev-specific drift.
3	ArgoCD application iss-dev exists and is synced	kubectl get application iss-dev -n argocd	PASS	Sync status: Synced. Operation phase: Succeeded. Source: overlays/intelligentstaffingsystems/dev from pal-e-deployments.git, targetRevision=main.
4	Namespace iss-dev exists	kubectl get ns iss-dev	PASS	Status: Active.
5	Kubernetes resources created and managed	ArgoCD resource list	PASS	All 5 resources Synced: Namespace (iss-dev), ConfigMap (nginx-config), Service (iss-dev, Healthy), Deployment (iss-dev, Degraded — see health note), Ingress (iss-dev, Healthy).
6	Tailscale funnel configured for dev access	kubectl get ingress -n iss-dev	PASS	ingressClassName=tailscale, tailscale.com/funnel=true. Load balancer hostname: iss-dev.tail5b443a.ts.net:443.
7	Auto-sync with prune and self-heal enabled	ArgoCD app spec inspection	PASS	syncPolicy.automated: prune=true, selfHeal=true. syncOptions: CreateNamespace=false.
8	Nginx reverse proxy correctly configured	kubectl exec -- cat /etc/nginx/conf.d/default.conf	PASS	Rendered config: proxy_pass http://100.110.151.59:8888; WebSocket upgrade headers; X-Forwarded-Proto https. Envsubst template correctly resolved UPSTREAM_TARGET.
9	No image updater annotations on dev ArgoCD app	ArgoCD app metadata inspection	PASS	Annotations: {} (empty). image_updater opt-out flag working as intended.
10	No Harbor resources created (image_updater=false)	kubectl get secret harbor-creds -n iss-dev	PASS	Error from server (NotFound): secrets "harbor-creds" not found — correctly skipped.

Health Status Note

ArgoCD health shows Degraded because the Deployment readiness probe (HTTP GET /up on port 80) returns 404. This is expected and by-design: the iss-dev pod runs nginx:alpine as a reverse proxy to the developer's local machine (UPSTREAM=100.110.151.59:8888). The readiness probe passes only when the developer is actively running the Rails app locally with a healthy database. The infrastructure registration is complete and correct; the health will transition to Healthy when the dev app is running. The upstream IS reachable (returns HTTP responses with content), confirming the proxy is functional.

Regression Check

• pal-e-docs (image_updater=true): All 6 image updater annotations present, Harbor pull secret exists (69d old). No regression from image_updater flag introduction.
• ISS prod (intelligentstaffingsystems): Correctly has no image updater annotations (disabled by later PR #201). No regression.
• ISS staging (intelligentstaffingsystems-staging): Exists and operational. No regression.
• Tofu plan shows 0 resources to add or destroy — no unintended side effects.

Discovered Issues

None. All terraform-managed resources are created, synced, and functioning as designed. The /up 404 from the dev server is an operational state (dev server not fully initialized), not a registration defect.

Re-validation Context

Initial validation on 2026-07-26 failed because k3s.tfvars had not been updated with the iss-dev entry and tofu apply had never been run — the ArgoCD app and namespace did not exist. The tfvars were updated and pipeline #275 (manual tofu apply on 2026-07-27) resolved this. Re-validation on 2026-07-27 confirms all resources are live and the previous FAIL root cause is fully resolved. Independent corroborating validation confirms tofu plan shows no iss-dev drift and all Kubernetes resources match expected state.

Verdict: PASS

Ticket

ldraney/pal-e-services#193 — Create ISS staging environment with auto-deploy on merge to main. Adds a terraform-managed staging service that auto-deploys the ISS Rails app on every merge to main via ArgoCD Image Updater.

Environment

Production k3s cluster (archbox). Namespace: intelligentstaffingsystems-staging. ArgoCD app: intelligentstaffingsystems-staging. Tailscale funnel: intelligentstaffingsystems-staging.tail5b443a.ts.net.

Checks

#	Criterion	How Verified	Result	Evidence
1	Terraform state clean (no drift for staging resources)	tofu plan -lock=false -var-file=k3s.tfvars	PASS	All 7 staging resources refreshed with no planned changes: namespace, harbor_project, 2x robot_accounts, harbor_creds, ingress, argocd_application
2	ArgoCD application synced and healthy	kubectl get application -n argocd intelligentstaffingsystems-staging	PASS	Sync: Synced, Health: Healthy. Resources: Secret (Synced), Service (Synced/Healthy), Deployment (Synced/Healthy), ServiceMonitor (Synced)
3	Staging pod running with correct image	kubectl get pods -n intelligentstaffingsystems-staging -o wide	PASS	Pod intelligentstaffingsystems-staging-568fd4699b-cll5z Running 1/1, 0 restarts. Image: harbor.tail5b443a.ts.net/intelligentstaffingsystems/app:b46c43399b... matches ISS main HEAD (b46c433)
4	Image Updater auto-deploy configured	kubectl get application -n argocd intelligentstaffingsystems-staging -o json (annotations)	PASS	Annotations present: image-list points to harbor.../intelligentstaffingsystems/app, strategy=newest-build, allow-tags=commit-hash regex, write-back=git:repocreds to kustomization on main
5	Staging databases created	kubectl exec -n postgres pal-e-postgres-1 -- psql -c "SELECT datname..."	PASS	4 databases exist: intelligentstaffingsystems_staging, _staging_cache, _staging_queue, _staging_cable
6	Tailscale funnel ingress active	kubectl get ingress -n intelligentstaffingsystems-staging + curl -sk	PASS	Ingress intelligentstaffingsystems-staging-funnel exists (class: tailscale, ports 80/443). curl returns HTTP 403 (consistent with prod behavior behind auth)
7	Woodpecker pipeline green for merge	mcp__woodpecker__get_pipeline_status(#260)	PASS	Pipeline #260 (pull_request_closed, "feat: create ISS staging environment...") status: success

Regression Check

Production ISS app (intelligentstaffingsystems) verified: Synced, Healthy, pod Running with 0 restarts (20h uptime). Tofu plan shows 6 unrelated changes (keycloak realm drift on iss/westside, mdview ingress label, iss-dev namespace label, gcal-scheduler harbor-creds label) — none affect staging resources.

Discovered Issues

None. The staging environment is fully operational and auto-deploying correctly from the ISS main branch.

Verdict: PARTIAL

Ticket

ldraney/pal-e-services#200 — Disable ISS prod auto-deploy via ArgoCD Image Updater; add manual promote-to-prod Woodpecker pipeline step.

Environment

Production cluster (k3s, archbox node). Namespaces: intelligentstaffingsystems (prod), intelligentstaffingsystems-staging (staging). ArgoCD namespace: argocd. Terraform workspace: ~/pal-e-services/terraform with k3s.tfvars.

Checks

#	Criterion	How Verified	Result	Evidence
1	Merging to main does NOT auto-deploy to prod (image updater annotations removed)	kubectl get applications.argoproj.io intelligentstaffingsystems -n argocd -o yaml | grep image-updater	PASS	No output — no image-updater annotations on prod ArgoCD app
2	Merging to main still auto-deploys to staging	kubectl get applications.argoproj.io intelligentstaffingsystems-staging -n argocd -o yaml | grep image-updater	PASS	Staging app has full image-updater annotations: argocd-image-updater.argoproj.io/image-list, update-strategy: newest-build, write-back-method: git:repocreds
3	promote-to-prod step exists in Woodpecker pipeline, gated to event: manual	Read .woodpecker.yaml in intelligentstaffingsystems repo; checked pipeline #188 (push event) step list	PASS	Step promote-to-prod present with when: event: manual. Pipeline #188 (push) ran 7 steps; promote-to-prod was NOT among them.
4	promote step sets DEPLOY_REPO=ldraney/pal-e-deployments	Read .woodpecker.yaml environment block	PASS	DEPLOY_REPO: "ldraney/pal-e-deployments" confirmed in pipeline config
5	Manual trigger updates prod overlay newTag in pal-e-deployments	Checked Woodpecker manual pipeline history	UNTESTED	No manual pipelines have been triggered (list_pipelines event:manual returned empty). Configuration is correct and follows proven westside-basketball pattern.
6	ArgoCD picks up kustomization change and deploys to prod	Verified ArgoCD source_path config	UNTESTED	ArgoCD app watches overlays/intelligentstaffingsystems/prod in pal-e-deployments. Pattern proven with other services. Requires AC#5 to trigger first.
7	Prod remains Synced and Healthy in ArgoCD	kubectl get applications.argoproj.io intelligentstaffingsystems -n argocd	PASS	Status: Synced, Health: Healthy. Pod: 1/1 Running, 0 restarts.
8	tofu plan is clean (no image updater annotation drift)	tofu plan -var-file=k3s.tfvars -lock=false	PASS	Plan shows 6 changes — all unrelated services (mdview label, gcal-scheduler secret, keycloak smtp sensitivity). Zero ISS-related drift. image_updater = false confirmed in k3s.tfvars line 382.
9	kubectl grep image-updater returns empty on prod app	kubectl get applications.argoproj.io intelligentstaffingsystems -n argocd -o yaml | grep image-updater	PASS	No output. Prod app metadata.annotations is empty.

Regression Check

• ISS prod pod running: 1/1, 0 restarts, image b46c43399b...
• ISS staging pod running: 1/1, 0 restarts, Synced/Healthy
• Prod URL (intelligentstaffingsystems.ai) returns HTTP 200
• tofu plan shows no ISS-related resource changes
• Woodpecker pipeline #188 (latest push to main) succeeded — build-and-push completed, promote-to-prod correctly skipped

Discovered Issues

• staging.intelligentstaffingsystems.ai returns connection refused (curl exit 6). The staging ArgoCD app is Synced/Healthy and the pod is running, but the external URL is unreachable. Likely a Tailscale funnel or DNS issue for the staging subdomain. Not a regression from this ticket (staging was just created by #196). Recommend a separate issue to wire the staging funnel.
• End-to-end promote flow untested. The promote-to-prod pipeline step has never been manually triggered. The first real prod deploy via this pipeline will be the true acceptance test for AC #5 and #6. Configuration matches the proven westside-basketball pattern.

Verdict: FAIL

Ticket

svc#192 (board item #1892 on board-iss) — Register ISS dev environment as terraform-managed service. Merged via PR #195 (commit 6df8aa6).

Environment

Prod cluster (k3s, default context). Repo: pal-e-services (terraform). Validation tiers: Tier 1 (local) + Tier 3 (prod).

Checks

#	Criterion	How Verified	Result	Evidence
1	Namespace exists on cluster matching chosen service key (iss-dev)	kubectl get ns | grep iss	FAIL	Only intelligentstaffingsystems (prod) exists. No iss-dev namespace. tofu plan shows kubernetes_namespace_v1.service["iss-dev"] will be created.
2	ArgoCD application is Synced and Healthy	kubectl get applications.argoproj.io -n argocd	FAIL	No iss-dev ArgoCD app exists. tofu plan shows argocd_application.service["iss-dev"] will be created.
3	curl -sI https://dev.intelligentstaffingsystems.ai returns 200	curl -sI	FAIL	Returns HTTP/2 502 (Caddy, no backend).
4	No Harbor project or robot accounts for dev service	Code review + tofu plan output	PASS	grep -E 'harbor.*iss-dev' plan returns empty. local.services_with_image_updater correctly filters out iss-dev (image_updater = false).
5	No image updater annotations on dev ArgoCD app	Code review of services.tf	PASS	Annotations block is conditional: each.value.image_updater ? merge(...) : {}. iss-dev entry has image_updater = false in k3s.tfvars.
6	terraform plan is clean after apply	tofu plan -lock=false -var-file=k3s.tfvars	FAIL	Plan: 14 to add, 7 to change, 4 to destroy. tofu apply has NOT been run. Includes changes from PR #195 (iss-dev), #196 (staging), and #201 (prod image_updater disable).

Tier 1 (Local) Summary

• Code review: PASS — image_updater = optional(bool, true) added to variables.tf; services.tf gates Harbor resources behind local.services_with_image_updater; ArgoCD annotations conditional on the flag. iss-dev entry in k3s.tfvars is correct (port 80, funnel false, image_updater false, source_path points to dev overlay).
• CI pipeline #255: SUCCESS — push to main for merge commit 6df8aa6.
• tofu plan: iss-dev resources planned correctly (namespace + ArgoCD app only, no Harbor).

Tier 3 (Prod) Summary

• iss-dev namespace: Does not exist.
• iss-dev ArgoCD app: Does not exist.
• dev.intelligentstaffingsystems.ai: HTTP 502.

Regression Check

ISS prod is unaffected by the merge:

• intelligentstaffingsystems ArgoCD app: Synced / Healthy
• Pod intelligentstaffingsystems-69c4f699d6-vp89s: 1/1 Running, 0 restarts
• curl -sI https://intelligentstaffingsystems.ai: HTTP 200

Root Cause

Merged does not equal applied. PR #195 was merged to main (commit 6df8aa6) and CI passed, but tofu apply was never executed. The code changes are correct; the deployment step was missed. Manual pipeline runs (#206, #216, #217) all predate the merge.

Action Required

Run tofu apply -var-file=k3s.tfvars in pal-e-services/terraform. Note: the plan includes changes from three merged PRs (#195 iss-dev, #196 staging, #201 prod image_updater disable). All should be reviewed before a single apply. After apply, re-validate AC 1-3 and 6.

Discovered Issues

Multiple merged PRs (#195, #196, #201) are stacked unapplied. This creates a compound apply that is harder to validate per-ticket. Consider running apply after each merge, or at minimum per-sprint.

Verdict: FAIL

Ticket

ldraney/pal-e-services#200 — Replace ISS prod auto-deploy with manual Woodpecker promotion pipeline. Board item #1904 on board-iss. Closed by PR #201 (merged 2026-07-26). Companion PR: ldraney/intelligentstaffingsystems#109 (promote-to-prod Woodpecker step, merged).

Environment

Prod cluster (k3s on archbox). Namespace: intelligentstaffingsystems. ArgoCD app: intelligentstaffingsystems. Public URL: https://intelligentstaffingsystems.ai. Tailscale URL: https://intelligentstaffingsystems.tail5b443a.ts.net.

Checks

#	Criterion	How Verified	Result	Evidence
1	Merging to main does NOT auto-deploy to prod (image updater annotations removed from prod ArgoCD app)	kubectl get application intelligentstaffingsystems -n argocd -o jsonpath='{.metadata.annotations}'	FAIL	6 image-updater annotations still present: git-branch, image-list, allow-tags, update-strategy, write-back-method, write-back-target. Root cause: PR #201 only changed k3s.tfvars.example (the example file). The live k3s.tfvars (SOPS-encrypted) was NOT updated with image_updater = false. Pipeline #270 ran tofu apply but applied zero ISS-related changes (only mdview and gcal-scheduler drift).
2	Merging to main still auto-deploys to staging via image updater (staging ArgoCD app unchanged)	kubectl get application intelligentstaffingsystems-staging -n argocd	FAIL	ArgoCD app intelligentstaffingsystems-staging does not exist on the cluster. Error: NotFound. Staging environment from PR #196 was never deployed.
3	A promote-to-prod step exists in the ISS Woodpecker pipeline, gated to event: manual	Read .woodpecker.yaml in intelligentstaffingsystems repo	PASS	Step promote-to-prod present with when: - event: manual, uses alpine/git:latest, depends on build-and-push. Delivered by commit 5b227d9 (PR #109).
4	The promote step sets DEPLOY_REPO=ldraney/pal-e-deployments	Read .woodpecker.yaml environment block	PASS	DEPLOY_REPO: "ldraney/pal-e-deployments" is set in the step environment, overriding the default forgejo_admin/pal-e-deployments.
5	Manually triggering the Woodpecker pipeline updates prod kustomization.yaml newTag	Checked mcp__woodpecker__list_pipelines for manual events on ISS repo	BLOCKED	No manual pipeline triggers have ever been run on the ISS repo. Cannot verify end-to-end promotion flow without triggering it.
6	ArgoCD picks up the kustomization change and deploys the specified image to prod	N/A	BLOCKED	Depends on AC #5; cannot verify without a manual trigger.
7	Prod remains Synced and Healthy in ArgoCD after the change	kubectl get application intelligentstaffingsystems -n argocd	PASS	Status: Synced, Health: Healthy. Pod intelligentstaffingsystems-69c4f699d6-vp89s Running with 0 restarts, image tag b46c433....
8	tofu plan is clean after apply (no image updater annotation drift)	Reviewed Woodpecker pipeline #270 apply step logs	FAIL	Apply ran successfully but applied zero ISS changes. The plan/apply only touched mdview namespace labels and gcal-scheduler harbor creds. Live k3s.tfvars does not contain image_updater = false for ISS, so no annotation removal was attempted.
9	kubectl shows no image-updater annotations on prod ArgoCD app	kubectl get application intelligentstaffingsystems -n argocd -o yaml | grep image-updater	FAIL	Returns 6 lines of image-updater annotations. Auto-deploy is still active for prod.

Regression Check

Prod pod is healthy (Running, 0 restarts). Public URL https://intelligentstaffingsystems.ai returns HTTP 200. ArgoCD app is Synced/Healthy. No regressions introduced -- the terraform change was simply never applied to the ISS service.

Discovered Issues

1. Live k3s.tfvars not updated. PR #201 only changed k3s.tfvars.example. The live SOPS-encrypted k3s.tfvars still has the ISS prod service defaulting to image_updater = true. The PR body explicitly notes this as a manual step: "the live k3s.tfvars also needs image_updater = false added to the intelligentstaffingsystems block." This manual step was not completed.
2. No staging ArgoCD app. intelligentstaffingsystems-staging does not exist on the cluster. PR #196 (staging environment) was merged in pal-e-services but the staging app was never created. AC #2 depends on staging existing.
3. Manual promotion never tested. The promote-to-prod Woodpecker step exists but has never been triggered. End-to-end flow (manual trigger -> kustomization update -> ArgoCD deploy) is unverified.

Verdict: PASS

Ticket

ldraney/intelligentstaffingsystems#99 (board item #1887) — Fix dev environment: change dev port from 9999 to 8888 and fix Docker bundler failure by adding bundle install to the compose command.

Merged PR: #102 — fix: dev port 9999 → 8888, fix Docker bundler failure (#99)

Environment

Production cluster (archbox), namespace intelligentstaffingsystems. Production URL: https://intelligentstaffingsystems.ai. Local repo at HEAD b46c433.

Tiers Executed

Tier 1 (local/CI) + Tier 3 (production). Tier 2 skipped (no staging environment).

Checks

#	Criterion	How Verified	Result	Evidence
1	Dev port changed from 9999 to 8888 across all config files	grep -rn "9999" and grep -rn "8888" across repo	PASS	Zero port-9999 references in infrastructure/config files. Remaining "9999" hits are phone numbers in test fixtures and a CSS border-radius. Port 8888 consistently applied in docker-compose.yml, Makefile, config/environments/development.rb, README.md, .env.development.example, and all docs.
2	Docker bundler failure fixed	Read docker-compose.yml command line	PASS	Command: bash -c "bundle check || bundle install && bundle exec rails server -b 0.0.0.0 -p 8888". Adds bundle check || bundle install before server start. Refined from original PR to skip install when gems are present.
3	Documentation updated for new port	grep -rn "8888" in docs/	PASS	docs/architecture.md, docs/local-dev-setup.md, docs/pipeline.md all reference port 8888. Keycloak redirect URIs updated to http://localhost:8888/*.
4	CI pipeline green for PR	Woodpecker pipeline #126 (pull_request event)	PASS	All 6 steps passed: clone, database, bundle-install, lint, security, test.
5	Production pod healthy	kubectl get pods -n intelligentstaffingsystems	PASS	Pod intelligentstaffingsystems-69c4f699d6-vp89s: 1/1 Running, 0 restarts, 9h uptime.
6	ArgoCD synced and healthy	kubectl get application -n argocd	PASS	Status: Synced,Healthy
7	Production URL responds	curl -s -o /dev/null -w "%{http_code}" https://intelligentstaffingsystems.ai	PASS	HTTP 200. Response includes proper Rails headers, session cookie, and CSP.
8	Deployed image matches HEAD	kubectl get pods -o jsonpath image vs git rev-parse HEAD	PASS	Image tag b46c43399b... matches HEAD b46c433 exactly.

Regression Check

No production-facing code was changed — only dev environment config (ports, Docker compose command) and documentation. Production pod is healthy with 0 restarts. The /about route (added in a later PR) returns HTTP 200, confirming no regression from the merge.

Push-to-main pipeline #128 shows "failure" with all steps skipped (after clone). This is the known intermittent push-event gap documented in project_push_event_gap.md. Later push pipelines (e.g., #188) succeeded, confirming the gap is not systemic.

Discovered Issues

None. The dev subdomain dev.intelligentstaffingsystems.ai returns HTTP 502, but this is expected — it requires an active Tailscale funnel from a local dev environment, not a persistent service.

Verdict: PASS

Ticket

ldraney/intelligentstaffingsystems#56 — CRM tab with search, filter, business detail, and lead-to-client promotion. Admin-only business pipeline modeled after the landscaping-assistant "today tab" pattern.

Merged PR: #112

Board item: #1826 on board-iss

Environment

Production cluster, namespace intelligentstaffingsystems, URL https://intelligentstaffingsystems.ai

Pod: intelligentstaffingsystems-69c4f699d6-vp89s, image: harbor.tail5b443a.ts.net/intelligentstaffingsystems/app:b46c43399b... (HEAD of main)

ArgoCD: Synced, Healthy

Tiers Executed

Tier 1 (CI tests) + Tier 3 (production health, route checks, visual confirmation)

Checks

#	Criterion	How Verified	Result	Evidence
1	CRM tab visible to admin only	Controller declares require_role :admin; tests confirm lead/client redirected to root; curl /crm returns 302 to /login	PASS	GET /crm -> 302 to /login; test: "lead is redirected away from CRM", "client is redirected away from CRM" pass
2	Search by name, email, business name (case-insensitive)	Lead.search scope uses PostgreSQL ILIKE across first_name, last_name, email, business_name; 4 search tests pass	PASS	CI: 476 runs, 0 failures; search tests: by name, by email, case-insensitive, empty state
3	Filter by role (All / Leads / Clients)	Lead.by_role scope; filter buttons in UI; 2 filter tests pass	PASS	Tests: "filter by leads shows only leads", "filter by clients shows only clients" pass
4	Business detail page with contact info, project requests, appointments, messages	CRM show view renders all sections; GET /crm/:id returns 302 to login (auth gated); tests confirm detail content	PASS	GET /crm/1 -> 302; tests: "admin can view business detail", "business detail shows contact info", "business detail shows project requests" pass
5	Lead-to-client promotion with Keycloak integration	POST /crm/:id/promote route; controller calls KeycloakAdminService.promote_to_client; error handling for Keycloak failures; 4 promotion tests pass	PASS	POST /crm/1/promote -> 422 (CSRF, route exists); tests: promote lead, already-client alert, Keycloak success, Keycloak failure all pass
6	Paper Trail audit on promotions	Lead model has has_paper_trail only: [:role, :promoted_at]; test confirms whodunnit recorded	PASS	Test: "promote records whodunnit in paper trail" passes; versions migration deployed
7	Pod deployed and healthy	kubectl get pods; ArgoCD status	PASS	Pod Running, 0 restarts; ArgoCD: Synced, Healthy; image tag matches HEAD
8	Routes deployed and responsive	curl all 3 CRM routes + health check + regression routes	PASS	/up -> 200; /crm -> 302; /crm/:id -> 302; POST /crm/:id/promote -> 422 (CSRF, expected)

Regression Check

All other routes healthy:

• / (landing) -> 200
• /about -> 200
• /leads/new -> 200
• /catalog -> 302 (auth required, correct)
• /communications -> 302 (auth required, correct)
• /appointments/new -> 302 (auth required, correct)
• Landing page screenshot confirms app is live and rendering correctly

Brakeman security scan: 0 warnings. Rubocop: pass at error level.

Pipeline Note

Pipeline #185 (merge commit for #112) reports overall "failure" but every step (clone, bundle-install, lint, security, test, build-and-push) completed with exit_code 0. This appears to be a Woodpecker reporting anomaly. Pipeline #188 (subsequent push to main including #112 code) is fully green.

Visual Check Limitation

Cannot authenticate via browser to view /crm as admin because login redirects to App Store (by design -- auth is iOS-app-only via Keycloak). Route-level smoke tests and CI test assertions provide equivalent coverage.

Discovered Issues

Pipeline #185 Woodpecker anomaly: all steps pass but pipeline reports failure. This is not a regression from this PR -- it may be a known Woodpecker issue. No new Forgejo issue warranted as the subsequent pipeline (#188) runs green and the behavior is transient.

Verdict: PASS

Ticket

ldraney/postmark-server-sdk#2 — SDK implementation: Python client + pytest suite for all 43 Server API endpoints. Merged via PR #5. Board item #1914 on board-postmark.

Environment

Local validation against live Postmark API (api.postmarkapp.com). Repo cloned to /tmp/postmark-server-sdk-validation from origin/main. Python 3.14.5, pytest 9.1.1. Server token: ISS (intelligentstaffingsystems) Postmark server. Repo type: SDK (Python library — not a deployed service).

Deployment Evidence

For an SDK repo, "deployment" = merge commit present on origin/main. "Production verification" = tests pass against real Postmark API.

Merge commit on origin/main

$ git fetch origin && git log --oneline -1 origin/main
3c39076 Sprint 2: SDK implementation — 43 endpoints, 7 groups, integration tests (#5)

Full hash: 3c390760b31d40a5da1dbd337c04396e05640fd7

Package install

$ pip install -e ".[dev]"
Successfully installed postmark-server-sdk-0.1.0 httpx-0.28.1 pytest-9.1.1 python-dotenv-1.2.2 ruff-0.16.0

pytest output against live Postmark API

$ pytest tests/ -v
============================= test session starts ==============================
platform linux -- Python 3.14.5, pytest-9.1.1, pluggy-1.6.0
collected 43 items

tests/test_bounces.py::test_get_bounces PASSED
tests/test_bounces.py::test_get_single_bounce PASSED
tests/test_bounces.py::test_activate_bounce PASSED
tests/test_bounces.py::test_get_bounce_dump PASSED
tests/test_bounces.py::test_get_delivery_stats PASSED
tests/test_inbound_rules.py::test_list_inbound_rules PASSED
tests/test_inbound_rules.py::test_create_inbound_rule PASSED
tests/test_inbound_rules.py::test_delete_inbound_rule PASSED
tests/test_messages.py::test_search_outbound_messages PASSED
tests/test_messages.py::test_get_outbound_message_details PASSED
tests/test_messages.py::test_get_outbound_message_dump PASSED
tests/test_messages.py::test_search_outbound_opens PASSED
tests/test_messages.py::test_get_outbound_message_opens SKIPPED (No open events)
tests/test_messages.py::test_search_outbound_clicks PASSED
tests/test_messages.py::test_get_outbound_message_clicks SKIPPED (No click events)
tests/test_messages.py::test_search_inbound_messages PASSED
tests/test_messages.py::test_get_inbound_message_details SKIPPED (No inbound messages)
tests/test_messages.py::test_bypass_inbound_message SKIPPED (No blocked messages)
tests/test_messages.py::test_retry_inbound_message SKIPPED (No failed messages)
tests/test_sending.py::test_send_email PASSED
tests/test_sending.py::test_send_email_batch PASSED
tests/test_sending.py::test_send_email_with_template PASSED
tests/test_sending.py::test_send_email_batch_with_templates PASSED
tests/test_server.py::test_get_server_configuration PASSED
tests/test_server.py::test_edit_server_configuration PASSED
tests/test_stats.py::test_get_outbound_overview PASSED
tests/test_stats.py::test_get_sent_counts PASSED
tests/test_stats.py::test_get_bounce_counts PASSED
tests/test_stats.py::test_get_spam_complaints PASSED
tests/test_stats.py::test_get_tracked_counts PASSED
tests/test_stats.py::test_get_open_counts PASSED
tests/test_stats.py::test_get_open_counts_by_email_client PASSED
tests/test_stats.py::test_get_open_counts_by_platform PASSED
tests/test_stats.py::test_get_click_counts PASSED
tests/test_stats.py::test_get_click_counts_by_browser_family PASSED
tests/test_stats.py::test_get_click_counts_by_location PASSED
tests/test_stats.py::test_get_click_counts_by_platform PASSED
tests/test_templates.py::test_list_templates PASSED
tests/test_templates.py::test_create_template PASSED
tests/test_templates.py::test_get_template PASSED
tests/test_templates.py::test_update_template PASSED
tests/test_templates.py::test_validate_template PASSED
tests/test_templates.py::test_delete_template PASSED

======================== 38 passed, 5 skipped in 5.30s =========================

Lint verification

$ ruff check src/ tests/
All checks passed!

$ ruff format --check src/ tests/
18 files already formatted

Checks

#	Criterion	How Verified	Result	Evidence
1	Merge commit present on origin/main	git log --oneline -1 origin/main	PASS	3c39076 — squash-merge of PR #5
2	Package installs cleanly	pip install -e ".[dev]" in fresh venv	PASS	postmark-server-sdk-0.1.0 installed with all deps
3	All 7 endpoint groups implemented	find src/ -name "*.py"	PASS	sending, bounces, messages, templates, stats, server, inbound_rules
4	All 7 test files present	find tests/ -name "test_*.py"	PASS	7 test files matching 7 source modules
5	Tests pass against live Postmark API	pytest tests/ -v	PASS	38 passed, 5 skipped in 5.30s (see full output above)
6	PostmarkClient composes all domain APIs	Read client.py	PASS	7 mixins composed via MRO inheritance
7	pyproject.toml configured correctly	Read pyproject.toml	PASS	hatchling build, httpx dep, pytest+ruff dev deps
8	ruff check passes clean	ruff check src/ tests/	PASS	"All checks passed!"
9	ruff format passes clean	ruff format --check src/ tests/	PASS	"18 files already formatted"
10	POSTMARK_SERVER_TOKEN only required env var	Reviewed client.py constructor	PASS	Single env var, no other config needed

Regression Check

Full 43-test integration suite against live Postmark API serves as regression. All 7 endpoint groups exercised end-to-end: emails sent and verified, bounces queried, messages searched, templates CRUD lifecycle, stats retrieved across 12 sub-endpoints, server config read/modified/restored, inbound rules created/deleted. No regressions detected.

Discovered Issues

None. Woodpecker CI pipeline (issue #3) is tracked separately as a distinct board item.

What it covers

The MCP tools layer across all MCP servers — the tool definitions that Claude Code sessions and agents use to interact with external systems. Distinct from the MCP server infrastructure (arch:mcp) which covers the server process lifecycle.

Components

MCP Server	Repo	Tool Module
forgejo	ldraney/forgejo-mcp	src/forgejo_mcp/tools/workflows.py
pal-e-docs	ldraney/pal-e-docs	Django MCP app
woodpecker	ldraney/woodpecker-mcp	Woodpecker CI tools

Pattern

Each MCP tool follows the same shape: @mcp.tool() decorator, Annotated params with Field descriptions, JSON return, _error_response on exception. Tools are the agent-facing API — they determine what agents can and cannot do with external systems.

Why it matters

Missing tools force agents into unreliable fallbacks (e.g. curl with tokens from .mcp.json that aren't in the shell env). Every operation an agent needs must be exposed as an MCP tool.

Related

• arch-mcp — MCP server infrastructure (process lifecycle, not tools)
• convention-architecture-ids — defines arch:mcp-tools label

Verdict: PARTIAL

Ticket

ldraney/intelligentstaffingsystems#79 — DNS A record and Caddy vhost for dev.intelligentstaffingsystems.ai (decomp of #77, sprint:B infra)

Merged PR: ldraney/pal-e-platform#543

Environment

Production edge proxy at 178.156.129.142 (Hetzner edge). Caddy reverse proxy managed via terraform in pal-e-platform. ArgoCD application intelligentstaffingsystems in namespace intelligentstaffingsystems.

Checks

#	Criterion	How Verified	Result	Evidence
1	DNS A record for dev.intelligentstaffingsystems.ai points to edge proxy	curl -v (DNS resolution output)	PASS	IPv4: 178.156.129.142 confirmed in verbose curl output
2	Caddy vhost configured for dev subdomain	curl http://dev.intelligentstaffingsystems.ai/	PASS	HTTP 308 redirect to https://dev.intelligentstaffingsystems.ai/ — vhost exists and routes
3	Dev domain accessible over HTTPS	curl https://dev.intelligentstaffingsystems.ai/	FAIL	TLS handshake error: "tlsv1 alert internal error" — Caddy cannot provision Let's Encrypt cert
4	ArgoCD application synced and healthy	kubectl get application -n argocd	PASS	Sync: Synced, Health: Healthy
5	Pod running, no crash loops	kubectl get pods -n intelligentstaffingsystems	PASS	1/1 Running, 0 restarts, 6h55m uptime

Regression Check

Production domain unaffected:

• https://intelligentstaffingsystems.ai/ returns HTTP 200 with valid Let's Encrypt cert (expires Oct 5, 2026)
• /up health endpoint returns HTTP 200
• Landing page renders correctly with all CSS assets
• Pod image matches latest main commit: dc97ba0

Discovered Issues

TLS certificate provisioning for dev.intelligentstaffingsystems.ai is broken. Already tracked as issue #98 ("Fix TLS cert for dev.intelligentstaffingsystems.ai + deploy register.ftl to Keycloak configmap"). The DNS record and Caddy vhost (the explicit deliverables of #79) are deployed and functional, but the dev environment is not usable over HTTPS until #98 is resolved.

Verdict: PASS

Ticket

ldraney/intelligentstaffingsystems#86 — Dev environment setup: shared Keycloak auth config, ephemeral DB via make reset, dev URL hostname allowlisting, migration practices documentation, and port convention (9999 dev / 3000 prod).

Merged PR: #94

Environment

Production cluster (k3s, archbox node), namespace intelligentstaffingsystems. URL: https://intelligentstaffingsystems.ai. ArgoCD-managed deployment.

Checks

#	Criterion	How Verified	Result	Evidence
1	CI pipeline green for merge commit	Woodpecker pipeline #116 (push event, branch main)	PASS	Pipeline #116 status: success, message: "feat: dev environment — shared Keycloak, ephemeral DB, dev URL, migration docs (#94)"
2	Image tag propagated to running pod	kubectl get pods -n intelligentstaffingsystems -o jsonpath='{.items[*].spec.containers[*].image}'	PASS	harbor.tail5b443a.ts.net/intelligentstaffingsystems/app:dc97ba0a017aad90140d68fcd41267197433e716 — matches merge commit dc97ba0
3	Pod running and ready, 0 restarts	kubectl get pods -n intelligentstaffingsystems	PASS	intelligentstaffingsystems-5ddd4556dd-nbbjd 1/1 Running 0 6h53m
4	Health endpoint returns 200	curl -s -o /dev/null -w "%{http_code}" https://intelligentstaffingsystems.ai/up	PASS	HTTP 200
5	ArgoCD sync and health	kubectl get application -n argocd intelligentstaffingsystems	PASS	sync.status: Synced, health.status: Healthy
6	Production root URL responds	curl -s -o /dev/null -w "%{http_code}" https://intelligentstaffingsystems.ai/	PASS	HTTP 200
7	dev.intelligentstaffingsystems.ai in config.hosts (production.rb)	File inspection: config/environments/production.rb line 88	PASS	config.hosts << "dev.intelligentstaffingsystems.ai" present
8	Port convention: dev on 9999, prod on 3000	docker-compose.yml port mapping + kubectl svc	PASS	docker-compose: ports 9999:9999; k8s svc: ClusterIP 3000/TCP
9	.env.development.example exists with Keycloak vars	File inspection	PASS	File present with KEYCLOAK_URL, KEYCLOAK_REALM, KEYCLOAK_CLIENT_ID, KEYCLOAK_CLIENT_SECRET placeholders
10	make reset target for ephemeral DB	Makefile inspection	PASS	reset: $(RUN) rails db:drop db:create db:migrate db:seed

Tiers Executed

• Tier 1 (Local): SKIPPED — Docker tests hang locally (known issue #65). CI pipeline #116 green serves as equivalent (runs full test suite in containerized CI).
• Tier 3 (Production): PASS — Pod deployed with correct image, health endpoint healthy, ArgoCD synced and healthy.

Regression Check

Production app continues to serve at https://intelligentstaffingsystems.ai/ (200). No crash loops, 0 restarts on the pod. ArgoCD reports Healthy state. The only production code change was a single line adding dev.intelligentstaffingsystems.ai to the Rails allowed hosts list — no logic changes that could regress existing functionality.

Discovered Issues

dev.intelligentstaffingsystems.ai TLS handshake failure: DNS resolves correctly to 178.156.129.142 (Hetzner edge), but the TLS handshake fails with "tlsv1 alert internal error". The Caddy reverse proxy on the edge VPS does not have a certificate provisioned for this subdomain. HTTP returns 308 (redirect to HTTPS), confirming the vhost exists but lacks TLS. This is an infrastructure-level issue (Caddy cert config) outside the scope of this Rails ticket, which correctly added the hostname to config.hosts. Recommend creating a separate infra ticket for Caddy TLS provisioning on the dev subdomain.

Verdict: PARTIAL

Ticket

intelligentstaffingsystems#78 — Create prod and dev kustomize overlays for ISS in pal-e-deployments. Merged via pal-e-deployments#234.

Environment

Production cluster, namespace intelligentstaffingsystems, ArgoCD application intelligentstaffingsystems sourcing from overlays/intelligentstaffingsystems/prod in pal-e-deployments. Public URL: https://intelligentstaffingsystems.ai.

Checks

#	Criterion	How Verified	Result	Evidence
1	ArgoCD syncs the prod overlay	kubectl get application -n argocd intelligentstaffingsystems -o jsonpath='{.status.sync.status}'	PASS	Returns Synced. Source path: overlays/intelligentstaffingsystems/prod from pal-e-deployments.
2	ArgoCD application is healthy	kubectl get application -n argocd intelligentstaffingsystems -o jsonpath='{.status.health.status}'	FAIL	Returns Degraded. Deployment resource is degraded; Service is Healthy; Secret and ServiceMonitor are synced.
3	Pods running new image, not crash-looping	kubectl get pods -n intelligentstaffingsystems	FAIL	Two pods exist: intelligentstaffingsystems-6d6896dd95-ls9k4 (1/1 Running, 0 restarts, 11h old) and intelligentstaffingsystems-8474c67bc8-nxphp (0/1 Init:CrashLoopBackOff, 13 restarts). Both use image harbor.tail5b443a.ts.net/intelligentstaffingsystems/app:93b9a79b8a88cbb07a7f8fda1b6d85803580cbbb.
4	Secret values are correct (not placeholders)	kubectl get secret -n intelligentstaffingsystems intelligentstaffingsystems-secrets (decoded)	FAIL	Four keys contain placeholder values: POSTGRES_HOST=PLACEHOLDER_POSTGRES_HOST, POSTGRES_USER=PLACEHOLDER_POSTGRES_USER, APP_URL=PLACEHOLDER_APP_URL, POSTMARK_API_TOKEN=PLACEHOLDER_POSTMARK_API_TOKEN. Keycloak keys are correctly populated.
5	Production site accessible	curl -sk -o /dev/null -w "%{http_code}" https://intelligentstaffingsystems.ai/	PASS	Returns HTTP 200. Site loads correctly from the old pod that cached correct secret values at startup.
6	Dev overlay deployed via ArgoCD	kubectl get applications -n argocd filtered for ISS	FAIL	Only intelligentstaffingsystems (prod) exists. No dev ArgoCD Application found. No intelligentstaffingsystems-dev namespace exists either.

Root Cause Analysis

The kustomize overlay in PR #234 includes a Secret manifest with placeholder values. When ArgoCD synced, it overwrote the previously-manually-populated secret with the placeholder values from the overlay. The old pod (replicaset 6d6896dd95) survives because Kubernetes does not restart running pods when referenced secrets change (for secretKeyRef env vars). The new pod (replicaset 8474c67bc8) picks up the placeholder values at creation time and the migrate init container fails with ActiveRecord::DatabaseConnectionError: There is an issue connecting with your hostname: PLACEHOLDER_POSTGRES_HOST.

The deployment shows ProgressDeadlineExceeded on the new replicaset.

Regression Check

The production site (https://intelligentstaffingsystems.ai) remains accessible via the old pod. However, this is fragile: any pod restart, scaling event, or deployment rollout will cause all pods to pick up the placeholder secrets and crash. The next ISS image push from Woodpecker CI will trigger a rollout that replaces the old working pod, taking the site down.

Discovered Issues

• Placeholder secrets in kustomize overlay: The Secret manifest in overlays/intelligentstaffingsystems/prod contains placeholder values for POSTGRES_HOST, POSTGRES_USER, APP_URL, and POSTMARK_API_TOKEN. These must be replaced with actual values, either via SealedSecrets, manual kubectl apply, or removing the Secret from the overlay and managing it out-of-band.
• No dev ArgoCD Application: The dev overlay may exist in the pal-e-deployments repo, but no ArgoCD Application deploys it. A dev ArgoCD app and namespace need to be created.
• Imminent production risk: The next CI image push will trigger a full rollout, replacing the old working pod and causing a production outage due to the placeholder secrets.

Verdict: FAIL

Ticket

ldraney/intelligentstaffingsystems#51 (PR #83) — Projects tab with project request form and status cards. Board item #1821 on board-iss.

Environment

Production cluster, namespace intelligentstaffingsystems. Production URL: https://intelligentstaffingsystems.ai. Tiers executed: Tier 1 (code review — Docker tests blocked per #65) + Tier 3 (prod health check).

Checks

#	Criterion	How Verified	Result	Evidence
1	Projects tab accessible to all authenticated roles (lead, client, admin)	Code review: controller inherits ApplicationController (requires auth). Tests verify lead/client/admin all get 200.	PASS (Tier 1)	projects_controller_test.rb lines 15-31
2	"Request a Project" button prominent at top of page	Code review: index.html.erb line 19 renders btn-gold link at top. Test asserts presence.	PASS (Tier 1)	index.html.erb line 19; test line 80
3	Request form captures: business name (pre-filled), description, target audience, inspiration	Code review: new.html.erb has all four fields. Business name is disabled/pre-filled from current_lead.	PASS (Tier 1)	new.html.erb lines 26-46
4	Form submission creates ProjectRequest with lead_id	Code review: controller sets lead from session. Tests verify lead_id set from session, not params.	PASS (Tier 1)	projects_controller.rb lines 19-22; test lines 152-163
5	Empty state for users with no projects	Code review: index.html.erb renders "No projects yet" heading + request button when empty.	PASS (Tier 1)	index.html.erb lines 29-40; test lines 49-59
6	Project cards with name, status, description (submitted/active/completed)	Code review: _project_card.html.erb renders all fields. Model validates status in [submitted, active, completed].	PASS (Tier 1)	_project_card.html.erb; project_request.rb line 4
7	Form validation: description required, length limits	Code review: Model validates presence + max 5000. Tests cover boundary values. Controller returns 422 on invalid.	PASS (Tier 1)	project_request.rb line 9; model test lines 37-58; controller test lines 176-187
8	Success message after submission	Code review: Controller redirects with notice "Project request submitted!". Test asserts flash-notice with /submitted/.	PASS (Tier 1)	projects_controller.rb line 24; test line 135
9	/projects route accessible in production	curl -s -o /dev/null -w "%{http_code}" https://intelligentstaffingsystems.ai/projects	FAIL (Tier 3)	Returns HTTP 404. Code not deployed.
10	Woodpecker pipeline green for merge commit	mcp__woodpecker__list_pipelines — pipeline #89 (merge commit) status: failure	FAIL (Tier 3)	Pipeline #89 and #90 both fail at test step: cannot load such file -- minitest/mock (LoadError)
11	New image tag propagated to running pod	kubectl get pods — image tag 93b9a79b (commit: "fix: align pipeline push repo") — old image, not merge commit	FAIL (Tier 3)	Running pod image is from pre-Sprint-B commit. Last successful pipeline: #18.
12	Pod running and healthy	kubectl get pods — old pod Running (0 restarts), new pod Init:CrashLoopBackOff	FAIL (Tier 3)	New pod intelligentstaffingsystems-8474c67bc8-nxphp migrate init container fails: PLACEHOLDER_POSTGRES_HOST

Regression Check

Root URL (/) returns 200 — base app is serving. However, /catalog returns 302 (auth redirect expected), /communications returns 404, /projects returns 404. All Sprint B routes are absent from the running production pod because it runs pre-Sprint-B code.

Discovered Issues

1. CI pipeline broken (pre-existing): All pipelines since #21 have failed. The test step fails with cannot load such file -- minitest/mock (LoadError) in Ruby 3.4. This blocks all image builds and deployments. This is a pre-existing issue not caused by this PR.
2. New pod CrashLoopBackOff: The migrate init container on the new deployment pod fails because POSTGRES_HOST is set to PLACEHOLDER_POSTGRES_HOST. The Kubernetes secret intelligentstaffingsystems-secrets likely contains placeholder values instead of real credentials. This deployment config issue prevents any new pod from starting.
3. All Sprint B features undeployed: Since CI has been broken since pipeline #21, none of the Sprint B merges (PRs #73, #74, #76, #81, #82, #83, #84) have been deployed to production.

Root Causes

Two independent blockers prevent deployment:

1. minitest/mock not available in CI's Ruby 3.4 bundled gems — needs gem "minitest" in Gemfile or CI base image update.
2. Kubernetes secret intelligentstaffingsystems-secrets has placeholder DB host — needs real CNPG connection string.

Verdict: FAIL

Re-validated 2026-07-17. Previous validation also FAIL. Root cause unchanged: CI pipeline broken, production deployment stale.

Ticket

ldraney/intelligentstaffingsystems#58 (PR #74) — Landing page rewrite: replace "Book an Appointment" CTA with App Store download badge, add target audience section, update journey steps to lead with "Download the App."

Board item #1830 on board-iss.

Environment

Production: https://intelligentstaffingsystems.ai
Validation tiers executed: Tier 1 (codebase review) + Tier 3 (production browser verification via Playwright)
Repo type: frontend

Checks

#	Criterion	How Verified	Result	Evidence
1	Landing page is public (no auth required)	Playwright: opened https://intelligentstaffingsystems.ai/	PASS	Page loads at root URL without authentication. Title: "Intelligence Staffing Systems — Enterprise infrastructure for small businesses"
2	ISS pitch clearly communicated: three pillars, what ISS builds, who it's for	Playwright screenshot + accessibility snapshot	PARTIAL	Three pillars (Web Presence, Operations, Internal Tooling) visible with icons and descriptions. However, audience section ("Built for businesses like yours" — Farmers Market Vendors, Sports Programs, Local Shops) is MISSING from production. Exists in codebase at commit 035d838 but not deployed.
3	Prominent App Store download button/badge as primary CTA	Playwright screenshot + snapshot	FAIL	Production hero shows "Book an Appointment" button (link to #book). App Store SVG badges exist in codebase (_app_store_badge.html.erb partial) but not deployed. Two App Store CTAs in template (hero + bottom) replaced by two "Book an Appointment" buttons in production.
4	App Store link opens App Store (or TestFlight during beta)	Playwright: inspected CTA link hrefs	FAIL	Hero CTA href: https://intelligentstaffingsystems.ai/#book. Should be: https://testflight.apple.com/join/intelligentstaffingsystems (ApplicationHelper::APP_STORE_URL).
5	No login/register form on the website — auth happens in-app only	Playwright: navigated to /login, took screenshot	FAIL	/login renders "Intelligence Staffing Systems" heading, "Sign in to continue" text, and "Sign in with Keycloak" button. Should redirect (302) to App Store URL per merged SessionsController#new.
6	Website login route redirects to App Store download (not Keycloak)	Playwright: /login page stayed at /login URL	FAIL	No redirect occurred. URL remained at /login. Merged code has redirect_to ApplicationHelper::APP_STORE_URL, allow_other_host: true, status: :found but this is not deployed.
7	Responsive, mobile-first	CSS review of pages.css in codebase	PASS (code only)	Mobile-first grid layout: 1fr default columns, @media (min-width: 600px) breakpoint expands to repeat(3, 1fr). Cannot verify in production since deployed code differs from codebase.
8	Target audience messaging: farmers market vendors, sports programs, local businesses	Playwright accessibility snapshot	FAIL	Audience section with "Farmers Market Vendors", "Sports Programs", "Local Shops & Services" cards not present in production DOM. Section exists in codebase landing.html.erb lines 34-68.
9	Endpoint test: landing page loads (200, public)	Playwright: root URL loaded successfully	PASS	Root URL returns 200, renders without auth redirect.
10	Endpoint test: login route redirects to App Store URL (302)	Playwright: /login URL	FAIL	/login renders a page (200) instead of redirecting (302) to App Store URL.
11	Endpoint test: no Keycloak redirect from website login	Playwright: /login page snapshot	FAIL	/login page contains button "Sign in with Keycloak" — direct Keycloak integration still present.
12	Woodpecker pipeline green for merge commit	Woodpecker API: list_pipelines	FAIL	Pipeline #90 (latest on main) status: failure. Error: cannot load such file -- minitest/mock (LoadError). All 5 most recent main-branch pipelines (#85-#90) show failure status.

Summary: 3 PASS, 1 PARTIAL, 8 FAIL

Codebase Verification (Tier 1)

The merged codebase is correct. All acceptance criteria are properly implemented in code:

• app/views/pages/landing.html.erb — App Store badges, audience section, updated journey steps all present
• app/views/shared/_app_store_badge.html.erb — SVG badge partial with dark/light variants
• app/controllers/sessions_controller.rb — #new redirects to APP_STORE_URL with status: :found
• app/helpers/application_helper.rb — APP_STORE_URL = "https://testflight.apple.com/join/intelligentstaffingsystems"
• test/controllers/pages_controller_test.rb — 8 tests covering all ACs (public access, three pillars, App Store CTA, no login form, audience cards)
• test/controllers/sessions_controller_test.rb — Tests for App Store redirect from /login and no Keycloak redirect

Regression Check

The production site's existing functionality (pre-PR#74 landing page) is still operational — root URL loads with three pillars, "How it works", and offer section intact. No regressions to the currently deployed version. The stale deployment has not introduced new breakage.

Root Cause

The merged code (commit 035d838) has not been deployed to production. The CI/CD pipeline is broken:

1. CI pipeline failure: Woodpecker pipeline #90 (and all recent pipelines) fail with cannot load such file -- minitest/mock (LoadError) in the test step. This is a Ruby 3.4 gem dependency issue — minitest/mock was moved to a bundled gem and requires explicit inclusion in the Gemfile.
2. No image built: Because CI fails at the test step, the build-and-push step is skipped. No new container image is pushed to Harbor.
3. ArgoCD Image Updater has nothing to pull: Without a new image tag, the Image Updater cannot trigger a deployment.
4. Push event gap: Per project memory, Forgejo squash merges may not reliably trigger Woodpecker push events, compounding the issue.

Discovered Issues

1. CI pipeline broken — blocks ALL deployments: The minitest/mock LoadError prevents all test runs in CI. This is not specific to this ticket; it blocks deployment of every merged PR. The fix: add gem "minitest" (with mock support) to the Gemfile, or add require "minitest/mock" with proper gem resolution in test_helper.rb.
2. Production deployment drift — 8+ undeployed commits: At least commits from 035d838 through ca24329 are merged but undeployed: landing page (#74), tab bar restructure (#73), Messages fix (#76), Makefile/seed (#81), Communications tab (#82), Projects tab (#83), Catalog tab (#84), and CI blocker fix (ca24329).

Verdict: PARTIAL

Ticket

ldraney/intelligentstaffingsystems#79 — dev.intelligentstaffingsystems.ai DNS CNAME record and Caddy vhost for local dev environment. Merged via pal-e-platform#543. Board item #1870 on board-iss.

Environment

Validation targets: GoDaddy DNS (via Terraform GoDaddy provider), edge server Caddy (via SaltStack pillar), public DNS resolvers (Google DNS API). Repo type: terraform (pal-e-platform).

Checks

#	Criterion	How Verified	Result	Evidence
1	dev.intelligentstaffingsystems.ai DNS CNAME record exists in terraform/dns.tf	Fetched PR #543 diff from Forgejo	PASS	PR diff shows resource "godaddy_dns_record" "iss_dev" with type=CNAME, name="dev", data="intelligentstaffingsystems.ai", TTL=600
2	Caddy vhost configured in salt/pillar/caddy.sls with correct proxy_target	Fetched PR #543 diff from Forgejo	PASS	PR diff shows iss-dev entry: domain=dev.intelligentstaffingsystems.ai, proxy_target=intelligentstaffingsystems-dev.tail5b443a.ts.net, www_redirect=false
3	dig dev.intelligentstaffingsystems.ai returns expected record after terraform apply	Google DNS API (dns.google/resolve) for CNAME and A records; Python socket.getaddrinfo	FAIL	NXDOMAIN (Status: 3) from Google DNS for both CNAME and A queries. Python resolution: "Name or service not known". Root cause: tofu apply has not been run since merge — known push event gap (Forgejo squash merges do not trigger Woodpecker push events).
4	Local dev environment accessible via dev.intelligentstaffingsystems.ai when dev tunnel is active	curl with --resolve to edge IP 178.156.129.142; direct curl	BLOCKED	DNS does not resolve (AC3 fail), so direct access impossible. curl to edge IP with Host header returned TLS handshake failure (exit 35) — Caddy has no cert for this domain (ACME cannot validate without DNS). Salt highstate may also not have been applied.

Regression Check

Main production domain intelligentstaffingsystems.ai resolves correctly (178.156.129.142) and returns HTTP 200 with correct page title. No regression on existing DNS or Caddy configuration.

Pipeline Status

Woodpecker pipeline #1489 (most recent manual on main): killed, all steps skipped. Pipeline #1470 (last successful manual on main): ran clone and build-and-push only, no apply step. No push event was triggered on main for the merge, consistent with the known Forgejo squash-merge push event gap.

Pending Actions

• Trigger manual Woodpecker pipeline on pal-e-platform main to run tofu apply — this will create the GoDaddy DNS CNAME record.
• Run salt highstate on the edge server to deploy the Caddy vhost configuration.
• Re-validate AC3 and AC4 after apply completes: confirm DNS resolves and dev environment is accessible.

Discovered Issues

No new issues. The blocking condition (terraform not applied) is a known operational gap documented in project memory (Push Event Gap). The code changes are correct and complete.

Verdict: PASS

Ticket

ldraney/intelligentstaffingsystems#80 (PR #81) — Added Makefile (dev entry point), expanded idempotent seed data (Leads, CatalogEntries, Messages), and updated docs (local-dev-setup.md, architecture.md, pipeline.md, README.md).

Board item: #1871 on board-iss. Merge commit: e11e04a.

Environment

Production k3s cluster, namespace intelligentstaffingsystems. Public URL: https://intelligentstaffingsystems.ai. ArgoCD application: intelligentstaffingsystems.

Changes are developer-facing only (Makefile, seed data, docs) — zero production runtime impact. Validation covers code correctness on main plus production health (no regression).

Checks

#	Criterion	How Verified	Result	Evidence
1	Makefile exists with all expected targets (help, dev, down, logs, setup, migrate, seed, console, test, lint, security, ci)	Read Makefile on main	PASS	66-line Makefile present with all 12 targets. .DEFAULT_GOAL := help. Uses docker compose run --rm web pattern.
2	db/seeds.rb is idempotent and creates representative data	Read db/seeds.rb on main	PASS	Seeds 4 Leads (admin, client, 2 leads), 3 CatalogEntries (one per pillar), and sample Message threads. Uses find_or_create_by! throughout for idempotency.
3	docs/local-dev-setup.md documents Makefile usage	Read docs/local-dev-setup.md on main	PASS	Full Makefile target table, prerequisites section, first-time setup, running instructions, raw docker compose equivalents. References Makefile as "single entry point."
4	README.md updated with Makefile references	Read README.md on main	PASS	Local development section references make setup, make dev, make logs, make ci.
5	docs/architecture.md and docs/pipeline.md updated	Read both docs on main	PASS	Architecture shows ISS namespace topology. Pipeline shows local dev with docker-compose on :9999.
6	Production app is healthy (no regression from merge)	kubectl get pods + curl	PASS	Pod intelligentstaffingsystems-6d6896dd95-ls9k4: 1/1 Running, 0 restarts. Root URL returns HTTP 200. Title: "Intelligence Staffing Systems — Enterprise infrastructure for small businesses".
7	Woodpecker pipeline green for merge commit	Woodpecker list_pipelines	N/A	No push pipeline triggered for merge commit e11e04a (known gap: Forgejo squash merges don't trigger Woodpecker push events). Changes are developer-facing only — no new image build required.

Regression Check

Production site verified healthy:

• GET / — HTTP 200, correct page title and CSS assets loading
• GET /catalog — HTTP 302 (auth redirect, expected)
• Deployment: 1/1 READY, 1 available
• ArgoCD sync status: Synced (health: Degraded due to unrelated crash-looping pod)

No regression from this PR. Changes are Makefile, seeds, and docs — they do not alter application runtime behavior.

Discovered Issues

These are pre-existing issues, not introduced by PR #81:

1. Crash-looping pod: intelligentstaffingsystems-8474c67bc8-nxphp in Init:CrashLoopBackOff. Init container (migrate) fails with PLACEHOLDER_POSTGRES_HOST — deployment config has a placeholder database hostname instead of a real one. Causes ArgoCD to report Degraded.
2. CI pipeline failures: All recent Woodpecker pipelines show failure. Pipeline #90 (most recent, commit ca24329) fails in the test step with a require error. This is a pre-existing CI issue.
3. Push event gap: Forgejo squash merges not triggering Woodpecker push events (known issue per project memory).

Verdict: PARTIAL

Ticket

svc#184 (PR #187) — Add login_theme = "iss" and verify_email = true to the ISS Keycloak realm config in pal-e-services terraform.

Board item: #1864 on board-iss

Environment

Production cluster. Keycloak at keycloak.tail5b443a.ts.net, ISS realm name iss. ISS app at intelligentstaffingsystems.tail5b443a.ts.net.

Checks

#	Criterion	How Verified	Result	Evidence
1	CI pipeline green for merge commit	Woodpecker pipeline #234 (push/main)	PASS	Pipeline #234 status=success. Steps: clone (success), apply (success), cross-pillar-review (success).
2	tofu apply succeeds	Pipeline #234 apply step logs	PASS	Apply complete! Resources: 0 added, 3 changed, 0 destroyed. (3 changes were unrelated ArgoCD label drift on mdview/gcal-scheduler.)
3	Terraform code wires login_theme and verify_email to keycloak_realm	Read keycloak.tf lines 35-36; variables.tf lines 144, 149	PASS	login_theme = each.value.login_theme and verify_email = each.value.verify_email on keycloak_realm.this. Variable type: optional(string) and optional(bool, false).
4	Example tfvars includes ISS realm with login_theme and verify_email	Read k3s.tfvars.example lines 88-104	PASS	ISS realm block has verify_email = true (line 93) and login_theme = "iss" (line 94).
5	ISS Keycloak theme files deployed (platform#541 dependency)	kubectl exec -n keycloak deploy/keycloak -- find /opt/keycloak/themes/iss -type f	PASS	Theme files present: theme.properties, resources/css/login.css, resources/img/logo.svg. Deployed 2026-07-17 18:05.
6	ISS realm login_theme = "iss" in Keycloak	Keycloak Admin API: GET /admin/realms/iss	FAIL	loginTheme: (default) — not set. The CI apply showed zero Keycloak realm changes, meaning the Woodpecker TFVARS_CONTENT secret does not include login_theme = "iss" for the ISS realm.
7	ISS realm verify_email = true in Keycloak	Keycloak Admin API: GET /admin/realms/iss	FAIL	verifyEmail: False. Same root cause — TFVARS_CONTENT secret not updated.

Root Cause Analysis

PR #187 correctly updates the terraform code and example tfvars to support login_theme and verify_email on the ISS realm. However, the actual CI secret TFVARS_CONTENT (base64-encoded, stored in Woodpecker) has not been updated to include these values. The CI tofu apply ran with the old secret, so the Keycloak realm config was unchanged.

Action required: Update the Woodpecker TFVARS_CONTENT secret for pal-e-services to include login_theme = "iss" and verify_email = true in the ISS realm block, then trigger a manual pipeline run (or push) to apply.

Regression Check

• Keycloak pod: Running, 0 restarts (age: 39m)
• ISS pod: Running, 0 restarts (age: 6h17m)
• Other realm themes unaffected: westside-basketball still has theme=westside, landscaping has theme=landscaping
• ISS app root: HTTP 200
• ISS realm general config: enabled=True, registrationAllowed=True, SMTP configured via Postmark, bruteForceProtected=True

Discovered Issues

1. TFVARS_CONTENT secret out of sync. The Woodpecker CI secret for pal-e-services does not include the login_theme and verify_email fields for the ISS realm. This is the blocking issue. Lucas needs to update the secret manually via the Woodpecker UI, then trigger a pipeline.

Architecture: Documentation

Platform-wide documentation component backing the arch:docs label. Covers docs/ directory content in any project repo: onboarding guides, architecture docs, strategy docs, user stories, and operational runbooks.

Scope

Any ticket that creates or modifies files in a repo's docs/ (or the README/CLAUDE.md docs surface) without changing application code. Documentation-about-a-component (e.g. CI/CD pipeline docs) may use a more specific arch label like arch:ci-pipeline when the doc is tightly coupled to that component.

westside-basketball docs

• docs/consolidation.md — app consolidation plan
• docs/dashboard.md — dashboard layout
• docs/keycloak.md — Keycloak integration
• docs/roles.md — roles and access control
• docs/routes.md — route inventory
• docs/spike-47-actionmailer-gmail-api.md — ActionMailer spike
• docs/stripe-subscription-architecture.md — Stripe subscription design

intelligentstaffingsystems docs

Docs-first repo (Sprint 0 gate: docs merge before any implementation sprint). Tree and roadmap: docs/adoption-plan.md in the repo.

• docs/user-stories.md — roles, client journey, 6 epics, permission matrix
• docs/architecture.md — system, data model, Keycloak, Lead↔Keycloak linking, deployment
• docs/ios.md — Turbo Native companion repo + update model
• docs/security.md, docs/pipeline.md, docs/testing-strategy.md, docs/local-dev-setup.md — Tier 1 adoption (issues #20–#24)

Related

• convention-architecture-ids — arch label registry (Docs / Process category)
• project-iss — ISS project page

Validation & Smoke Testing

End-to-end smoke tests are manual validation runs that verify a full user flow works. Results are documented in the repo's docs/ directory as smoke-test-results.md.

Conventions

• Smoke tests are manual, not CI — they require real infrastructure and user interaction
• Results include: steps executed, timestamps, screenshots, measurements
• Qualitative assessments are acceptable when precise measurement isn't practical

Salt Configuration Management (pal-e-platform)

Host-level configuration is managed via Salt in pal-e-platform/salt/. Salt states run on archbox via salt-call --local state.apply.

Directory Layout

salt/
├── states/          # State modules (packages, nvidia, kernel, etc.)
│   ├── top.sls      # State registry
│   ├── packages/init.sls
│   ├── nvidia/init.sls
│   └── kernel/init.sls
├── pillar/          # Pillar data (config values)
│   ├── top.sls      # Pillar registry
│   └── secrets/     # SOPS-encrypted secrets (*.sls)
└── minion           # Local minion config

Conventions

• Flat pillar files at salt/pillar/ for non-secret config
• SOPS-encrypted secrets go in salt/pillar/secrets/*.sls
• New states must be registered in salt/states/top.sls
• New pillars must be registered in salt/pillar/top.sls
• AUR packages use paru helper

Tailscale Networking Conventions

Public Domain Architecture

Public domains (e.g. westsidekingsandqueens.com) are served via a Hetzner edge-proxy running Caddy for TLS termination (Let's Encrypt ACME). Caddy reverse-proxies to the Tailscale funnel hostname (e.g. westside-basketball.tail5b443a.ts.net:443) on the k8s cluster.

Funnel Ingress Pattern

Each service gets a Tailscale Funnel ingress in its k8s namespace, managed via kustomize overlays in pal-e-deployments. The dev overlay has the ingress pattern to follow. Prod overlays need explicit funnel ingress files.

Two-Hop TLS

Client → Caddy (Let's Encrypt cert) → Tailscale funnel (Tailscale cert) → k8s service. The Caddy Caddyfile on the edge-proxy must have a site block for the public domain pointing to the correct tailnet hostname.

DNS

Public domain DNS (GoDaddy) A records point to the Hetzner edge-proxy IP. Tailnet hostnames are managed by Tailscale automatically.

Terraform IaC Conventions (pal-e-services)

Infrastructure is managed via OpenTofu in pal-e-services/terraform/. Woodpecker CI runs tofu plan on PRs and tofu apply on merge to main.

Services Map Pattern

Services are defined as a map in k3s.tfvars keyed by service name. Each entry provisions: Harbor project + robot accounts, k8s namespace, pull secret, ArgoCD app, and Tailscale funnel ingress. The key name propagates everywhere — renaming requires moved blocks to avoid destroy/recreate.

State Management

When renaming a services map key, use moved blocks in the relevant .tf files to migrate state without destroying resources. Precedent: keycloak.tf moved blocks. Always run tofu plan to verify no unexpected destroys before merging.

Secrets

Woodpecker injects tfvars_content secret containing k3s.tfvars. After any tfvars change, the secret must be synced via Woodpecker UI or API.

Validation: #212 Schedule digest feature flag

Verdict: PASS

PR #213 merged via squash. Feature flag schedule_digest defaults to OFF. Upload button and digest flow are gated behind the flag — no user-visible change in production.

Checks

• QA review: APPROVED (no blockers)
• Feature flag registered in feature_flags.rake
• Controller guards check flag before DB access
• View gating on Week tab upload button
• Tests cover flag-on and flag-off paths

Verdict: PASS

Ticket

ldraney/pal-e-services#101 — Removed stale lifecycle { ignore_changes } block from ArgoCD application terraform resource and cleared stale kustomize.images overrides from 3 apps so Image Updater git write-back deploys propagate correctly.

Merged PR: ldraney/pal-e-services#102 (commit 44490d0)

Board item: #1247 on board-production-pipeline

Environment

Prod cluster (k3s on archbox), ArgoCD namespace, all service namespaces. Tailscale funnel URL: https://landscaping-assistant.tail5b443a.ts.net

Tiers Executed

Tier 1 (local: tofu plan), Tier 3 (prod: kubectl + curl). Tier 2 skipped (no staging environment).

Checks

#	Criterion	How Verified	Result	Evidence
1	Annotations and lifecycle block agree on one write-back strategy	Pulled main (commit 44490d0), inspected services.tf. lifecycle { ignore_changes } block removed entirely. Only git:repocreds annotation remains at line 135.	PASS	grep -n 'lifecycle\|ignore_changes' services.tf returns no matches in the ArgoCD application resource.
2	Stale kustomize.images overrides cleared from all ArgoCD apps	kubectl get application -n argocd {app} -o jsonpath='{.spec.source.kustomize}' for landscaping-assistant, notion-mcp-remote, pal-e-docs	PASS	All 3 apps return empty string (no kustomize override present).
3	Push a test commit, confirm new image deploys without manual intervention	kubectl get deployment landscaping-assistant -n landscaping-assistant -o jsonpath='{.spec.template.spec.containers[0].image}'	PASS	Image tag: harbor.tail5b443a.ts.net/landscaping-assistant/app:86a6ba036e9113b61d28c0519ac331b4ba04d619 — matches expected tag from the test commit. Pod running, 0 restarts.
4	Comment in terraform matches actual behavior	Read services.tf lines 165-176 after merge. Stale comment "Image Updater uses argocd write-back" removed along with lifecycle block.	PASS	No misleading comments remain. Resource goes directly from sync_options to depends_on.

Regression Check

• tofu plan -var-file=k3s.tfvars -lock=false: 0 ArgoCD application changes. Only 2 unrelated harbor-creds label drifts (gcal-scheduler, westsidekingsandqueens — ArgoCD instance label, pre-existing).
• All 10 ArgoCD apps: Synced. 9/10 Healthy. pal-enterprises Degraded (pre-existing, unrelated).
• curl -s -o /dev/null -w "%{http_code}" https://landscaping-assistant.tail5b443a.ts.net returns 200.
• landscaping-assistant pod: 1/1 Running, 0 restarts, age 4h.

Discovered Issues

None. All checks pass cleanly. The pre-existing pal-enterprises Degraded status and harbor-creds label drift are known and unrelated to this ticket.

Verdict: APPROVED

Board item: #1085 (board-pal-e-agency) | Forgejo issue: forgejo_admin/claude-custom#243 | Type: Feature

Template Completeness

• [x] Type — Feature
• [x] Lineage — Lucas decision in pal-e-platform session 2026-04-24, evolution rationale documented
• [x] Repo — forgejo_admin/claude-custom
• [x] User Story — full As/I want/So that
• [x] Context — explains Ava sprawl pattern, Hemingway+military comms inversion, prior precedent
• [x] Environment — repo, hook path, exact line, API base, enumeration tool, prior precedent slug
• [x] File Targets — hook line, CLAUDE.md, pal-e-docs note set (CREATE/UPDATE/BULK UPDATE)
• [x] Test Expectations — 4 verifiable steps
• [x] Checklist — 10 items
• [x] Acceptance Criteria — 7 items
• [x] Constraints — ordering dependency, audit-trail preservation, worktree
• [x] Out of Scope — peer agents, MEMORY.md, Hem persona authorship
• [x] Related — prior precedent, validation note, deprecating note, paradigm, design convention

Traceability

• [x] story:pm-scope — verified in project-pal-e-agency user-stories table (PM/Ava role: triage boards, scope work, dispatch agents, /update-docs). Persona-evolution work directly affects PM execution; appropriate story link.
• [x] arch:agent — backing note agent-paradigm exists (Layer 5: Agents in the 5-layer model). Persona swap at the Agent layer; appropriate arch link.
• [x] Forgejo issue — claude-custom#243 verified open, body fetched, fully populated.
• [x] type:feature, scope:unplanned — labels consistent with ticket type.

File Targets

• [x] ~/.claude/hooks/session-start-context.sh:246 — VERIFIED. Line 246 reads "${PAL_E_API_URL}/notes/agent-ava" 2>/dev/null) || true. Exact one-line patch: agent-ava → agent-hem.
• [x] ~/.claude/CLAUDE.md — VERIFIED. 3 references at lines 1 ("# Ava — Strategic Partner"), 3 ("You are Ava..."), 7 ("get_note(slug=\"agent-ava\")"). All require update.
• [x] agent-ava note — exists (id 998, project pal-e-agency, status active). Will be flipped to deprecated with redirect content.
• [x] agent-hem note — does NOT exist (correct precondition; must be CREATEd before hook repoint per ordering constraint).
• [x] Bulk-update enumeration strategy — search_notes(query="Ava") is the documented enumerator. Filter rule "exclude review-* and validation-*" is explicit. Pattern mirrors validation-247-2026-03-29 (Betty Sue → Ava precedent referenced).

Repo Placement

OK. Code edits go to forgejo_admin/claude-custom (the only Forgejo repo in scope — pal-e-agency project has repo_url: null, so doc edits land via pal-e-docs API only, not a separate Forgejo issue). Single PR on claude-custom + bulk pal-e-docs writes is the correct split.

Dependencies

Hard ordering dependency (already documented in Constraints): create agent-hem note BEFORE patching the hook. Session-start-context.sh fetches the slug at SessionStart; a missing slug yields a silent no-op personality block, which would degrade every new session.

External dependency: persona content authorship is explicitly Out of Scope (the dev agent must produce the Hem definition as part of AC #1). This is a soft scope risk — see Recommendation [SCOPE] below.

No board-level blockers. No item is in in_progress on board-pal-e-agency that conflicts.

Acceptance Criteria

All 7 AC are agent-verifiable: note existence (API GET), line-grep on hook + CLAUDE.md, status field check, search_notes enumeration with exclusion filter, fresh-session inspection, validation note publication. Test Expectations align 1:1 with AC. No untestable criteria.

Blast Radius

Personality injection is platform-wide — every Claude Code session in every repo on this machine reads from session-start-context.sh. A broken slug or malformed Hem persona affects all main-session work until rolled back. Mitigations are present: ordering constraint, validation note as final AC.

20+ doc references per ticket body. The Betty Sue → Ava precedent (validation-247-2026-03-29) is named as the surgical-update template. Risk is acceptable given the proven precedent.

Subagent context inheritance — the SubagentStart hook may inject the personality block into spawned agents. Worth a spot-check during validation that subagents receive Hem context, not stale Ava text. Calling out as a validation hint, not a body fix.

Decomposition Assessment

5-minute rule: File targets = 2 (hook + CLAUDE.md) plus N pal-e-docs notes (~20). Single repo. AC count = 7. Estimated agent time = 15–25 minutes (dominated by bulk doc updates).

Verdict: Borderline. The bulk-doc-update pattern is well-precedented (Betty Sue → Ava ran as a single agent successfully). Splitting would add coordination overhead without quality gain. No decomposition required, but the dev agent should batch the doc-updates phase and the code-edit phase as logical sub-steps within one PR.

Recommendation

APPROVED — ready to advance backlog → todo. Two non-blocking notes for the dev agent (do not require ticket refinement):

• [SCOPE] Persona content authorship is Out of Scope per ticket. Lucas should provide voice exemplars or approve the Hem persona draft before merge — this is a Lucas decision gate, not an agent deliverable boundary issue.
• [BODY] Optional: add an explicit validation step to verify SubagentStart hook injects Hem (not just SessionStart). Not required — covered implicitly by "fresh session" Test Expectation.

Ticket scope is solid, traceability complete, file targets verified, precedent established. Ready to dispatch once it reaches next_up.

Verdict: PASS (by inspection)

Empirical push-to-Harbor verification is explicitly deferred to ticket board #1048 / forgejo_admin/notion-mcp-remote#8 (Activate Woodpecker), which gates pipeline execution for this repo. All in-scope inspection checks green.

Ticket

• Forgejo issue: forgejo_admin/notion-mcp-remote#5 — fix(ci): switch Woodpecker image push to internal Harbor URL
• Merged PR: forgejo_admin/notion-mcp-remote#10 (squash-merged as cb91a12)
• Board item: #1042 on board-notion-mcp-remote, column validation
• Labels: type:bug,story:ops-deploy-gitops,arch:woodpecker
• One-liner: change .woodpecker.yaml kaniko registry: from the external Tailscale URL to the in-cluster Harbor service DNS.

Environment

• Repo: forgejo_admin/notion-mcp-remote branch main at cb91a12
• Config surface under test: .woodpecker.yaml (CI config, not a runtime pod)
• Downstream registry (for context only): harbor-core.harbor.svc.cluster.local (in-cluster) — exercised once pipelines run on this repo
• Woodpecker repo status: active: true, but list_pipelines shows only the PR/push events for this change; pipeline #2 (post-merge push) reported status: error, consistent with the unresolved activation work tracked on board #1048.

Tier Selection

This PR is a CI build-config change, not a pod deploy. The repo is labeled api-like, but Tier 3 prod-pod/endpoint checks are not applicable to this specific diff (no image was rebuilt, no pod rolled). The validation therefore reduces to Tier 1 inspection of the merged config on main plus boundary confirmation that nothing else shifted. Empirical CI validation (Tier 1b: actual push to Harbor) is explicitly scoped to #1048.

Checks

#	Acceptance Criterion	How Verified	Result	Evidence
1	Squash-merge landed on main with the harbor-core.harbor.svc.cluster.local registry value	git show origin/main:.woodpecker.yaml	PASS	Line 22: registry: harbor-core.harbor.svc.cluster.local
2	Diff is exactly one line; no regressions in adjacent kaniko settings	git show cb91a12 -- .woodpecker.yaml	PASS	1 file changed, 1 insertion(+), 1 deletion(-). Only the registry: line changed; repo, tags, dockerfile, build_args, username (from_secret: harbor_username), password (from_secret: harbor_password) all unchanged.
3	YAML still parses	python3 -c "import yaml; yaml.safe_load(...)" on the file from origin/main	PASS	YAML PARSES OK
4	k8s/deployment.yaml external URL intentionally untouched (per scope review — image pull is kubelet-side and external URL stays until image-pull path is redone)	grep -nE "harbor\|tail5b443a\|image:" k8s/deployment.yaml on origin/main	PASS	Line 23: image: harbor.tail5b443a.ts.net/notion-mcp-remote/notion-mcp-remote:latest — unchanged, matches scope expectation.
5	Forgejo issue #5 closed	mcp__forgejo__list_issues(state=closed)	PASS	Issue #5 appears in closed list, state=closed.
6	PR #10 merged	mcp__forgejo__list_prs(state=closed)	PASS	PR #10, merged: true.
7	Empirical end-to-end: Woodpecker push-to-Harbor succeeds on main after merge	Would require list_pipelines to show a green build-and-push step against harbor-core.harbor.svc.cluster.local	DEFERRED	Pipeline #2 (push event on main at cb91a12) reports status: error. Root cause is the Woodpecker activation / secrets / trust-flags work tracked on board #1048 / notion-mcp-remote#8, not a defect in this PR's diff. Empirical signal for this AC will be captured in that ticket's validation pass.

Regression Check

• Pipeline parse: YAML still loads via yaml.safe_load; no structural damage.
• Test step: unchanged. Pipeline #1 (PR #10) ran the test step to success, proving the file still schedules at least the pre-build steps.
• Deployment manifest: k8s/deployment.yaml image reference unchanged; kubelet pull path not disturbed by this PR.
• Secrets reference: from_secret: harbor_username and from_secret: harbor_password untouched; no secret rename required.

Discovered Issues

None introduced by PR #10. The post-merge pipeline error on main (pipeline #2, status: error) is a pre-existing condition already captured by board #1048 / forgejo_admin/notion-mcp-remote#8 — Activate Woodpecker (currently in todo). No new follow-up ticket needed.

Verdict Reasoning

PASS by inspection is the right call because:

1. The fix is correct by direct inspection of main — the registry value is now the in-cluster Harbor service DNS, which is what Woodpecker runners need.
2. The empirical step has a named ticket and owner (#1048 / notion-mcp-remote#8), so the chain is traceable and not lost.
3. Blocking #1042 in validation would create false pressure on the #1048 timeline without adding safety — the inspection-level checks are sufficient to confirm this PR did its job.

If #1048's validation pass later exposes a problem that traces back to the registry value set here, reopen #5 and revisit.

Related

• sop-validation — SOP this note follows
• template-validation — template format
• skill-validate-ticket — driving skill
• Board #1048 / forgejo_admin/notion-mcp-remote#8 — Activate Woodpecker (owns the deferred empirical step)

Validation Report

Board item	#820 (board-pal-e-agency)
Issue	forgejo_admin/claude-custom#235
PR	forgejo_admin/claude-custom#237 (merged)
Date	2026-04-06

Verdict: PASS

What was validated

The /validate-ui skill was exercised in production across 3 roles during the schedule validation session:

• Public (no auth): Navigated to /schedule, captured snapshot, validated 2 local team cards. First run caught team_name null bug (FAIL). Second run after API fix: PASS (4/4).
• Coach (ken10seka@gmail.com): Logged into Keycloak via Playwright, navigated to /coach, validated schedule tab. PASS (5/5).
• Parent (apaisasandra@gmail.com): Logged into Keycloak, navigated to /my-players, validated 3 players with grouped schedules. PASS (5/5).

Key finding

The validation agent caught a real production bug on its first run (team_name null in API response) that passed both dev and QA code review. This validates the core thesis: agents-as-users catch integration bugs invisible to code review.

Acceptance criteria verified

1. Skill accepts role, URL, criteria parameters — PASS
2. Skill logs into Keycloak via Playwright — PASS (coach + parent)
3. Skill captures browser_snapshot for text validation — PASS
4. Skill captures browser_take_screenshot for evidence — PASS
5. Skill reports PASS/PARTIAL/FAIL verdict — PASS (all 3 runs produced structured verdicts)
6. Works with existing Playwright MCP — PASS (no new infrastructure needed)

Overview

Pattern for automating complex web forms via Playwright MCP using browser_evaluate with raw DOM JavaScript. Bypasses input masks, session-sensitive forms, and flaky UI interactions that break with standard Playwright .fill() and .click().

Problem

Playwright's standard UI interaction tools (browser_type, browser_click, browser_select_option) fail on:

• Input masks — SSN fields (___-__-____), phone, date fields that fight with .fill()
• Session-sensitive forms — multi-page wizards (JSF, ASP.NET) that lose state between interactions
• Submit button targeting — .click() hitting wrong elements when multiple buttons share text
• Radio buttons with JS listeners — state changes that don't fire with Playwright's synthetic events

Solution: 3-Step JS Pattern

Step 1: Inspect — map all form fields

browser_evaluate(() => {
  const inputs = document.querySelectorAll('input[type="text"], select');
  const results = {};
  inputs.forEach(el => {
    results[el.id || el.name] = { 
      tag: el.tagName, value: el.value, id: el.id, name: el.name 
    };
  });
  const radios = document.querySelectorAll('input[type="radio"]');
  const radioInfo = [];
  radios.forEach(r => {
    radioInfo.push({ 
      id: r.id, name: r.name, value: r.value, 
      checked: r.checked, label: r.parentElement?.textContent?.trim() 
    });
  });
  return { inputs: results, radios: radioInfo };
})

Step 2: Fill — set all values with proper event dispatch

browser_evaluate(() => {
  function fill(id, val) {
    const el = document.getElementById(id);
    if (!el) return false;
    el.focus();
    el.value = val;
    el.dispatchEvent(new Event('input', {bubbles:true}));
    el.dispatchEvent(new Event('change', {bubbles:true}));
    el.blur();
    return true;
  }
  function selectByText(id, text) {
    const el = document.getElementById(id);
    if (!el) return false;
    const opt = Array.from(el.options).find(o => o.text === text);
    if (opt) { 
      el.value = opt.value; 
      el.dispatchEvent(new Event('change', {bubbles:true})); 
      return true; 
    }
    return false;
  }
  return {
    field1: fill('input_firstName', 'Marcus'),
    dropdown1: selectByText('citySelect', 'Philadelphia'),
  };
})

Step 3: Submit — click by ID

browser_evaluate(() => {
  document.getElementById('navNextButton').click();
  return 'clicked';
})

Key Details

• Event dispatch is critical — React, JSF, and Angular forms listen for input, change, and blur events. Setting .value alone doesn't register.
• focus() before setting value — helps input mask fields initialize properly
• For radios: set .checked = true, then dispatch change and call .click()
• Inspect first, fill second, submit third — never combine steps; IDs may change between pages
• Return values for verification — every fill function returns true/false so you confirm all fields were set

When to Use

• Government forms (VitalChek, DMV, business registration)
• Any JSF/server-rendered form with input masks
• Multi-page wizards that lose state with slow UI interactions
• Forms where browser_type/browser_click fail more than once

When NOT to Use

• Simple forms with no input masks — standard Playwright tools work fine
• Forms behind iframes from different origins (Stripe Elements) — can't access cross-origin DOMs

Origin

Discovered 2026-03-30 while automating PA VitalChek birth certificate order for Marcus Draney's DoorDash onboarding. Standard Playwright interactions failed 3 times on the SSN masked input and multi-page JSF form. One browser_evaluate call filled all fields and submitted successfully.

Validation: claude-custom#231 — validate-ticket SKILL.md

Board item: #674 on board-pal-e-agency

Verdict: PASS (invalid bug — resolved by git pull)

Finding

The ticket's premise was invalid. PR #230 had already merged the SKILL.md to Forgejo. The local checkout was 1 commit behind (d217aab vs 6bca6be). Running git pull origin main on ~/claude-custom brought the file down and hardlinks propagated automatically to ~/.claude/skills/validate-ticket/SKILL.md.

Verification

Check	Result
~/.claude/skills/validate-ticket/SKILL.md exists	PASS
/validate-ticket appears in skill list	PASS — visible in session

Root Cause

Local clone was behind remote after worktree-based agent work. Same pattern as the Ava personality injection gap. Consider auto-pull in session-start hook for claude-custom.

Verdict: BLOCK

Template Completeness

• [x] Type -- Bug
• [x] Lineage -- references #228, #209
• [x] Repo -- forgejo_admin/claude-custom
• [x] What Broke -- describes missing SKILL.md on filesystem
• [x] Repro Steps -- 4 concrete steps
• [x] Expected Behavior -- clear reference to review-ticket pattern
• [x] Environment -- local workstation, commit SHA d217aab
• [x] Acceptance Criteria -- 4 items
• [x] Related -- project + parent issues listed

All bug template sections present. Template is complete.

Traceability

• [x] story:pm-scope label -- PM (Ava) scope management story
• [x] story note verified -- found in project-pal-e-agency user-stories section (story:pm-scope maps to PM role)
• [x] arch:skills label -- skills architecture component
• [ ] arch note MISSING -- [SCOPE] No arch-skills note found in pal-e-docs. Search returned zero results.
• [x] Forgejo issue -- forgejo_admin/claude-custom#231, open

File Targets

• [x] ~/.claude/skills/validate-ticket/SKILL.md -- verified MISSING from local filesystem as claimed
• [x] ~/.claude/skills/review-ticket/SKILL.md -- verified EXISTS as reference pattern

However, investigation reveals the file DOES exist in the Forgejo repo (see Repo Placement).

Repo Placement

FUNDAMENTAL SCOPE ERROR. The issue states the SKILL.md "was never persisted" and was "lost in worktree cleanup." Investigation reveals:

• PR #230 (feat: add /validate-ticket skill for post-merge validation) was merged to main on claude-custom (merge commit 6bca6be)
• The file skills/validate-ticket/SKILL.md exists in the Forgejo repo on main branch
• The local checkout ~/claude-custom is 1 commit behind (d217aab vs 6bca6be)
• Board item #656 (original #228 work) is correctly in done
• The fix is cd ~/claude-custom && git pull origin main followed by hardlink creation -- NOT writing a new SKILL.md

This is an operational sync issue (stale local checkout), not a missing deliverable. A dev agent dispatched against this ticket would create a duplicate SKILL.md or fail in confusion.

Dependencies

• Board item #518 (parent #209, "Right-side validation pipeline") is in backlog -- parent decomposed ticket, not a blocker
• Board item #656 (original #228) is in done -- the work WAS completed and merged
• No in_progress items block this

Acceptance Criteria

All 4 AC are already satisfied in the repo:

• [x] ~/.claude/skills/validate-ticket/SKILL.md exists -- in the repo, just not synced locally
• [x] Skill parses board-slug#item-id argument -- verified in repo content
• [x] Skill dispatches agent that reads skill-validate-ticket from pal-e-docs -- verified
• [x] Pattern matches review-ticket skill structure -- same routing/dispatch/verdict pattern

An agent executing this ticket would produce a no-op or duplicate.

Blast Radius

Checked all 27 skill directories in ~/.claude/skills/ against the 28 in the Forgejo repo. Only validate-ticket is missing locally. No other skills have this desync. The root cause is the local clone not being updated after PR #230 merged.

Decomposition Assessment

No decomposition needed. The ticket should not be executed as written -- the premise is invalid. If rewritten as a sync task, it would be a single operational step (git pull + ln), well under the 5-minute rule.

Recommendation

1. [SCOPE] This ticket is fundamentally invalid. The SKILL.md deliverable exists in the claude-custom repo (merged via PR #230, commit 6bca6be). The local filesystem is 1 commit behind. This is NOT a code bug requiring a new PR.
2. [SCOPE] Close Forgejo issue #231 as "not a bug" -- the original board item #656 (#228) was correctly completed.
3. [SCOPE] The operational fix is: cd ~/claude-custom && git pull origin main then mkdir -p ~/.claude/skills/validate-ticket && ln ~/claude-custom/skills/validate-ticket/SKILL.md ~/.claude/skills/validate-ticket/SKILL.md.
4. [SCOPE] Create architecture note arch-skills for the skills component (missing from pal-e-docs).

Validation: claude-custom#217 — Enhance skill-review-ticket

Board item: #591 on board-pal-e-agency

Verdict: PASS

Acceptance Criteria

Criterion	Result
Review checks arch note exists in pal-e-docs	PASS — Step 4b added with search_notes verification
Review checks story entry exists on project page	PASS — Step 4a added with get_section verification
Decomposition routes to skill-decompose-ticket	PASS — Steps 10, 11, 14 updated + skill-decompose-ticket created (note 1029)
Review note format includes arch/story verification	PASS — code-8000 template updated with checklist lines

Deliverables

• skill-review-ticket: 7 blocks updated (traceability, decomposition, verdict, report, review format, MCP tools, related)
• skill-decompose-ticket: new skill note created (10 steps, constraints, MCP tools table)

Verification

Both notes read back correctly via get_section. Related list cross-references verified.

Verdict: READY

This is a well-scoped parent/coordination ticket. It does no direct work itself -- all implementation is decomposed into 4 sequenced child tickets across 4 repos. The parent issue serves as the spec and coordination point.

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- Standalone, discovered during board item creation workflows
• [x] Repo -- Cross-repo correctly identified (pal-e-docs, pal-e-docs-sdk, pal-e-mcp, claude-custom)
• [x] User Story -- Clear persona (platform operator), motivation (eliminate "issue" overloading)
• [x] Context -- Thorough explanation of the semantic collision and deploy-order rationale
• [x] File Targets -- Extensive, per-repo, with line numbers and change descriptions
• [x] Acceptance Criteria -- 10 items, all verifiable
• [x] Test Expectations -- 4 items with run command
• [x] Constraints -- 4 constraints including historical migration protection and deploy ordering
• [x] Checklist -- Present
• [x] Related -- Present

Traceability

• [x] story:pm-scope -- present on board item, appropriate for platform operator workflow improvements
• [x] arch:note-system -- present on board item, correct (BoardItemType is part of the note/board system)
• [x] Forgejo issue -- forgejo_admin/claude-custom#181, open

File Targets

All file targets verified against current filesystem state:

• [x] pal-e-docs/src/pal_e_docs/models.py:34-39 -- verified: BoardItemType enum exists with issue = "issue" at line 37
• [x] pal-e-docs/src/pal_e_docs/schemas.py:225 -- verified: BoardItemTypeType Literal includes "issue"
• [x] pal-e-docs/src/pal_e_docs/schemas.py:265-268 -- verified: BoardItemCounts has issue: int = 0 at line 268
• [x] pal-e-docs/src/pal_e_docs/routes/boards.py -- verified: sync endpoint and validation code reference BoardItemType.issue (minor line drift from issue description)
• [x] pal-e-docs/tests/test_boards.py -- verified: 13 references to item_type.*issue
• [x] pal-e-docs/tests/test_board_issue_sync.py -- verified: 7 references to item_type.*issue
• [x] pal-e-docs/tests/test_pagination_activity.py -- verified: 1 reference to item_type.*issue
• [x] pal-e-docs/alembic/versions/f6a7b8c9d0e1_sprint_schema_expansion.py:30-31 -- verified: historical migration with "issue" in tuples (correctly marked do-not-modify)
• [x] pal-e-docs-sdk/src/pal_e_sdk/boards.py:110-113 -- verified: docstring says "issue items require"
• [x] pal-e-docs-sdk/tests/test_boards.py -- verified: 4 references to item_type="issue" at lines 143, 165, 198, 205
• [x] pal-e-mcp/src/pal_e_mcp/tools/boards.py -- verified: 3 tool descriptions list 'issue' (lines 117, 159, 384), plus "issue-type items" at line 195 and docstring at line 227
• [x] pal-e-mcp/tests/test_param_alignment.py -- verified: 5 references to item_type="issue" at lines 359, 369, 378, 385, 392
• [x] claude-custom/hooks/check-board-item.sh -- verified: issue) case branch at line 74 (issue says 52-57, actual is 72-78)
• [x] claude-custom/skills/review-ticket/SKILL.md:27 -- verified: lists "(phase, issue, incident, repo)"
• [x] claude-custom/skills/review-ticket/SKILL.md:42 -- verified: "For `issue` items" section

All targets are specific enough for an agent to act on. Line numbers have minor drift from the issue description (expected for issues written before recent merges), but all patterns and files are correctly identified. Child tickets should verify line numbers at execution time.

Repo Placement

OK. Issue is filed on claude-custom (the hooks/config repo) which is correct for cross-repo coordination tickets. Each of the 4 child tickets is filed on its correct repo: pal-e-api#229 (API), pal-e-sdk#40 (SDK), pal-e-mcp#53 (MCP), claude-custom#191 (hooks/skills). No misplacement detected.

Dependencies

• [x] Deploy ordering (A->B->C->D) -- documented in Decomposition section. Each child blocks the next. This is correct and necessary (SDK must consume new API before MCP can use new SDK).
• [x] Board item #478 (Spike: Note type system audit) -- in in_progress. This spike targets NoteType (not BoardItemType), so no conflict with this ticket's scope.
• [x] No other board items on board-pal-e-agency are blocked by or block this ticket.

Acceptance Criteria

All 10 acceptance criteria are verifiable by an agent:

• Enum presence: grep/read models.py for ticket = "ticket"
• API acceptance/rejection: pytest integration tests
• Alembic migration: run migration on test DB, verify row conversion
• SDK/MCP/hook string changes: grep for old pattern, verify absence
• "No remaining references" criterion: grep across all 4 repos for item_type.*=.*"issue"

Each child ticket inherits a subset of these criteria. The parent's criteria are the union. No ambiguous "works correctly" language -- all criteria are specific and testable.

Blast Radius

• MCP tool descriptions are visible to all agents at session start. Changing 'issue' to 'ticket' will change agent behavior when creating board items. The backward-compat transition period in child ticket A mitigates this.
• Convention/SOP notes that reference item_type="issue" will need updating. Discovered Scope #192 catches the SKILL.md phantom incident type. A content sweep for item_type.*issue in pal-e-docs notes may surface additional convention notes needing updates (not blocking, but worth tracking).
• Cached MCP sessions may use old value after backward compat removal. Session restart resolves this.
• Rollback is straightforward: reverse Alembic migration + revert code changes. The backward-compat transition period means rollback is only needed if the new value causes problems after the transition window closes.

Decomposition Assessment

Already decomposed into 4 child tickets with strict deploy ordering:

1. pal-e-api#229 -- Enum + schema + routes + Alembic migration + transition alias (single repo, ~10 files)
2. pal-e-sdk#40 -- Docstrings + test fixtures (single repo, ~2 files)
3. pal-e-mcp#53 -- Tool descriptions + test fixtures + SDK bump (single repo, ~2 files)
4. claude-custom#191 -- Hook case branch + SKILL.md routing (single repo, ~2 files)

Each child ticket targets a single repo and should complete well within the 5-minute rule. Child ticket A is the largest (~10 files including tests and migration) but remains within the 3-file-target-per-repo limit when counting logical changes (enum, schema, routes, migration). The parent ticket itself requires no direct work -- it closes when all 4 children merge. No further decomposition needed.

Recommendation

No action needed. Ticket is well-scoped, fully decomposed, all file targets verified, traceability complete.

Informational observations (not blocking):

1. Line numbers in file targets have minor drift from current file state. Child tickets should verify line numbers at execution time -- this is normal and expected.
2. Consider grepping pal-e-docs note content for item_type.*issue references in SOPs/conventions beyond what Discovered Scope #192 covers. If found, add as discovered scope on the parent.

Validation: pal-e-api#247 — Content sweep: rename Betty Sue → Ava

Board item: #646 on board-pal-e-agency

Verdict: PASS

Acceptance Criteria

Criterion	Result
All 13 target notes updated with Ava references	PASS — 61 block-level updates across 13 notes
search_notes(query="Betty Sue") returns only archived/historical/completed	PASS — top results are review notes, agent-betty-sue (deprecated), completed phases only
Block-level updates only, no full rewrites	PASS — all 61 edits via update_block
Completed phase notes untouched	PASS — historical "Owner: Betty Sue" preserved

QA Nit Fix

agent-ava Constraints: "above your pay grade" → "decisions that require Lucas's explicit input". Verified via get_section.

Discovered Scope

14 additional notes with Betty Sue references found outside the 13-note target list. Tracked as follow-up: pal-e-api#248 (board item #672, backlog).

Verification Method

search_notes(query="Betty Sue") post-sweep. All 13 target notes absent from results. Remaining hits are all in excluded categories (review notes, archived agent, completed phases, out-of-scope templates/SOPs).

Decision: Agent Dottie (Documentation Subagent)

Decision record for creating a fourth agent in the operating model. Made 2026-03-07 by Ava and Lucas.

Context

At 133K tokens into a session, documentation operations consume 5,000-15,000 tokens each. Creating a note requires reading the style guide, reading related notes, composing HTML, calling create_note, and verifying the result. Updating a note requires reading current content, modifying it, calling update_note. Each operation expands the main session conversation, consuming the most valuable resource: context window space in Ava's session.

The main session is where strategic decisions happen, sprint planning occurs, and agent coordination takes place. Every token spent on mechanical doc operations is a token not available for higher-value work.

Decision

Aspect	Choice
Action	Create a documentation agent ("Dottie") to execute doc tasks in a separate context
Name	Dottie (from "docs")
Role	Librarian -- executes doc updates, content audits, quality tracking
Access	pal-e-docs read/write + Forgejo read-only. No code, no repo writes.
Spawned as	General-purpose subagent with Dottie personality injected in prompt
Boss	Ava. Dottie never makes strategic decisions.

Token Economics

Operation	Inline (before Dottie)	With Dottie	Savings
Create a note	~5,000-8,000 tokens (read style guide + related notes + compose + create + verify)	~300 tokens (spawn prompt + summary response)	~95%
Update a note	~3,000-6,000 tokens (read current + modify + update)	~300 tokens	~90%
Content audit	~10,000-15,000 tokens (read many notes, compile findings)	~300 tokens	~97%
Batch doc updates (3+ notes)	~15,000-25,000 tokens	~300 tokens	~98%

Key insight: The savings come from context isolation. Dottie's full conversation (reading notes, composing HTML, making MCP calls) happens in a separate context window. Ava only sees the spawn prompt and the summary.

Why Not Earlier?

• Subagent spawning was not available until recently
• Earlier sessions were shorter and doc operations were fewer
• The three-agent model (Ava, Dev, QA) was sufficient when docs were simpler
• As the corpus grew to 256 notes and doc operations became more frequent, the cost became visible

Constraints

• Dottie never makes strategic decisions -- presents options to Ava
• Dottie never writes code in repos
• Dottie never creates or closes Forgejo issues (that is Ava's job)
• Dottie always follows note templates and html-style-guide conventions
• Dottie always reports what was created/updated/changed

Impact on Operating Model

The three-agent model becomes four agents. Rule 4 ("Ava owns docs") is refined: Ava directs doc operations; Dottie executes them. The separation preserves the principle that agents don't make strategic decisions about documentation -- Dottie is purely mechanical execution.

Related

• agent-dottie -- Dottie's personality definition
• agent-workflow -- the operating model (updated to include Dottie)
• agent-ava -- Dottie's boss

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — Feature
• [x] Lineage — references claude-custom#224
• [x] Repo — forgejo_admin/pal-e-api
• [x] User Story — well-formed (As Lucas, I want..., So that...)
• [x] Context — clear motivation, references parent ticket
• [x] File Targets — N/A for filesystem (MCP operations); note targets listed but incomplete (see below)
• [x] Acceptance Criteria — 3 criteria present, verifiable
• [x] Test Expectations — manual search verification described
• [x] Constraints — clear (update_block only, no archived notes, no content rewrites beyond name)
• [x] Checklist — present
• [x] Related — project + parent ticket

Traceability

• [x] story:pm-scope — present on board item, matches PM scoping role
• [x] arch:note-system — present on board item, matches note content operations
• [x] Forgejo issue — forgejo_admin/pal-e-api#247, open

File Targets

No filesystem file targets — this is a pal-e-docs MCP operation via update_block. Verified the listed notes exist and contain Betty Sue references:

• [x] agent-workflow — verified: exists, Betty Sue references confirmed via search (role descriptions)
• [x] project-pal-e-agency — verified: exists, Betty Sue in user stories table (PM row, block 13984) and likely architecture diagram
• [x] convention-agent-autonomy-levels — verified: exists, Betty Sue in per-agent table (block 8688, row: "Betty Sue", "L2 with L0 escalation")
• [x] convention-escalation-triggers — verified: exists, Betty Sue in escalation chain diagram
• [x] convention-validation-checkpoints — verified: exists, Betty Sue in 3 blocks (paragraph-4, paragraph-8, paragraph-12)
• [ ] INCOMPLETE — Issue says "Any other notes found via search_notes" but does not enumerate them. Search reveals 8 additional active notes with Betty Sue references not listed in the issue (see Blast Radius).

Repo Placement

Issue is filed on pal-e-api — correct, that is where the pal-e-docs data and API live. No code file changes needed, only MCP update_block operations against the database. Repo placement is correct. Single-repo scope (Dottie agent operates via MCP, not filesystem).

Dependencies

• [ ] claude-custom#224 (board item #643, "Evolve main session agent: Betty Sue → Ava") — currently in_progress. HARD BLOCKER. This ticket must NOT execute until #643 merges, otherwise pal-e-docs notes will reference "Ava" while the running agent is still "Betty Sue." The issue's Lineage section documents this relationship but the board item lacks a depends:643 label.

Acceptance Criteria

All 3 criteria are agent-verifiable:

• [x] search_notes(query="Betty Sue") returns only archived/historical — verifiable via MCP call
• [x] All active SOPs/conventions reference "Ava" — verifiable via MCP search
• [x] Block-level updates only — enforceable by instruction (use update_block not update_note)

Missing criterion: No AC explicitly excludes completed phase notes. Several completed phases reference "Owner: Betty Sue" (historical records). Should be explicitly listed as excluded, same as archived notes.

Blast Radius

The issue significantly underestimates scope. It lists 5 notes plus a wildcard search, but search reveals 12+ active notes with Betty Sue references.

Listed in issue (5 notes): agent-workflow, project-pal-e-agency, convention-agent-autonomy-levels, convention-escalation-triggers, convention-validation-checkpoints

NOT listed in issue but found via search (8 additional active notes):

• sop-index — "Betty Sue (main session)" in multiple table rows
• agent-spawn-conventions — Betty Sue in agent role descriptions
• pr-lifecycle — "Betty Sue (MCP)" in multiple action items
• decision-agent-dottie — "Betty Sue" in Dottie constraint descriptions
• sop-board-workflow — "Betty Sue has triaged"
• agent-dottie — "Betty Sue's assistant" in mission statement
• convention-cross-pillar-triggers — "Betty Sue is responsible"
• plan-pal-e-agency — Betty Sue in plan description

Completed phases (should be explicitly excluded as historical): phase-pal-e-platform-14a-webhook-fix, phase-pal-e-docs-project-taxonomy, phase-postgres-7f-3-template-drift

Already correctly excluded: agent-betty-sue (archived), project-pal-e-portfolio (archived), review notes (historical)

Rollback is straightforward — update_block calls are individually reversible by swapping "Ava" back to "Betty Sue".

Decomposition Assessment

13 active notes with potentially 20-30 update_block calls total. Each call is mechanical (find "Betty Sue" in block content, replace with "Ava"). Applying the rules:

• >3 discrete changes? Yes — 13 notes. However, each change is identical in nature (text substitution). This is a single-pattern sweep, not 13 distinct features.
• >5 minutes? Borderline. A Dottie agent with a complete note list can execute this in ~5 minutes if the list is pre-enumerated. Without enumeration (relying on runtime search), the agent wastes time discovering targets.
• Independent subtasks? All note updates are independent — could be parallelized, but the overhead of spinning up multiple agents for text substitution exceeds the time saved.

No decomposition needed — but the issue body MUST enumerate ALL target notes upfront so the agent does not waste time discovering them. The wildcard "search for more" approach is insufficient for a scoped spec.

Recommendation

1. [BODY] Add the 8 missing active notes to the File Targets / notes-to-update list: sop-index, agent-spawn-conventions, pr-lifecycle, decision-agent-dottie, sop-board-workflow, agent-dottie, convention-cross-pillar-triggers, plan-pal-e-agency
2. [BODY] Add explicit exclusion for completed phase notes to the "Files the agent should NOT touch" section (historical records, same treatment as archived notes and review notes)
3. [BODY] Add acceptance criterion: "Completed phase notes are NOT modified (historical records)"
4. [LABEL] Add depends:643 label to board item #646 — hard dependency on personality evolution merging first

Verdict: APPROVED

Re-review after refinement. All previous feedback addressed. Scope is solid, file targets verified, traceability complete, fits a single agent pass.

Template Completeness

• [x] Type — Feature
• [x] Lineage — Standalone, Lucas decision during session 2026-03-28
• [x] Repo — forgejo_admin/claude-custom
• [x] User Story — present, well-formed
• [x] Context — present, thorough motivation
• [x] File Targets — 9 files listed, with exclusion list and pal-e-docs MCP actions
• [x] Acceptance Criteria — 7 criteria, all testable
• [x] Test Expectations — 5 tests including verified grep command
• [x] Constraints — 5 constraints, clear boundaries
• [x] Checklist — present
• [x] Related — present with follow-up ticket reference
• [x] Post-merge — present (added per previous review feedback)

Traceability

• [x] story:pm-scope label — PM scope management story
• [x] arch:context-inject label — context injection architecture component
• [x] Forgejo issue — forgejo_admin/claude-custom#224, open

File Targets

• [x] agents/betty-sue.md — verified: exists (5.9k), 13 "Betty Sue" references. Rename to ava.md.
• [x] CLAUDE.md — verified: exists, 3 "Betty Sue" references in personality section
• [x] hooks/session-start-context.sh — verified: exists, 1 reference (agent-betty-sue slug in API call)
• [x] hooks/inject-subagent-context.sh — verified: exists, 2 "Betty Sue" references in subagent context strings
• [x] agents/dev.md — verified: exists, 1 "Betty Sue" reference in MCP tools table
• [x] agents/qa.md — verified: exists, 1 "Betty Sue" reference in MCP tools table
• [x] agents/dottie.md — verified: exists, 3 "Betty Sue" references (mission, constraint, output)
• [x] agents/penny.md — verified: exists, 3 "Betty Sue" references (mission, constraint, reporting)
• [x] docs/superpowers/specs/2026-03-18-review-ticket-design.md — verified: exists, 5 "Betty Sue" references

Completeness check: Full repo grep confirms exactly 9 files contain "Betty Sue" references. The ticket's file target list covers all 9 — no files missed.

Repo Placement

OK. Issue filed on claude-custom, all 9 file targets are in claude-custom. pal-e-docs MCP operations (create agent-ava, archive agent-betty-sue) are correctly documented as MCP calls, not file edits. The pal-e-docs content sweep is correctly deferred to pal-e-api#247 (board item #646).

Dependencies

• Board item #646 (pal-e-docs content sweep, pal-e-api#247) — follow-up, not a blocker
• Memory files (~/.claude/projects/) — documented as post-merge main-session task, not part of PR
• No items in in_progress that block this ticket

Acceptance Criteria

All 7 criteria are agent-verifiable:

• AC1-2: Session/subagent injection — verifiable by grepping hook output
• AC3-4: pal-e-docs note creation/archival — verifiable via MCP get_note
• AC5: All 5 agent files updated — verifiable via grep
• AC6: Personality tone — subjective but bounded by Context section's definition
• AC7: Operational constraints unchanged — verifiable by diffing constraint sections

Test command verified: grep -ri "betty sue" ~/claude-custom/agents/ ~/claude-custom/CLAUDE.md ~/claude-custom/hooks/ ~/claude-custom/docs/ returns 27 matches pre-implementation. Post-implementation should return 0.

Blast Radius

• Memory files: MEMORY.md references "Betty Sue" extensively — correctly scoped as post-merge task
• pal-e-docs notes: References in SOPs, conventions, architecture — correctly deferred to follow-up #646
• Other repos: No "Betty Sue" references outside claude-custom repo files. Clean boundary.

Decomposition

9 file targets in 1 repo. 7 acceptance criteria. 8 of 9 files are mechanical text replacement. One file (agents/ava.md) requires creative personality rewrite bounded by the spec. Tight but feasible single agent pass. No decomposition needed.

Recommendation

No action needed. Ticket is APPROVED for next_up.

Previous review feedback (from review-643-2026-03-28 v1) fully addressed:

• [BODY] docs/superpowers spec file added to file targets — DONE
• [BODY] grep test command expanded to include docs/ — DONE
• [BODY] Post-merge section added for memory file updates — DONE
• [SCOPE] pal-e-docs sweep deferred to follow-up ticket (pal-e-api#247) — DONE

Verdict: APPROVED

Template Completeness

• [x] Type -- Bug
• [x] Lineage -- board, story, arch, discovery context documented
• [x] Repo -- forgejo_admin/claude-custom (correct)
• [x] What Broke -- clear description of keyword mismatch between hook and skill note
• [x] Repro Steps -- 5-step reproduction with exact behavior at each step
• [x] Expected Behavior -- two clear resolution options proposed
• [x] Environment -- hook path, skill slug, grep pattern all specified
• [x] File Targets -- both targets listed with specific function and section references
• [x] Acceptance Criteria -- 3 criteria, all verifiable by an agent
• [x] Test Expectations -- 3 concrete test cases specified
• [x] Constraints -- backward compatibility requirement stated
• [x] Checklist -- 4 discrete execution steps
• [x] Related -- links to #214 and the review note that exposed the bug

Traceability

• [x] story:scope-review -- present on board item
• [x] arch:hooks -- present on board item
• [x] Forgejo issue -- forgejo_admin/claude-custom#220, open

File Targets

• [x] hooks/check-board-advance.sh -- verified: check_review_approved() at line 46. Grep pattern at lines 62 and 71: grep -vi 'NOT APPROVED' | grep -qi 'APPROVED'. Only accepts "APPROVED", rejects everything else including "READY".
• [x] pal-e-docs note skill-review-ticket -- verified: Step 11 defines verdicts as "READY", "NEEDS_REFINEMENT", "BLOCK". The spawned review agent reads this note and writes "READY" as the passing verdict.
• [x] skills/review-ticket/SKILL.md -- verified (additional context): The router skill already says "APPROVED" throughout (lines 3, 9, 77-78, 97, 104-105). The mismatch is specifically between the pal-e-docs note (what the spawned agent reads) and the hook (what gates advancement).
• [x] tests/test_check_board_advance.sh -- verified: Tests 12-19 cover APPROVED/NOT APPROVED verdicts. No test currently covers "READY" as a passing verdict.

Repo Placement

Issue correctly filed on claude-custom. The hook shell script lives in that repo. The pal-e-docs skill-review-ticket note is a data update via MCP tool (not a code change requiring a separate repo PR), so a single-repo PR is appropriate. The agent can update the pal-e-docs note content as part of the same work unit.

Dependencies

• [x] Item #581 (claude-custom#214 -- backlog-to-todo gate) -- in done, satisfied
• [x] Item #585 (claude-custom#216 -- the review that exposed this bug) -- in done, satisfied
• No unresolved dependencies. No items currently blocked by this ticket.

Acceptance Criteria

All 3 acceptance criteria are testable and specific:

• "Hook and skill use the same passing verdict keyword" -- verifiable by grepping hook and note after fix
• "Existing review notes with READY are recognized by the hook" -- testable via new test case in test suite
• "No manual update_block workaround needed" -- verifiable via end-to-end flow (create review with READY, advance item)

Test expectations are well-specified with 3 concrete cases: READY allows, APPROVED allows, NOT APPROVED blocks.

Blast Radius

• label-on-verdict.sh -- NOT affected. Uses "### VERDICT: APPROVED" / "### VERDICT: NOT APPROVED" for QA PR reviews. Entirely separate pipeline (PR reviews vs scope reviews). Different vocabulary, different context.
• skills/review-pr/SKILL.md -- NOT affected. PR review uses "APPROVED" / "NOT APPROVED" verdicts for code review, not scope review.
• Existing review notes already using "APPROVED" (from manual workaround) will continue to work regardless of fix approach.
• docs/superpowers/specs/2026-03-18-review-ticket-design.md -- uses "READY" vocabulary in the design spec. Informational only; not executable. Low priority alignment but noted.
• Rollback is straightforward -- revert one grep pattern change.

Decomposition Assessment

2 file targets in 1 repo plus 1 pal-e-docs note update via MCP. 3 acceptance criteria. 1 new test case to add. Estimated agent time: under 5 minutes. Three-thing limit: hook grep (1), test case (2), optional note alignment (3). No decomposition needed.

Recommendation

No action needed. Scope is solid, all file targets verified, traceability complete, single agent pass.

Implementation note: The issue's recommended approach (accept both READY and APPROVED in the hook) is correct. Changing the grep from grep -qi 'APPROVED' to grep -qiE 'APPROVED|READY' at lines 62 and 71 (preserving NOT APPROVED rejection via the preceding grep -vi) is the minimal safe change. Add a test case for "Verdict: READY" alongside existing "Verdict: APPROVED" test.

Verdict: NEEDS_REFINEMENT

Template Completeness

Issue uses a hybrid format -- some bug template sections, some feature template sections. Checking against the canonical issue template (template-issue):

• [x] Type -- present (but says "Feature" instead of "Bug" -- contradicts board label type:bug and title prefix "Bug:")
• [x] Lineage -- present
• [x] Repo -- present
• [x] User Story -- present, clear who/what/why
• [x] Context -- present, detailed session context with 8 false negatives
• [/] File Targets -- present but WRONG primary target (see File Targets section below)
• [x] Acceptance Criteria -- present, 3 criteria
• [x] Test Expectations -- present, 3 test cases
• [x] Constraints -- present
• [x] Checklist -- present
• [x] Related -- present

Since this is typed as a Bug on the board, it should follow template-issue-bug which requires What Broke, Repro Steps, Expected Behavior, and Environment. Those are missing but the equivalent info exists in the User Story and Context sections. The Type mismatch (body says Feature, board says Bug) is the primary template issue.

Traceability

• [x] story:pm-scope -- PM scope management story
• [x] arch:hooks -- hooks architecture component
• [x] Forgejo issue -- forgejo_admin/claude-custom#216, open

File Targets

• [x] hooks/post-mcp-merge-rebase.sh -- verified exists, but this is NOT the right fix target. This file calls _parse_merged_status at line 16 but does not define it.
• [ ] hooks/forgejo-helper.sh -- MISSING FROM TICKET. This is where _parse_merged_status lives (lines 333-380). This is the actual file needing the fix. Bug confirmed: the function does not handle the double-stringified shape where tool_response is a string containing JSON with a result key that is itself a string containing {"merged": true}.
• [ ] tests/test_parse_merged_status.sh -- MISSING FROM TICKET. Existing test file with 13 passing tests. Needs a new test case for the double-stringified shape. The debug capture at /tmp/hook-debug-merge.json provides the exact shape to test.

Root cause verified via codebase: _parse_merged_status returns "false" for the actual PostToolUse JSON shape captured in /tmp/hook-debug-merge.json. The shape is: tool_response (string) -> parse -> {"result": "..."} -> parse result -> {"merged": true}. None of the 5 existing parsing shapes handle this two-level unwrap.

Repo Placement

OK. Issue filed on claude-custom, fix targets are in claude-custom. Single-repo scope.

Dependencies

• [x] Board item #505 (issue #189, "post-merge hook false alarm on squash merge") -- satisfied (done). This was the predecessor bug that introduced _parse_merged_status with 5 shapes. The current bug is a regression from an unhandled 6th shape.
• No blocking items found in in_progress or next_up columns.

Acceptance Criteria

3 criteria from the issue:

• AC1: "Hook correctly detects merged: true in tool output and reports success" -- testable but vague. Should specify the double-stringified shape explicitly. Unit test against _parse_merged_status with the exact /tmp/hook-debug-merge.json shape.
• AC2: "Hook correctly detects actual merge failures and reports failure" -- already covered by existing tests (9 edge cases pass). Low risk of regression.
• AC3: "/update-docs reminder fires on successful merges" -- integration-level. Cannot be verified without a real merge. Should be split: unit test (parse function) + manual validation (real merge).

Blast Radius

Three hooks share _parse_merged_status via forgejo-helper.sh:

• remind-update-docs.sh -- emits false "Merge was not successful" message (the visible symptom)
• post-mcp-merge-rebase.sh -- silently skips local main fast-forward after merge
• board-item-on-merge.sh -- silently skips board item auto-move to done

Fixing _parse_merged_status in forgejo-helper.sh fixes all three. No other consumers found. Rollback is straightforward (revert single function change).

Decomposition Assessment

1 primary file to change (hooks/forgejo-helper.sh), 1 test file to update (tests/test_parse_merged_status.sh). 3 acceptance criteria. Well under the three-thing limit and five-minute rule. No decomposition needed. No independent subtasks to parallelize.

Recommendation

1. [BODY] Fix Type header: change "Feature" to "Bug" to match board label and title.
2. [BODY] Fix primary file target: change hooks/post-mcp-merge-rebase.sh to hooks/forgejo-helper.sh (lines 333-380, _parse_merged_status function). The hook scripts themselves need no changes.
3. [BODY] Add file target: tests/test_parse_merged_status.sh -- add test case for double-stringified shape (string tool_response containing JSON with string result field).
4. [BODY] Add root cause to Context: the shape is tool_response(string) -> parse -> {result: string} -> parse -> {merged: true}. None of the 5 existing shapes handle the two-level unwrap. Reference /tmp/hook-debug-merge.json for the exact payload.
5. [BODY] Clarify AC1: specify that the double-stringified shape must be detected, not just generic "tool output".

Verdict: READY

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- board, story, arch, discovered scope context from PR #213 merge
• [x] Repo -- forgejo_admin/claude-custom
• [x] User Story -- PM wants review gate at backlog-to-todo so TODO always means REVIEWED
• [x] Context -- Lucas correction on kanban semantics, corrected flow diagram included
• [x] File Targets -- 2 files identified with specific change descriptions
• [x] Acceptance Criteria -- 4 testable items
• [x] Test Expectations -- 3 items including manual verification
• [x] Constraints -- 3 constraints (preserve existing gate, naming pattern, verdict check)
• [x] Checklist -- 5 discrete steps
• [x] Related -- 3 references (parent issue, originating PR, behavioral correction)

Traceability

• [x] story:scope-review -- scope review pipeline story, present on board item
• [x] arch:hooks -- hooks architecture component, present on board item
• [x] arch:board-api -- board API architecture component, present on board item
• [x] Forgejo issue -- forgejo_admin/claude-custom#214, open

File Targets

• [x] hooks/check-board-advance.sh -- verified exists at ~/claude-custom/hooks/check-board-advance.sh (194 lines). Currently only gates todo-to-next_up (line 92-95: exits 0 if target column is not next_up). The shared check_review_approved function (lines 46-77) is reusable for the new backlog-to-todo gate without modification. Ticket correctly identifies the gap.
• [x] tests/test_check_board_advance.sh -- verified exists at ~/claude-custom/tests/test_check_board_advance.sh (544 lines, 20 tests). Well-structured mock API server. Existing Test 2 (line 251) explicitly allows "move to todo" without review -- this will need updating for the new gate. Mock data already has items in "todo" column that can be extended to test backlog-to-todo scenarios.

Targets are specific enough. Agent can act without guessing.

Repo Placement

OK. Issue filed on forgejo_admin/claude-custom, which is the correct repo for hooks and hook tests. No cross-repo concerns. Single-repo scope.

Dependencies

• [x] Board #364 "Scope review pipeline" (done) -- parent work that created this hook. Satisfied.
• [x] Board #523 "Enforce backlog-first column on create_board_item" (done) -- prerequisite ensuring items start in backlog. Satisfied.
• [x] PR #213 (merged) -- the PR that created check-board-advance.sh. Satisfied.

No unresolved dependencies. No blockers in in_progress or next_up.

Acceptance Criteria

All 4 criteria are testable and specific:

• AC1: "blocks backlog-to-todo without APPROVED review note" -- testable via mock API using same pattern as existing Test 11 (deny path). Agent can add mock item in "backlog" column and attempt move to "todo".
• AC2: "Existing todo-to-next_up gate remains functional" -- testable by running existing tests 11-20 unchanged after modifications.
• AC3: "Tests cover both gates" -- verifiable by reviewing test file for both backlog-to-todo AND todo-to-next_up scenarios.
• AC4: "Regression test: backlog-to-todo without review note is blocked" -- testable via mock API, same infrastructure as existing deny tests.

Test command bash tests/test_check_board_advance.sh is real and runs correctly today.

Blast Radius

• settings.json hook matcher (line 191) already covers update_board_item and bulk_move_board_items -- no matcher change needed.
• skill-review-ticket SKILL.md references "check-board-advance hook will now allow the todo -> next_up transition" -- this remains accurate since todo-to-next_up gate is preserved.
• Existing Test 2 ("move to todo -- no gate") will need to become a deny test for backlog-to-todo, but this is correctly scoped within the ticket's test file target.
• No similar ungated transitions found in other hooks. check-board-item.sh handles item creation enforcement, not column transitions.
• Rollback is straightforward -- revert the conditional logic back to next_up-only gating.

Decomposition Assessment

2 file targets in 1 repo. 4 acceptance criteria. Estimated agent time: 3-4 minutes. The check_review_approved function already exists and is reusable -- the change extends existing conditional logic (add backlog-to-todo alongside todo-to-next_up in both single-item and bulk-move code paths). No independent subtasks that warrant parallelization. No decomposition needed.

Recommendation

No action needed. Ticket is fully scoped, traceable, and executable in a single agent pass.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — Feature
• [x] Lineage — Standalone, scoped during admin interface review
• [x] Repo — forgejo_admin/basketball-api
• [x] User Story — story:WS-S13, well-written admin schedule management story
• [x] Context — Thorough: explains hardcoded schedule in westside-app, architecture decision (two tables), full data model with column specs
• [x] File Targets — 5 files to modify/create, 2 files explicitly excluded
• [x] Acceptance Criteria — 7 criteria
• [x] Test Expectations — 4 test categories with run command
• [x] Constraints — 5 constraints listed
• [x] Checklist — Present with migration testing added
• [x] Related — Lists project, arch doc, and follow-up tickets

All required sections for the Feature template are present. Template is complete.

Traceability

• [x] story:WS-S13 — "As an admin, I want to view and manage the program schedule" (label present on board item)
• [x] arch:basketball-api — Correctly targets the basketball-api architecture component (label present on board item)
• [x] Forgejo issue — forgejo_admin/basketball-api#230, open

Traceability triangle is complete.

File Targets

• [x] src/basketball_api/models.py — Verified: exists (489 lines). Contains existing Division enum, Team model, Tenant model. EventType enum and new models would be added here. Pattern confirmed: uses Mapped types, tenant FK, server_default=func.now().
• [x] src/basketball_api/routes/admin.py — Verified: exists (1048 lines). Contains existing admin CRUD patterns with require_admin dependency, tenant scoping, Pydantic response models.
• [ ] src/basketball_api/schemas.py — ISSUE: This file does NOT exist. The codebase has NO centralized schemas.py. All Pydantic schemas are defined inline in route files (e.g., admin.py line 51 defines GenerateTokensResponse, public.py defines InterestLeadRequest/InterestLeadResponse). The agent should follow existing convention and define schedule schemas inline in the route file, not create a new schemas.py.
• [x] alembic/versions/xxx_add_schedule_tables.py — Verified: alembic/versions/ directory exists with 21 existing migrations (001 through 021). Next migration would be 022.
• [x] scripts/seed_schedule.py — Verified: scripts/ directory exists with 10 existing scripts (seed.py, backfill_stripe.py, create_groupme_groups.py, etc.). New seed script fits this pattern.
• [x] src/basketball_api/routes/public.py (excluded) — Verified: correctly excluded, public endpoints are a separate concern.

Repo Placement

Correct. Issue is filed on forgejo_admin/basketball-api and all file targets are within basketball-api. The ticket explicitly states westside-app frontend is a follow-up ticket. No cross-repo work needed.

Dependencies

• [x] No blocking dependencies — all prerequisites are satisfied.

Board item #130 "Phase 13: Practice Schedule" exists in backlog with label blocked-by:marcus-input. This is a legacy plan-era phase item. Item #627 appears to be the properly scoped replacement. No active blocker — the marcus-input block on #130 was about schedule details, which are now captured in the seed data section of this ticket.

Board item #410 "Update Schedule: Kings/Queens toggle" is done — frontend schedule page with hardcoded data. No conflict. Board item #299 "Practice schedule page" is done — earlier frontend iteration. No conflict.

No items currently in in_progress that block this work. Follow-up dependencies (admin frontend view, public page refactor) are documented in the issue body and would be separate tickets.

Acceptance Criteria

7 acceptance criteria. All are verifiable by an agent:

• "Alembic migration creates tables" — testable via alembic upgrade head
• "Models follow existing patterns" — verifiable by code review against existing models
• "GET /admin/schedule returns combined" — testable via pytest
• "CRUD endpoints work" — testable via pytest
• "Seed script populates data" — testable by running script
• "Division filter works" — testable via pytest
• "Existing tests still pass" — testable via pytest tests/ -v

Criteria are individually testable and specific. However, combined volume (7 AC + 9 endpoints + 2 models + migration + seed) is substantial. See Decomposition Assessment.

Blast Radius

• Division enum mismatch (CRITICAL): The ticket states division: Enum(Division), nullable with values "kings/queens" in both table specs. However, the actual Division enum in models.py (line 52-54) has values boys = "boys" and girls = "girls", NOT kings/queens. The InterestLead model (line 458-460) uses a freetext String(20) field called program for "kings"/"queens" values. The public.py route (line 186) validates _VALID_PROGRAMS = {"kings", "queens"} separately. The ticket must clarify: use the existing Division(boys/girls) enum, or use a freetext program string field like InterestLead, or extend the enum. This is a design decision that an agent cannot make.
• Tenant model relationships: Adding new tables with tenant_id FK should also add relationship lists to the Tenant model (lines 156-159 show existing patterns: parents, registrations, coaches, teams). Not mentioned in file targets.
• admin.py is already 1048 lines: Adding 9 new endpoints (~200-300 lines) to an already large file. Existing codebase has precedent for separate route files (jersey.py, checkout.py, coaches_api.py, password_reset.py). A new routes/schedule.py would be more maintainable.
• Rollback is straightforward: alembic downgrade -1 removes tables, route removal is clean.
• No similar bug patterns found in sibling services.

Decomposition Assessment

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

• Discrete changes: (1) new enum + 2 models in models.py, (2) alembic migration, (3) 9 CRUD endpoints with Pydantic schemas, (4) seed script, (5) tests for all of the above. That is 5 discrete changes — exceeds the 3-thing limit.
• Estimated agent time: 10-15 minutes minimum (2 models, 9 endpoints, migration, seed script, integration tests). Exceeds 5-minute rule significantly.
• Independent subtasks: Yes. Data model + migration is independent from endpoint implementation. Seed script is independent from both. These could be parallelized after the model ticket merges.

NEEDS DECOMPOSITION. Recommend splitting via template-board into 3 sub-tickets:

1. Data model + migration: EventType enum, PracticeSchedule model, Event model, alembic migration, model unit tests. ~3 files, 2 AC, ~3 min.
2. Schedule API endpoints: 9 CRUD endpoints with Pydantic schemas in a new routes/schedule.py, endpoint integration tests. ~2 files, 3 AC, ~4 min.
3. Seed script: Populate current hardcoded schedule data, verify with assertions. ~1 file, 2 AC, ~2 min.

Recommendation

1. [BODY] Fix Division enum reference: the ticket says "kings/queens" but the codebase Division enum (models.py:52-54) uses boys/girls. The InterestLead model uses a freetext String(20) "program" field for kings/queens. Clarify which approach to use for schedule tables.
2. [BODY] Fix file target: src/basketball_api/schemas.py does not exist. The codebase defines all Pydantic schemas inline in route files. Either remove this target or replace with a new routes/schedule.py route file.
3. [SCOPE] Clarify: should schedule endpoints go in existing admin.py (already 1048 lines) or a new routes/schedule.py? Existing codebase precedent supports separate route files (jersey.py at 200 lines, checkout.py, coaches_api.py).
4. [DECOMPOSE] 7 AC, 9 endpoints, 2 models, migration, seed script, tests across 5 discrete changes. Exceeds both the 3-thing limit and 5-minute rule. Recommend decomposition via template-board into 3 sub-tickets (data model, API endpoints, seed script).

Verdict: READY

Re-review Context

Prior review (review-511-2026-03-28) found 6 issues: missing template sections (Repo, Checklist, Context as standalone header), duplicate ACs, unlisted test commands, and embedded content not matching template structure. All 6 were addressed in the body rewrite. This re-review verifies the fixes and checks for any new issues.

Template Completeness

Checked against template-issue (Task type — Scope replaced by standalone sections per convention):

• [x] Type — Task
• [x] Lineage — Board, Story, Arch listed
• [x] Repo — forgejo_admin/claude-custom
• [x] Context — standalone section, explains no-CI validation model
• [x] User Story — proper As/I want/So that format
• [x] Acceptance Criteria — 4 items, no duplicates
• [x] Test Expectations — 2 items with guidance
• [x] Constraints — 2 items
• [x] Checklist — 5 items
• [x] Related — board + related issue
• [x] PRs merged — 9 PRs listed (extra section, acceptable for validation tasks)

All required template sections present. Prior issues resolved.

Traceability

• [x] story:pm-scope — platform operator validation story, present on board item
• [x] arch:hooks — hooks architecture component, present on board item
• [x] Forgejo issue — forgejo_admin/claude-custom#208, open

All three traceability legs present and correct.

File Targets

N/A — Task type. No file targets required. Validation task does not modify code.

Repo Placement

OK. Issue filed on forgejo_admin/claude-custom. All 9 PRs are on the same repo. No cross-repo concerns.

Dependencies

• [x] All 9 PRs merged to main — satisfied
• [x] ~/claude-custom checkout on main — verified (HEAD at 26293e8)
• [ ] Session restart — pending (requires human action, correctly marked MANUAL in AC 1)

Board context: Item #478 (in_progress, same repo) is independent spike work. No blockers.

Acceptance Criteria

4 ACs — clean, no duplicates (prior review's AC 5/6 duplicates removed):

• AC 1: Session restart without hook load errors — marked MANUAL, correct. Verifiable by human.
• AC 2: All 5 test suites pass — explicit commands listed. See nit below about one incorrect filename.
• AC 3: No regressions in agent spawn — now actionable ("spawn a test dev/qa agent"). Acceptable.
• AC 4: Hook enforcement verified — specific test named (check-board-advance.sh). Verifiable.

All ACs are agent-verifiable or correctly marked as manual.

Blast Radius

Hooks are hardlinked from ~/claude-custom/hooks/ to ~/.claude/hooks/. Changes are live immediately. 9 PRs touched 17+ files (hooks, settings, agent docs, test files). Blast radius is system-wide (hooks fire on every tool use across all projects). No CI gate — manual validation only. Rollback via git revert is straightforward.

Decomposition

No decomposition needed. This is a validation task with zero code changes. Running all tests takes <30 seconds. Single agent pass is appropriate.

Recommendation

Prior review's 6 recommendations — all resolved:

1. [BODY] Add ### Repo — DONE
2. [BODY] Add ### Checklist — DONE
3. [BODY] Restructure into proper template sections — DONE
4. [BODY] Remove duplicate ACs — DONE (6→4, no duplicates)
5. [BODY] Add explicit test commands — DONE
6. [BODY] Mark AC 1 as manual — DONE

New nit found (non-blocking):

• [BODY] Nit: AC 2 lists test_check_board_item.sh (if exists) — this file does NOT exist. The actual 5th test suite is test_block_groupme_send.sh, which is missing from the list. Also, test_validate_branch_name.sh DOES exist, so its "(if exists)" qualifier is unnecessary. Recommend replacing test_check_board_item.sh (if exists) with test_block_groupme_send.sh and removing "(if exists)" from test_validate_branch_name.sh. Non-blocking because an executing agent can discover test files via ls tests/.

Verdict: READY. Scope is solid, template complete, traceability intact, ACs verifiable. The test filename nit is cosmetic — agent can self-correct at execution time.

Verdict: NEEDS_REFINEMENT

Template Completeness

Checked against template-issue (Task type — Scope replaces File Targets):

• [x] Type — Task
• [x] Scope — present, replaces File Targets per Task convention
• [x] Acceptance Criteria — 6 items
• [x] Related — references project-pal-e-platform
• [x] Lineage — present (embedded in Scope as "Lineage:" line)
• [x] User Story — present (embedded in Scope as "User Story:" line)
• [x] Test Expectations — present (embedded in Scope as "Test Expectations:" line)
• [x] Constraints — present (embedded in Scope as "Constraints:" line)
• [ ] Repo — MISSING. Should be forgejo_admin/claude-custom
• [ ] Context — MISSING as standalone section. Background is folded into Scope.
• [ ] Checklist — MISSING

Note: Lineage, User Story, Test Expectations, and Constraints are all embedded within the Scope block as bold inline labels rather than as standalone ### heading sections. The content is present but the structure does not match template headers.

Traceability

• [x] story:pm-scope — platform operator validation story, present on board item
• [x] arch:hooks — hooks architecture component, present on board item
• [x] Forgejo issue — forgejo_admin/claude-custom#208, open

All three traceability legs are present and correct.

File Targets

N/A — Task type uses Scope instead of File Targets. No file targets required.

For reference, the 9 PRs touched these files across claude-custom:

• hooks/cleanup-worktrees.sh (PR #196)
• hooks/pre-spawn-freshness.sh, settings.json (PR #197)
• agents/betty-sue.md (PR #198)
• hooks/forgejo-helper.sh, hooks/post-mcp-merge-rebase.sh, hooks/post-merge-rebase.sh (PR #199)
• hooks/board-item-on-merge.sh, hooks/forgejo-helper.sh, hooks/post-mcp-merge-rebase.sh, hooks/remind-update-docs.sh, tests/test_parse_merged_status.sh (PR #201)
• hooks/check-note-template.sh, tests/test_check_note_template.sh (PR #200)
• agents/penny.md, spikes/133-penny-mcp-inventory.md (PR #204)
• hooks/check-branch-freshness.sh, settings.json (PR #206)
• commands/update-docs.md (PR #207)

All 9 modified hooks pass bash -n syntax check. All 5 test suites pass (115/115 tests).

Repo Placement

OK. Issue is filed on forgejo_admin/claude-custom and all 9 PRs are on the same repo. No cross-repo concerns.

Dependencies

• [x] All 9 PRs merged to main — satisfied
• [x] ~/claude-custom checkout is on main with all PRs present — satisfied
• [ ] Session restart — pending (requires human action, cannot be verified by the reviewing agent)

Board context:

• Item #478 (in_progress): "Spike: Note type system audit" — same repo, independent work, not a blocker.
• Item #523 (done): "Enforce backlog-first column" (PR #212) — merged around the same session but NOT in scope of this ticket's 9 PRs. Separate validation scope.
• Items #518, #519 (backlog): downstream validation pipeline features, not blockers.

Acceptance Criteria

6 ACs listed. Assessment:

• AC 1: "Hooks load on session restart without errors" — verifiable but requires a NEW session. Cannot be tested from within the current session. Mark as manual step.
• AC 2: "Test suites pass (run any hook test commands)" — verifiable. 5 test suites exist but the issue does not list the specific commands. Commands are: bash tests/test_parse_merged_status.sh, bash tests/test_check_note_template.sh, bash tests/test_validate_branch_name.sh, bash tests/test_check_board_advance.sh, bash tests/test_block_groupme_send.sh. All 115 tests currently pass.
• AC 3: "No regressions in agent behavior after merges" — NOT objectively verifiable. Too vague. What behaviors? Which agents? Which regressions?
• AC 4: "Pipeline verified (N/A — no CI)" — correctly marked N/A.
• AC 5: "Deployment confirmed (session restart)" — duplicates AC 1. For claude-custom, deployment IS session restart.
• AC 6: "Features validated (hooks load, tests pass)" — duplicates AC 1 + AC 2.

Effective unique ACs: 2 (hooks load on restart + tests pass). ACs 3, 5, 6 are either vague or duplicative of 1 and 2.

Blast Radius

• Hooks are hardlinked from ~/claude-custom/hooks/ to ~/.claude/hooks/. Changes are live immediately on git pull — no deployment step beyond session restart.
• 9 PRs touched 17 files total: 9 hooks, 2 settings.json changes, 2 agent docs, 1 command doc, 1 spike doc, 2 test files.
• The modified hooks fire on every PreToolUse, PostToolUse, and SessionStart event across ALL projects — blast radius is system-wide.
• No CI pipeline exists for this repo, so these changes were merged without automated gate. The test suites are run manually.
• Rollback: git revert on individual PRs is straightforward since all are merge commits on main.

Decomposition Assessment

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

• Does the ticket have >3 discrete changes? No — this is a validation task, not a code change task. Zero changes required.
• Would an agent need >5 minutes? No — running all tests takes <30 seconds. Syntax checking takes <5 seconds.
• Are there independent subtasks that could be parallelized? No.

No decomposition needed.

However: AC 1 (session restart verification) is a human action, not an agent action. The agent can run tests and verify syntax but cannot restart its own session. The ticket should explicitly mark this as a manual validation step.

Recommendation

1. [BODY] Add missing ### Repo section: forgejo_admin/claude-custom
2. [BODY] Add missing ### Checklist section (standard items: tests pass, no unrelated changes; PR items N/A for validation)
3. [BODY] Restructure embedded content into proper template sections — move Lineage, User Story, Context, Test Expectations, Constraints out of Scope into their own ### headers
4. [BODY] Remove duplicate ACs: collapse AC 5 and AC 6 into AC 1 + AC 2. Either sharpen AC 3 ("No regressions") into something testable (e.g., "SessionStart hooks complete without error output") or remove it.
5. [BODY] Add explicit test commands to Test Expectations: bash tests/test_parse_merged_status.sh, bash tests/test_check_note_template.sh, bash tests/test_validate_branch_name.sh, bash tests/test_check_board_advance.sh, bash tests/test_block_groupme_send.sh
6. [BODY] Mark AC 1 (session restart) as a manual validation step — agent cannot restart its own session.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- Standalone, discovered during parallel agent incident 2026-03-26
• [x] Repo -- Tracker (pal-e-platform), Primary PR (claude-custom), SOP updates (pal-e-docs)
• [x] User Story -- platform operator spawning parallel Dev agents
• [x] Context -- thorough incident description with root cause analysis
• [x] File Targets -- 4 targets across 2 repos + pal-e-docs SOPs, with exclusions listed
• [x] Acceptance Criteria -- 7 ACs, all verifiable
• [x] Test Expectations -- 4 manual tests + run command
• [x] Constraints -- 6 constraints including performance (< 50ms), QA exclusion
• [x] Checklist -- 7 items tracking child issues and deliverables
• [x] Related -- 5 cross-references to SOPs, conventions, adjacent issues

All required Feature template sections present and populated. Issue has been through 4 prior review rounds with body updated from comment refinements.

Traceability

• [x] story:dev-execute -- present on board item #418
• [ ] arch:worktree -- MISMATCH: board item has arch:ci-pipeline but issue body explicitly states arch:worktree (not arch:ci-pipeline -- this is worktree/hooks domain, not Woodpecker CI). The board label was never corrected.
• [x] Forgejo issue -- forgejo_admin/pal-e-platform#188, state: open

File Targets

• [x] hooks/cross-repo-isolation.sh (new) -- confirmed does not exist yet in ~/claude-custom/hooks/. Parent directory exists with 30 existing hooks. New file is appropriate.
• [x] agents/dev.md -- verified exists at ~/claude-custom/agents/dev.md. Confirmed no cross-repo isolation content present (only isolation: worktree in frontmatter). Ready for update.
• [x] cleanup-worktrees.sh -- verified exists at ~/claude-custom/hooks/cleanup-worktrees.sh. Currently handles .claude/worktrees/ cleanup across 22 repos. Does NOT handle /tmp/ clone cleanup -- confirming the gap this ticket addresses.
• [x] worktree-workflow SOP (pal-e-docs) -- verified exists (slug: worktree-workflow, type: sop, status: active). Has no "Cross-Repo Isolation" section yet.
• [x] agent-spawn-conventions (pal-e-docs) -- verified exists (slug: agent-spawn-conventions, type: convention, status: active). Pre-spawn checklist has 4 items, none address cross-repo isolation.

All targets verified. Specificity is high -- agent can act without guessing.

Repo Placement

OK. This is a tracking/umbrella issue filed on pal-e-platform (where the gap was discovered). Decomposition correctly routes:

• Code work to claude-custom#205 (hook + agent profile + cleanup)
• SOP work to Dottie (pal-e-docs MCP updates)

The umbrella/child structure is clean. No single-repo misfiling.

Dependencies

• [x] claude-custom#184 (worktree isolation enforcement gaps) -- board item #485 is in done column. Issue body correctly states "no overlap": #184 covers freshness + cleanup, this covers cross-repo isolation. No blocker.
• [x] claude-custom#205 (child issue, hook + agent profile) -- open, ready for execution.
• [x] No items in in_progress block this ticket.

Acceptance Criteria

7 ACs, all agent-verifiable:

• AC 1-2: /tmp/ clone or git worktree for non-spawning repos -- verifiable by code inspection of hook logic
• AC 3-4: SOP updates -- verifiable by reading pal-e-docs notes post-update
• AC 5: PreToolUse hook warns on unsafe cd ~/repo && git checkout pattern -- verifiable by running hook with mock input
• AC 6: Dev agent profile updated -- verifiable by reading agents/dev.md
• AC 7: /tmp/ cleanup mechanism -- verifiable by reading cleanup-worktrees.sh

All ACs are testable and specific. No ambiguous "works correctly" language. Test expectations include 4 manual tests and a concrete run command.

Blast Radius

• No existing hook handles cd ~/repo && git checkout cross-repo detection. The new hook is purely additive -- no existing behavior modified.
• cleanup-worktrees.sh currently scans 22 repos for .claude/worktrees/ but does NOT clean /tmp/ clones. Adding /tmp/ cleanup is a net-new code path -- low regression risk.
• pre-spawn-freshness.sh and check-branch-freshness.sh handle freshness for worktrees. The cross-repo hook is orthogonal -- no overlap or conflict.
• Only agents/dev.md needs updating among the 5 agent profiles (QA is read-only, Betty Sue/Dottie/Penny don't write code). Constraint correctly identified in issue.
• Rollback: removing the hook file + reverting dev.md changes. Straightforward.

Decomposition Assessment

Already decomposed into 2 children per the 5-minute rule:

• Child 1: claude-custom#205 -- hook + agent profile + cleanup (AC 1,2,5,6,7). 3 file targets in 1 repo. Fits three-thing limit and five-minute rule.
• Child 2: Dottie SOP task -- 2 pal-e-docs note updates (AC 3,4). Fits five-minute rule.

Parent issue #188 is an umbrella tracker. The two children are independent and can be parallelized. No further decomposition needed.

Recommendation

1. [LABEL] Fix arch label on board item #418: change arch:ci-pipeline to arch:worktree. The issue body explicitly states this correction in its "Board Labels" section, but the board item was never updated to match.

One label fix and this ticket is READY. All other aspects are solid after 4 prior review rounds and a full body rewrite incorporating all comment refinements.

Glossary: Platform Definitions

Canonical definitions for the DORA Elite AI Enterprise operating model. If a term is used in plans, SOPs, conventions, or templates, it is defined here. A stranger should be able to read this note and understand the vocabulary without asking anyone.

Enterprise

The superuser can manage the entire platform and all its projects from a single Claude Code interface, with the right context loading at the right time.

Enterprise means the system is legible (a stranger can read the docs and understand the product), auditable (every decision traces back to a reason), and operational (work continues without the founder narrating). The documentation answers questions without Lucas in the room.

Three properties make this concrete:

• Platform-wide context loads automatically — personality, SOP index, plan index, superuser stories across all projects
• Project-specific context loads on demand — when the superuser points at a project (via working directory or explicit signal), that project's board, roles, active phases, and skills come into focus
• The superuser has a story in every project — not "Lucas is the founder" but specific needs per project that drive observability, prioritization, and acceptance criteria

Role Hierarchy

Role	Scope	Maps To	Example
Superuser	Platform-wide	Keycloak realm admin, k8s access, all projects	Lucas
Admin	Per-project	Keycloak client role: admin, /admin routes, CRUD ops	Marcus (Westside)
Domain Role	Per-project, specific	Keycloak client-specific roles, scoped routes	Coach, Parent, Player (Westside)

Superuser and Admin are platform-level concepts — they appear on every project page. Domain Roles are project-specific and defined only on the projects that have them.

User Story

Who uses the system, what they need, how we measure success. Section #2 on every project page (per template-project-page). User stories are organized by role from the Role Hierarchy. Each story should be specific enough to derive acceptance criteria and observability metrics.

Format: "As a [role], I can [action], measured by [metric]."

The superuser has stories in every project. Domain roles have stories only in their project.

Traceability Triangle

           User Story (story:X)
          /                    \
         /   ticket carries     \
        /    all three legs      \
       /                          \
Architecture (arch:Y) ———————— Phase (note_slug)

Every board ticket answers three questions:

1. Why are we doing this? → User story from the project page (story:X label)
2. What part of the system does it touch? → Architecture diagram (arch:Y label)
3. How is it scoped? → Plan phase (note_slug) or Forgejo issue (forgejo_issue_url)

When any leg changes, the other two must be checked for alignment. Defined in template-ticket.

Scoping Pipeline

Discovery → Typed Forgejo Issue → Board (backlog → todo → next_up) → Agent → PR → Merge → Deploy

The chain that turns an idea into deployed code. Management (Betty Sue) owns everything left of the agent spawn. Agents own everything right. The Forgejo Issue is the handoff point — by the time an agent sees it, all context, scope, and acceptance criteria are baked in.

Single entry point — all work enters as a typed Forgejo issue on a project board:

• Feature — new capability or enhancement
• Bug — something broke that used to work
• Spike — investigation before scoping
• Task — housekeeping, docs, config (no code file targets)

Three Pillars

Pillar	Owns	DORA Metric	Project
Platform	Infrastructure, DevOps, SRE, observability	Deployment Frequency / MTTR	pal-e-platform
Docs	Knowledge system, boards, note taxonomy, product	Change Lead Time	pal-e-docs
Agency	Process, enforcement, SOPs, agents, scoping pipeline, hooks	Change Failure Rate	pal-e-agency

Together, the three pillars form the DORA Elite AI Enterprise. Each pillar maps to a DORA metric and eliminates a dependency on the founder: Platform (infra runs without you), Agency (process runs without you), Docs (product intent is legible without you).

Continuous Kanban

Continuous flow, not time-boxed sprints. One board per project. Columns are statuses (backlog → todo → next_up → in_progress → qa → needs_approval → done), not time periods. Left side (backlog → next_up) is the scoping pipeline owned by Betty Sue. Right side (in_progress → done) is hook-automated. See sop-board-workflow.

Nit

A QA finding on an approved PR that isn't a blocker. Nits are bundled per PR into a single typed Forgejo issue (### Type\nNit-Bundle) on the relevant repo. The issue auto-syncs to the project board's backlog. During triage, Betty Sue can segment individual nits into separate issues if warranted. The plan Epilogue references the nit-bundle issue for provenance but is not the tracking mechanism. See template-issue-nit-bundle.

Issue Types

Type	When	Template
Feature	New functionality, enhancements, planned work	template-issue-feature
Bug	Broken behavior, regressions, alert-driven fixes	template-issue-bug
Spike	Unclear scope, needs investigation, time-boxed	template-issue-spike
Nit-Bundle	QA nits from an approved PR, bundled for triage	template-issue-nit-bundle

Related

• template-project-page — project page structure (User Stories at position #2)
• template-ticket — board ticket structure (traceability triangle labels)
• template-issue — canonical issue design principle
• sop-board-workflow — continuous kanban column semantics
• agent-workflow — management/execution layer boundary
• dora-framework — DORA metric mapping

TODO: Document .claude-no-enforce in agent-workflow SOP

What

The .claude-no-enforce dotfile exists in check-issue.sh (line 74) as a repo-level opt-out from issue-driven development enforcement. It's undocumented in pal-e-docs — the agent-workflow SOP, betty-sue agent profile, and related conventions don't mention it.

Why

Frontend iteration with Lucas in the loop requires direct coding by the main session. The full agent spawn → issue → PR lifecycle is too heavy for "move this div, check on phone, tweak the color." The dotfile already exists in the hook system but needs to be documented as a first-class escape hatch.

Updates needed

• agent-workflow — add exception to Rule 5: "Unless .claude-no-enforce is present in the repo root, which authorizes direct coding by the main session"
• agent-betty-sue — update Code Tools and Constraints sections to reference the dotfile
• betty-sue.md in claude-custom — same updates
• Consider: create a convention note (convention-claude-no-enforce) documenting when/why to use it
• Consider: should .claude-no-enforce be in a global .gitignore or per-repo?

Links

• check-issue.sh line 74 — the implementation
• feedback_frontend_iteration — the principle behind it
• sop-frontend-dev-overlay — the workflow this supports

BUG: MCP servers silently fail to load in Claude Code sessions

Problem

Claude Code silently drops MCP servers that fail to initialize during session startup. No error is surfaced to the user or agent. In a 2026-03-13 session on pal-e-platform, both pal-e-docs and forgejo MCP servers were absent from the tool registry, while notion and woodpecker loaded fine. All four servers are defined in ~/.mcp.json, all import and start correctly when tested manually. Session restart fixed it.

Root Cause

Unknown — likely a transient timeout or dependency resolution delay during Claude Code's MCP initialization. No MCP startup logs exist (~/.claude/logs/ doesn't exist). Claude Code provides zero observability into MCP server health. The private Forgejo PyPI index used by pal-e-docs-sdk and ldraney-forgejo-sdk may contribute to slower uv run startup times, but both servers start fine when tested manually.

Recovery

See sop-mcp-server-recovery for the full recovery procedure. This bug's content has been absorbed into that SOP as part of Phase 5 (plan-pal-e-agency). The SOP covers detection, diagnosis, and recovery for all MCP server failure modes including this silent load issue.

Fix (TODO)

Create a SessionStart hook in claude-custom that verifies expected MCP servers loaded. See Forgejo issue forgejo_admin/claude-custom#76.

Related

• sop-mcp-server-recovery — the recovery SOP that absorbs this bug's failure mode
• plan-pal-e-agency — Phase 5 created the recovery SOP
• sop-claude-config-development — workflow for claude-custom changes

Update SOPs for mature-project ticket pattern

As projects mature, not all work needs plan lineage. Phases are for foundational/architectural work. Improvements, features, and bugs on mature projects can be board tickets with Forgejo issues — no phase note needed. Five docs need updates to reflect this evolved practice:

1. convention-todo-lifecycle (medium) — Graduation can mean "Forgejo issue on board," not just "phase in plan." Distinguish greenfield (→ phase) from mature (→ ticket).
2. agent-spawn-conventions (small) — Reword "No plan, no agent" axiom headline to match the actual rule (plan, TODO, or project slug).
3. sop-board-workflow (small) — Triage step 3: differentiate scoping by item_type (phase needs phase note, issue needs acceptance criteria, todo needs clear title).
4. template-ticket (small) — Lifecycle: add mature-project arrival path (direct issue/todo without plan parentage).
5. template-phase (small) — Add "When to Use" decision gate (architecture change? cross-repo? new capability?).

Discovered: 2026-03-15, during F12/F13 scoping session. The practice already works — the docs just haven't caught up.

Severity: High — breaks agent spawning mid-session

Observed: 2026-03-07 (twice in same session, PR #58 and issue #59), 2026-03-16 (session startup warning: ~/claude-custom on branch 115-vector-powered-startup-briefing with uncommitted changes to plugins/installed_plugins.json)

Problem

Dev agents spawned with isolation: "worktree" targeting claude-custom repo check out feature branches in ~/claude-custom directly instead of using an isolated worktree. Because ~/.claude/hooks/ symlinks to ~/claude-custom/hooks/, every branch checkout makes the in-progress hook live immediately.

Impact

• PR #58: New issue-gate hook was live before merge (harmless — desired behavior)
• Issue #59: Schema-based hook went live referencing a schema file that doesn't exist on main. Broke QA agent spawning with "Agent spawn schema not found"
• 2026-03-16: Session startup hook warns about uncommitted changes — branch 115 left dirty after vector-powered-startup work. Hooks on that branch are live instead of main.

Root Cause

isolation: "worktree" creates a worktree relative to the invoking repo (~/pal-e-platform), not the target repo (~/claude-custom). The dev agent then clones or checks out claude-custom in ~/claude-custom directly, switching the branch on the main checkout.

Workaround

After every agent that touches claude-custom, run: cd ~/claude-custom && git checkout main && git pull

Acceptance Criteria

• Dev agents working on claude-custom never switch the branch on ~/claude-custom
• ~/.claude/hooks/ always reflects main branch during a session
• In-progress hook changes are never live before merge

Recommended Fix (from Phase 16 analysis)

1. Best: CLAUDE.md instruction — Add to claude-custom's CLAUDE.md: "Always clone to /tmp/claude-custom-{branch} for development. Never work in ~/claude-custom directly." Cheapest fix, aligns with agent-spawn-conventions.
2. Better: Post-agent reset hook — SessionStart hook that checks ~/claude-custom is on main and clean. Already partially exists (the startup warning is this hook). Extend it to auto-reset.
3. Best long-term: Break the symlink — Copy hooks on deploy/merge instead of symlinking. Requires a deploy step but eliminates the root cause entirely.

Related

• todo-worktree-tmp-migration — /tmp worktrees would partially solve this
• phase-postgres-epilogue-cleanup — worktree migration is epilogue item 1
• plan-pal-e-agency Phase 16 — Agent Model Completion (absorbs this bug)

Overview

I build production MCP servers connecting Claude to internal tools — not tutorials, not proofs of concept. This page is a guided tour of live work, architecture, and methodology. Everything here is running on self-hosted infrastructure I maintain.

Production MCP Servers

Seven MCP servers in production, each following the same repeatable integration architecture:

Server	Integrates	Pattern	Status
pal-e-docs-mcp	Knowledge platform API (500+ notes, semantic search, project management)	SDK → MCP stdio	Production
forgejo-mcp	Self-hosted Git platform (Forgejo) — issues, PRs, repos, labels	SDK → MCP stdio	Production
woodpecker-mcp	CI/CD pipeline (Woodpecker) — 117 SDK endpoints	SDK → MCP stdio	Production
gmail-mcp	Email (Gmail API) — send, read, draft	MCP Remote HTTP	Production
gcal-mcp	Calendar (Google Calendar API) — events, scheduling	MCP Remote HTTP	Production
linkedin-mcp-scheduler	Social media publishing — scheduled posts with SQLite queue	MCP Remote HTTP	Production
notion-mcp	External knowledge base (Notion API)	MCP Remote HTTP	Production

Integration Architecture: The Triplet Pattern

Every integration follows the same three-layer architecture. This is the repeatable pattern — new systems plug in without reinventing the wheel:

1. SDK — Typed Python client for the service API. Published to PyPI (private registry). Full type hints, error handling, retry logic. This is the foundation — everything else builds on it.
2. MCP Server (stdio) — MCP server wrapping the SDK for local Claude Code use. Agents get structured tool access to the service. Runs as a subprocess alongside Claude.
3. MCP Remote (HTTP) — Streamable HTTP connector for Claude.ai and remote clients. OAuth-secured, deployed to k8s. This is the production-grade access layer.

This pattern means ramping on a new system is predictable: write the SDK, wrap it in MCP tools, deploy. The architecture is documented in detail: Integration Triplet Pattern.

Agentic Workflow

MCP servers are infrastructure. What matters is the operating model built on top of them. I run a 5-agent system where each agent has scoped MCP access and clear responsibilities:

• Betty Sue (Coordinator) — Plans work, dispatches agents, manages documentation. Uses pal-e-docs-mcp, forgejo-mcp, woodpecker-mcp.
• Dev (Developer) — Writes all code across frontend, backend, and infrastructure. Uses forgejo-mcp for issue/PR lifecycle.
• QA (Quality) — Reviews PRs with domain-specific expertise. Catches bugs AND process violations.
• Penny (Communications) — Handles email, calendar, social, external knowledge bases. Uses gmail-mcp, gcal-mcp, linkedin-mcp-scheduler, notion-mcp.
• Dottie (Documentation) — Maintains the knowledge platform. Uses pal-e-docs-mcp for note lifecycle.

The full agent architecture, including separation of concerns and DORA metric integration, is documented here: Pal-E Agency Architecture.

Project execution is tracked via continuous kanban boards with DORA metrics (Deployment Frequency, Lead Time, Change Failure Rate, Mean Time to Recovery). The workflow SOP: Agent Workflow.

How I'd Approach Your Problem

The job description asks for MCP integrations connecting Claude to CRM, deal platforms, and data systems. Here's how my proven pattern maps to each:

• CRM Integration — SDK-first: build a typed Python client for the CRM's REST API (HubSpot, Salesforce, Pipedrive — the pattern is the same). Then wrap it in an MCP server so Claude can search contacts, update deals, log activities, and pull reports through structured tools. No prompt-stuffing, no screen scraping — clean API access with type safety.
• Deal Platforms — Same triplet pattern. OAuth for production access. MCP tools scoped to deal lifecycle: create, update status, attach documents, notify stakeholders. Each platform gets its own SDK so integrations don't couple.
• Data Systems — Webhook listeners for real-time events + MCP query tools for Claude to pull structured data. If the system has an API, it gets an SDK. If it pushes events, we catch them and surface them as tool context.
• Workflow Automation — Agent specialization. Each workflow gets a purpose-built agent with scoped MCP access — just like my current system where the communications agent only touches email/calendar tools and the developer agent only touches code/git tools. Separation of concerns prevents Claude from taking unintended actions.

Platform

Everything above — this page, the documentation, the git hosting, the CI/CD, the MCP servers — runs on self-hosted k3s with Tailscale ingress, Forgejo for git, Woodpecker CI for pipelines, and Prometheus/Grafana for observability. No vendor lock-in. Full control. This page is served by the platform.

Hook Catalog — Complete Enforcement Surface

Complete map of every hook script in claude-custom/hooks/ to its event, matcher, SOP/convention, and enforcement layer. This is the single source of truth for the enforcement surface. 34 scripts total: 30 settings hooks, 3 frontmatter hooks, 1 utility.

Last audited: 2026-03-14. Repo: forgejo_admin/claude-custom.

Layer 1: Block (PreToolUse — hard stops)

Hard enforcement — rejects non-compliant actions before they execute. Exit 2 = blocked.

Script	Matcher	What it blocks	Backs SOP/Convention
block-upstream.sh	Bash	git push upstream — prevents pushing to upstream remotes	Branch protection convention
block-main-commits.sh	Bash	git commit on main branch — forces branch workflow	branch-protection
block-pr-merge.sh	Bash	gh pr merge / git merge — prevents CLI merges (use MCP)	solo-dev-pr-workflow
block-claude-custom-main-edit.sh	Write|Edit|NotebookEdit	Direct edits to claude-custom files on main branch	sop-claude-config-development
block-mcp-merge.sh	mcp__forgejo__merge_approved_pr	Merge without explicit user approval	pr-lifecycle
check-issue.sh	Write|Edit|NotebookEdit	File writes without Forgejo issue tracking	agent-workflow
check-agent-spawn.sh	Task (Agent tool)	Agent spawn without plan/issue/project slug in prompt	agent-spawn-conventions
check-pr-template.sh	mcp__forgejo__submit_pr	PR without required template sections	template-pr-body
check-issue-template.sh	mcp__forgejo__create_issue*	Issue without required template sections	template-issue
check-note-template.sh	mcp__pal-e-docs__create_note	Note creation without proper structure	Various templates
check-phase-template.sh	mcp__pal-e-docs__create_note	Phase creation without Lineage/template compliance	template-phase
warn-delete-note.sh	mcp__pal-e-docs__delete_note	Note deletion without backup (warning, not hard block)	sop-note-deletion
check-ruff-before-commit.sh	Bash	git commit in Python repos with ruff violations	Code quality convention

Layer 2: Auto-format (PreToolUse — fix compliance automatically)

Automatically fixes compliance issues — no human intervention needed.

Script	Matcher	What it does	Backs SOP/Convention
auto-ruff-format.sh	Bash	Runs ruff format on staged .py files before git commit	Code quality convention
pypi-pr-checklist.sh	Bash	Adds PyPI publishing checklist to PR body for SDK repos	PyPI publishing convention

Layer 3: Auto-label (PostToolUse — state machine advancement)

Automatically advances the Forgejo issue lifecycle state machine via label changes.

Script	Matcher	What it does	Backs SOP/Convention
label-on-branch.sh	mcp__forgejo__create_issue_and_branch	Sets status:in-progress label when branch created	pr-lifecycle
label-on-pr.sh	mcp__forgejo__submit_pr	Sets status:qa label when PR submitted	pr-lifecycle
label-on-verdict.sh	mcp__forgejo__comment_on_pr	Sets status:approved or status:needs-fix based on verdict	pr-lifecycle

Layer 4: Remind (PostToolUse — nudge downstream obligations)

Non-blocking reminders that nudge the next step in the workflow.

Script	Matcher	What it reminds	Backs SOP/Convention
remind-review-loop.sh	Bash (git push)	Run /review-pr after pushing a branch	pr-review-loop
remind-mcp-review-loop.sh	mcp__forgejo__submit_pr	Same, for MCP-submitted PRs	pr-review-loop
remind-update-docs.sh	mcp__forgejo__merge_approved_pr	Run /update-docs after merging	sop-post-merge-docs
remind-sprint-update.sh	mcp__forgejo__merge_approved_pr	Move board item to done after merging	Board management convention
post-merge-rebase.sh	Bash (git push)	Rebase other branches after merge to main	worktree-workflow
post-mcp-merge-rebase.sh	mcp__forgejo__merge_approved_pr	Same, for MCP merges	worktree-workflow

Layer 5: Context inject (SessionStart + SubagentStart)

Inject personality, SOPs, plan context at session/agent startup.

Script	Event	What it injects	Backs SOP/Convention
session-start-context.sh	SessionStart	Personality, active SOPs, plan TOCs, open bugs/TODOs	agent-workflow
check-claude-custom-clean.sh	SessionStart	Warns if claude-custom not on main (stale hooks risk)	sop-claude-config-development
cleanup-worktrees.sh	SessionStart	Cleans stale worktrees on session start	worktree-workflow
check-mcp-servers.sh	SessionStart	Detects missing MCP servers, warns (fail-open)	sop-mcp-server-recovery
inject-subagent-context.sh	SubagentStart (qa|dev|general-purpose|dottie)	Injects plan context + personality into spawned agents	agent-spawn-conventions

Layer 6: Agent containment (frontmatter + Stop)

Defense-in-depth inside agent contexts. Frontmatter hooks fire only inside the agent.

Script	Location	What it enforces	Backs SOP/Convention
block-docs-writes.sh	Frontmatter: dev.md, qa.md	Blocks all pal-e-docs write MCP tools (17 ops)	agent-spawn-conventions
block-write-tools.sh	Frontmatter: qa.md	Blocks Write/Edit/Bash inside QA agent	agent-spawn-conventions
block-dottie-code-writes.sh	Frontmatter: dottie.md	Blocks code writes (Write/Edit/Bash on repos) inside Dottie	agent-spawn-conventions
stop-doc-checkin.sh	Stop event (settings)	Prompts doc check-in at session end	sop-post-merge-docs

Utility (not a hook)

Script	Purpose
forgejo-helper.sh	Shared helper sourced by label-on-*.sh scripts. Provides Forgejo API auth and label functions.

Coverage Gaps

SOPs/conventions that exist but have NO hook enforcement:

SOP/Convention	Gap	Suggested Hook	Phase
sop-platform-tf-changes	tofu plan without -lock=false from worktrees	PreToolUse:Bash — block tofu plan missing -lock=false	—
sop-platform-tf-changes	Infra PRs merged without pre-merge validation evidence (tofu plan output, kubectl kustomize output)	PreToolUse:mcp__forgejo__merge_approved_pr — check PR body/comments for validation evidence on infra repos	Phase 17a
sop-incident-response	Incident board tracking is in the SOP (Step 4) but not hook-enforced — manual process	PostToolUse:incident note creation — prompt for board item creation	—
sop-note-deletion	warn-delete-note.sh warns but doesn't enforce backup	PreToolUse — require backup confirmation before delete	—
convention-arch-sop-pairing	No hook ensures new arch notes link to SOPs	PostToolUse:create_note — check if note_type=reference, prompt for SOP link	—
ci-rules	CI conventions are documented but not hook-enforced	PreToolUse:Bash — block skip-ci patterns	—

Statistics

Category	Count
Total scripts	34
Settings hooks	30
Frontmatter hooks	3
Utility scripts	1
Events used	5 of 17 (SessionStart, PreToolUse, PostToolUse, Stop, SubagentStart)
Events unused	12 (SessionEnd, PreCompact, UserPromptSubmit, PostToolUseFailure, PermissionRequest, SubagentStop, TeammateIdle, TaskCompleted, ConfigChange, Notification, WorktreeCreate, WorktreeRemove)
SOPs backed by hooks	12
Coverage gaps identified	4

Related

• hook-events-reference — event types, inputs/outputs, matchers
• enforcement-architecture — enforcement layer model (4 layers within Agency)
• sop-index — SOP → agent → enforcement mapping
• sop-hook-block-recovery — what to do when a hook blocks unexpectedly
• sop-claude-config-development — how to safely develop hooks
• Procedures: sop-hook-block-recovery — recovery when hooks block unexpectedly

Agent Paradigm

The 5-layer model for how AI agents operate on the pal-e platform. Each layer has a distinct role and clean boundaries. This is the corrected paradigm — the previous "four pillars" model (enforcement-architecture) is correct but incomplete, missing the Events layer.

flowchart TD
    EVENTS["Events\n(16 lifecycle moments)"]
    HOOKS["Hooks\n(attach to events, enforce)"]
    MCP["MCP\n(data + operations)"]
    SKILLS["Skills\n(workflows using MCP)"]
    AGENTS["Agents\n(stateless roles)"]

    EVENTS -->|trigger| HOOKS
    HOOKS -->|query & guard| MCP
    MCP -->|data for| SKILLS
    SKILLS -->|executed by| AGENTS
    AGENTS -->|work triggers| EVENTS

Layer 1: Events

Events are lifecycle moments — things that happen during a Claude Code session. They are the trigger system. Nothing else fires without an event.

• 16 events total (see hook-events-reference for the complete list)
• Categories: Session, User, Tools, Agents, Config, Git
• Events themselves don't DO anything — they fire, and hooks attach to them
• Key events: SessionStart, PreToolUse, PostToolUse, SubagentStart, Stop

Layer 2: Hooks

Hooks attach to events and enforce rules. They are shell scripts that run when events fire. Hooks are the hard enforcement layer — agents cannot bypass them.

• Inject context — SessionStart queries pal-e-docs for project page, SOPs, active plans
• Block bad actions — PreToolUse prevents main commits, unauthorized merges, missing issues
• Block unauthorized spawns — SubagentStart prevents native delegation without plan context (exit 2)
• Remind workflows — PostToolUse triggers review-fix loop reminders after PR submission
• Guard both Bash commands AND MCP tool calls via separate matchers

Layer 3: MCP (Data + Operations)

MCP servers provide queryable data and structured operations. They are the knowledge layer.

• pal-e-docs MCP: 14 tools — notes, projects, tags, links, repos. The knowledge base.
• forgejo-mcp: 12 tools — issues, PRs, branches, reviews. Git operations with SOP awareness.
• Data is structured and tagged — agents query by tag intersection, not file paths
• MCP is the single source of truth — no scattered local files

Layer 4: Skills

Skills define multi-step workflows that use MCP tools. They are thin orchestration layers — the content lives in pal-e-docs, not in the skill definition.

• /plan — fetches plan template, creates plan note, archives previous, updates project page
• /review-pr — orchestrates review-fix loop using forgejo-mcp tools
• Skills reference templates and SOPs by slug
• Invoked by users via /skill-name syntax
• Skills can delegate to agents via context: fork + agent field (convenience wiring)

Layer 5: Agents

Agents are stateless roles that follow skills and query MCP. Context comes from the system, not from memory.

• Betty Sue: Main session coordinator. Plans, manages docs, spawns agents. Injected via SessionStart hook, not a subagent.
• Dev Agent: Writes code, manages repos, creates PRs. Follows SOPs injected at session start.
• QA Agent: Reviews PRs for correctness and SOP compliance. Read-only tools.
• Issue Creator: Proposes well-formed issues from plan phases.
• Review agents: Fresh-context agents spawned by /review-pr to review diffs.
• Fix agents: Task agents that address review findings.

How They Compose

1. Event (SessionStart) fires → Hook queries MCP (pal-e-docs) → context injected into agent
2. Agent receives task → queries MCP for SOPs and current state
3. Agent follows Skill workflow → skill uses MCP tools
4. Every tool call triggers Events (PreToolUse, PostToolUse) → Hooks guard and remind
5. Agent updates MCP (pal-e-docs) with new knowledge → cycle continues

Key Insight

The previous "four pillars" model describes Hooks, MCP, Skills, and Agents as co-equal pillars. The corrected model shows they are layers with a directional flow: Events trigger Hooks, Hooks use MCP, MCP feeds Skills, Skills are run by Agents. The cycle is closed because Agent work triggers new Events.

Related

• hook-events-reference — complete event list with inputs and outputs
• enforcement-architecture — enforcement layer detail with stack hierarchy (Note: the three operating model pillars — Platform, Docs, Agency — are separate from these enforcement layers.)
• agent-workflow — practical agent workflow SOP

Hook Events Reference

Claude Code provides 17 lifecycle events that hooks can attach to. Events are the trigger system — hooks attach to events and enforce rules.

All Events

Category	Event	When it fires	Can block?	Supports matcher?
Session	SessionStart	Session begins, resumes, or clears	No	Yes (startup, resume, clear, compact)
Session	SessionEnd	Session terminates	No	Yes (clear, logout, prompt_input_exit, etc.)
Session	PreCompact	Before context compaction	No	Yes (manual, auto)
User	UserPromptSubmit	User submits a prompt (before processing)	Yes (decision: block)	No
User	Stop	Agent finishes responding	Yes (decision: block)	No
User	Notification	Claude Code sends a notification	No	Yes (notification type)
Tools	PreToolUse	Before a tool call executes	Yes (deny/allow/ask)	Yes (tool name regex)
Tools	PostToolUse	After a tool call succeeds	No (tool already ran)	Yes (tool name regex)
Tools	PostToolUseFailure	After a tool call fails	No (tool already failed)	Yes (tool name regex)
Tools	PermissionRequest	Permission dialog appears	Yes (allow/deny)	Yes (tool name regex)
Agents	SubagentStart	Subagent spawned	No — can only inject context	Yes (agent type name)
Agents	SubagentStop	Subagent finishes	Yes (decision: block prevents stopping)	Yes (agent type name)
Agents	TeammateIdle	Team teammate about to go idle	Yes (exit 2)	No
Agents	TaskCompleted	Task marked complete	Yes (exit 2)	No
Config	ConfigChange	Config file changes during session	Yes (decision: block)	Yes (config source)
Git	WorktreeCreate	Worktree being created	Yes (non-zero exit fails creation)	No
Git	WorktreeRemove	Worktree being removed	No	No

SubagentStart / SubagentStop Detail

SubagentStart — Context Injection (NOT Blocking)

SubagentStart CANNOT block subagent creation. Exit code 2 only shows stderr to the user — it does not prevent the subagent from spawning. This is a critical distinction from PreToolUse.

What SubagentStart CAN do:

• Inject additionalContext: Return JSON with hookSpecificOutput.additionalContext — this string is added to the subagent's context.
• Side effects: Logging, notifications, etc.
• Matchers: Filter by agent type name (e.g., qa, dev, issue-creator, Explore, Plan).

SubagentStart input (on stdin as JSON):

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/current/working/directory",
  "permission_mode": "default",
  "hook_event_name": "SubagentStart",
  "agent_id": "agent-abc123",
  "agent_type": "Explore"
}

Note: No prompt field is available in SubagentStart input. Only agent_id and agent_type are provided beyond the common fields.

SubagentStart output (inject context):

{
  "hookSpecificOutput": {
    "hookEventName": "SubagentStart",
    "additionalContext": "You are working on plan-2026-02-28-agent-skill-frontmatter. Read the plan: get_note(slug=\"plan-2026-02-28-agent-skill-frontmatter\")"
  }
}

Settings.json example:

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "qa|dev|issue-creator",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/inject-subagent-context.sh"
          }
        ]
      }
    ]
  }
}

SubagentStop — CAN Block (Prevents Stopping)

SubagentStop CAN block via decision: "block" — this prevents the subagent from stopping (it continues working). Uses the same decision control as Stop hooks.

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../abc123.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "SubagentStop",
  "stop_hook_active": false,
  "agent_id": "def456",
  "agent_type": "Explore",
  "agent_transcript_path": "~/.claude/projects/.../abc123/subagents/agent-def456.jsonl",
  "last_assistant_message": "Analysis complete. Found 3 potential issues..."
}

Enforcement Asymmetry

This creates an enforcement asymmetry between the two spawn paths:

Spawn path	Can block spawn?	Can inject context?	Can enforce tool use?
Manual (Agent tool)	Yes — PreToolUse deny	Yes — via prompt	Yes — PreToolUse hooks
Native delegation	No	Yes — additionalContext	Yes — frontmatter PreToolUse hooks

To compensate: use SubagentStart to inject plan context and frontmatter PreToolUse hooks for defense-in-depth (e.g., QA agent blocks Write/Edit/Bash at the hook level).

Common Input (all events receive on stdin as JSON)

{
  "session_id": "unique_session_id",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/current/working/directory",
  "permission_mode": "default|plan|acceptEdits|dontAsk|bypassPermissions",
  "hook_event_name": "NameOfEvent"
}

Tool Events — Additional Input

PreToolUse, PostToolUse, PostToolUseFailure, and PermissionRequest also receive:

{
  "tool_name": "Bash",
  "tool_input": { ... }
}

SessionStart — Additional Input

{
  "source": "startup|resume|clear|compact",
  "model": "claude-opus-4-6",
  "agent_type": "optional_agent_name"
}

Hook Response Patterns

Pattern	How	Used by
Add context	Exit 0, stdout text	SessionStart, UserPromptSubmit, SubagentStart
Block action	Exit 2, stderr message	PreToolUse, UserPromptSubmit, Stop, SubagentStop, WorktreeCreate
Allow/Deny tool	JSON: hookSpecificOutput.permissionDecision	PreToolUse
Decision block	JSON: decision: "block"	UserPromptSubmit, PostToolUse, Stop, SubagentStop, ConfigChange
Stop execution	JSON: {"continue": false, "stopReason": "..."}	Universal
Side effect only	Exit 0, no output	Any event

MCP Tool Matching

MCP tools follow the pattern mcp__<server>__<tool>. Matchers are regex patterns.

mcp__forgejo__merge_approved_pr    // exact match
mcp__forgejo__.*                    // all forgejo tools
mcp__pal-e-docs__create_note       // specific pal-e-docs tool
mcp__.*__create.*                   // any MCP create operation

Hook Types per Event

Not all events support all hook types:

All four types (command, http, prompt, agent): PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, Stop, SubagentStop, TaskCompleted, UserPromptSubmit

Command only: ConfigChange, Notification, PreCompact, SessionEnd, SessionStart, SubagentStart, TeammateIdle, WorktreeCreate, WorktreeRemove

Related

• enforcement-architecture — four pillars overview with enforcement stack
• agent-workflow — how agents use the enforcement system
• agent-spawn-conventions — spawn axiom and enforcement asymmetry
• Claude Code hooks docs — official reference
• Claude Code subagent docs — frontmatter hooks
• Procedures: sop-hook-block-recovery — recovery procedure when hooks block unexpectedly

Enforcement Architecture

The pal-e enforcement stack is built on four enforcement layers that work together within Agency. Each layer has a distinct role. (Note: these are enforcement layers within the Agency pillar, not the three operating model pillars — Platform, Docs, Agency. The headings below use "Pillar" to mean "enforcement layer" for historical reasons.)

Enforcement Stack (Hierarchy)

Agents wrap skills. Skills wrap MCP tools. But none of that is enforcement — it's organizational convenience. The only guaranteed enforcement mechanisms are hooks and disallowedTools. Everything else can be bypassed.

Hard enforcement (cannot be bypassed)
  ├── disallowedTools — strips tools from agent palette entirely
  ├── Frontmatter PreToolUse hooks — blocks tool calls inside agents (exit 2)
  └── Settings PreToolUse hooks — blocks tool calls in main session (exit 2)

Organizational (useful but not guarantees)
  ├── Agent frontmatter — mcpServers scoping, model selection
  └── Skills — workflow wiring via context: fork

Operations layer
  └── MCP tools — the actual operations agents perform

Three Enforcement Mechanisms (Verified 2026-03-01)

Live testing revealed three distinct enforcement mechanisms, each with different properties:

Mechanism	Scope	How it works	What it blocks	Strength
disallowedTools	Inside agent	Strips tools from the agent's tool palette entirely — agent cannot even attempt the call	Internal tools only (Write, Edit, Bash, etc.). Cannot filter individual MCP tools.	Strongest — tool doesn't exist in agent's world
Frontmatter PreToolUse hooks	Inside agent	Hook script runs on every tool call matching the matcher. Exit 2 = blocked.	Any tool including MCP tools. The only way to block individual MCP tool calls inside agents.	Strong — hook fires, exit 2 blocks, agent sees denial message
Settings PreToolUse hooks	Main session + agents	Hook script runs on every matching tool call at session level.	Any tool. Fires in main session AND inside agents (but frontmatter hooks are preferred for agent-specific rules).	Strong — same mechanism, broader scope

Key insight: disallowedTools is the strongest enforcement for internal tools (Write/Edit/Bash) because the tool simply doesn't exist in the agent's palette. But it cannot filter individual MCP tools — only mcpServers controls server-level access. To block specific MCP tools (like mcp__pal-e-docs__update_note), you MUST use frontmatter PreToolUse hooks.

Defense-in-depth example (QA agent):

1. disallowedTools: Write, Edit, Bash — strips from palette (can't even try)
2. Frontmatter hook block-write-tools.sh — catches Write/Edit/Bash if disallowedTools somehow fails (belt and suspenders)
3. Frontmatter hook block-docs-writes.sh — blocks all 7 pal-e-docs write MCP tools (only way to block these)
4. Settings hook check-issue.sh — bonus layer, gates file writes behind issue tracking

flowchart TD
    subgraph Hooks["Pillar 1: Hooks"]
        SS[SessionStart] & PTU[PreToolUse] & POTU[PostToolUse] & SAS[SubagentStart] & SAST[SubagentStop]
    end
    subgraph MCP["Pillar 2: MCP Data"]
        PD[pal-e-docs] & FM[forgejo-mcp]
    end
    subgraph Skills["Pillar 3: Skills"]
        PLAN["/plan"] & REVIEW["/review-pr"]
    end
    subgraph Agents["Pillar 4: Agents"]
        DEV[Dev Agent] & QA[QA Agent] & IC[Issue Creator]
    end
    SS -->|injects context| PD
    PTU -->|guards| FM
    SAS -->|injects context| AGENTS
    PLAN -->|reads/writes| PD
    REVIEW -->|uses| FM
    DEV -->|follows| PLAN
    QA -->|follows| REVIEW

Pillar 1: Hooks Enforce

Hooks are the hard enforcement layer. They can't be bypassed by the agent.

• SessionStart: Injects project context, SOPs, bug/TODO counts
• PreToolUse: Blocks bad actions (main commits, unauthorized merges, missing issues). Also enforces "no plan, no agent" on manual Agent tool spawns.
• PostToolUse: Reminds workflows (review-fix loop, main fast-forward)
• SubagentStart: CANNOT block agent creation. CAN inject additionalContext into the subagent. Supports matchers by agent type name. Use for injecting plan context, SOPs, or instructions into spawned agents.
• SubagentStop: CAN block via decision: "block" (prevents subagent from stopping). Supports matchers by agent type name.
• Frontmatter PreToolUse: Hooks defined inside agent .md files. Fire during subagent lifetime. Hard enforcement for tool restrictions inside agents. This is the ONLY way to block individual MCP tool calls inside agents.

Key property: Hooks fire on both Bash commands AND MCP tool calls. Separate scripts handle each input format (bash command strings vs MCP JSON params). Frontmatter hooks provide defense-in-depth inside subagent contexts.

Pillar 2: MCP Provides Data

MCP tools are the queryable knowledge layer. Agents pull context on demand.

• pal-e-docs MCP: SOPs, conventions, plans, templates, project pages — all as notes
• forgejo-mcp: Git operations (issues, PRs, branches, reviews) as SOP-aware compound tools

Key property: Data is structured and tagged. Agents query by tag intersection, not by remembering file paths. All agents are read-only consumers of pal-e-docs — only the main session (Betty Sue) writes.

Pillar 3: Skills Guide Workflows

Skills define multi-step procedures that use MCP tools and follow SOPs.

• /plan: Fetches plan template from pal-e-docs, creates plan as note, archives previous
• /review-pr: Orchestrates review-fix loop using MCP tools for Forgejo, CLI for GitHub

Key property: Skills reference templates and SOPs from pal-e-docs by slug. The skill definition is thin; the content lives in pal-e-docs. Skills can delegate to agents via context: fork + agent field — this is convenience wiring, not enforcement. It makes the right thing easy but doesn't make the wrong thing impossible.

Pillar 4: Agents Do Work

Agents are the execution layer. They follow SOPs, use skills, and query MCP.

• Betty Sue: Main session coordinator. Plans, manages knowledge, spawns agents. Not a subagent — injected via SessionStart hook. The only entity that writes to pal-e-docs.
• Dev Agent: Writes code, manages repos, creates PRs. Worktree isolation. Frontmatter PreToolUse hooks block all pal-e-docs writes (verified).
• QA Agent: Reviews PRs for correctness and SOP compliance. disallowedTools strips Write/Edit/Bash from palette (verified — can't even attempt). Frontmatter hooks block pal-e-docs writes (verified).
• Dottie: Documentation librarian. Executes doc updates, content audits, bulk cleanup under Betty Sue's direction. general-purpose subagent type. pal-e-docs read/write + Forgejo read-only. Frontmatter hooks block code writes (verified).

Key property: Agents are stateless across sessions. Context comes from pal-e-docs (project pages, active plans), not from memory. No agent can write to pal-e-docs — this is enforced at the hook level, not just by convention.

How They Compose

1. Agent starts → Hook (SessionStart/SubagentStart) injects project context from MCP (pal-e-docs)
2. Agent receives task → queries MCP for SOPs and current state
3. Agent follows Skill workflow (/plan, /review-pr) which uses MCP tools
4. Hooks guard every tool call — blocking bad actions, reminding workflows
5. Main session (Betty Sue) updates MCP (pal-e-docs) with results — agents never write docs

Two Spawn Paths — Asymmetric Enforcement

There are two ways agents get spawned. They have different enforcement capabilities:

Spawn path	Mechanism	Can block spawn?	Can inject context?	Can enforce tool use?
Manual (Agent tool)	Betty Sue calls Agent tool with prompt	Yes — PreToolUse deny via check-agent-spawn.sh	Yes — via prompt	Yes — PreToolUse hooks
Native delegation	Claude Code routes to subagent via frontmatter	No — SubagentStart cannot block	Yes — additionalContext	Yes — frontmatter PreToolUse hooks

Mitigation strategy: Since native delegation cannot be blocked, we use a layered approach:

1. SubagentStart hook: Inject plan context and SOP instructions via additionalContext — guidance, not enforcement
2. Frontmatter PreToolUse hooks: Hard enforcement inside the agent — QA can't Write, no agent can write to pal-e-docs
3. disallowedTools: Strips restricted tools from palette entirely — strongest enforcement for internal tools

Design Principles

• Three enforcement layers — disallowedTools strips from palette, frontmatter hooks block inside agents, settings hooks block at session level
• Defense-in-depth — multiple layers catch what others miss. disallowedTools can't filter MCP tools, but frontmatter hooks can. Settings hooks catch what frontmatter hooks don't scope to.
• MCP is the single source of truth — no scattered local files
• Skills are thin — they reference pal-e-docs, not inline content
• Agents are stateless — context comes from the system, not memory
• Main session owns docs, agents own repos — enforced by hooks, not just by convention
• Fail-open on reads, fail-closed on writes — if pal-e-docs is down, hooks still block bad actions but don't block reads

• agent-paradigm — the 5-layer model (Events → Hooks → MCP → Skills → Agents)
• agent-workflow — practical agent workflow SOP
• hook-events-reference — all events with blocking, matcher, and enforcement asymmetry details
• agent-spawn-conventions — the "no plan, no agent" axiom and enforcement asymmetry
• project-claude-config — the technical enforcement layer
• project-ai-agency — the system that defines what gets enforced
• Procedures: sop-hook-block-recovery — recovery procedure when enforcement hooks block unexpectedly

Problem

The PreToolUse:mcp__forgejo__merge_approved_pr hook threw an error on every merge but did not block. Merges proceeded despite the error. The agent could not see the error in tool results.

Root Cause

block-mcp-merge.sh used permissionDecision: "allow_with_user_confirmation" which is not a valid Claude Code hook value. Valid values are allow, deny, ask. Claude Code failed open -- showed "hook error" in the CLI but proceeded with the tool call.

Fix

Changed permissionDecision from "allow_with_user_confirmation" to "ask" in ~/.claude/hooks/block-mcp-merge.sh. This matches the working pattern in block-pr-merge.sh.

Impact

Every MCP merge showed a "hook error" in the CLI. The merge gate was effectively disabled -- merges proceeded without the intended prompt. Low actual risk because Lucas was manually approving merges, but the hook's purpose was undermined.

Acceptance Criteria

• Hook prompts user cleanly on next merge (no "hook error" message)
• Merge proceeds only after user approval

Related

• ai-agency -- project (claude-custom repo)
• plan-2026-02-26-tf-modularize-postgres -- discovered during Phase 8b/8c work

Verdict: APPROVED

Re-review after refinement. Prior review: review-1970-2026-08-01 (NEEDS_REFINEMENT). All three prior recommendations resolved.

Template Completeness

• [x] Type — Bug
• [x] Lineage — Standalone, discovered during palinks session
• [x] Repo — ldraney/claude-custom
• [x] What Broke — detailed root cause: update-ref moves ref without updating index/working tree
• [x] Repro Steps — 5 clear steps
• [x] Expected Behavior — clear
• [x] Environment — Linux + macOS, specific hook and line number
• [x] Acceptance Criteria — 4 criteria
• [x] Related — project, reflog evidence, forgejo-helper.sh reference, arch component

All 9 required bug template sections present.

Traceability

• [x] story:superuser-manage label — present on board item
• [x] story note verified — found in project-pal-e-agency user-stories section (Superuser role, row 1)
• [x] arch:claude-custom label — present on board item
• [~] arch note pending — arch-claude-custom note does not yet exist (404), but creation is tracked in Forgejo issue ldraney/claude-custom#236. Label correctly identifies the component. Not a scope defect in this ticket.
• [x] Forgejo issue — ldraney/claude-custom#296, open

Prior Review Resolution

• [x] [SCOPE] story:agent-reliability → Reassigned to story:superuser-manage. Verified: exists in project-pal-e-agency user-stories table.
• [x] [SCOPE] arch:claude-hooks missing → Changed to arch:claude-custom. Note creation tracked in #236. Correct component label.
• [x] [BODY] forgejo-helper.sh reference → Added to Related section: forgejo-helper.sh:_sync_working_tree() with context about post-mcp-merge-rebase.sh usage.

File Targets

• [x] hooks/pre-spawn-freshness.sh line 64 — verified: contains git -C "$CWD" update-ref refs/heads/main "$REMOTE_SHA" "$LOCAL_SHA" 2>/dev/null || exit 0
• [x] Confirmed: hook has no branch detection (no symbolic-ref or current-branch check before update-ref)
• [x] Confirmed: hook does NOT source forgejo-helper.sh and does NOT call _sync_working_tree
• [x] hooks/forgejo-helper.sh line 476 — verified: _sync_working_tree() helper exists, uses symbolic-ref to detect branch + reset --hard HEAD

Repo Placement

Correct. Issue filed on ldraney/claude-custom, fix targets hooks/pre-spawn-freshness.sh in the same repo. Single repo, no cross-repo concerns.

Dependencies

No blocking items on the board. Related but non-blocking:

• Issue #236 — "Create arch-landing-site and arch-claude-custom architecture notes" (open, tracks arch note creation)
• Issue #294 — "SOP: Enforce worktree-first" (complementary prevention)
• Board items #822, #784 — same arch:claude-custom label, both in backlog, no ordering dependency

Acceptance Criteria

4 criteria, all agent-verifiable:

• AC1: When on main, use git merge --ff-only — testable by inspecting code path
• AC2: When on feature branch, keep update-ref — testable by inspecting code path
• AC3: No phantom staged changes — testable via git status after hook runs on main
• AC4: Fail-open on errors — testable by verifying || exit 0 pattern preserved

Well-scoped. No missing criteria detected.

Blast Radius

• post-mcp-merge-rebase.sh (line 68) — uses identical update-ref pattern but ALREADY PATCHED: calls _sync_working_tree() from forgejo-helper.sh at line 74.
• forgejo-helper.sh (lines 472-494) — _sync_working_tree() helper already handles the desync. Issue body now references this as existing art, giving the implementing agent both fix approaches.
• pre-spawn-freshness.sh is the only remaining unpatched instance of bare update-ref on main.

Decomposition Assessment

1 file target, 1 repo, 4 acceptance criteria. Estimated agent work under 5 minutes. No decomposition needed.

Recommendations

No action needed.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — Bug
• [x] Lineage — Standalone, discovered during palinks session
• [x] Repo — ldraney/claude-custom
• [x] What Broke — detailed, includes root cause (update-ref moves ref without updating index/working tree)
• [x] Repro Steps — 5 clear steps
• [x] Expected Behavior — clear
• [x] Environment — Linux + macOS, specific hook and line number
• [x] Acceptance Criteria — 4 criteria
• [x] Related — project-pal-e-agency, reflog evidence

All 9 required bug template sections present.

Traceability

• [x] story:agent-reliability label — present on board item
• [ ] story note MISSING — [SCOPE] story:agent-reliability does not exist in project-pal-e-agency user-stories section. Available stories: superuser-manage, superuser-onboard, pm-scope, dev-execute, qa-review, validation-execute, dottie-docs. Create user story entry or reassign to an existing story (e.g. story:superuser-manage).
• [x] arch:claude-hooks label — present on board item
• [ ] arch note MISSING — [SCOPE] arch-claude-hooks note does not exist in pal-e-docs (404). Create architecture note arch-claude-hooks for the hooks subsystem. Note: issue #236 tracks creating missing arch notes but does not specifically cover arch-claude-hooks.
• [x] Forgejo issue — ldraney/claude-custom#296, open

File Targets

• [x] hooks/pre-spawn-freshness.sh line 64 — verified: contains git -C "$CWD" update-ref refs/heads/main "$REMOTE_SHA" "$LOCAL_SHA" 2>/dev/null || exit 0
• [x] Confirmed: hook does NOT check which branch the user is on before running update-ref (no symbolic-ref or branch detection)
• [x] Confirmed: hook does NOT source forgejo-helper.sh and does NOT call _sync_working_tree

Repo Placement

Correct. Issue filed on ldraney/claude-custom, fix targets hooks/pre-spawn-freshness.sh in the same repo. Single repo, no cross-repo concerns.

Dependencies

No blocking items found on the board. Related but non-blocking:

• Issue #294 — "SOP: Enforce worktree-first — never develop on main" (complementary prevention, not a dependency)
• Issue #248 — "Add hook to block destructive git commands" (tangentially related)

Acceptance Criteria

4 criteria, all agent-verifiable:

• AC1: When on main, use git merge --ff-only — testable by checking out main, creating upstream commits, and verifying behavior
• AC2: When on feature branch, keep update-ref — testable by checking out a branch and verifying code path
• AC3: No phantom staged changes — testable via git status after hook runs
• AC4: Fail-open on errors — testable by simulating network/merge failures

Criteria are well-scoped. No missing criteria detected.

Blast Radius

• post-mcp-merge-rebase.sh (line 68) — uses identical update-ref pattern but is ALREADY PATCHED: it calls _sync_working_tree() from forgejo-helper.sh (line 74) to reset the working tree after update-ref.
• forgejo-helper.sh (lines 472-494) — already has a _sync_working_tree() helper that detects if user is on the default branch and does git reset --hard HEAD if no uncommitted changes. This is an alternative fix approach the implementing agent should be aware of.
• The issue proposes merge --ff-only (which updates HEAD + index + working tree atomically) rather than update-ref + reset --hard. Both approaches solve the problem; merge --ff-only is arguably cleaner as it avoids the destructive reset --hard.

Decomposition Assessment

1 file target, 1 repo, 4 acceptance criteria, estimated agent work under 5 minutes. No decomposition needed.

Recommendations

• [SCOPE] Create user story entry story:agent-reliability on project-pal-e-agency user-stories section, or reassign to existing story:superuser-manage.
• [SCOPE] Create architecture note arch-claude-hooks for the hooks subsystem in pal-e-docs.
• [BODY] Add note in Related section referencing forgejo-helper.sh:_sync_working_tree() as existing art for the implementing agent's awareness.

Verdict: READY

Template Completeness

• [x] Type — Feature
• [x] Lineage — Follow-up from svc#193
• [x] Repo — ldraney/pal-e-platform
• [x] User Story — As a developer / staging reachable from public internet
• [x] Context — ArgoCD app exists, Kustomize overlay on main, domain doesn't resolve
• [x] File Targets — terraform/dns.tf with modify/don't-touch boundaries
• [x] Feature Flag — none (infrastructure, appropriate)
• [x] Acceptance Criteria — 3 criteria
• [x] Test Expectations — dig and tofu plan commands
• [x] Constraints — Follow existing CNAME pattern
• [x] Checklist — Standard PR checklist
• [x] Related — project-iss, svc#193, svc#198, deploy#242

Traceability

• [x] story:dev-environment label — "Dev to staging to prod pipeline"
• [x] story note verified — found in project-iss user-stories section
• [x] arch:terraform label — Terraform IaC
• [x] arch note verified — arch-terraform note exists in pal-e-docs
• [x] Forgejo issue — ldraney/pal-e-platform#560, open

File Targets

• [x] terraform/dns.tf — verified: file exists in pal-e-platform, contains iss_dev CNAME block (resource "godaddy_dns_record" "iss_dev") with domain/type/name/data/ttl/lifecycle pattern. The iss_staging record should copy this block with name = "staging".

Repo Placement

OK — issue filed on ldraney/pal-e-platform, file target is terraform/dns.tf in that repo. Single repo, no cross-repo work needed.

Dependencies

• Upstream (done): svc#193 ISS staging environment — ArgoCD app and namespace provisioned (board item #1893, done)
• Downstream (documented): svc#198 Caddy reverse proxy for staging.intelligentstaffingsystems.ai — depends on this DNS landing first (board item #1931, backlog)
• Related: deploy#242 ISS staging CNPG database (board item #1928, backlog) — parallel work, no ordering dependency

Dependencies are correctly documented in the issue's Related section.

Acceptance Criteria

3 criteria, all verifiable by an agent post-implementation:

• DNS resolution — dig +short staging.intelligentstaffingsystems.ai
• Existing records unchanged — tofu plan diff
• Plan shows only addition — "1 to add, 0 to change, 0 to destroy"

Test commands are real and specific. Note: DNS resolution verification requires the tofu apply to have run (CI merges to main). Agent can verify plan output locally; dig verification happens post-merge.

Blast Radius

Minimal. Single CNAME record addition following an established pattern. No other staging subdomains exist for other services in dns.tf. No downstream consumers affected until svc#198 (Caddy vhost) is implemented.

Decomposition Assessment

No decomposition needed. 1 file target, 1 repo, 3 acceptance criteria. Estimated agent work: under 2 minutes (copy iss_dev block, change resource name to iss_staging, change CNAME name from "dev" to "staging").

Recommendation

No action needed.

Verdict: APPROVED

Re-review of board item #1827. The single finding from review-1827-2026-07-25 (NEEDS_REFINEMENT) has been resolved.

Previous Finding Resolution

• [x] [SCOPE] story:communications user story entry on project-iss -- FIXED. Row now present: Key=communications, Backing="docs/ui-ux.md (Communications tab layouts) + docs/messaging.md", Role="Lead/Client/Admin", Success metric="Lead/client: email + appointment + DM card; admin: incoming inbox with DM and appointment streams"

Template Completeness

• [x] Type -- Feature
• [x] Lineage
• [x] Repo
• [x] User Story
• [x] Context
• [x] File Targets
• [x] Feature Flag -- "None" (core admin view, appropriate)
• [x] Acceptance Criteria (8 items)
• [x] Test Expectations
• [x] Constraints
• [x] Checklist
• [x] Related
• [x] Dependencies (bonus section, well-documented)

All required template sections present and filled in.

Traceability

• [x] story:communications label -- present on board item
• [x] story note verified -- communications row found in project-iss user-stories section
• [x] arch:rails label -- present on board item
• [x] arch note verified -- arch-rails note exists in pal-e-docs (ISS Rails Architecture)
• [x] Forgejo issue -- #57, state: open, valid URL

File Targets

• [x] app/controllers/communications_controller.rb -- verified: exists, admin branch renders :admin_index at line 15-16. Controller needs data loading added.
• [x] app/views/communications/admin_index.html.erb -- verified: exists as placeholder. Line 27 references "Coming soon -- see ticket #57." Ready to replace.
• [x] app/views/communications/_inbox_card.html.erb -- does not exist yet (new partial to create). Expected per ticket scope.
• [x] app/assets/stylesheets/communications.css -- verified: exists (145 lines), will receive inbox styling additions.

Files NOT to touch also verified present: index.html.erb, messages_controller.rb, appointments_controller.rb.

Repo Placement

OK -- issue filed on ldraney/intelligentstaffingsystems, all file targets in same repo. No cross-repo work needed.

Dependencies

• #54 (Appointment scheduling) -- board item #1824, column: validation. Soft dependency handled gracefully: "scope the inbox to DM cards only; appointment display is additive."
• #55 (Live DM) -- board item #1825, column: validation. Provides message data for inbox cards. Message model exists with belongs_to :lead and relevant scopes.
• #52 (Communications tab lead/client) -- board item #1822, column: done. Prerequisite satisfied.
• #56 (CRM tab) -- board item #1826, column: todo. Parallel admin view, no blocking dependency.

Acceptance Criteria

8 acceptance criteria, all verifiable via endpoint tests. Test expectations align with ISS testing strategy (endpoint-first, Minitest, Keycloak stubs). Run command correct: rails test test/controllers/communications_controller_test.rb.

Blast Radius

Low risk. The admin branch pattern (admin? helper, render :admin_index) is established. Message and Appointment models have the necessary associations. No changes to existing models or other controllers needed.

Decomposition Assessment

• 4 file targets, 1 repo -- does NOT exceed the >3 files across >2 repos threshold
• 8 acceptance criteria -- exceeds the >5 AC threshold
• Estimated agent work: ~5 minutes (replace placeholder view, create partial, add controller data loading, add CSS)

Work is cohesive (one view with supporting parts in a single repo). Per standing directive, inclusive tickets preferred over decomposition. No decomposition needed.

Recommendation

No action needed. Previous finding resolved.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type -- Feature
• [x] Lineage
• [x] Repo
• [x] User Story
• [x] Context
• [x] File Targets
• [x] Feature Flag -- "None" (core admin view, appropriate)
• [x] Acceptance Criteria (8 items)
• [x] Test Expectations
• [x] Constraints
• [x] Checklist
• [x] Related
• [x] Dependencies (bonus section, well-documented)

All required template sections are present and filled in.

Traceability

• [x] story:communications label -- present on board item
• [ ] story note MISSING -- [SCOPE] The key communications does not appear in the project-iss user-stories section. The table lists messaging (Epic 4: DM threads) but not communications (the admin inbox/contact tab). Create a communications user story entry on project-iss user-stories section, or reconcile with the existing messaging key.
• [x] arch:rails label -- present on board item
• [x] arch note verified -- arch-rails note exists in pal-e-docs (ISS Rails Architecture)
• [x] Forgejo issue -- #57, state: open, valid URL

File Targets

• [x] app/controllers/communications_controller.rb -- verified: exists, admin branch already renders :admin_index at line 15-16. Controller needs data loading added.
• [x] app/views/communications/admin_index.html.erb -- verified: exists as placeholder. Line 27 references "Coming soon -- see ticket #57." Ready to replace.
• [x] app/views/communications/_inbox_card.html.erb -- does not exist yet (new partial to create). Expected per ticket scope.
• [x] app/assets/stylesheets/communications.css -- verified: exists (3.3k), will receive inbox styling additions.

All existing file targets verified. New partial creation is expected.

Repo Placement

OK -- issue filed on ldraney/intelligentstaffingsystems, all file targets are in the same repo. No cross-repo work needed.

Dependencies

• #54 (Appointment scheduling) -- board item #1824, column: validation (merged, awaiting validation). Ticket correctly handles this as a soft dependency: "scope the inbox to DM cards only; appointment display is additive."
• #55 (Live DM / block lead role from DM) -- board item #1825, column: validation. Provides message data for inbox cards. The Message model exists with belongs_to :lead and scopes (chronological, reverse_chronological, for_lead).
• #52 (Communications tab lead/client) -- board item #1822, column: done. Prerequisite is satisfied.
• #56 (CRM tab) -- board item #1826, column: todo. No blocking dependency; CRM is a parallel admin view.

Dependencies are well-documented and the soft dependency on #54 is handled gracefully.

Acceptance Criteria

8 acceptance criteria, all verifiable via endpoint tests:

• AC 1-3: Admin inbox view rendering with card content -- directly testable with assert_select
• AC 4: Filter (All / DMs / Appointments) -- testable; appointments filter gracefully degrades
• AC 5-7: Quick actions (DM thread, appointment details, CRM) -- testable as link presence
• AC 8: Lead/client still sees contact buttons -- already partially tested (existing test at line 49 checks for 3 contact cards)

Test expectations align with ISS testing strategy (endpoint-first, Minitest, Keycloak stubs). Run command is correct: rails test test/controllers/communications_controller_test.rb. Existing test file already has admin and role-specific tests to extend.

Blast Radius

Low risk. The admin branch pattern (admin? helper, render :admin_index) is already established in the communications controller. The Message model (belongs_to :lead, scopes) and Appointment model (belongs_to :lead, upcoming/recent scopes) have the necessary associations and query methods. The Lead model has has_many :messages and has_many :appointments. No changes to existing models or other controllers are needed.

Decomposition Assessment

• 4 file targets, 1 repo -- does NOT exceed the >3 files across >2 repos threshold
• 8 acceptance criteria -- exceeds the >5 AC threshold
• Estimated agent work: 5-8 minutes (replace placeholder view, create partial, add controller data loading, add CSS)

The AC count exceeds the formal threshold. However, the work is cohesive (one view with supporting parts in a single repo) and per standing directive, inclusive tickets are preferred over decomposition. No decomposition recommended.

Recommendation

• [SCOPE] Create user story entry for communications on project-iss user-stories section. The key is used on multiple board items (#52 done, #54 validation, #57 todo) but has no backing entry in the project page. Suggested row: Key=communications, Backing="Epic 4 (US-4.3)", Role="Admin", Success metric="Admin sees unified inbox of DMs and appointments; leads/clients see contact cards"

Verdict: READY

Template Completeness

• [x] Type (Feature)
• [x] Lineage
• [x] Repo
• [x] User Story
• [x] Context
• [x] File Targets
• [x] Feature Flag (none)
• [x] Acceptance Criteria (6)
• [x] Test Expectations
• [x] Constraints
• [x] Checklist
• [x] Related
• [x] PRs Required (bonus section, clearly separates two-repo scope)

Traceability

• [x] story:dev-environment label -- verified in project-iss user-stories section. Backing: "#192 / #193 / #194 + docs/pipeline.md"
• [x] story note verified -- found in project-iss user-stories table (key: dev-environment, role: Developer)
• [x] arch:argocd label -- ArgoCD + Image Updater Deployment Pattern
• [x] arch note verified -- arch-argocd note exists in pal-e-docs (doc type, tags: architecture, argocd, platform)
• [x] Forgejo issue -- ldraney/pal-e-services#194, open

File Targets

• [x] terraform/variables.tf (pal-e-services, line 269-282) -- verified: variable "services" is a map(object({...})) with fields forgejo_repo, image_repo, port, funnel, target_revision, source_repo, source_path, cmp_plugin. No image_updater field yet. Ticket correctly identifies adding image_updater = optional(bool, true).
• [x] terraform/services.tf (pal-e-services, lines 196-207) -- verified: image updater annotations are applied unconditionally to all services in argocd_application.service. Ticket correctly identifies adding conditional logic gated on var.services[key].image_updater.
• [x] terraform/k3s.tfvars.example (pal-e-services, lines 517-524) -- verified: ISS prod entry exists at key intelligentstaffingsystems with source_repo/source_path overlay pattern. No image_updater field. Ticket correctly identifies setting image_updater = false.
• [x] .woodpecker.yaml (intelligentstaffingsystems) -- verified: 94-line CI pipeline with lint/security/test/build-and-push steps. Build-and-push fires on push to main. No manual promotion pipeline exists yet. Ticket correctly identifies adding a manual event pipeline.

Repo Placement

Issue filed on pal-e-services (#194). Ticket explicitly documents two repos and two PRs in the "PRs Required" section:

• PR 1: pal-e-services (terraform changes: variables.tf, services.tf, k3s.tfvars.example)
• PR 2: intelligentstaffingsystems (.woodpecker.yaml manual promotion pipeline)

Cross-repo scope is clearly delineated. No additional Forgejo issues needed -- the single issue serves as the spec for both PRs.

Dependencies

• #193 (board item 1893, backlog) -- staging auto-deploy. Explicitly documented as a blocker: "This ticket depends on #193 (staging must exist before removing auto-deploy from prod)." #193 is also open and in backlog. Sequencing is correct: staging must exist before prod can switch to manual.
• #192 (board item 1892, backlog) -- dev environment. Related but independent; no blocking relationship with #194.
• All three tickets (#192, #193, #194) share labels: type:feature, scope:iss, arch:argocd, story:dev-environment.

Acceptance Criteria

6 criteria, all verifiable:

• AC 1-2: Deployment behavior (auto-deploy to staging, NOT to prod) -- verifiable after both #193 and #194 are deployed
• AC 3-4: Manual pipeline existence and triggerability -- verifiable in Woodpecker UI/CLI
• AC 5: ArgoCD health -- verifiable via argocd app get
• AC 6: End-to-end promotion -- verifiable by running the pipeline

Test expectations include terraform plan -var-file=k3s.tfvars for clean plan verification. All criteria are agent-testable.

Blast Radius

The image_updater flag defaults to true, preserving existing auto-deploy behavior for all other services. 10+ services use the overlay pattern via source_repo = "ldraney/pal-e-deployments"; none are affected because the flag only changes behavior when explicitly set to false. Only the ISS prod entry opts out. The change to services.tf wraps existing annotation logic in a conditional, which is safe for all other entries.

Decomposition Assessment

4 file targets across 2 repos. 6 acceptance criteria (exceeds 5 threshold). However, the work is tightly cohesive: the terraform changes are 3 small edits to existing files, and the Woodpecker pipeline is a single new step definition. The PRs Required section already provides natural two-repo separation. Per project preference: no decomposition needed. Fits within a single agent pass per repo.

Recommendation

No action needed.

Verdict: APPROVED

Re-review. Previous verdict was NEEDS_REFINEMENT (missing arch-mcp-tools note). That note has now been created (ID 2632). All criteria pass.

Template Completeness

Checked against template-issue-bug:

• [x] Type — Bug
• [x] Lineage — Present (discovered during ISS session)
• [x] Repo — ldraney/forgejo-mcp
• [x] What Broke — Present (no get_issue tool, agents cannot read issue bodies)
• [x] Repro Steps — Present (4 steps)
• [x] Expected Behavior — Present
• [x] Environment — Present
• [x] Acceptance Criteria — Present (4 criteria)
• [x] Related — Present
• [x] File Targets — Present (bonus, not required by bug template)
• [x] Constraints — Present (bonus, not required by bug template)
• [x] Checklist — Present (bonus, not required by bug template)

Traceability

• [x] story:superuser-manage label — "I can scope, dispatch, and track all work across all projects from one Claude Code session"
• [x] story note verified — found in project-pal-e-agency user-stories section (Superuser row)
• [x] arch:mcp-tools label — present on board item
• [x] arch note verified — arch-mcp-tools note exists (ID 2632, "Architecture: MCP Tools Layer"). Covers the tool definitions across all MCP servers including forgejo-mcp.
• [x] Forgejo issue — ldraney/forgejo-mcp#32, state: open

File Targets

• [x] src/forgejo_mcp/tools/workflows.py — verified: file exists, contains all current MCP tool definitions. list_issues at line 314 returns only number/title/state/url (no body). New get_issue tool belongs here.
• [x] SDK method issue_get_issue — verified: used in tests/test_update_issue.py (lines 40, 68, 98). Method available on ForgejoClient.

Repo Placement

Correct. Issue filed on ldraney/forgejo-mcp, fix is in the same repo. Single-repo change.

Dependencies

No blocking dependencies. Related board items with arch:mcp-tools label (#360, #227) are both in done column. No items blocked by this ticket.

Acceptance Criteria

All 4 criteria are agent-verifiable:

• [x] "get_issue tool registered in MCP server" — verifiable via tool list check
• [x] "Returns: number, title, body, state, url, labels, assignees, created_at, updated_at" — verifiable via code review of return dict
• [x] "Handles None labels/assignees from API (use or [] guard)" — verifiable via code review
• [x] "Manual test: get_issue('ldraney', 'intelligentstaffingsystems', 99) returns full body" — verifiable via MCP call

Blast Radius

Low. Purely additive change — a new @mcp.tool() function in workflows.py. No modifications to existing tools. Follows the established pattern: @mcp.tool() + Annotated params with Field + _error_response on exception.

Decomposition Assessment

No decomposition needed. 1 file target, 1 repo, 4 acceptance criteria, estimated <5 minutes agent work.

Recommendation

No action needed.

Verdict: APPROVED

Round 3 re-review. All three issues from round 2 (review-1825-2026-07-18b) are resolved. Ticket is ready for implementation.

Template Completeness

• [x] Type (Feature)
• [x] Lineage
• [x] Repo
• [x] User Story
• [x] Context
• [x] File Targets (with DO/DON'T lists)
• [x] Feature Flag (None — correct, this is an access control fix)
• [x] Acceptance Criteria
• [x] Test Expectations
• [x] Constraints
• [x] Checklist
• [x] Related

Traceability

• [x] story:messaging label — Epic 4 (US-4.1–4.2)
• [x] story note verified — found in project-iss user-stories section (key: messaging, role: Lead/Client/Admin)
• [x] arch:rails label — Rails controller work
• [ ] arch note MISSING — [SCOPE] Create architecture note arch-rails (systemic gap; does not block this ticket)
• [x] Forgejo issue — ldraney/intelligentstaffingsystems#55, open

File Targets

• [x] app/controllers/messages_controller.rb — verified: exists, 103 lines, currently has no lead-blocking guard, has before_action :set_thread_lead and private admin? helper
• [x] test/controllers/messages_controller_test.rb — verified: exists, 375 lines, 40 tests total, 22 use lead role (21 via sign_in_as :lead + 1 via OmniAuth direct)
• [x] Files NOT to touch listed — views, model, Stimulus controller, cable.yml all exist and are correctly excluded

Repo Placement

OK. Issue filed on ldraney/intelligentstaffingsystems, all work is in the same repo. No cross-repo concerns.

Dependencies

• #40 (Message CRUD) — done (board confirms, column: done)
• #42 (Turbo Streams live delivery) — done (board confirms, column: done)
• No in-progress blockers
• Dependencies correctly documented in Lineage section

Acceptance Criteria

5 AC, all machine-verifiable:

• AC 1: Lead redirect to /communications with flash — testable via integration test (302 + flash check)
• AC 2: Client access unchanged — testable (existing tests unchanged)
• AC 3: Admin access unchanged — testable (existing tests unchanged)
• AC 4: 22 lead tests rewritten to assert 302 — testable (run test file, verify count)
• AC 5: Client/admin tests pass unchanged — testable (regression baseline)

Test Expectations section adds specific endpoint tests and conversion strategy. Run command is correct: rails test test/controllers/messages_controller_test.rb

Blast Radius

• Change is confined to MessagesController — no other controller routes leads to /messages
• /communications route confirmed to exist (routes.rb line 29)
• ApplicationController has existing require_role class method but ticket correctly uses custom method for non-standard redirect target and flash
• docs/messaging.md currently documents UI-only gating; ticket correctly notes it must be updated to reflect controller-level enforcement

Decomposition Assessment

No decomposition needed:

• 2 file targets in 1 repo
• 5 acceptance criteria (at threshold, not over)
• Estimated agent work: ~3 minutes (add before_action + rewrite test assertions)
• Single-concern change: add one guard, update tests to match

Round 2 Issues — Resolution Status

• [x] AC #4 contradictory ("49 tests still pass" vs "22 lead tests break") — FIXED: AC now reads "22 existing lead-role tests rewritten to assert 302 redirects"
• [x] Wrong test count (49 vs 40) — FIXED: Context now reads "40 tests passing"
• [x] Missing test expectation for lead test rewrite — FIXED: Test Expectations includes "Existing lead tests converted: assert redirect instead of 200" and "Lead rendering tests converted to client role"

Recommendation

• [SCOPE] Create architecture note arch-rails for component rails (systemic gap across board — non-blocking)

No action needed for ticket advancement. Ticket is APPROVED for implementation.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — Feature
• [x] Lineage
• [x] Repo
• [x] User Story
• [x] Context
• [x] File Targets (issues found below)
• [x] Feature Flag — none (acceptable for core admin view)
• [x] Acceptance Criteria
• [x] Test Expectations
• [x] Constraints
• [x] Checklist
• [x] Related

Traceability

• [x] story:communications label — Epic 5: Communications (US-5.4)
• [ ] story note MISSING — [SCOPE] The project-iss user-stories section on pal-e-docs has no "communications" key (only "messaging" for Epic 4). Create user story entry "communications" on project-iss covering Epic 5 (US-5.1–5.4).
• [x] arch:rails label — Rails application component
• [ ] arch note MISSING — [SCOPE] No arch-rails note found in pal-e-docs. Create architecture note arch-rails for the ISS Rails component.
• [x] Forgejo issue — ldraney/intelligentstaffingsystems#57, open

File Targets

• [x] app/controllers/communications_controller.rb — verified: exists, already has admin branch rendering :admin_index
• [ ] app/views/communications/inbox.html.erb — ISSUE: File does not exist. The controller currently renders :admin_index which maps to admin_index.html.erb (already exists as placeholder). Ticket should target admin_index.html.erb or explicitly document the rename.
• [ ] app/views/communications/_inbox_card.html.erb — new file (acceptable, to be created)
• [x] app/assets/stylesheets/communications.css — verified: exists
• [x] app/views/communications/index.html.erb (NOT touch) — verified: exists, lead/client contact cards
• [x] app/controllers/messages_controller.rb (NOT touch) — verified: exists, has its own admin inbox at /messages
• [ ] app/controllers/appointments_controller.rb (NOT touch) — does not exist: no appointment system exists in the codebase

Repo Placement

OK — issue filed on ldraney/intelligentstaffingsystems and all file targets are in that repo.

Dependencies

• #54 — Appointment scheduling (board item 1824, backlog, sprint:C) — BLOCKER. The ticket expects to show appointment data in inbox cards, filter by Appointments, and provide "view appointment details" quick action. No Appointment model or controller exists. AC4, AC6, and parts of AC2–AC3 depend on this.
• #55 — Live DM messaging (board item 1825, backlog, sprint:C) — Soft dependency. The existing Message model and messages/inbox.html.erb already provide DM thread data, but #55 adds real-time features. Not a blocker for basic inbox display.
• #56 — CRM tab (board item 1826, backlog, sprint:C) — AC7 references "jump to CRM business card." CRM ticket is in backlog. Quick action link can be added but destination may not exist.
• #52 — Communications tab lead/client (done) — Prerequisite met. Controller branching and lead/client view already work.

Acceptance Criteria

8 acceptance criteria total. Assessment:

• AC1 (admin sees inbox) — verifiable, controller branch already exists
• AC2 (cards sorted by activity) — partially verifiable; DM activity sortable via Message model, but appointment activity requires #54
• AC3 (card content) — same dependency on appointments for "appointment summary"
• AC4 (filter: All/DMs/Appointments) — BLOCKED by #54, no appointment data to filter
• AC5 (quick action: open DM) — verifiable, messages path exists
• AC6 (quick action: view appointment) — BLOCKED by #54, no appointment controller
• AC7 (quick action: jump to CRM) — soft dependency on #56; link target may 404
• AC8 (lead/client still sees contact buttons) — verifiable, already works

Test commands are real (rails test test/controllers/communications_controller_test.rb). Existing test file already covers role-based access.

Blast Radius

Low. The change is isolated to the communications admin view. The existing messages/inbox.html.erb pattern at /messages already demonstrates the admin inbox pattern. No downstream consumers affected. Existing tests for lead/client communications access will confirm no regression.

Decomposition Assessment

4 file targets in 1 repo, 8 acceptance criteria (exceeds 5 threshold). However, the primary issue is the dependency blocker (#54 appointments), not size. If the ticket is scoped to DM-only inbox first (dropping AC4 appointment filter and AC6 appointment quick action), it fits within a single agent pass at ~5 minutes. No decomposition needed — dependency resolution recommended instead.

Recommendation

• [BODY] Fix file target: app/views/communications/inbox.html.erb should be app/views/communications/admin_index.html.erb (the controller already renders :admin_index and the placeholder file exists)
• [BODY] Document dependency on #54 (Appointment scheduling). Options: (a) reduce scope to DM-only inbox initially, adding appointment integration after #54 lands; or (b) mark this ticket as blocked by #54.
• [BODY] AC4 and AC6 should be deferred or marked as depending on #54
• [SCOPE] Create user story entry "communications" on project-iss user-stories section (covering Epic 5: US-5.1–5.4)
• [SCOPE] Create architecture note arch-rails for the ISS Rails component

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — Feature
• [x] Lineage — replaces #14
• [x] Repo — ldraney/intelligentstaffingsystems
• [x] User Story — As the admin, I want a searchable pipeline...
• [x] Context — models after landscaping-assistant today tab
• [x] File Targets — 7 files listed plus exclusions
• [x] Feature Flag — none (core admin functionality)
• [x] Acceptance Criteria — 13 items
• [x] Test Expectations — 9 items plus run command
• [x] Constraints — 6 constraints listed
• [x] Checklist — standard 3-item
• [x] Related — references project and related issues

Traceability

• [ ] story:crm label — MISMATCH: project-iss user-stories section lists key "admin" (Epic 6: US-6.1–6.2, "Pipeline list; lead→client promotion with audit") but board item uses story:crm. The user-stories.md doc has "Epic 7: CRM (Admin)" as a distinct epic. [SCOPE] Add "crm" row to project-iss user-stories table, or change board label to story:admin.
• [ ] arch note MISSING — [SCOPE] search for "arch-rails" returned no results. Create architecture note arch-rails for the Rails component.
• [x] Forgejo issue — https://forgejo.tail5b443a.ts.net/ldraney/intelligentstaffingsystems/issues/56, state: open

File Targets

• [ ] app/controllers/admin/crm_controller.rb — ISSUE: Ticket says admin-namespaced path, but existing stub is top-level at app/controllers/crm_controller.rb with require_role :admin. Routes have get "/crm", to: "crm#index" (line 37, top-level), not under namespace :admin. The tab bar pattern keeps tab controllers top-level (catalog, communications, messages all follow this). Fix file path to match existing convention: app/controllers/crm_controller.rb.
• [ ] app/views/admin/crm/index.html.erb — ISSUE: Same namespace mismatch. Existing view is at app/views/crm/index.html.erb (stub). Should be app/views/crm/.
• [ ] app/views/admin/crm/_business_card.html.erb — ISSUE: Should be app/views/crm/_business_card.html.erb per above.
• [ ] app/views/admin/crm/show.html.erb — ISSUE: Should be app/views/crm/show.html.erb per above.
• [x] app/assets/stylesheets/admin_crm.css — to be created; pattern matches existing admin_catalog.css
• [x] app/services/keycloak_admin_service.rb — EXISTS. Currently has get_user and update_user. Ticket correctly notes "may already exist from #6". promote_to_client method needs to be added. NOTE: Keycloak role assignment uses realm-role-mapping API (POST /admin/realms/{realm}/users/{id}/role-mappings/realm), not user PUT — service needs a new HTTP method and endpoint.
• [x] config/routes.rb — EXISTS. Currently has stub route at line 37. Will need show + promote action added.

Repo Placement

OK — issue filed on ldraney/intelligentstaffingsystems, all work targets that repo.

Dependencies

• #6 (Keycloak OIDC auth) — DONE. Provides KeycloakAdminService foundation.
• #51 (Projects tab) — DONE. Provides ProjectRequest model for "project requests visible on business detail" AC.
• Messaging subsystem — DONE. Message model and threads exist for "message thread link" AC.
• PaperTrail gem — NOT INSTALLED. AC #12 requires "audit trail (PaperTrail)" but PaperTrail gem is not in Gemfile. This is an undocumented dependency that needs to be added.
• Lead.search scope — does NOT exist. AC #2 requires search; the model has no search scope yet.

Acceptance Criteria

13 acceptance criteria. Most are testable by an agent. Issues:

• AC #12 (PaperTrail audit trail) — requires gem installation, migration generation, and model setup that isn't scoped in the ticket.
• AC #9 (Keycloak role update) — requires realm-role-mapping API, not the user-attribute PUT currently in the service. Insufficiently detailed for implementation.
• AC #5 (last activity aggregation) — complex query across messages, appointments, and project_requests. Appointments model does not appear to exist yet.

Blast Radius

• The tab bar helper (app/helpers/tab_bar_helper.rb or similar) likely references the CRM path — route changes could break navigation.
• The existing stub controller and view will need to be replaced in-place (not moved to admin namespace).
• KeycloakAdminService changes affect profile sync (#13, done) — any method signature changes need to preserve existing behavior.
• PaperTrail installation affects the entire app (adds a versions table, may need initializer configuration).

Decomposition Assessment

NEEDS DECOMPOSITION — route to skill-decompose-ticket.

• 13 acceptance criteria (threshold: 5)
• 7+ file targets
• Multiple distinct concerns: search/filter UI, business detail view, Keycloak role promotion, PaperTrail audit setup, route restructuring
• Estimated agent work: 15-20 minutes (well over 5-minute threshold)
• 8 story points confirms this is oversized for a single pass

Suggested decomposition:

1. CRM index with search and filter (controller, view, Lead.search scope, CSS)
2. CRM business detail view (show action, detail template, related data)
3. Lead promotion (Keycloak role-mapping API, promote action, confirmation UI, PaperTrail)

Recommendation

• [BODY] Fix file paths: app/controllers/admin/crm_controller.rb → app/controllers/crm_controller.rb; app/views/admin/crm/* → app/views/crm/*
• [BODY] Add PaperTrail gem installation to scope (Gemfile addition + migration + model setup) or remove AC #12 and defer audit trail
• [BODY] Clarify Keycloak promotion mechanism: realm-role-mapping API, not user attribute PUT
• [BODY] Note that "Appointments" model may not exist — AC #5 references "last appointment" but no appointment feature is built
• [LABEL] Change story:crm to story:admin OR add "crm" key to project-iss user-stories table
• [SCOPE] Create architecture note arch-rails for component rails
• [SCOPE] Add "crm" entry to project-iss user-stories section if keeping story:crm label
• [DECOMPOSE] 13 AC across search/detail/promotion concerns, route to skill-decompose-ticket

Verdict: READY

Board item #1870 — ldraney/intelligentstaffingsystems#79. Type: Feature. Points: 2. Sprint B, decomp of #1868 (#77).

Issue body was updated during this review to resolve two [BODY] gaps (proxy_target dependency, sibling links). After fixes, scope is solid and implementable.

Template Completeness

• [x] Type — Feature
• [x] Lineage — Sub-ticket of #77
• [x] Repo — ldraney/pal-e-platform
• [x] User Story
• [x] Context — updated to include dev-tunnel dependency on #78
• [x] File Targets — updated: CNAME clarification, proxy_target source documented
• [x] Feature Flag — none (infrastructure)
• [x] Acceptance Criteria — 4 items, all testable
• [x] Test Expectations — terraform plan + dig
• [x] Constraints — includes blocker on #78
• [x] Checklist
• [x] Related — updated: siblings #78 (blocker), #80 linked

Traceability

• [x] story:project-setup label — verified in project-iss user-stories table ("Repo, docs, infra, and CI exist; sprints can dispatch")
• [x] story note verified — found in project-iss user-stories section
• [x] arch:infra label — present on board item
• [ ] arch note MISSING — no arch-infra note exists in pal-e-docs. [SCOPE] This is a project-wide gap (many tickets use arch:infra), not specific to this ticket. Does not block implementation.
• [x] Forgejo issue — ldraney/intelligentstaffingsystems#79, open

File Targets

• [x] terraform/dns.tf — verified: file exists in pal-e-platform. Contains existing ISS records (iss_a apex A record, iss_www CNAME). The www CNAME pattern (name = "www", data = "intelligentstaffingsystems.ai") is the correct reference for the dev subdomain CNAME.
• [x] salt/pillar/caddy.sls — verified: file exists in pal-e-platform. Contains existing ISS vhost (domain: intelligentstaffingsystems.ai, proxy_target: intelligentstaffingsystems.tail5b443a.ts.net). New dev entry follows same structure; proxy_target comes from #78's dev-tunnel hostname.

Repo Placement

Issue filed on ldraney/intelligentstaffingsystems but all code changes are in ldraney/pal-e-platform. The ### Repo section correctly identifies pal-e-platform, and the checklist says "PR opened on pal-e-platform". This cross-repo filing is consistent with the ISS board tracking all ISS-related work. Acceptable.

Dependencies

• #77 (parent, board #1868) — deployment overlays umbrella, in todo
• #78 (sibling, board #1869) — pal-e-deployments dev overlay; blocker — provides the dev-tunnel Tailscale hostname needed as Caddy proxy_target. In backlog.
• #80 (sibling, board #1871) — ISS repo Makefile + docs. No dependency in either direction.
• PR #534 (pal-e-platform) — wired apex domain. Done; serves as reference pattern.
• #4 (board #1783) — service registration in pal-e-services. Done.

Dependencies now documented in issue body (Constraints + Related sections).

Acceptance Criteria

4 criteria, all verifiable:

• AC1: CNAME record in dns.tf — agent can verify by reading file after edit
• AC2: Caddy vhost in caddy.sls — agent can verify by reading file after edit
• AC3: dig resolution — requires post-apply infra access, appropriate for infra ticket
• AC4: Dev environment accessible — requires runtime verification with dev tunnel active, appropriate for infra ticket

Blast Radius

Low. Adding a DNS CNAME record and a Caddy vhost entry are both additive operations that don't affect existing entries. The 6 existing Caddy sites and all existing DNS records remain unchanged. No downstream consumers affected.

Decomposition Assessment

2 file targets in 1 repo. 4 acceptance criteria. Estimated agent work well under 5 minutes (add one DNS resource block, add one Caddy site entry). No decomposition needed.

Recommendation

• [SCOPE] Create architecture note arch-infra in pal-e-docs for the infra component. This is a project-wide gap affecting multiple tickets, not specific to #79.

All [BODY] issues resolved during this review. Ticket is implementable once #78 provides the dev-tunnel Tailscale hostname.

Fixes Applied During Review

• [BODY] Clarified DNS record type: CNAME pointing to apex (follows www pattern in dns.tf)
• [BODY] Documented that Caddy proxy_target depends on #78's dev-tunnel Tailscale hostname
• [BODY] Added Context paragraph explaining dev-tunnel dependency
• [BODY] Added #78 as blocker in Constraints section
• [BODY] Added #78 (blocker) and #80 (sibling) to Related section
• [BODY] Updated AC1 to say "CNAME" instead of ambiguous "DNS record"
• [BODY] Updated AC2 to mention "correct proxy_target"

Verdict: READY

Re-review of board item #1822 — Forgejo issue ldraney/intelligentstaffingsystems#52. Type: Feature. Sprint B, 3 points. Re-review of review-1822-2026-07-17 (v1 verdict: NEEDS_REFINEMENT).

V1 Refinement Status

All three [BODY] recommendations from v1 were correctly applied:

• [x] [BODY] File Targets clarity — Controller and view now described as "exists as a stub from #49" with specific modification instructions (add role branching, extract partial, add interactivity). Previously said "create or modify."
• [x] [BODY] tabs.css migration — communications.css entry now documents that contact-card styles live in tabs.css (lines 87-133), which is staged for deletion, and must be migrated.
• [x] [BODY] #49 blocker — Related section now explicitly marks #49 as "blocker dependency" with detail: "PR #73, merged… Must be merged before this work begins."

Two [SCOPE] items from v1 remain outstanding (external work, not issue body changes):

• [ ] communications story entry not yet created in project-iss user-stories (issue body now documents this gap in a Traceability Note section)
• [ ] arch-rails architecture note not yet created in pal-e-docs

Template Completeness

• [x] Type — Feature
• [x] Lineage — Standalone, replaces old Messages tab #12
• [x] Repo — ldraney/intelligentstaffingsystems
• [x] User Story — lead/client wants clear contact methods
• [x] Context — three action buttons (DM, Email, Appointment), role gating, detailed behavior
• [x] File Targets — 5 files listed with exists/new annotations, migration path documented
• [x] Feature Flag — none
• [x] Acceptance Criteria — 9 items
• [x] Test Expectations — 5 items with run command and existing test file reference
• [x] Constraints — Stimulus, importmap, no Node, role branching pattern
• [x] Checklist — present
• [x] Related — present with explicit blocker and downstream dependencies

All required sections present.

Traceability

• [x] story:communications label — present on board item
• [ ] story note — communications not listed in project-iss user-stories section. Issue body documents the gap in a Traceability Note. Three board items (#1822, #1824, #1827) use this label. [SCOPE] Create user story entry communications on project-iss user-stories section.
• [x] arch:rails label — present on board item
• [ ] arch note — no arch-rails note found in pal-e-docs. [SCOPE] Create architecture note arch-rails for the Rails application component.
• [x] Forgejo issue — ldraney/intelligentstaffingsystems#52, open

File Targets

• [x] app/controllers/communications_controller.rb — verified: EXISTS on HEAD (16 lines, stub with empty index action). Issue correctly says "exists as a stub from #49, modify to add role-branching render logic."
• [x] app/views/communications/index.html.erb — verified: EXISTS on HEAD (57 lines, renders three static contact cards with SVG icons). Issue correctly says "exists as a stub from #49, modify to add role-conditional rendering and extract partial."
• [x] app/views/communications/_contact_cards.html.erb — verified: DOES NOT EXIST on HEAD. Correctly identified as new file (extracted partial).
• [x] app/assets/stylesheets/communications.css — verified: DOES NOT EXIST on HEAD. Correctly identified as new file. Issue accurately notes that contact-card styles live in tabs.css lines 87-133 (verified: 47 lines of .tab-cards and .contact-card styles).
• [x] app/javascript/controllers/clipboard_controller.js — verified: DOES NOT EXIST on HEAD. Correctly identified as new file. Importmap pin_all_from "app/javascript/controllers" confirmed on line 7 of importmap.rb.
• [x] test/controllers/communications_controller_test.rb — verified: EXISTS on HEAD (55 lines). Correctly referenced.
• [x] Route /communications — verified: exists on line 29 of routes.rb.
• [x] admin? helper pattern — verified: exists in messages_controller.rb at line 100. Constraint to follow this pattern is accurate.

Repo Placement

OK — all work is in ldraney/intelligentstaffingsystems, matching the Forgejo issue repo.

Dependencies

• #49 (tab bar restructure, board #1829) — in validation. Provides the stub controller, view, route, and nav entry. Explicitly marked as blocker in issue body. PR #73 merged.
• #12 (messaging model, board #1792) — in backlog, decomposed. Scope overlap documented; decomposed children #40 and #42 already in done.
• #54 (admin communications, board #1824, sprint:C) — depends on the role branching this ticket introduces.
• #55 (live DM, board #1825, sprint:C) — depends on the DM placeholder this ticket creates.
• #57 (board #1827, sprint:C) — depends on this ticket.

All dependencies accurately documented in the issue body.

Acceptance Criteria

9 AC items, all concrete and verifiable by an agent via endpoint assertions and assert_select. Test expectations reference existing test file (55 lines) and include run command. No missing criteria detected.

Blast Radius

• tabs.css style migration is now documented in the issue body — the agent knows to migrate lines 87-133 to communications.css.
• The admin? helper pattern from messages_controller.rb is explicitly called out in Constraints.
• No downstream API consumers affected. Turbo Native picks up UI changes automatically.

Decomposition Assessment

• 5 file targets in 1 repo — below the >3 files across >2 repos threshold
• 9 acceptance criteria — above the >5 threshold
• Estimated agent work — borderline 5 minutes
• Work is cohesive: single controller/view/partial/CSS/stimulus in one feature area, existing stubs reduce scope

No decomposition needed. Same assessment as v1 — cohesive work within a single domain.

Recommendations

Issue body is complete and ready for implementation. Two [SCOPE] items from v1 remain as non-blocking external tasks:

• [SCOPE] Create user story entry communications on project-iss user-stories section. Three board items (#1822, #1824, #1827) use this label. The issue body's Traceability Note documents the gap and recommends creating the entry rather than relabeling.
• [SCOPE] Create architecture note arch-rails for the Rails application component. This is a generic component label shared across many tickets.

Neither [SCOPE] item blocks the implementation agent — the issue body contains all information needed to execute.

Verdict: APPROVED

Re-review of board item #1821 — Forgejo issue ldraney/intelligentstaffingsystems#51. Feature type, sprint:B, 5 points. Previous review review-1821-2026-07-17 was NEEDS_REFINEMENT with 8 recommendations. This re-review verifies refinements were applied.

Refinement Audit

5 of 5 [BODY] recommendations applied correctly. 1 [DECOMPOSE] acknowledged with deliberate deferral. 2 [SCOPE] items remain as documentation follow-up (tracked in issue body).

#	Tag	Recommendation	Status
1	[SCOPE]	Create "projects" user story entry on project-iss	NOT DONE — tracked in issue body Traceability section
2	[SCOPE]	Create arch-rails note	NOT DONE — acknowledged as general-purpose label in issue body
3	[BODY]	Fix file targets: controller + index.html.erb to "modify"	FIXED
4	[BODY]	Add config/routes.rb to file targets	FIXED
5	[BODY]	Add test file targets	FIXED
6	[BODY]	Add Lead model has_many to file targets	FIXED
7	[BODY]	Clarify AC #6 status field	FIXED — now specifies submitted/active/completed
8	[DECOMPOSE]	8 AC, ~10 file targets, route to skill-decompose-ticket	ACKNOWLEDGED — Decomposition Note added, deliberately kept as one ticket

Template Completeness

• [x] Type — Feature
• [x] Lineage
• [x] Repo
• [x] User Story
• [x] Context
• [x] File Targets — now properly split into "Files to modify" and "Files to create" with accurate descriptions
• [x] Feature Flag — None (acceptable; no feature-flags doc in repo)
• [x] Acceptance Criteria — 8 items, all testable
• [x] Test Expectations — 9 items with run command
• [x] Constraints
• [x] Checklist
• [x] Related
• [x] Decomposition Note (extra section, acceptable)
• [x] Traceability (extra section, documents outstanding gaps)

Traceability

• [x] story:projects label present
• [ ] story note MISSING — project-iss user-stories section has no "projects" key. Issue body explicitly tracks this: "needs to be created before or during implementation." Non-blocking for implementation — the user story IS defined in the issue body itself.
• [x] arch:rails label present
• [ ] arch note MISSING — search for arch-rails returned no results. This is a general-purpose label shared across ~15 board items. Issue body acknowledges as "general Rails application component." Non-blocking — this is a platform-wide documentation gap, not specific to this ticket.
• [x] Forgejo issue — ldraney/intelligentstaffingsystems#51, state: open

File Targets

All file targets verified against main branch:

Files to modify (all verified to exist):

• [x] app/controllers/projects_controller.rb — exists as stub from #49, empty index action. Correctly listed as modify.
• [x] app/views/projects/index.html.erb — exists as stub from #49, empty-state placeholder. Correctly listed as modify.
• [x] config/routes.rb — exists, has resources :projects, only: %i[index]. Correctly describes adding :new, :create.
• [x] app/models/lead.rb — exists, currently has has_many :messages only. Correctly listed for adding has_many :project_requests.
• [x] test/controllers/projects_controller_test.rb — exists with 7 tests. Correctly listed as extend.

Files to create (all verified to NOT exist):

• [x] app/views/projects/new.html.erb — does not exist. Correct.
• [x] app/views/projects/_project_card.html.erb — does not exist. Correct.
• [x] app/models/project_request.rb — does not exist. Correct. Model fields specified (lead_id, business_name, description, target_audience, inspiration, status).
• [x] app/assets/stylesheets/projects.css — does not exist. Correct.
• [x] db/migrate/XXX_create_project_requests.rb — no project migrations exist. Correct. Status column default specified (submitted).
• [x] test/models/project_request_test.rb — does not exist. Correct.

Repo Placement

OK — issue filed on ldraney/intelligentstaffingsystems, all work targets that repo. No cross-repo impact.

Dependencies

• #49 (tab bar restructure, board item 1829) — in validation column. Created stubs this ticket extends. Already merged to main (commit bf5f912). Not a blocker.
• #56 (CRM, Sprint C, board item 1826) — in backlog. Forward dependency: CRM will consume ProjectRequest records. Documented in issue body. Not a blocker.
• #50 (catalog Sprint B, board item 1820) — in todo. Same sprint, independent work. No conflict.
• #52 (communications Sprint B, board item 1822) — in backlog. Same sprint, independent work. No conflict.
• No blockers found. All dependencies documented in issue body.

Acceptance Criteria

8 AC, all testable by an agent:

• AC 1-5 and 7-8: clear, directly testable via endpoint tests and model tests
• AC 6: now includes explicit status field values (submitted, active, completed) — FIXED from previous review. Agent can implement status enum and test card rendering by status.

Test Expectations section includes 9 specific test cases with a run command. Comprehensive coverage.

Blast Radius

• Navigation helper (app/helpers/navigation_helper.rb) — already references :projects tab with path /projects for lead/client/admin roles. No changes needed.
• Tab bar tests (test/controllers/tab_bar_test.rb) — already verify projects tab link. Additive controller changes should not break.
• Existing stub tests (test/controllers/projects_controller_test.rb) — 7 tests for index access and empty state. Extension is additive.
• Lead model — adding has_many :project_requests is additive. No existing code depends on absence of this association.
• docs/user-stories.md — already mentions ProjectRequest (line 156). Consistent with ticket scope.
• No blast radius concerns.

Decomposition Assessment

Two of three 5-minute rule criteria exceeded (same as v1 review):

• >3 file targets across >2 repos — NO (1 repo)
• >5 acceptance criteria — YES (8 AC)
• Estimated agent work >5 minutes — YES (~10 minutes)

Issue body includes explicit Decomposition Note acknowledging this and deliberately keeping as one ticket: "the implementing agent can assess whether to split at implementation time." This is a reasonable override — the work is cohesive (one repo, one domain, one feature) and the natural split would add coordination overhead without improving clarity. Accepted as deliberate deferral.

Recommendation

All [BODY] refinements from review-1821-2026-07-17 were correctly applied. The issue body is complete, accurate, and implementable. Two [SCOPE] items remain as non-blocking follow-up:

• [SCOPE] Create user story entry "projects" on project-iss user-stories section — tracked in issue body, can be done during or after implementation.
• [SCOPE] Create architecture note arch-rails — platform-wide gap affecting ~15 board items, not specific to this ticket. Consider creating as a separate todo.

No action needed on the issue body. Ticket is ready for implementation.

Verdict: NEEDS_REFINEMENT

Board item #1822 — Forgejo issue ldraney/intelligentstaffingsystems#52. Type: Feature. Sprint B, 3 points.

Template Completeness

• [x] Type — Feature
• [x] Lineage — Standalone, replaces old Messages tab #12
• [x] Repo — ldraney/intelligentstaffingsystems
• [x] User Story — lead/client wants clear contact methods
• [x] Context — three action buttons (DM, Email, Appointment), role gating
• [x] File Targets — 5 files listed (create or modify)
• [x] Feature Flag — none
• [x] Acceptance Criteria — 9 items
• [x] Test Expectations — 5 items with run command
• [x] Constraints — Stimulus, importmap, no Node
• [x] Checklist — present
• [x] Related — project-iss, #12

All required sections present.

Traceability

• [x] story:communications label — present on board item
• [ ] story note MISSING — communications is not listed in project-iss user-stories section. Closest key is messaging. Three board items (#1822, #1824, #1827) use this label, so a new story entry should be created rather than relabeling. [SCOPE] Create user story entry communications on project-iss user-stories section.
• [x] arch:rails label — present on board item
• [ ] arch note MISSING — no arch-rails note found in pal-e-docs. [SCOPE] Create architecture note arch-rails for the Rails application component.
• [x] Forgejo issue — ldraney/intelligentstaffingsystems#52, open

File Targets

• [x] app/controllers/communications_controller.rb — verified: EXISTS as stub from #49 (empty index action, 16 lines). Ticket says "create or modify" but should say "modify — add role branching".
• [x] app/views/communications/index.html.erb — verified: EXISTS as stub from #49 (57 lines, already renders three static contact cards with SVG icons). Ticket should acknowledge this stub and describe what to change (add role-conditional rendering, extract partial).
• [x] app/views/communications/_contact_cards.html.erb — verified: DOES NOT EXIST. Correctly identified as new file.
• [ ] app/assets/stylesheets/communications.css — ISSUE: Does not exist yet (correctly), but the ticket does not mention that contact-card styles already live in app/assets/stylesheets/tabs.css (lines 87-133). tabs.css is staged for deletion in the current working tree. The ticket should state that existing styles should be migrated from tabs.css to communications.css and augmented with locked/disabled state styling.
• [x] app/javascript/controllers/clipboard_controller.js — verified: DOES NOT EXIST. Correctly identified as new file. Importmap already has pin_all_from "app/javascript/controllers" so auto-discovery will work.

Existing tests at test/controllers/communications_controller_test.rb (55 lines) already cover basic access and card rendering from #49 stub. The ticket's test expectations build on these with role-specific assertions.

Repo Placement

OK — all work is in ldraney/intelligentstaffingsystems, matching the Forgejo issue repo.

Dependencies

• #49 (tab bar restructure, board #1829) — in validation. Provides the stub controller, view, route, and nav entry this ticket builds on. This ticket depends on #49 being merged first.
• #12 (messaging model, board #1792) — in backlog, decomposed. Scope overlap noted in issue. This ticket renders DM as a placeholder; #12's decomposed children (#40, #42) already shipped messaging CRUD and Turbo Streams.
• #54 (admin communications, board #1824, sprint:C) — depends on the role branching this ticket introduces.
• #55 (live DM, board #1825, sprint:C) — depends on the DM placeholder this ticket creates.
• #57 (board #1827, sprint:C, story:communications) — depends on this ticket.

Dependencies are documented in the Related section but should explicitly note the #49 dependency as a blocker.

Acceptance Criteria

9 AC items, all verifiable by an agent:

• AC 1-2: testable via endpoint assertions (already partially covered by existing tests)
• AC 3: clipboard copy + toast — testable via Stimulus controller unit test or manual verification (noted in test expectations)
• AC 4-5: DM locked/active by role — testable via assert_select with role-specific sign-in
• AC 6: appointment link — testable via assert_select
• AC 7: icon + label + description — testable via CSS class assertions
• AC 8: responsive/mobile-first — testable via CSS inspection (grid breakpoint)
• AC 9: admin different view — testable via role-specific rendering assertion

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

Blast Radius

• tabs.css is staged for deletion — the contact-card styles living there need to be migrated to communications.css before or as part of this ticket. If tabs.css deletion lands first (from another PR), the existing stub view will lose its styling.
• The messages controller (app/controllers/messages_controller.rb) already implements an admin? helper for role branching — this ticket should follow the same pattern for consistency.
• No downstream API consumers affected. The iOS Turbo Native app will pick up UI changes automatically.

Decomposition Assessment

• 5 file targets in 1 repo — below the >3 files across >2 repos threshold
• 9 acceptance criteria — ABOVE the >5 threshold
• Estimated agent work — borderline 5 minutes
• However: work is cohesive (single controller/view/partial/CSS/stimulus in one feature area), existing stubs reduce scope, and all files are in the same domain

Borderline. The 9 AC count formally triggers the decomposition rule, but the work is cohesive enough that a single agent pass is feasible. Recommend keeping as-is but could split into (a) controller+view role branching + tests and (b) Stimulus clipboard + CSS if desired.

Recommendations

• [SCOPE] Create user story entry communications on project-iss user-stories section. Three board items use this label. Suggested row: Key=communications, Backing="Epic 4 (broadened from messaging)", Role="Lead/Client/Admin", Success metric="Three contact methods displayed; DM gated behind client role".
• [SCOPE] Create architecture note arch-rails for the Rails application component.
• [BODY] File Targets: note that communications_controller.rb and index.html.erb already exist as stubs from #49. Describe what specifically needs to change (add role branching, extract partial, add interactivity) rather than "create or modify".
• [BODY] File Targets: add note that contact-card styles currently live in tabs.css (lines 87-133) and must be migrated to communications.css.
• [BODY] Related section: explicitly note #49 as a blocker dependency (stub controller/view/route must be merged first).

Verdict: NEEDS_REFINEMENT

Board item #1821 — Forgejo issue ldraney/intelligentstaffingsystems#51. Feature type, sprint:B, 5 points.

Template Completeness

• [x] Type — Feature
• [x] Lineage
• [x] Repo
• [x] User Story
• [x] Context
• [x] File Targets
• [x] Feature Flag — None (acceptable; no feature-flags doc in repo)
• [x] Acceptance Criteria
• [x] Test Expectations
• [x] Constraints
• [x] Checklist
• [x] Related

Traceability

• [x] story:projects label present
• [ ] story note MISSING — project-iss user-stories section has no "projects" key. Existing keys: project-setup, landing-page, registration, auth, dashboard, navigation, catalog, messaging, profile, admin, ios-app, domains, ui-ux. [SCOPE] Create user story entry "projects" on project-iss user-stories section.
• [x] arch:rails label present
• [ ] arch note MISSING — search for arch-rails returned no results. Note: arch:rails is shared across ~15 board items as a general-purpose label for the Rails app. [SCOPE] Create architecture note arch-rails for the Rails application component, or decide whether this is an intentional general-purpose label that doesn't need a backing note.
• [x] Forgejo issue — ldraney/intelligentstaffingsystems#51, state: open

File Targets

• [ ] app/controllers/projects_controller.rb — ISSUE: Listed as "create" but already EXISTS as a stub from #49 (commit bf5f912). Contains an empty index action. Should say "modify/extend" not "create."
• [ ] app/views/projects/index.html.erb — ISSUE: Listed as "create" but already EXISTS as a stub from #49. Contains empty-state placeholder. Should say "modify" not "create."
• [x] app/views/projects/new.html.erb — verified does not exist, correctly listed as create
• [x] app/views/projects/_project_card.html.erb — verified does not exist, correctly listed as create
• [x] app/models/project_request.rb — verified does not exist, correctly listed as create
• [x] app/assets/stylesheets/projects.css — verified does not exist, correctly listed as create
• [x] db/migrate/XXX_create_project_requests.rb — no project-related migrations exist, correctly listed as create
• [ ] config/routes.rb — MISSING from file targets. Currently has resources :projects, only: %i[index]. Needs :new, :create actions added.
• [ ] test/controllers/projects_controller_test.rb — MISSING from file targets. Already EXISTS as stub tests from #49 (6 tests for index access and empty state). Needs extension for new/create actions. Mentioned in Test Expectations but not File Targets.
• [ ] test/models/project_request_test.rb — MISSING from file targets. Does not exist. Mentioned in Test Expectations but not File Targets.

Repo Placement

OK — issue filed on ldraney/intelligentstaffingsystems, all work targets that repo. No cross-repo impact.

Dependencies

• #49 (tab bar restructure) — in validation column. Created the stub controller, view, routes, and tests that this ticket extends. Already merged to main (commit bf5f912). Not a blocker.
• #56 (CRM, Sprint C) — forward dependency. Issue body says "admin sees requests from the CRM tab, not from here." The CRM ticket will consume ProjectRequest records. Not a blocker for this ticket, but documents a downstream consumer.
• No other dependencies found on the board. No blockers.

Acceptance Criteria

8 criteria total. Most are testable by an agent. One issue:

• AC #6: "Project cards display for users with active projects: name, status, description" — The ticket only defines a ProjectRequest model, not a Project model. No status field or lifecycle is defined on the model. It is unclear what makes a request become an "active project" or what status values exist. The agent cannot implement this AC without clarification on the data model. This needs a status field defined (e.g., submitted, active, completed) or clarification that all submitted requests show as cards.
• Other AC are clear and testable.

Blast Radius

• Navigation helper (app/helpers/navigation_helper.rb:17) — already references :projects tab with path /projects for lead/client/admin roles. No changes needed here.
• Tab bar tests (test/controllers/tab_bar_test.rb) — already verify projects tab link. Additive changes to the controller should not break existing tests.
• Existing stub tests (test/controllers/projects_controller_test.rb) — 6 tests verify index access and empty state. Extending the controller is additive.
• No similar pattern bugs found elsewhere. The Lead model has has_many :messages but no has_many :project_requests yet — this needs to be added.

Decomposition Assessment

Two of three 5-minute rule criteria exceeded:

• >3 file targets across >2 repos — NO (1 repo) — does not trigger
• >5 acceptance criteria — YES (8 AC) — triggers
• Estimated agent work >5 minutes — YES (~10 minutes: model + migration + controller expansion + 3 views + CSS + routes + 2 test files) — triggers

NEEDS DECOMPOSITION — route to skill-decompose-ticket. Suggested natural split:

1. Sub-ticket 1: ProjectRequest model layer — model, migration, model tests, has_many on Lead. (~3 files, 2 AC)
2. Sub-ticket 2: Controller + views + routes — controller expansion, routes update, index.html.erb update, new.html.erb, project card partial, projects.css, controller test expansion. (~7 files, 6 AC)

Recommendation

• [SCOPE] Create user story entry "projects" on project-iss user-stories section.
• [SCOPE] Create architecture note arch-rails for the Rails application component (shared across ~15 board items).
• [BODY] Fix file targets: app/controllers/projects_controller.rb and app/views/projects/index.html.erb already exist as stubs from #49 — change "create" to "modify."
• [BODY] Add missing file target: config/routes.rb — add :new, :create to projects resource.
• [BODY] Add missing file targets: test/controllers/projects_controller_test.rb (exists, extend) and test/models/project_request_test.rb (create).
• [BODY] Add has_many :project_requests to Lead model in file targets.
• [BODY] Clarify AC #6: define a status field on ProjectRequest (e.g., submitted/active/completed) or clarify that all requests display as cards.
• [DECOMPOSE] 8 AC, ~10 file targets, estimated ~10 minutes — route to skill-decompose-ticket. Natural split: model layer sub-ticket + UI layer sub-ticket.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — Feature
• [x] Lineage — Replaces scope of #11
• [x] Repo — ldraney/intelligentstaffingsystems
• [x] User Story — As a lead or client, browse portfolio
• [x] Context — Portfolio positioning, target audience described
• [x] File Targets — 6 files listed (modify or create)
• [x] Feature Flag — None (correct, core tab)
• [x] Acceptance Criteria — 7 items
• [x] Test Expectations — 6 tests + run command
• [x] Constraints — Turbo Native, responsive, ISS tokens, read-only
• [x] Checklist — PR/tests/unrelated
• [x] Related — project-iss, #11

Traceability

• [x] story:catalog label — Epic 3 (US-3.1–3.2), Lead/Client, "Browse portfolio by three pillars; admin CRUD"
• [x] story note verified — found in project-iss user-stories section
• [x] arch:rails label — present on board item
• [ ] arch note MISSING — [SCOPE] No arch-rails note exists in pal-e-docs. Create architecture note arch-rails for the Rails application component.
• [x] Forgejo issue — ldraney/intelligentstaffingsystems#50, open

File Targets

• [x] app/controllers/catalog_controller.rb — verified: EXISTS with index + show actions, all roles see same content
• [x] app/views/catalog/index.html.erb — verified: EXISTS with card grid, pillar grouping, and tech tags
• [ ] app/views/catalog/_catalog_entry.html.erb — ISSUE: Does not exist. Index renders cards inline. Creating this partial is a refactoring extraction — acceptable as a "create" target but should be noted.
• [x] app/views/catalog/show.html.erb — verified: EXISTS with breadcrumb, gallery, tech sidebar
• [x] app/assets/stylesheets/catalog.css — verified: EXISTS
• [x] app/models/catalog_entry.rb — verified: EXISTS but does NOT have app_store_url field. Schema confirms no such column.
• [ ] Migration file — ISSUE: [BODY] Issue says "add app_store_url field if not present" but no migration file is listed in File Targets. Add db/migrate/XXXXXX_add_app_store_url_to_catalog_entries.rb to the File Targets section.

Repo Placement

OK — issue filed on ldraney/intelligentstaffingsystems, all file targets are in that repo. No cross-repo concerns.

Dependencies

• #1791 (#11) — original catalog ticket (decomposed, sprint:4). Its children #38 (model), #39 (browsing UI), #41 (admin CRUD) are all DONE. The catalog infrastructure this ticket builds on is fully shipped.
• #1829 (#49) — tab bar restructure (sprint:A, validation). Catalog tab already wired in navigation helper. No blocker.
• No blocking items in in_progress or todo columns.
• No downstream items depend on this ticket.
• Dependencies are not explicitly documented in the issue body, but the Lineage section references #11 which covers the relationship.

Acceptance Criteria

7 AC items. Assessment of each:

• AC 1 (portfolio description) — NEW work. Current header says "What We Build" / "Browse our catalog." Needs portfolio-focused language about customization and target audience. Testable via assert_select.
• AC 2 (target audience copy) — NEW work. Testable via assert_select for content.
• AC 3 (cards with App Store link) — PARTIALLY DONE. Cards already show title, description, screenshot, pillar. App Store link is the new addition. Testable.
• AC 4 (external browser for App Store links) — NEW work. Requires data-turbo="false". This is the first use of this pattern anywhere in the app. Testable via assert_select for the data attribute.
• AC 5 (responsive card grid) — ALREADY DONE. Grid exists in catalog.css.
• AC 6 (all three roles see identical content) — ALREADY DONE. Tests exist and pass.
• AC 7 (detail page with expanded info, multiple screenshots, tech stack) — ALREADY DONE. Show page exists with gallery and tech sidebar.

Concern: An implementing agent may not realize that ACs 5-7 are already satisfied, wasting time rebuilding existing functionality. The issue should clarify which ACs are "verify existing" vs "implement new."

Blast Radius

• No data-turbo="false" or target="_blank" patterns exist anywhere in the app currently. This ticket introduces the first external-link-in-Turbo-Native convention. The pattern should be documented or noted as precedent-setting for future tickets.
• The landing page uses a constant ApplicationHelper::APP_STORE_URL for a single TestFlight link. Catalog entries will have per-entry app_store_url columns — a different mechanism. No conflict.
• Admin catalog CRUD (app/controllers/admin/catalog_controller.rb) exists and would need updating to allow editing the new app_store_url field, but the issue correctly says "Files NOT to touch: app/controllers/admin/catalog_controller.rb — admin CRUD is separate." This is consistent — a follow-up ticket should handle the admin form update.

Decomposition Assessment

6 file targets in 1 repo. 7 AC items (over the 5-item guideline), but 3 are already implemented. Real new work: 1 migration, update header copy, add App Store link buttons with data-turbo="false", add model validation, optionally extract a partial. Estimated agent work: ~4 minutes. No decomposition needed.

Recommendation

• [BODY] Add migration file to File Targets: db/migrate/XXXXXX_add_app_store_url_to_catalog_entries.rb — adds app_store_url:string column.
• [BODY] Clarify which ACs are "verify existing" vs "implement new." ACs 5-7 are already satisfied by Sprint 4 work. Mark them as verification-only or remove them to avoid confusing the implementing agent.
• [SCOPE] Create architecture note arch-rails for the Rails application component. This label is used across many board items.

Verdict: APPROVED

Re-review: Both issues from the initial NEEDS_REFINEMENT review have been resolved. Verdict upgraded to APPROVED.

Template Completeness

• [x] Type (Feature)
• [x] Lineage
• [x] Repo
• [x] User Story
• [x] Context
• [x] File Targets
• [x] Feature Flag (None -- docs only, acceptable)
• [x] Acceptance Criteria (6 items)
• [x] Test Expectations (No tests -- docs only)
• [x] Constraints
• [x] Checklist
• [x] Related

Traceability

• [x] story:ui-ux label -- UI/UX design story
• [x] story note verified -- ui-ux row found in project-iss user-stories table (Key=ui-ux, Backing=docs/ui-ux.md, Role=All roles, Success metric=Design doc + tab architecture established as single source of truth)
• [x] arch:docs label -- category label, no backing architecture note required (consistent with 7+ board items: #1780, #1800, #1803, #1804, #1805, #1806, #1807)
• [x] Forgejo issue -- https://forgejo.tail5b443a.ts.net/ldraney/intelligentstaffingsystems/issues/48, open

File Targets

• [x] docs/ui-ux.md -- verified: does not exist yet (to be created). docs/ directory confirmed present with 10 existing files.
• [x] docs/user-stories.md -- verified: exists (16k). Current Role-Tab Access Matrix (lines 237-242) shows old tab structure: Catalog, Messages, Profile, Admin. Ticket correctly identifies this for update.

Repo Placement

OK. Issue filed on ldraney/intelligentstaffingsystems, all file targets are in the same repo. Single repo, no cross-repo concerns.

Dependencies

This ticket establishes the UX spec that other Sprint A tickets depend on:

• #1829 (issue #49, story:navigation, sprint:A) -- needs tab architecture from this doc
• #1830 (issue #58, story:landing-page, sprint:A) -- landing page redesign references design philosophy
• #1831 (issue #59, story:registration, sprint:A) -- registration flow needs new UX context

Dependencies are not explicitly documented in the issue body. This ticket should be completed before the other sprint A tickets begin, or at minimum in parallel with clear references.

Acceptance Criteria

6 AC, all verifiable via file existence and content grep:

• AC1: file existence + section presence check
• AC2: diff review of user-stories.md Role-Tab matrix
• AC3: grep for new role-tab matrix content
• AC4: grep for DM-on-promotion gating
• AC5: grep for target audience descriptions
• AC6: grep for admin vs lead/client Communications view differences

No test commands needed (docs-only). Criteria are specific and machine-verifiable.

Blast Radius

The old tab structure (Catalog, Messages, Profile, Admin) is referenced across 5 docs files:

• docs/user-stories.md (lines 10, 24, 138, 237-242) -- IN SCOPE of this ticket
• docs/security.md (lines 64, 76) -- out of scope (intentional)
• docs/keycloak-setup.md (line 32) -- out of scope
• docs/architecture.md (line 173) -- out of scope (explicitly excluded)
• docs/testing-strategy.md (line 176) -- out of scope

The issue explicitly states that architecture.md and security.md changes belong to individual feature tickets. This is a valid scoping decision, but will leave temporary inconsistency across docs until those feature tickets land. Acceptable.

Decomposition Assessment

2 file targets in 1 repo. 6 acceptance criteria (borderline on the >5 threshold, but all are tightly coupled doc sections in the same 2 files). Estimated agent work: ~3-4 minutes. No decomposition needed.

Recommendation

No action needed.

Resolution Notes

• [RESOLVED] story:ui-ux label registered. Added ui-ux row to project-iss user-stories table: Key=ui-ux, Backing=docs/ui-ux.md, Role=All roles, Success metric=Design doc + tab architecture established as single source of truth.
• [RESOLVED] arch:docs is a category label and does not require a backing architecture note -- consistent with existing usage across 7+ board items (#1780, #1800, #1803, #1804, #1805, #1806, #1807).

Verdict: NEEDS_REFINEMENT

Round 3 review. The dev overlay scope and reference counts are now accurate (verified: 5+4+4+6 = 19 stale references across 4 files). However, the issue still contains a critical factual error about the prod overlay, and the ACs are incomplete as a result.

Template Completeness

• [x] Type — Bug
• [x] Lineage — sub-ticket of #220, discovered during sprint 5 validation
• [x] Repo — ldraney/pal-e-deployments
• [x] What Broke — present, detailed
• [x] Repro Steps — present, 3 steps
• [x] Expected Behavior — present
• [x] Environment — present with file listings
• [x] Acceptance Criteria — present, 7 items
• [x] Related — present with prior reviews

Traceability

• [x] story:WS-S1 — "As superadmin, I want to deploy platform changes via IaC so that infrastructure is reproducible and auditable"
• [x] story note verified — found in project-westside-basketball user-stories section (Superadmin list)
• [x] arch:iac label — infrastructure-as-code component
• [ ] arch note MISSING — [SCOPE] No arch-iac note found in pal-e-docs. Acceptable for now: IaC is a cross-cutting concern, not a discrete component. Low priority.
• [x] Forgejo issue — ldraney/pal-e-deployments#221, open

File Targets

• [x] overlays/westside-ror/dev/deployment.yaml — verified: 5 stale westside-ror references, hostPath at line 47 confirmed
• [x] overlays/westside-ror/dev/service.yaml — verified: 4 stale references
• [x] overlays/westside-ror/dev/ingress.yaml — verified: 4 stale references
• [x] overlays/westside-ror/README.md — verified: 6 stale references
• [ ] overlays/westside-ror/prod/kustomization.yaml — ISSUE: issue claims "already reference westside-basketball correctly" and lists as "Clean files (no action needed)." In reality this file has 9 stale westside-ror references and 0 westside-basketball references.
• [ ] overlays/westside-ror/prod/deployment-patch.yaml — ISSUE: issue claims "Clean files (no action needed)." In reality this file has 1 stale westside-ror reference (hostPath line 58: /home/ldraney/westside-ror) and 0 westside-basketball references.

Repo Placement

Correct. Issue filed on pal-e-deployments, fix is in pal-e-deployments overlay files.

Dependencies

• Parent issue: pal-e-deployments#220 (decomposed parent)
• Sibling: board item #1632 — "Update NetworkPolicy: replace westside-ror with westside-basketball" (todo, sprint:6)
• Sibling: board item #1633 — "Drop stale basketball DB role + update Keycloak westside-ror references" (todo, sprint:6)
• Predecessor: pal-e-deployments#219 — namespace hotfix (merged)
• No blockers identified. This ticket can proceed independently.

Acceptance Criteria Assessment

• [x] AC1: "Overlay directory renamed from westside-ror to westside-basketball" — clear, verifiable (git mv)
• [x] AC2: "Dev overlay: all resource names, labels, and selectors updated" — clear, verifiable (grep)
• [x] AC3: "Dev overlay: deployment.yaml hostPath updated (line 47)" — verified line 47 is correct
• [x] AC4: "Tailscale funnel ingress resource added to prod kustomization" — correct, prod kustomization has no ingress/funnel resources currently
• [x] AC5: "README.md updated to reference westside-basketball" — clear, verifiable
• [ ] AC6: "ArgoCD sync succeeds with renamed overlay" — not agent-verifiable post-merge without cluster access, but reasonable as a manual validation step
• [ ] AC7: "No stale westside-ror references remain in this repo" — ISSUE: contradicts the "prod is clean" claim in the body. Also, 10 additional westside-ror references exist outside the overlay (docs/overlay-structure.md, docs/overlay-inventory.md, README.md, basketball-api/README.md, westsidekingsandqueens/README.md, westsidekingsandqueens/prod/kustomization.yaml, dev-tunnel/README.md). Either scope AC7 to the overlay directory only, or add prod and repo-wide docs to the file targets.
• [ ] MISSING AC: prod overlay kustomization.yaml — 9 stale references need renaming
• [ ] MISSING AC: prod overlay deployment-patch.yaml — hostPath at line 58 needs renaming

Blast Radius

10 westside-ror references exist outside overlays/westside-ror/:

• docs/overlay-structure.md (1 reference)
• docs/overlay-inventory.md (2 references)
• README.md (2 references)
• overlays/basketball-api/README.md (1 reference)
• overlays/westsidekingsandqueens/README.md (1 reference)
• overlays/westsidekingsandqueens/prod/kustomization.yaml (1 reference — comment)
• overlays/dev-tunnel/README.md (2 references — current target URL)

The dev-tunnel overlay references westside-ror.westside-ror.svc.cluster.local as its current target. After the rename, this will break unless updated. Either add to scope or document as known follow-up.

Decomposition Assessment

3 file targets (dev overlay) + 2 prod files + 1 README + directory rename = 6 files across 1 repo. 7+ ACs (after adding missing prod ACs). Estimated agent work: 3-4 minutes. Borderline but single-pass feasible. No decomposition needed.

Recommendations

• [BODY] Remove false claim: "The prod overlay files (kustomization.yaml, deployment-patch.yaml) already reference westside-basketball correctly" — prod has 10 stale westside-ror references (9 in kustomization.yaml, 1 hostPath in deployment-patch.yaml)
• [BODY] Remove false "Clean files" listing: "Clean files (no action needed): overlays/westside-ror/prod/kustomization.yaml, overlays/westside-ror/prod/deployment-patch.yaml" — both need renaming
• [BODY] Update total count: from "19 stale references across 4 files" to "29 stale references across 6 files" (19 dev+README + 10 prod)
• [BODY] Add AC: "Prod overlay: all resource names, labels, selectors, comments updated to westside-basketball in kustomization.yaml (9 references) and deployment-patch.yaml hostPath (line 58)"
• [BODY] Scope AC7: either narrow to "No stale westside-ror references remain in the westside-basketball overlay directory" or expand file targets to include repo-wide docs and sibling overlays (10 additional references). Recommend narrowing — repo-wide doc updates are a separate cleanup.
• [BODY] Add dev-tunnel/README.md to Related section as a known follow-up (its service URL will break after rename)

Verdict: READY

Template Completeness

• [x] Type — Bug
• [x] Lineage — Sub-ticket of pal-e-deployments #220, decomposed per review-1630-2026-06-27
• [x] Repo — ldraney/pal-e-services
• [x] What Broke — two issues described (stale DB role + stale Keycloak refs)
• [x] Repro Steps — 3 steps, clear and actionable
• [x] Expected Behavior — 4 bullet points covering both fix areas
• [x] Environment — cluster/namespace: prod, files identified
• [x] Acceptance Criteria — 9 criteria, all verifiable
• [x] Related — parent issue, predecessor, review note, project page

Traceability

• [x] story:WS-S1 label — "As superadmin, I want to deploy platform changes via IaC so that infrastructure is reproducible and auditable"
• [x] story note verified — found in project-westside-basketball user-stories section (Superadmin list, first item)
• [ ] arch:iac label — arch note MISSING — [SCOPE] No arch-iac note exists in pal-e-docs. However, this is a cross-cutting infrastructure concern (Terraform IaC) not a project-specific architecture component. Acceptable as foundational infrastructure — creating an arch note for "iac" would be too generic to be useful.
• [x] Forgejo issue — ldraney/pal-e-services#152, state: open

File Targets

• [x] terraform/k3s.tfvars — verified via k3s.tfvars.example: Keycloak client block for westside-basketball (example lines 149-176) contains client_id = "westside-ror" and 4 URL references to westside-ror.tail5b443a.ts.net. The actual k3s.tfvars is gitignored (contains secrets), so exact line numbers (156-175) cannot be verified against the example, but the content is confirmed correct.
• [x] terraform/k3s.tfvars source_path — verified: example line 343 shows source_path = "overlays/westside-ror/prod" in the westside-basketball services block. Issue says line 274 — line number mismatch vs example, but content confirmed.
• [x] terraform/k3s.tfvars databases — the service_databases variable structure is confirmed in databases.tf and variables.tf. The issue mentions "line 22" with databases = ["basketball", ...] which would be in the actual gitignored k3s.tfvars. Convention per databases.tf: map key = PostgreSQL role name = service name. The stale "basketball" role is a manual artifact outside Terraform state.
• [x] terraform/keycloak.tf — verified: contains moved blocks (lines 13-21) documenting the westside-ror to westside-basketball key rename. Comment on line 152 of example says "client_id stays westside-ror to avoid Keycloak client re-registration" — this is the intentional decision being reversed by this ticket.
• [x] terraform/services.tf — verified: contains moved blocks (lines 1-33) for Harbor/namespace/ArgoCD renames from westside-ror to westside-basketball.

Repo Placement

Correct. The Forgejo issue is filed on ldraney/pal-e-services and all file targets (terraform/k3s.tfvars) are in that repo. The stale DB role is a manual psql operation in prod, which is appropriate to track in the IaC repo since the fix involves verifying no Terraform state drift.

Note: the source_path change (overlays/westside-ror/prod to overlays/westside-basketball/prod) references a path in pal-e-deployments, but the config change itself is in pal-e-services. The sibling ticket pal-e-deployments#221 handles the actual overlay rename. This ticket must NOT run until the overlay rename lands, or ArgoCD will break.

Dependencies

Critical ordering dependency identified:

• Depends on pal-e-deployments#221 (Add Tailscale funnel ingress + rename overlay) — board item #1631. The source_path update in this ticket points to overlays/westside-basketball/prod, which does not exist until the overlay rename in #221 lands. If this ticket's source_path change applies first, ArgoCD will fail to sync because the path won't exist.
• Board item #1632 (Update NetworkPolicy: replace westside-ror with westside-basketball) is a sibling decomposition ticket — no ordering dependency, can run in parallel.
• Board item #1618 (Add rails-env Kubernetes secret) is in validation — no conflict.
• Board item #1605 (Keycloak auth with admin/coach/player roles) is done — predecessor, no conflict.

The dependency on #1631/#221 is NOT documented in the issue body. This is acceptable since the Keycloak config changes (client_id, URLs) can apply independently — only the source_path change has ordering sensitivity. An agent can apply the Keycloak changes first and hold the source_path change.

Acceptance Criteria

9 acceptance criteria. Assessment:

• AC 1-2 (DB role drop + no state drift): Requires manual psql access + terraform plan. Verifiable but involves prod access — agent needs SSH/kubectl context.
• AC 3-7 (Keycloak config updates): Straightforward find-and-replace in k3s.tfvars. Fully agent-automatable.
• AC 8 (terraform plan clean): Verifiable via terraform plan. Requires kubectl port-forward for CNPG + Keycloak providers.
• AC 9 (Auth flow works end-to-end): Requires browser-based test of login/logout. Could use validate-ui skill but needs Keycloak propagation time.

All criteria are testable. The mix of manual ops (psql, terraform apply) and automated checks (terraform plan, auth test) is appropriate for a 2pt bug fix.

Blast Radius

• pal-e-deployments overlay: overlays/westside-ror/ still exists with prod and dev subdirectories. The sibling ticket #221 handles the rename. If this ticket runs first on the source_path change, ArgoCD sync will fail.
• westside-basketball repo: No westside-ror references found in file paths. The Rails app's omniauth-keycloak config references the client_id, so changing from "westside-ror" to "westside-basketball" requires a corresponding update in the Rails app's Keycloak config (likely env var or initializer). The issue does NOT mention this — however, the Rails app likely reads client_id from an environment variable, and the Keycloak provider matches on the client_id value, so the client_id change in Terraform must be coordinated with the Rails app config.
• keycloak.tf moved blocks: Lines 13-21 have existing moved blocks for the westside-ror to westside-basketball key rename. These are already in place and should not conflict.
• Comment on line 152 of k3s.tfvars.example: # NOTE: client_id stays "westside-ror" to avoid Keycloak client re-registration. — This comment documents the original intentional decision. Changing the client_id will trigger Keycloak client re-registration. The issue should note whether this is acceptable or whether the moved block approach should be used instead.

Decomposition Assessment

File targets: 1 file (k3s.tfvars) + 1 manual psql operation. All in 1 repo. 9 acceptance criteria (above the 5 threshold), but 7 of them are trivial find-and-replace verifications. Estimated agent work: ~3-4 minutes (edit k3s.tfvars, run terraform plan, verify). No decomposition needed — the AC count is high but the work is uniform.

Recommendation

No action needed — scope is solid for a 2pt bug fix. Two advisory notes:

• Advisory: The source_path change (AC 7) must not apply until pal-e-deployments#221 (overlay rename) merges. The implementing agent should either: (a) hold the source_path change for a follow-up, or (b) verify the overlay exists before applying.
• Advisory: Changing client_id from "westside-ror" to "westside-basketball" will trigger Keycloak client re-registration (the comment on line 152 of k3s.tfvars.example explicitly warns against this). The implementing agent should verify that the Rails app's OmniAuth config reads client_id from an environment variable that can be updated in lockstep, or accept a brief auth outage during the transition.

Verdict: APPROVED

Re-review of board item #1615 after refinement. Previous review (review-1615-2026-06-26) returned NEEDS_REFINEMENT with 3 body fixes and 1 scope gap. All 3 body fixes have been addressed. The arch-salt note gap remains but is not blocking.

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- Discovered during Sprint 5 validation (Caddy pillar deploy delay)
• [x] Repo -- ldraney/pal-e-platform
• [x] User Story -- As a platform operator, I want Salt highstate to run automatically...
• [x] Context -- Manual SSH gap after merge, second time causing deploy delay
• [x] File Targets -- .woodpecker/salt.yaml (new file), explicit DO NOT TOUCH list
• [x] Feature Flag -- none (infra automation, correct)
• [x] Acceptance Criteria -- 4 criteria, all testable
• [x] Test Expectations -- integration test described (merge no-op pillar change)
• [x] Constraints -- 3 items including SSH secret name and reference pattern
• [x] Checklist -- present
• [x] Related -- 2 references (project-westside-basketball, sop-platform-tf-changes)

Traceability

• [x] story:WS-S1 label -- "As superadmin, I want to deploy platform changes via IaC so that infrastructure is reproducible and auditable"
• [x] story note verified -- found in project-westside-basketball user-stories section (Superadmin list)
• [x] arch:salt label -- Salt configuration management component
• [ ] arch note MISSING -- [SCOPE] Create architecture note arch-salt for the Salt component. No note found via search_notes("arch-salt"). NOT BLOCKING per re-review instructions.
• [x] Forgejo issue -- ldraney/pal-e-platform#466, open

Previous Review Fixes -- All Addressed

• [x] [BODY] File target path fixed: now correctly specifies .woodpecker/salt.yaml (new file in existing .woodpecker/ directory)
• [x] [BODY] SSH secret name added: AC4 now specifies ssh_edge_proxy_key as Woodpecker repo secret, states it must be provisioned before first run
• [x] [BODY] Constraints reference fixed: now says "Follow existing .woodpecker/terraform.yaml clone block and path-filter patterns from this same repo" (was incorrectly referencing pal-e-services)

File Targets

• [x] .woodpecker/salt.yaml -- new file, follows directory convention. Verified: .woodpecker/ directory exists with terraform.yaml and ruby-arch.yaml.
• [x] .woodpecker/terraform.yaml -- correctly listed as reference only (DO NOT TOUCH)
• [x] terraform/ -- correctly listed as separate concern (DO NOT TOUCH)

Repo Placement

OK. Issue filed on ldraney/pal-e-platform, work lives entirely in pal-e-platform. Single-repo, single-file change.

Dependencies

• No blocking dependencies. This ticket is independent.
• Board item #1480 (pal-e-platform#453, tofu CI pipeline) is the predecessor that established the Woodpecker CI pattern -- DONE, not blocking.
• Board item #1104 (pal-e-platform#306, arch:salt chore) is related Salt work in backlog -- not blocking.
• No in_progress items conflict with this work.

Acceptance Criteria

• [x] AC1: "Woodpecker pipeline triggers Salt highstate on edge-proxy after merge to main" -- verifiable via Woodpecker UI
• [x] AC2: "Pipeline only runs when salt/ directory has changes (path filter, matching .woodpecker/terraform.yaml pattern)" -- verifiable. Note: terraform.yaml uses internal git-diff module detection rather than Woodpecker path filters, but the agent can implement either approach. The intent is clear.
• [x] AC3: "Failure alerts via Woodpecker notification (existing pattern)" -- verifiable, references existing pattern
• [x] AC4: "Pipeline uses SSH key via Woodpecker secret ssh_edge_proxy_key to connect to edge-proxy (secret must be provisioned as a repo secret before first run)" -- verifiable, secret name and provisioning requirement are now clearly specified

All criteria are testable and unambiguous.

Blast Radius

• New .woodpecker/salt.yaml is a separate file -- no interference with existing terraform.yaml pipeline.
• Salt changes will trigger both cross-pillar-review (in terraform.yaml) AND the new salt pipeline -- correct behavior.
• Edge-proxy SSH access requires Tailscale (noted in Constraints). Woodpecker runner must be on tailnet -- infrastructure prerequisite.
• Salt is only managed in pal-e-platform -- no similar gap in other repos.

Decomposition Assessment

1 new file (.woodpecker/salt.yaml), 4 acceptance criteria, single repo. Estimated agent work under 5 minutes. No decomposition needed.

Recommendations

• [SCOPE] Create architecture note arch-salt for the Salt configuration management component in pal-e-docs. (Carried forward from previous review -- not blocking this ticket.)

No other action needed. Ticket is ready for implementation.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- Standalone, discovered during Sprint 5 validation
• [x] Repo -- ldraney/pal-e-platform
• [x] User Story -- As a platform operator...
• [x] Context -- Manual SSH gap after merge
• [x] File Targets -- present but contains error (see below)
• [x] Feature Flag -- none (correct, infra automation)
• [x] Acceptance Criteria -- 4 criteria
• [x] Test Expectations -- integration test described
• [x] Constraints -- present, 3 items
• [x] Checklist -- present
• [x] Related -- 2 references

Traceability

• [x] story:WS-S1 label -- "As superadmin, I want to deploy platform changes via IaC so that infrastructure is reproducible and auditable"
• [x] story note verified -- found in project-westside-basketball user-stories section (Superadmin list)
• [x] arch:salt label -- Salt configuration management component
• [ ] arch note MISSING -- [SCOPE] Create architecture note arch-salt for the Salt component. No note found via search_notes("arch-salt").
• [x] Forgejo issue -- ldraney/pal-e-platform#466, open
• [ ] project page MISSING -- No project-pal-e-platform page exists in pal-e-docs. This is acceptable for now as pal-e-platform is an infra repo without a dedicated project page, but the story references project-westside-basketball which does exist.

File Targets

• [ ] .woodpecker.yml -- ISSUE: File does not exist. The repo uses a .woodpecker/ directory pattern (contains terraform.yaml and ruby-arch.yaml). The correct target is .woodpecker/salt.yaml (new file, following directory convention).
• [x] salt/ -- verified: directory exists with bootstrap.sh, master.conf, minion.conf, pillar/, states/ subdirectories. Correctly noted as "no changes to Salt itself."

Repo Placement

OK. Issue is filed on ldraney/pal-e-platform, and the work (adding a Woodpecker pipeline for Salt) lives entirely in pal-e-platform. Single-repo change.

Dependencies

• Board item #1480 (ldraney/pal-e-platform#453, "Woodpecker CI: tofu plan on PR, apply on merge") -- CLOSED/DONE. This established the Woodpecker CI pattern in pal-e-platform that this ticket extends. The existing .woodpecker/terraform.yaml is the reference implementation.
• Board item #1104 (forgejo_admin/pal-e-platform#306, arch:salt) -- backlog, "Salt-manage admin-kubeconfig". Related Salt work but not a blocker.
• Board item #1149 (forgejo_admin/pal-e-platform#332, arch:salt) -- the k3s maxPods Salt ticket is CLOSED, confirms Salt patterns are established in the repo.
• No blocking dependencies. This ticket is independent.

Acceptance Criteria

• [x] AC1: "Woodpecker pipeline triggers Salt highstate on edge-proxy after merge to main" -- verifiable via Woodpecker UI
• [x] AC2: "Pipeline only runs when salt/ directory has changes (path filter)" -- verifiable, but Woodpecker path filter implementation detail should be specified in Constraints (Woodpecker uses when: path: syntax)
• [x] AC3: "Failure alerts via Woodpecker notification (existing pattern)" -- verifiable, references existing pattern
• [ ] AC4: "Pipeline uses SSH key to connect to edge-proxy (no password auth)" -- verifiable, but missing detail: which Woodpecker secret name holds the SSH key? Is the secret already provisioned, or does this ticket need to create it? This is a scoping gap.

Overall: criteria are testable but AC4 needs the SSH secret name and provisioning status clarified.

Blast Radius

• The existing .woodpecker/terraform.yaml pipeline runs on push to main. The new Salt pipeline will coexist as a separate file (.woodpecker/salt.yaml), so no interference.
• The cross-pillar-review step in the existing terraform pipeline already watches for salt/* changes and creates review issues. Adding a separate Salt pipeline means Salt changes will trigger BOTH the cross-pillar review AND the new Salt pipeline -- this is correct behavior but worth noting.
• Edge-proxy SSH access via Tailscale is a constraint already noted. The Woodpecker runner pod must have Tailscale access. This is an infrastructure prerequisite that should be verified exists (or flagged as a pre-req).
• No similar gap exists in other repos -- Salt is only managed in pal-e-platform.

Decomposition Assessment

1 new file (.woodpecker/salt.yaml), 4 acceptance criteria, single repo. Estimated agent work under 5 minutes. No decomposition needed.

Recommendations

• [BODY] Fix file target path: .woodpecker.yml should be .woodpecker/salt.yaml (new file in the existing .woodpecker/ directory, matching terraform.yaml convention).
• [BODY] Add to Constraints: specify the Woodpecker secret name for the edge-proxy SSH key, and state whether the secret already exists or must be created as part of this ticket.
• [BODY] Add to Constraints: "Follow .woodpecker/terraform.yaml clone block and path-filter patterns from this same repo" (currently says "Follow existing .woodpecker.yml patterns in pal-e-services" -- wrong reference).
• [SCOPE] Create architecture note arch-salt for the Salt configuration management component in pal-e-docs.

Verdict: APPROVED

Note: Both READY and APPROVED are accepted as passing verdicts by the check-board-advance hook.

Re-review of review-1614-2026-06-25. All 6 previous findings have been addressed.

Previous Findings Resolution

1. Root cause misidentified -- FIXED. Issue body now correctly describes the Caddy edge-proxy to Tailscale funnel chain: DNS A record to Hetzner edge-proxy, Caddy TLS termination via Let's Encrypt, reverse-proxy to tailnet hostname. The root cause section in "What Broke" accurately identifies the missing funnel ingress for the hostname Caddy targets.
2. Missing prod ingress in pal-e-deployments -- FIXED. Issue body now includes a "Scope" section covering both pal-e-platform (Caddy/Salt verification) and pal-e-deployments (prod funnel ingress). The Repo field also lists both repos.
3. Multi-repo scope not documented -- FIXED. Repo field now lists ldraney/pal-e-platform and ldraney/pal-e-deployments. Scope section has separate subsections for each repo's work.
4. arch-tailscale note missing -- FIXED. Note arch-tailscale now exists in pal-e-docs (created 2026-06-26), tagged architecture, networking, tailscale. Covers public domain architecture, funnel ingress pattern, two-hop TLS, and DNS conventions.
5. story label wrong -- FIXED. Board item #1614 now has story:WS-S1 ("As superadmin, I want to deploy platform changes via IaC so that infrastructure is reproducible and auditable") instead of WS-S9 (payment tracking). Confirmed in project-westside-basketball user-stories section under Superadmin.
6. Co-dependency with #1613 documented -- FIXED. Related section now references pal-e-services#148 as a co-dependency with explanation that both bugs must resolve for Sprint 4/5 auth changes to go live.

Template Completeness

• [x] Type -- Bug
• [x] Lineage -- Related to pal-e-platform#463 (Sprint 3 proxy setup)
• [x] Repo -- ldraney/pal-e-platform AND ldraney/pal-e-deployments (both listed)
• [x] What Broke -- TLS handshake fails with clear error output and accurate root cause chain
• [x] Repro Steps -- 3 curl commands provided
• [x] Expected Behavior -- stated clearly
• [x] Environment -- DNS, edge-proxy, k8s ingresses documented
• [x] Scope -- file targets for both repos listed with specific paths
• [x] Acceptance Criteria -- 5 criteria, all testable
• [x] Related -- project, original issue, co-dependency, arch note all referenced

All required bug template sections present and complete.

Traceability

• [x] story:WS-S1 label -- "As superadmin, I want to deploy platform changes via IaC so that infrastructure is reproducible and auditable" (Superadmin tier)
• [x] story note verified -- found in project-westside-basketball user-stories section under Superadmin (Lucas)
• [x] arch:tailscale label -- Tailscale networking component
• [x] arch note verified -- arch-tailscale note exists in pal-e-docs (id: 2179, created 2026-06-26). Covers public domain architecture, funnel ingress pattern, two-hop TLS, DNS.
• [x] Forgejo issue -- ldraney/pal-e-platform#464, state: open

File Targets

• [x] salt/pillar/caddy.sls (pal-e-platform) -- verified: westside entry exists at HEAD (commit 34fd30d, PR #463) with proxy_target: westside-basketball.tail5b443a.ts.net and www_redirect: true
• [x] salt/states/caddy/Caddyfile.j2 (pal-e-platform) -- verified: template generates site blocks from pillar data, reverse-proxies to {proxy_target}:443 with TLS server name header
• [x] salt/states/caddy/init.sls (pal-e-platform) -- verified: manages Caddyfile rendering via Jinja template and Caddy service lifecycle
• [x] overlays/westside-ror/dev/ingress.yaml (pal-e-deployments) -- verified: dev overlay has funnel ingress pattern with westside-ror hostname, port 3000, tailscale.com/funnel annotation
• [x] overlays/westside-ror/prod/ (pal-e-deployments) -- verified: prod overlay has kustomization.yaml and deployment-patch.yaml only, NO ingress file. This confirms the scope: a new ingress.yaml needs to be created here.

Additional finding (informational): A separate overlay at overlays/westsidekingsandqueens/prod/ingress.yaml exists with hostname westsidekingsandqueens (resolves to westsidekingsandqueens.tail5b443a.ts.net). This is the "wrong hostname" funnel the issue mentions -- Caddy targets westside-basketball.tail5b443a.ts.net but this ingress serves westsidekingsandqueens.tail5b443a.ts.net. The fix should either add a matching ingress in westside-ror/prod/ with hostname westside-basketball, or update the Caddy pillar to target the existing funnel hostname. The issue's scope correctly identifies this discrepancy.

Repo Placement

CORRECT. Issue is filed on ldraney/pal-e-platform (primary repo for Caddy/Salt/DNS). Scope section explicitly documents work in ldraney/pal-e-deployments as well. A single issue covering both repos is appropriate since the fix is coordinated and small (2 points).

Dependencies

• Board item #1613 (pal-e-services#148) -- Harbor pull creds bug. Also sprint:5, type:bug, story:WS-S1. Co-dependent: even if TLS/funnel fix lands, pods may be running stale code until Harbor creds are fixed. Documented in issue's Related section.
• PR #463 (merged, commit 34fd30d) -- Added Caddy pillar entry. Pillar is correct at HEAD. Salt highstate verification is in scope.
• No blockers preventing this ticket from starting. Both #1613 and #1614 can be worked in parallel.

Acceptance Criteria

5 criteria, all testable:

• AC #1 ("loads with valid TLS cert") -- verifiable: curl -sv https://westsidekingsandqueens.com 2>&1 | grep "SSL certificate verify ok"
• AC #2 ("response matches tailnet URL content") -- verifiable: diff response bodies
• AC #3 ("Caddy config verified") -- verifiable: inspect Caddyfile on edge-proxy
• AC #4 ("funnel ingress exists in k8s") -- verifiable: kubectl get ingress -n westside-ror
• AC #5 ("no regression in tailnet URL access") -- verifiable: curl https://westside-ror.tail5b443a.ts.net

Previous review's missing AC (www redirect) was not explicitly added, but the Caddy pillar has www_redirect: true and the template handles it. This is implicitly covered by AC #1 (the Caddy config is data-driven). Not a blocking concern.

Blast Radius

Two other domains use the same Caddy edge-proxy pattern:

• palinks.app -- proxy_target: palinks.tail5b443a.ts.net. No prod funnel ingress in kustomize overlay either, but palinks works because its funnel ingress is likely managed by Terraform (platform services) or was created manually. Not affected by this fix.
• landscaping-assistant.app -- proxy_target: landscaping-assistant.tail5b443a.ts.net. Same pattern. Not affected.

The westside-ror case is unique because it has a separate westsidekingsandqueens overlay with a mismatched hostname. No blast radius beyond westside.

Decomposition Assessment

2-3 file changes across 2 repos (ingress.yaml in pal-e-deployments, possible kustomization.yaml update, Salt highstate verification on pal-e-platform). 5 acceptance criteria. Estimated agent work under 5 minutes. No decomposition needed.

Recommendation

No action needed. All previous NEEDS_REFINEMENT findings have been addressed. Scope is solid, traceability complete (story note and arch note both verified), file targets confirmed, multi-repo scope documented, dependencies clear. Ready for todo.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type -- Bug
• [x] Lineage -- Related to pal-e-platform#463
• [x] Repo -- ldraney/pal-e-platform
• [x] What Broke -- TLS handshake fails, clear error output
• [x] Repro Steps -- curl commands provided
• [x] Expected Behavior -- stated clearly
• [x] Environment -- DNS, ingress, and funnel hostname documented
• [x] Acceptance Criteria -- 3 criteria, testable
• [x] Related -- project and original issue referenced

All required bug template sections are present.

Traceability

• [x] story:WS-S9 label -- "As an admin, I want to track payment status per player so that I know who owes what" (found in project-westside-basketball user-stories section under Admin)
• [x] story note verified -- found in project-westside-basketball user-stories section
• [ ] arch:tailscale label -- arch note MISSING -- [SCOPE] No arch-tailscale note exists in pal-e-docs. Search returned zero results.
• [x] Forgejo issue -- ldraney/pal-e-platform#464, state: open

story:WS-S9 label accuracy: WS-S9 is about payment tracking. This bug is about the public domain's TLS cert for the whole westside site. The story label is a stretch -- this is infrastructure/networking, not payment tracking. A more accurate story would be WS-S1 (superadmin deploy via IaC) or no story (foundational infra bug). Not blocking, but worth noting.

File Targets

The issue does not specify explicit file targets (it is a bug report with symptoms). However, investigation reveals the relevant files:

• [x] salt/pillar/caddy.sls -- verified: PR #463 added the westside site entry with proxy_target: westside-basketball.tail5b443a.ts.net. This entry exists at HEAD.
• [x] salt/states/caddy/Caddyfile.j2 -- verified: template generates site blocks from pillar data, pattern is correct.
• [x] salt/states/caddy/init.sls -- verified: manages Caddyfile rendering and Caddy service reload.
• [ ] pal-e-deployments/overlays/westside-ror/prod/ -- ISSUE: NO ingress resource exists in the prod overlay. The k3s.tfvars.example comment says "kustomize overlay manages TWO Tailscale Funnel ingresses" but the prod overlay only has kustomization.yaml and deployment-patch.yaml -- zero ingress files. The dev overlay at overlays/westside-ror/dev/ingress.yaml has one funnel ingress, but prod does not.
• [ ] terraform/modules/networking/main.tf -- verified: this file manages all Tailscale funnels for platform services (grafana, forgejo, woodpecker, etc.) but has NO westside funnel. The westside-ror service has funnel = false in the services map, delegating to kustomize.

Repo Placement

ISSUE: The Forgejo issue is filed on ldraney/pal-e-platform, and the Caddy pillar fix is indeed there. However, the root cause spans TWO repos:

• ldraney/pal-e-platform -- Caddy pillar + Salt states (proxy config is correct)
• ldraney/pal-e-deployments -- Missing Tailscale funnel ingress in the prod kustomize overlay

The Caddy proxy targets westside-basketball.tail5b443a.ts.net:443 as the upstream, but no Tailscale funnel ingress serves that hostname. The fix likely needs a prod ingress resource in pal-e-deployments (following the dev overlay's pattern) AND possibly verifying the Caddy highstate was applied on the edge server. A single pal-e-platform issue may be sufficient if the scope documents both repos, but currently it does not mention pal-e-deployments at all.

Dependencies

• Board item #1613 (pal-e-services#148) -- Harbor pull creds bug. Also sprint:5, also type:bug. This bug prevents new pods from deploying (ImagePullBackOff). Even if the TLS/funnel fix lands, the westside-ror pod may be running stale code until #1613 is resolved. These two bugs are co-dependent blockers for sprint 4/5 auth changes going live.
• PR #463 (merged) -- Added the Caddy pillar entry. The pillar is correct but may not have been applied via Salt highstate on the edge server yet.
• Salt highstate -- Not a board item, but the Caddy config won't take effect until salt '*' state.highstate runs on the edge-proxy node.

Acceptance Criteria

The 3 criteria are clear and testable via curl commands. However:

• AC #1 ("loads with valid TLS cert") is verifiable: curl -sv https://westsidekingsandqueens.com 2>&1 | grep "SSL certificate verify ok"
• AC #2 ("response matches tailnet URL content") is verifiable: diff the response bodies
• AC #3 ("no regression in tailnet URL") is verifiable: curl https://westside-ror.tail5b443a.ts.net
• Missing AC: www redirect should be tested: curl -sI https://www.westsidekingsandqueens.com should return 301 to apex domain (Caddy pillar has www_redirect: true)

Blast Radius

Two other domains use the same Caddy edge-proxy pattern:

• palinks.app -- proxy_target: palinks.tail5b443a.ts.net
• landscaping-assistant.app -- proxy_target: landscaping-assistant.tail5b443a.ts.net

Both of these have funnel = true in the services map (Terraform manages their funnel ingress automatically). The westside-ror case is unique because funnel = false delegates to kustomize, and the kustomize overlay is incomplete. No blast radius beyond westside.

Decomposition Assessment

2 file targets across 2 repos (Caddy pillar verification in pal-e-platform, ingress addition in pal-e-deployments). 3 acceptance criteria. Estimated agent work under 5 minutes. No decomposition needed.

Root Cause Analysis (Reviewer Addition)

The issue body describes the symptom correctly but the root cause analysis is misleading. It says "Tailscale funnel not serving public domain cert" -- but the architecture does NOT use Tailscale funnel for public domain cert provisioning. The architecture is:

1. DNS A record points westsidekingsandqueens.com to Hetzner edge-proxy (178.156.129.142)
2. Caddy on edge-proxy terminates TLS via Let's Encrypt ACME
3. Caddy reverse-proxies to westside-basketball.tail5b443a.ts.net:443 via Tailscale mesh
4. That hostname requires a Tailscale funnel ingress in the k8s cluster

The failure chain: Caddy cannot reach the upstream because no Tailscale funnel ingress exists for hostname westside-basketball in the westside-ror namespace. The westsidekingsandqueens-funnel ingress mentioned in the issue appears to be manually created and serves the wrong hostname (westsidekingsandqueens.tail5b443a.ts.net instead of westside-basketball.tail5b443a.ts.net).

Recommendation

• [BODY] Update issue body to clarify root cause: the fix is adding a Tailscale funnel ingress to pal-e-deployments/overlays/westside-ror/prod/ (following the dev overlay pattern at overlays/westside-ror/dev/ingress.yaml), and verifying Salt highstate was applied on the edge-proxy for the Caddy config.
• [BODY] Add file targets section listing: (1) pal-e-deployments/overlays/westside-ror/prod/ingress.yaml (new file, funnel ingress), (2) pal-e-deployments/overlays/westside-ror/prod/kustomization.yaml (add ingress to resources), (3) verify Salt highstate on edge-proxy.
• [BODY] Add missing acceptance criterion: https://www.westsidekingsandqueens.com should 301 redirect to apex domain.
• [BODY] Document the pal-e-deployments repo involvement -- currently only pal-e-platform is mentioned.
• [SCOPE] Create architecture note arch-tailscale for the Tailscale networking component (funnels, ACLs, subnet router, edge proxy pattern).
• [LABEL] Consider changing story label from story:WS-S9 to story:WS-S1 (superadmin IaC/deploy) -- this is infra, not payment tracking.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- Standalone, discovered during paldocs sprint:1
• [x] Repo -- listed as ldraney/pal-e-platform
• [x] User Story -- present
• [x] Context -- good explanation of Bundler 2.x vs 4.x checksum mismatch
• [x] File Targets -- present (but WRONG, see below)
• [x] Feature Flag -- none (correct for infra)
• [x] Acceptance Criteria -- 4 items
• [x] Test Expectations -- present
• [x] Constraints -- present, good backward-compat note
• [x] Checklist -- present
• [x] Related -- present

Traceability

• [ ] story:base-images -- NOT found on project-pal-e-platform user-stories table. No matching story key exists. The story label is novel and has no backing user story entry. [SCOPE] Create user story entry for story:base-images on project-pal-e-platform user-stories section, OR reclassify under an existing story like story:superuser-deploy (since CI base images directly enable the deploy pipeline).
• [ ] arch:ci-cd -- no architecture note arch-ci-cd found in pal-e-docs. [SCOPE] Create architecture note arch-ci-cd for the CI/CD pipeline component, OR use a more specific label like arch:base-images with a corresponding note.
• [x] Forgejo issue -- https://forgejo.tail5b443a.ts.net/ldraney/pal-e-platform/issues/462, open

File Targets

• [ ] images/ruby-rails-build/Dockerfile -- ISSUE: path does NOT exist in pal-e-platform. The ruby-rails-build image is built from ldraney/base-images/Dockerfile (a separate repo). The pal-e-platform repo has an unrelated docker/ruby-arch/Dockerfile which builds a different image (pal-e/ruby-arch, Arch Linux based).

Actual file target: ldraney/base-images/Dockerfile -- this is the Dockerfile that produces library/ruby-rails-build:latest via the .woodpecker.yaml build-and-push-build step. Currently based on ruby:3.4.9-slim (Debian). Bundler is NOT explicitly pinned; it inherits whatever version ships with the Ruby Docker image.

Repo Placement

MISMATCH. The Forgejo issue is filed on ldraney/pal-e-platform but the actual Dockerfile to modify lives in ldraney/base-images. The issue should be moved to ldraney/base-images, or a new issue created there and this one closed with a cross-reference.

Dependencies

• No blocking items found on the board. The only in_progress item is Phase 7 (Block-Structured Content Model), which is unrelated.
• Downstream: 5+ Rails repos consume ruby-rails-build:latest -- paldocs, landscaping-assistant, palinks, westside-ror, rails-base, flightscanner, test-ruby. All must be tested after the image update.
• The issue correctly notes paldocs#72 and paldocs#73 as the triggering context.

Acceptance Criteria

4 ACs, mostly verifiable:

• AC1 (Bundler >= 4.0 in Dockerfile) -- verifiable by reading the Dockerfile, but the approach needs thought: the current Dockerfile does NOT pin bundler at all. The fix may be adding RUN gem install bundler -v '>=4.0' or switching to a Ruby image that ships Bundler 4.x natively.
• AC2 (paldocs CI passes) -- verifiable via Woodpecker pipeline.
• AC3 (Harbor image tagged) -- verifiable via Harbor registry check.
• AC4 (paldocs lockfile restored) -- verifiable, but this is work in a DIFFERENT repo (paldocs), not base-images. Should be a separate follow-up ticket or noted as cross-repo work.

Missing: no AC for backward-compatibility verification with other Rails repos, despite Constraints section calling this out.

Blast Radius

HIGH. This is a shared base image consumed by at least 5 Rails applications (paldocs, landscaping-assistant, palinks, westside-ror, rails-base, flightscanner, test-ruby). Pushing a broken image to :latest would break ALL Rails CI pipelines simultaneously. The Constraints section correctly flags this but the ACs do not include verification steps for non-paldocs repos.

Decomposition Assessment

File count: 1 file in 1 repo (base-images/Dockerfile). ACs: 4 (but AC4 is cross-repo). Estimated agent time: under 5 minutes for the Dockerfile change itself. However, cross-repo validation (AC2, AC4) adds complexity. No decomposition needed if scoped to just the Dockerfile change, but the cross-repo ACs should be split out or documented as manual follow-up.

Recommendation

• [BODY] Fix Repo field: ldraney/pal-e-platform to ldraney/base-images
• [BODY] Fix File Targets: images/ruby-rails-build/Dockerfile to Dockerfile (root of base-images repo). Note that bundler is currently inherited from the Ruby base image, not explicitly installed.
• [BODY] AC4 (paldocs lockfile restore) is cross-repo work -- either remove it from this ticket's ACs and create a follow-up paldocs issue, or note it as manual post-merge step.
• [BODY] Add AC: "All Rails repos using ruby-rails-build:latest pass CI after image update" (backward-compat verification).
• [SCOPE] Create user story entry story:base-images on project-pal-e-platform user-stories section, OR relabel to story:superuser-deploy.
• [SCOPE] Create architecture note arch-ci-cd, OR relabel to a more specific component like arch:base-images with a backing note.
• [LABEL] Move or re-file the Forgejo issue from ldraney/pal-e-platform to ldraney/base-images.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- Standalone
• [x] Repo -- ldraney/claude-custom
• [x] User Story -- present, well-formed
• [x] Context -- present, accurate repo size claims verified (43 hooks, ~28 skills, 3 agents, 8 MCP servers)
• [x] File Targets -- 8 files listed (7 new docs + README.md rewrite)
• [x] Feature Flag -- none (appropriate for docs-only work)
• [x] Acceptance Criteria -- 5 criteria
• [x] Test Expectations -- 3 items
• [x] Constraints -- present
• [x] Checklist -- present
• [x] Related -- present

Traceability

• [x] story:operational-reference label -- present on board item
• [ ] story note MISSING -- [SCOPE] No project page exists for claude-custom. Cannot verify user story entry. Create project page project-claude-config with user-stories section, or link to an existing project page.
• [x] arch:docs label -- present on board item
• [ ] arch note MISSING -- [SCOPE] No architecture note arch-docs found in pal-e-docs. Create architecture note arch-docs for the docs component.
• [x] Forgejo issue -- https://forgejo.tail5b443a.ts.net/ldraney/claude-custom/issues/264, state: open

File Targets

• [x] docs/filetree.md -- NEW file. docs/ directory exists but is empty. Confirmed no conflict.
• [x] docs/hooks.md -- NEW file. No conflict.
• [x] docs/agents.md -- NEW file. No conflict.
• [x] docs/skills.md -- NEW file. No conflict.
• [x] docs/settings.md -- NEW file. No conflict.
• [x] docs/mcp-servers.md -- NEW file. No conflict.
• [x] docs/enforcement.md -- NEW file. No conflict.
• [x] README.md -- EXISTS (151 lines). Will be rewritten as TOC. CLAUDE.md is symlink to README.md (confirmed: CLAUDE.md -> README.md).

Note: README.md currently describes the agent system with an outdated agents/nvim-minion/ directory structure. The actual agents are agents/dev.md, agents/overseer.md, agents/qa.md. The rewrite will fix this stale documentation.

Repo Placement

OK. Issue is filed on ldraney/claude-custom, and all file targets are within that repo. No cross-repo work.

Dependencies

No other items found on board-claude-custom. This is the sole item in backlog. No blocking dependencies. The issue references enforcement-architecture and sop-claude-config-development pal-e-docs notes as related context -- these are read-only references, not dependencies.

Acceptance Criteria

All 5 AC are verifiable by an agent:

• AC1: ls docs/*.md | wc -l should output 7 -- verifiable
• AC2: README.md contains TOC with links -- verifiable via grep
• AC3: ls -la CLAUDE.md shows symlink -- verifiable
• AC4: "Each doc is accurate against current repo state" -- verifiable by cross-referencing docs content against actual files
• AC5: "A new contributor can answer 'which file do I edit...'" -- subjective but reasonable

Test expectations are concrete shell commands -- all verifiable.

Blast Radius

Low risk. This is docs-only work. The README.md rewrite is the only change to an existing file. The CLAUDE.md symlink must be preserved (confirmed as symlink). No hooks, settings, or agent configs are modified. The "Files the agent should NOT touch" section correctly guards against scope creep.

One concern: README.md is symlinked to CLAUDE.md, which is symlinked to ~/.claude/CLAUDE.md. Rewriting README.md as a pure TOC will change the content injected into every Claude Code session via CLAUDE.md. The issue does not acknowledge this side effect. However, the user's global ~/.claude/CLAUDE.md is a separate file (not part of this repo), so the per-project CLAUDE.md change is contained to this repo only.

Decomposition Assessment

8 file targets (7 new + 1 rewrite), all in 1 repo. 5 AC + 3 test expectations = 8 total criteria. This is borderline on the 5-minute rule:

• File targets: 8 (above 3-file threshold but all in 1 repo)
• AC count: 5 (at the threshold)
• Estimated agent work: ~8-12 minutes (each doc requires reading current repo state and writing accurate reference content)

However, the work is inherently serial -- each doc is independent content creation within a single repo. Decomposition into sub-tickets would add overhead without meaningful parallelism benefit. The 200-line constraint per doc keeps each file manageable. No decomposition needed, but the 5-point estimate is appropriate for the volume.

Recommendation

• [SCOPE] Create project page project-claude-config with a user-stories section containing the "operational-reference" story, or assign this ticket to an existing project page.
• [SCOPE] Create architecture note arch-docs for the docs component describing the docs/ directory structure, relationship to README.md/CLAUDE.md, and content governance.
• [BODY] Add a note in the Context section acknowledging that rewriting README.md will change the CLAUDE.md content injected into Claude Code sessions for this repo, since CLAUDE.md is a symlink to README.md.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- Standalone
• [x] Repo -- ldraney/pal-enterprises
• [x] User Story -- present and well-formed
• [x] Context -- present, references convention-client-project-structure
• [x] File Targets -- present but inaccurate (see below)
• [x] Acceptance Criteria -- present, 6 criteria
• [x] Test Expectations -- present
• [x] Constraints -- present but contains conflicting guidance
• [x] Checklist -- present
• [x] Related -- present

Traceability

• [x] story:sso-gateway label -- present on board item
• [ ] story note MISSING -- [SCOPE] No project-pal-enterprises project page exists in pal-e-docs. Create project page with user-stories section containing sso-gateway story entry.
• [x] arch:rails-app label -- present on board item
• [ ] arch note MISSING -- [SCOPE] No arch-rails-app architecture note exists in pal-e-docs. Create architecture note arch-rails-app.
• [x] Forgejo issue -- ldraney/pal-enterprises#9, state: open
• [ ] convention-client-project-structure MISSING -- [SCOPE] Issue lineage references this convention but it does not exist in pal-e-docs. Create convention note or update lineage.

File Targets

• [ ] app/controllers/admin_controller.rb -- ISSUE: File does NOT exist. Issue claims it "already exists in the scaffold" but the controllers directory only contains: application_controller.rb, concerns/, contacts_controller.rb, dashboard_controller.rb, pages_controller.rb, sessions_controller.rb. Should say "create" not "modify."
• [ ] app/views/admin/ -- ISSUE: Directory does NOT exist. Only these view dirs exist: contacts, dashboard, layouts, pages, pwa, sessions. Should say "create" not "modify."
• [x] config/routes.rb -- verified: exists, currently has no admin routes. Modification is correct.
• [x] app/controllers/dashboard_controller.rb -- verified: exists, correctly listed under "do not touch."

Repo Placement

OK. Issue is filed on ldraney/pal-enterprises and the work targets that repo. However, the "promote lead to client" AC requires Keycloak admin API calls, which may involve configuration in pal-e-deployments (Keycloak realm config). This cross-repo dependency is not documented.

Dependencies

• Database schema gap (undocumented) -- The Lead model currently has only: name, email, message, timestamps. There is no status field (for pipeline tracking: new/pending/promoted), no business_name field, no logo field. The AC references "business name, name, logo, email" but the model lacks business_name and logo columns. A migration is required.
• No Client model (undocumented) -- The AC says "view all active clients with status" but there is no Client model. Either Lead needs a status enum for promotion, or a separate Client model/table is needed. This architectural decision is not scoped.
• No role-checking infrastructure (undocumented) -- ApplicationController has require_login but no require_owner or role-checking method. The session stores roles from Keycloak but nothing consumes them. A require_owner before_action needs to be built.
• Keycloak admin API integration (undocumented) -- AC: "lead promotion creates Keycloak user." No Keycloak admin API client exists in the codebase. This requires: Keycloak admin credentials (env vars), an HTTP client for the admin REST API, and realm-level user creation logic. This is a significant new capability.
• Board item #1188 (Remove Tailwind) -- in backlog. Not a blocker, but Constraints section says "Follow existing Rails patterns (Hotwire/Turbo, Tailwind)" which will conflict if #1188 lands first.
• Board item #1181 (Phase 4: Dashboard with tool grid) -- in backlog. The admin panel is separate from the dashboard, but both need auth. No conflict, but should be sequenced.

Acceptance Criteria

6 acceptance criteria. Testability assessment:

• "/admin shows leads pipeline" -- testable via integration test, but what does "pipeline" mean? Need to define states (new/pending review/promoted).
• "Owner can view lead details (business name, name, logo, email)" -- Lead model lacks business_name and logo fields. Not implementable without migration.
• "Owner can promote a lead to client (triggers Keycloak user creation)" -- requires Keycloak admin API integration that does not exist. Not implementable without new infrastructure.
• "Owner can view all active clients with status" -- No Client model exists. Not implementable without model creation.
• "Only owner role can access /admin -- clients get 403" -- testable but requires new role-checking method.
• "Per-client links to their -docs and -admin surfaces visible" -- requires knowing the URL pattern for client surfaces. How does the system know a client's surface URLs? Undocumented.

Blast Radius

Low blast radius to existing code -- this is additive (new controller, new views, new routes). However:

• The Lead model is shared with ContactsController. Adding status/fields to Lead affects the contact form flow.
• ApplicationController changes (adding require_owner) are cross-cutting and will be used by other controllers later.
• Keycloak admin API credentials will need to be added to deployment configs (pal-e-deployments).

Decomposition Assessment

NEEDS DECOMPOSITION -- This ticket violates the 5-minute rule on multiple counts:

• 6 acceptance criteria (threshold: 5)
• Requires new database migration (Lead fields + possibly Client model)
• Requires new infrastructure (Keycloak admin API client)
• Requires new auth infrastructure (role-checking)
• Estimated agent work: 15-20 minutes across 4 distinct concerns

Suggested decomposition:

1. Sub-ticket 1: Lead model expansion + admin scaffold -- Add status/business_name/logo fields to Lead, create AdminController with require_owner, add /admin route, basic lead list view.
2. Sub-ticket 2: Role-based access control -- Add require_owner to ApplicationController, owner role check against Keycloak roles in session, 403 for non-owners.
3. Sub-ticket 3: Lead detail views + pipeline UI -- Lead show/edit views, pipeline state management (new/pending/promoted).
4. Sub-ticket 4: Keycloak user creation on promote -- Keycloak admin API client, promote action that creates realm user, Client model or status update.

Recommendation

• [BODY] Fix file targets: admin_controller.rb and app/views/admin/ do not exist -- change "modify" to "create."
• [BODY] Add missing Lead fields to File Targets: migration needed for business_name, logo, status columns on leads table.
• [BODY] Document Keycloak admin API dependency: add to Context and Constraints that a new Keycloak admin HTTP client is required, plus KEYCLOAK_ADMIN_USER/KEYCLOAK_ADMIN_PASSWORD env vars.
• [BODY] Remove or qualify Tailwind constraint: board item #1188 plans to remove Tailwind. Change constraint to "Follow existing Rails patterns (Hotwire/Turbo)" or note Tailwind may be replaced.
• [BODY] Define "per-client links" data source: how does the system know a client's -docs and -admin URLs? This needs to be specified (convention-based from business name? stored in Client model?).
• [SCOPE] Create project-pal-enterprises project page in pal-e-docs with user-stories section.
• [SCOPE] Create arch-rails-app architecture note in pal-e-docs.
• [SCOPE] Create or verify convention-client-project-structure in pal-e-docs (referenced in issue lineage but does not exist).
• [DECOMPOSE] 6 AC across 4 concerns (model, auth, views, Keycloak API). Route to skill-decompose-ticket for sub-board creation.