pal-e-docs

Goal: Add semantic/vector search to pal-e-docs using pgvector. Enable AI agents to find conceptually related notes, not just keyword matches.

Owner: Dev agent

Repo: pal-e-platform, pal-e-docs, pal-e-docs-sdk, pal-e-docs-mcp

Depends on: Phase 5 (full-text search) — COMPLETED, Phase 7 (block content model) — COMPLETED, Phase 7f (clean data) — COMPLETED

Why

Full-text search finds keyword matches. Vector search finds conceptual matches. Example: searching "how do we handle credentials" should return the secrets management SOP even if it never uses the word "credentials."

Key Decisions (see decision-phase6-vector-search-architecture)

Decision	Choice
Embedding model	Qwen3-Embedding-4B via Ollama (GPU-accelerated on GTX 1070)
Dimensions	768 (configurable, can increase later)
What to embed	Per-block (paragraph, list, heading, table, code. Skip mermaid.)
Pipeline	Async via PostgreSQL LISTEN/NOTIFY (no Redis/Celery, event-driven, sub-30s)
Ollama	Platform service (own namespace, like CNPG)
Worker	Separate k8s Deployment (owns GPU resource request, independent failure domain)
Instruction prefixes	Asymmetric — different prefixes for document indexing vs query embedding

Sub-Phase Status

#	Sub-Phase	Repo	Status
6a	Deploy Ollama as platform service	pal-e-platform	COMPLETED
6b	pgvector extension + schema migration	pal-e-docs	COMPLETED
6b-1	Fix extension ownership (migration-only)	pal-e-docs	COMPLETED (PR #140, Issue #126)
6c	Async embedding pipeline + backfill	pal-e-docs	COMPLETED (PR #130, Issue #129)
6c-1	Enforce Closes #N + strengthen post-merge reminder	claude-custom	COMPLETED (PR #74, Issue #73)
6c-2	QA nits — dead code, N+1 query, dep hygiene, k8s hardening	pal-e-docs	COMPLETED (PR #136, Issue #135)
6d	Semantic search API + SDK + MCP tool	pal-e-docs, sdk, mcp	COMPLETED (API #138, SDK #20, MCP #30)
6d-1	SDK integration tests	pal-e-docs-sdk	COMPLETED (PR #23, Issue #22)
6e	Hybrid ranking (tsvector + vector)	pal-e-docs	COMPLETED (PR #141, Issue #139)

Sub-Phase Details

6a: Deploy Ollama as platform service

Repo: pal-e-platform (Terraform + Helm)

Status: COMPLETED — PR #25 (initial deploy), PR #27 (runtimeClassName fix). Issue #24, #26.

• Create ollama namespace
• Deploy Ollama via Helm chart with GPU resource request (nvidia.com/gpu: 1)
• Pull qwen3-embedding:4b model on startup
• ClusterIP service on port 11434 for internal access
• Verify GPU acceleration is active (ollama ps shows GPU layers)

Verification (2026-03-08): Node reports nvidia.com/gpu: 1 capacity. Ollama pod Running. Model qwen3-embedding:4b (4.0B, Q4_K_M) fully loaded in VRAM (3.5GB). Embedding API returns 768-dim vectors.

6b: pgvector extension + schema migration

Repo: pal-e-docs

Status: COMPLETED — PR #122. Issue #121.

• Enable pgvector extension via CREATE EXTENSION IF NOT EXISTS vector
• Alembic migration l2g3h4i5j6k7: add embedding vector(768) column to blocks table
• Add embedding_status varchar(20) column (default 'pending')
• Create HNSW index on embedding column (vector_cosine_ops)
• Postgres trigger: on block INSERT or UPDATE of content or block_type, sets embedding_status = 'pending' and NOTIFY embedding_queue. Skips mermaid blocks (sets 'skipped').
• Added pgvector>=0.3 dependency

6b-1: Fix extension ownership (platform-provides pattern)

Repo: pal-e-docs (migration fix), deployments (CNPG CRD)

Status: NOT STARTED — Issue #126.

Problem: The 6b migration includes CREATE EXTENSION IF NOT EXISTS vector, which requires superuser. The Alembic migration runs as the paledocs app user (not superuser), causing CrashLoopBackOff on deploy. Fixed manually via kubectl exec as postgres superuser, but this breaks fresh deployments.

Fix: Follow the platform-provides/app-consumes pattern:

• Remove CREATE EXTENSION from Alembic migration, replace with existence check + informative error
• Add extension provisioning to CNPG Cluster CRD in deployments repo (bootstrap.initdb.postInitSQL)
• Remove DROP EXTENSION from downgrade

6c: Async embedding pipeline + backfill

Repo: pal-e-docs (new module + k8s Deployment). Same Docker image, different entrypoint.

• Embedding worker process: src/pal_e_docs/embedding_worker.py — standalone Python process (not FastAPI). LISTEN embedding_queue as primary trigger, periodic poll fallback (every 60s) for missed notifications during restarts.
• Block text extraction: block_type-aware content JSON → plain text. Paragraph: strip HTML. List: join items. Heading: "{note_title} > {heading_text}" (parent context join). Table: flatten headers + rows. Code: raw text. Mermaid: already skipped by trigger.
• Ollama integration: POST http://ollama.ollama.svc.cluster.local:11434/api/embed with model qwen3-embedding:4b. Document prefix: "Represent this platform knowledge base section for retrieval: {block_text}". Store 768-dim vector in blocks.embedding.
• State machine: embedding_status transitions: pending → processing → completed | error. The processing state prevents duplicate work on pod restart. Existing skipped state (mermaid) unchanged.
• Reliability: retry with exponential backoff on Ollama transient errors. Batch processing (10 blocks/cycle live, higher for backfill). Graceful SIGTERM handling — finish current batch, don't leave blocks in processing state.
• Observability: Prometheus metrics — embedding_total, embedding_errors_total, embedding_duration_seconds, embedding_queue_depth. Health endpoint (/healthz) for k8s liveness/readiness probes. Structured logging.
• k8s Deployment: k8s/embedding-worker.yaml — same image as API pod, entrypoint python -m pal_e_docs.embedding_worker. No GPU resource request (worker calls Ollama over HTTP). Minimal resources (10m CPU, 64Mi request, 256Mi limit). Add to kustomization.yaml.
• Config: add ollama_url to Settings (PALDOCS_OLLAMA_URL, default: in-cluster service URL).
• Dependencies: add httpx to main deps (Ollama HTTP client). Use raw psycopg2 connection for LISTEN (SQLAlchemy doesn't expose it).
• Backfill: --backfill flag — one-time run to embed all ~5K pending blocks. Rate-limited batches, progress logging. Can run as kubectl exec into the worker pod.

6d: Semantic search API + SDK + MCP tool

Repos: pal-e-docs (API), pal-e-docs-sdk (client), pal-e-docs-mcp (tool)

• GET /notes/semantic-search?q=...&limit=10 — query prefix applied, cosine similarity search
• Returns: matching blocks with note context, similarity score, block content snippet
• SDK: client.semantic_search(query, limit)
• MCP: semantic_search tool wrapping SDK

6e: Hybrid ranking (tsvector + vector)

Repo: pal-e-docs

• Combine full-text search score (tsvector ts_rank) with vector similarity (cosine distance)
• Weighted ranking: configurable alpha between keyword relevance and semantic similarity
• GET /notes/search?q=...&mode=hybrid — unified search endpoint
• MCP: update search_notes tool to support mode parameter

Dependency Chain

6a (Ollama) → 6b (pgvector schema) → 6b-1 (extension fix) → 6c (pipeline + backfill) → 6d (API + MCP) → 6e (hybrid)

6a and 6b can run in parallel (different repos). 6b-1 doesn't block 6c (extension already installed). 6c depends on both 6a and 6b. 6d depends on 6c. 6e depends on 6d.

Related

• decision-phase6-vector-search-architecture — full decision record with model research and hardware analysis
• phase-postgres-7-block-content — prerequisite phase (COMPLETED)
• phase-postgres-7f-doc-cleanup-sop — prerequisite phase (COMPLETED, clean data)
• concept-phase5-self-hosted-rag — RAG architecture vision
• concept-phase5-database-side-intelligence — database-side intelligence pattern
• benchmark-phase5-knowledge-baseline — baseline measurements

Goal: Zero frontend tests → Playwright E2E smoke tests covering all major features. Backend has 513 tests; frontend needs parity.

Owner: Dev-Frontend agent

Repo: forgejo_admin/pal-e-app

Depends on: None — can start immediately. Auth tests (F5) can be added later.

Scope

• Install Playwright + @playwright/test as dev dependencies
• Create playwright.config.ts with dark theme, Chromium, base URL pointing to local dev server
• Add test and test:e2e scripts to package.json
• Smoke tests covering all shipped features:
  • T1: Home page loads with nav (Dashboard, Search, Notes, Projects, Boards, Tags, Repos)
  • T2: Search — navigate to /search, type query, see results with type badges
  • T3: Dashboard — /dashboard loads with board rollup, per-project cards
  • T4: Board filtering — type pills filter items, hide-done toggle works
  • T5: Quick-jot — FAB opens modal, fill title, create note, verify toast
  • T6: Note detail — navigate to /notes/{slug}, see blocks rendered, TOC sidebar
  • T7: Board drag-drop — move item between columns (desktop)
• Add Playwright test step to .woodpecker.yaml (after build, before push)
• CI runs tests against built app (not dev server) for production fidelity

Deliverables

• TBD — filled after completion

Related

• plan-pal-e-docs — parent plan
• phase-pal-e-docs-ci-infra — Phase 7 (CI hardening)

Goal: Add Keycloak OIDC authentication to pal-e-app. Write operations (Quick-Jot) require login. Read operations remain public. Reuse the proven westside-app Auth.js pattern.

Owner: Dev-Frontend agent

Repo: forgejo_admin/pal-e-app

Depends on: None — Keycloak is deployed, OIDC flow proven in westside-app (PR #9).

Scope

• Add Auth.js (SvelteKit) with Keycloak OIDC provider — reuse pattern from westside-app/src/auth.ts
• Create pal-e-app client in Keycloak realm (or reuse existing client)
• SOPS-encrypt client secret, deploy to pal-e-app namespace k8s secret
• Protect write routes: POST /api/notes requires authenticated session
• Quick-Jot FAB: show only when authenticated, prompt login when not
• Add sign-in/sign-out routes (/signin, /signout)
• Nav bar: show user name + sign out when authenticated, sign in button when not
• Read routes (/notes, /boards, /search, /dashboard) remain public — no auth required
• Session cookie: HttpOnly, Secure, SameSite=Lax

Deliverables

• TBD — filled after completion

Related

• plan-pal-e-docs — parent plan
• phase-pal-e-docs-quick-jot — Phase F3 (write capability that needs auth)
• phase-pal-e-docs-private-notes — Phase F6 (private notes depend on auth)

Goal: The board IS the DORA dashboard — this phase makes the metrics visible. Cross-project rollup showing what needs attention, deployment frequency, and lead time estimates.

Owner: Dev-Frontend agent

Repo: forgejo_admin/pal-e-app

Depends on: phase-pal-e-docs-board-filtering — reuses board filtering concepts and summary card patterns.

Scope

• New route: /dashboard (or enhance / landing page)
• Cross-project board rollup: items in each column across ALL boards
• Items needing attention: needs_approval items, stuck in_progress items
• Deployment frequency: done items per day/week (from board item timestamps)
• Lead time estimates: time from next_up → done (from board item created_at/updated_at)
• Per-project cards with board summary + link to full board
• Links to relevant boards for drill-down

Deliverables

• TBD — filled after completion

Related

• plan-pal-e-docs — parent plan
• phase-pal-e-docs-board-filtering — Phase F2 (reuses summary card patterns)
• project-dora-thesis — DORA = Observability + Kanban

Goal: First write capability in the frontend — capture thoughts fast via a quick-jot modal, triage later. The inbox concept.

Owner: Dev-Frontend agent

Repo: forgejo_admin/pal-e-app

Depends on: None — backend POST /notes already built and tested.

Scope

• Floating action button (bottom-right) or keyboard shortcut to open quick-jot modal
• Modal: title (required), optional body (single paragraph), optional project dropdown, optional note_type (defaults to todo)
• Creates note via SvelteKit API proxy route → POST /notes on backend
• Auto-generates slug from title (lowercase, hyphenated)
• Lands on project board as backlog item if project has a board (via board sync)
• Success feedback: toast/notification with link to created note
• New API proxy route: POST /api/notes in SvelteKit
• Minimal — no rich editor, just title + optional body text

Deliverables

• TBD — filled after completion

Related

• plan-pal-e-docs — parent plan
• phase-pal-e-docs-frontend-search — Phase F1 (search helps find created notes)
• phase-pal-e-docs-board-filtering — Phase F2 (board filtering helps triage quick-jots)

Goal: Add filtering and status overview to board pages so Lucas can filter 10-20+ items by type/label and see status at a glance.

Owner: Dev-Frontend agent

Repo: forgejo_admin/pal-e-app

Depends on: None — backend already supports item_type and column filtering on GET /boards/{slug}/items.

Scope

• Filter pills on board page: by item_type (phase, issue, todo, plan) using typeColor() for pill colors
• Active filter = filled pill, inactive = outline pill. Multiple filters AND together
• Column item counts in headers (enhance existing count badges)
• Collapsible columns option: click header to toggle, collapsed shows header + count only
• "Hide done" toggle — most common filter action
• Board status summary card at top: items by column, items by type, horizontal bar distribution
• Project page enhancement: show board mini-view on project detail page
• Client-side filtering (all items already loaded for drag-drop)
• URL-persistent filter state (?type=phase&hide_done=true)

Deliverables

• TBD — filled after completion

Related

• plan-pal-e-docs — parent plan
• phase-pal-e-docs-sprint-board-component — Phase 3 that built the kanban board
• phase-pal-e-docs-frontend-search — Phase F1 (parallel frontend work)

Goal: Expose the backend's full-text, semantic, and hybrid search through the pal-e-app frontend — the #1 feature that transforms browsing into operating.

Owner: Dev-Frontend agent

Repo: forgejo_admin/pal-e-app

Depends on: None — backend search APIs already built and tested.

Scope

• New route: /search with +page.server.ts calling GET /notes/search?q=...&mode=keyword|semantic|hybrid
• Display ranked results with headline snippets, note_type badges (using existing typeColor()), project tags
• URL-persistent query params (/search?q=deploy+recovery&mode=hybrid)
• Toggle: keyword vs semantic vs hybrid search mode
• Search input in nav bar (+layout.svelte) that navigates to /search on submit
• Keyboard shortcut: / or Cmd+K to focus search
• Add searchNotes() function to src/lib/api.ts
• Loading state for semantic search (Ollama embedding latency)
• Empty state with search tips

Deliverables

• TBD — filled after completion

Related

• plan-pal-e-docs — parent plan
• phase-pal-e-docs-activate-semantic-search — Phase 5a that built the backend search
• phase-pal-e-docs-board-filtering — Phase F2 (parallel frontend work)

Goal: Address 5 actionable QA nits from PR #130 review to bring the embedding worker to production quality.

Owner: Dev agent

Repo: forgejo_admin/pal-e-docs

Depends on: Phase 6c (PR #130 must merge first)

Problem

QA approved PR #130 with 7 nits. 2 are no-ops (hardcoded image tag is inherited pattern; health server binding 0.0.0.0 is standard k8s). 5 are actionable:

Fix

• Nit 1: Dead code. EMBEDDABLE_TYPES constant defined at line 52 but never referenced. Either use it in the block filtering logic (replacing inline checks) or remove it. Prefer using it — it makes the filtering explicit and testable.
• Nit 2: Redundant set_isolation_level. The reconnection path (line 523) calls conn.set_isolation_level() but _connect() already sets it. Remove the duplicate call in the reconnect path.
• Nit 3: N+1 query for note titles. _fetch_pending_blocks does a per-block query to get the parent note title for heading context. At 5K blocks during backfill, this is 5K extra queries. Fix: batch the title lookup with a JOIN or a single query that fetches all needed note titles upfront.
• Nit 4: Duplicate httpx dependency. httpx appears in both main deps (line 25) and dev deps (line 32) in pyproject.toml. Remove from dev deps — it's now a production dependency.
• Nit 6: No terminationGracePeriodSeconds. The worker handles SIGTERM gracefully but k8s defaults to 30s before SIGKILL. Add explicit terminationGracePeriodSeconds: 60 to give the worker time to finish a batch and reset processing blocks to pending.

Related

• phase-postgres-6-vector-search — parent phase
• phase-postgres-6c1-autoclose-enforcement — sibling subphase (also discovered during 6c)

Goal: Replace the AI-generated aesthetic with a distinctive, professional design system that prioritizes the "what are my latest projects / what changed recently" user story. Kill the AI slop.

Owner: Dev agent (code), Betty Sue (design direction + QA coordination)

Repo: forgejo_admin/pal-e-app

Depends on: F5 (auth), F6 (private notes), F8 (editing), F9 (board CRUD) — all COMPLETED

Context

The current pal-e-app aesthetic was built fast by dev agents and hits every AI slop anti-pattern: cyan-on-dark, pink neon accents on near-black, identical card grids, system fonts, centered everything, no design token system. The color palette (#e94560 accent, #0a0a14 background, #55efc4/#00cec9 type badges) is the textbook AI color palette warned against by the frontend-design guidelines.

The home page shows all 10 projects alphabetically — it doesn't answer the primary user question: "What are my latest projects? What changed? What needs attention?"

Current technical state: Tailwind 4.1, zero CSS custom properties, all colors hardcoded as arbitrary Tailwind values (bg-[#0e0e18]), no font imports, no type scale.

Design Direction

Aesthetic: Editorial / Command Center. Not a generic SaaS dashboard. Not a dark-mode dev tool. A well-typeset intelligence briefing — clean, scannable, information-dense but not cluttered. Every pixel earns its place.

• Light mode primary (dark mode secondary) — dark mode is lazy; light mode forces real design decisions
• Real typography — distinctive heading font + clean body font. Not Inter, not Roboto, not system defaults.
• Warm neutrals — stone/slate/warm grays, not blue-tinted near-black
• One accent color — not a rainbow of type badges. Typography-driven hierarchy.
• Activity-first home page — "Recently updated," "In progress," "Needs attention" — not alphabetical dumps
• Left-aligned, asymmetric layout — break the centered-everything pattern
• Progressive disclosure — the home page is a briefing, not a directory

Scope

F11a: Design Token System + Color Palette (COMPLETED — PR #35)

• Create CSS custom properties in app.css for all design tokens (colors, spacing, typography, radii)
• Replace ALL hardcoded hex values (bg-[#0e0e18]) with token references
• Choose a professional color palette — warm neutrals, one strong accent
• Support light mode (primary) and dark mode (secondary) via prefers-color-scheme or toggle
• Tint neutrals toward brand hue for cohesion
• Note type colors: simplify from 16 distinct colors to a restrained system (3-4 hues max with shade variations)

F11b: Typography + Font Loading (COMPLETED — PR #35)

• Select and import distinctive fonts: display/heading + body pair
• Implement modular type scale with clamp() for fluid sizing
• Font loading strategy: font-display: swap, preload critical fonts
• Vary weights and sizes to create clear visual hierarchy without relying on color

F11c: Home Page Redesign — "What Are My Latest Projects?" (COMPLETED — PR #37, Issue #36)

• Activity-first layout: recently updated notes/projects at top
• In-progress board items section — what's actively being worked on across all projects
• Project cards with last-updated timestamps and activity indicators
• Board summary with progress bars (backlog/in-progress/done ratios)
• Kill the alphabetical project dump and full tag wall
• Prototype approved in html-playground/6-pal-e-home before port

F11d: Navigation Rethink

• Streamline nav: Primary (Home/Activity, Projects, Search) vs Secondary (Notes, Tags, Repos)
• Consider sidebar navigation vs top bar
• Mobile-responsive hamburger menu
• Keyboard shortcuts (existing / for search is good — extend)
• Breadcrumb improvements for note navigation
• Gamification elements: progress indicators on project links, notification badges

F11e: Search + Discovery UX

• URL-driven search (?q= param should work on notes page)
• Search results with better context (snippet, project, type, date)
• Filter persistence across navigation
• Consider semantic search toggle (backend already supports it)

F11f: Private Notes + Auth UX Polish

• Lock icon visibility audit — current h-3 w-3 text-gray-600 is too subtle on dark backgrounds
• Signin page design — not Auth.js default
• Signout confirmation or redirect behavior
• Role display in nav (not just username)

F11g: Component Library Polish

• Cards: break the identical grid pattern. Vary sizes by importance/type.
• Badges: typography-driven, not rainbow colored
• Buttons: clear primary/secondary/ghost hierarchy
• Tables: readable in light mode
• Code blocks: proper syntax highlighting theme
• Empty states: teach the interface, not just "nothing here"

Investigation Required

• Does the pal-e-docs API support ?sort=updated_at or similar for activity-first queries? — YES, default sort is updated_at DESC, limit/offset params added in PR #181
• Can we add updated_at to the notes list response for "recently updated" sorting? — YES, already in NoteSummary schema
• What data does the DORA dashboard already expose that could feed gamification?
• Playground-first approach: should design experiments happen in html-playground before pal-e-app? — YES, SOP created: sop-frontend-experiment

Acceptance Criteria

• Zero hardcoded hex values in component code — all via CSS custom properties
• Home page answers "what changed recently?" within 2 seconds of loading
• Passes the AI Slop Test: if someone saw it, they wouldn't immediately say "AI made this"
• Lock icons visible and tested for private notes
• Search works via URL params
• Light mode looks professional; dark mode looks intentional (not the default)
• Lighthouse accessibility score >= 90

QA Nits (deferred from PR #37)

• Negative relativeTime handling for future dates
• Implicit boardProgress return type — add explicit TS type
• Asymmetric in-progress test assertion

Related

• plan-pal-e-docs — parent plan
• phase-pal-e-docs-validation-hardening — F10 (predecessor — design audit started there)
• phase-pal-e-docs-frontend-auth — F5 (auth foundation)
• phase-pal-e-docs-private-notes — F6 (private notes foundation)
• convention-frontend-css — CSS custom property rules
• sop-frontend-experiment — prototype-first workflow

Phase 4: Knowledge Tiering — list_notes Default Exclusion

Goal: Make list_notes stop returning completed/historical notes by default. Cold exclusion via status-based filtering.

Owner: Dev agent

Repo: forgejo_admin/pal-e-docs, forgejo_admin/pal-e-docs-sdk, forgejo_admin/pal-e-docs-mcp

Depends on: Phase 2 (milestone note type — completed)

Scope

Tiering Rules (status-based, first pass)

Tier	Rule	Default in list_notes
Hot/Warm	Notes with status NOT in cold set, or NULL status	Included
Cold	Status in {completed, done, deprecated, deferred, archived}	Excluded (include_cold=true to opt in)

Edge Cases

• Explicit status=completed param bypasses cold exclusion (caller clearly wants cold notes)
• NULL status → not cold (included by default)
• Search endpoints (semantic_search, search_notes) unaffected

Deliverables

Backend (COMPLETED)

• PR #191 on pal-e-docs — merged 2026-03-17
• COLD_STATUSES frozenset in routes/notes.py
• include_cold Query param on GET /notes (default false)
• Smart override: explicit status= bypasses cold filter
• NULL status handled via or_ clause
• 6 new tests, 638 total passing
• Forgejo issue #190 (closed)

SDK (COMPLETED)

• PR #33 on pal-e-docs-sdk — merged 2026-03-17
• include_cold: bool = False param on list_notes()
• 3 new tests
• Forgejo issue #32 (closed)

MCP (COMPLETED)

• PR #44 on pal-e-docs-mcp — merged 2026-03-17
• include_cold Field param on list_notes tool with descriptive help text
• 4 new tests
• Forgejo issue #43 (closed)

Deferred Scope

• Parent-chain CTE (notes under completed milestones) — stretch goal for subphase
• include_frozen param — not needed yet (archived notes are rare)
• Session injection hook changes — default behavior already correct

QA Nits (non-blocking)

• PR #191: Missing note_type + cold composition test; inaccurate _seed_notes docstring; resolved status not in COLD_STATUSES
• PR #33: Bool omission pattern differs from None-based convention (functionally correct)
• PR #44: Zero nits

Related

• plan-2026-03-16-knowledge-architecture — parent plan
• phase-2026-03-16-2-milestone-note-type — prerequisite (completed)
• convention-block-first-access — complementary access optimization

Phase 3: Gapped Integer Positions

Goal: Eliminate cascading position shifts on block inserts by using gapped integers (spacing of 1000) with periodic rebalance.

Owner: Dev agent

Repo: forgejo_admin/pal-e-docs

Depends on: None (independent of phases 1-2)

Scope

• Block positions: New blocks get positions spaced by 1000 (0, 1000, 2000, ...). Insert between 19000 and 20000 → position 19500. No other rows touched.
• Rebalance endpoint: POST /notes/{slug}/blocks/rebalance renumbers all blocks to gapped positions preserving order.
• Collision handling: Insert at occupied position shifts only the collider (+1). Gap exhaustion triggers automatic rebalance before insert.
• Delete preserves gaps: No more sequential reindexing on delete.

Deliverables

• PR #189 — merged 2026-03-17
• POSITION_GAP = 1000 constant in blocks/parser.py, exported from blocks/__init__.py
• Parser produces gapped positions (0, 1000, 2000...)
• Collision-only shift in create_block (was: shift all blocks at position >= target)
• Gap-preserving delete (was: reindex to sequential after every delete)
• POST /notes/{slug}/blocks/rebalance endpoint with RebalanceOut schema
• 24 new tests in test_gapped_positions.py, 4 existing test files updated
• 631 total tests passing

Deferred Scope

• Note child positions — not needed (already gap-tolerant)
• BoardItem positions — not needed (already tolerate gaps/collisions)
• Data migration — not needed (old sequential positions still work)

QA Nits (non-blocking)

• Stale docstring in parser.py lines 33/38 — still references "0-based ordering" and "paragraph-3" examples
• _seed_note_with_blocks in test_blocks_api.py could use a comment clarifying intentional use of legacy sequential positions

Related

• plan-2026-03-16-knowledge-architecture — parent plan
• Forgejo issue #188 (closed)

Phase 5: Retroactive Milestone Parenting (pal-e-docs dogfood)

Goal: Upgrade pal-e-docs existing milestone notes to proper note_type=milestone, parent completed plans under them, and validate the full hierarchy works before rolling out to other projects.

Owner: Betty Sue / Dottie (data migration, all pal-e-docs operations)

Repo: n/a (data migration via MCP tools, no code changes)

Depends on: Phase 2 (milestone note_type must exist in the enum)

Scope

• Upgrade 5 existing pal-e-docs milestone notes from note_type=doc to note_type=milestone
• Upgrade milestone-2026-03-16-knowledge-architecture (this plan's parent) to note_type=milestone
• Parent the 12 completed pal-e-docs plans under their respective milestones via update_note(parent_slug=...)
• Update project-pal-e-docs project page: milestones as primary structure
• Validate: list_notes(parent_slug="milestone-...") correctly returns plan hierarchy
• Document findings — what worked, what was awkward, what needs convention adjustment

Deliverables

• 5 milestone notes upgraded from note_type=doc to note_type=milestone, all set to status=completed
• milestone-2026-03-16-knowledge-architecture upgraded from doc to milestone (already done in Phase 2 verification)
• 11 completed plans parented under their respective milestones via parent_slug: 3 under project-genesis, 6 under knowledge-engine, 2 under board-system-frontend
• plan-pal-e-docs left unparented — per decision, in-flight work not reparented. Spans milestones 4+5.
• Validated: list_notes(note_type="milestone") returns 6 milestones (5 completed, 1 active). list_notes(parent_slug="milestone-2026-03-01-knowledge-engine") returns 6 child plans.

Related

• plan-2026-03-16-knowledge-architecture — parent plan
• phase-2026-03-16-2-milestone-note-type — prerequisite
• Existing milestones: milestone-2026-02-24-project-genesis, milestone-2026-03-01-knowledge-engine, milestone-2026-03-13-board-system-frontend, milestone-2026-03-14-frontend-workbench, milestone-2026-03-15-knowledge-loop

Phase 2: Milestone Note Type + Convention

Goal: Make milestone a first-class note_type with lifecycle statuses, create the template, and establish the "one milestone per project, one plan per milestone" convention.

Owner: Dev agent (schema change) + Betty Sue/Dottie (convention/template docs)

Repo: forgejo_admin/pal-e-docs, forgejo_admin/pal-e-docs-sdk, forgejo_admin/pal-e-docs-mcp

Depends on: None

Scope

Backend (pal-e-docs)

• Add "milestone" to NoteType literal in routes/notes.py
• Add VALID_STATUSES entry: "milestone": ["not-started", "active", "completed"]

SDK + MCP

• Update SDK note_type docstrings to include "milestone"
• Update MCP tool descriptions to include "milestone"

Conventions (pal-e-agency docs)

• Create template-milestone note
• Update template-plan — add guidance that plans should have a milestone parent
• Update template-project-page — milestones as primary organizer
• Create or update convention: "One active milestone per project, one plan per milestone"

Deliverables

• Backend: PR #187 merged — added "milestone" to NoteType + VALID_STATUSES (schemas.py, routes/notes.py). 577 tests pass.
• Convention: template-milestone created in pal-e-agency.
• Remaining: SDK + MCP docstring updates, template-plan and template-project-page convention updates still pending.

Related

• plan-2026-03-16-knowledge-architecture — parent plan
• milestone-2026-03-16-knowledge-architecture — this milestone is the first dogfood (created as doc type, will be upgraded to milestone type)
• template-plan — will be updated
• template-project-page — will be updated

Goal: Eliminate CSS duplication across pal-e-app, establish a single CSS methodology, and complete the design token system beyond colors.

Owner: Dev agent

Repo: forgejo_admin/pal-e-app

Depends on: phase-pal-e-docs-design-overhaul (F11, in-progress — F11a/b/c completed)

Forgejo Issue: pal-e-app #40

Why

CSS audit (2026-03-16) found two competing methodologies, incomplete design tokens, and repeated patterns across components.

Scope

Global utility classes, complete design tokens, refactor duplicated scoped styles. See issue #40 for full spec.

Deliverables

• PR #41 (pal-e-app) — 19 files, +184/-345 lines (net -161). QA approved after fix loop (blocker: missing .card transition, resolved).
• Design tokens added: --radius-sm/md/lg/pill, --shadow-sm/md/lg, --z-overlay/modal/toast, --transition-fast/normal
• Global classes added: .btn-primary, .form-input, .card-grid, .card
• Eliminated: 6 duplicate .btn-primary definitions, 3 duplicate .form-input, 5 duplicate .card-grid + .card, 40+ hardcoded border-radius values, 20+ hardcoded transition values
• Removed: dead .btn-secondary class, empty style block in repos page
• Methodology established: Tailwind for layout, CSS vars for theming, global classes for repeated component patterns

Related

• phase-pal-e-docs-design-overhaul — parent phase (F11)
• plan-pal-e-docs — parent plan
• convention-frontend-css — convention to update with methodology decision

Goal: pal-e-docs and pal-e-app are safe for public internet traffic — anonymous visitors see only public content, private projects/notes/boards are invisible.

Owner: Dev agent

Repo: forgejo_admin/pal-e-docs + forgejo_admin/pal-e-app

Depends on: phase-pal-e-docs-private-notes (F6, completed)

Forgejo Issues: pal-e-docs #184 (API filtering) + pal-e-app #38 (frontend SSR fix)

Why

Phase F6 implemented is_public filtering on note endpoints and added X-PaleDocs-Token auth. Two gaps remained: (1) the frontend sent the admin token on ALL SSR requests regardless of Keycloak session state; (2) the /projects and /boards API endpoints had no is_public filtering.

Scope

See original scope above. Both issues addressed.

Deliverables

• PR #185 (pal-e-docs) — is_public filtering on /projects and /boards endpoints using get_is_authenticated(). 7 endpoints updated, 22 new tests, 606 total passing. QA approved.
• PR #39 (pal-e-app) — ApiFetchOptions.authenticated flag threaded through all 18 API functions and every +page.server.ts loader. Token only sent when Keycloak session active. Sign-in page replaced with "Contact Lucas for access" + admin login via ?admin=true. 11 new E2E tests. QA approved.
• Data fixes — sop-secrets-management set to is_public=false. Private/Remember project page notes set to is_public=false. private-2026-03-16-chinese-room-devops journal set to is_public=false.
• SOP audit — 5 infrastructure SOPs audited. 1 made private, 3 flagged for Tailscale URL redaction (deferred), 1 safe.

Related

• plan-pal-e-docs — parent plan
• phase-pal-e-docs-private-notes — Phase F6, the foundation this builds on
• phase-pal-e-docs-frontend-auth — Phase F5, Keycloak OIDC integration
• phase-pal-e-docs-validation-hardening — Phase F10, prior auth hardening

Phase 1: Doc Drift Audit + Agent Alignment

Goal: Fix doc drift from pal-e-agency Phase 12 consolidation — align agent notes and SOPs to the actual 5-agent model (4 configs in claude-custom).

Owner: Dottie (documentation execution under Betty Sue's direction)

Repo: n/a (docs-only work in pal-e-docs)

Depends on: None

Scope

• Deprecate 6 stale specialized agent notes: agent-dev-frontend, agent-dev-backend, agent-devops, agent-frontend-qa, agent-dev-qa, agent-devops-qa
• Update agent-spawn-conventions to match agent-workflow (5-agent model: Betty Sue, Penny, Dev, QA, Dottie)
• Verify Penny's status — note exists in pal-e-docs but no config in claude-custom. Clarify: is Penny active or aspirational?
• Audit pal-e-agency done TODOs (22 notes) — confirm they're truly resolved, no orphan references

Deliverables

• 6 stale agent notes deprecated — agent-dev-frontend, agent-dev-backend, agent-devops, agent-frontend-qa, agent-dev-qa, agent-devops-qa. All set to status=deprecated, tags=agent,deprecated.
• agent-spawn-conventions updated to 5-agent model — "Nine Agents" heading changed to "Five Agents". Agent table, Access Scope table, When to Spawn table, and Deprecated section all updated to reflect Betty Sue, Penny, Dev, QA, Dottie. Explanatory text updated to describe dynamic domain expertise model.
• Penny clarified as active (not aspirational) — Penny appears in all agent-spawn-conventions tables with note that she is defined but not yet wired (no claude-custom config).
• TODO created: todo-penny-claude-config — tracks the gap: Penny needs a claude-custom/agents/penny.md config to be spawnable.
• Deferred: 22 done TODO audit — out of scope for this phase. Can be a subphase later.

Related

• plan-2026-03-16-knowledge-architecture — parent plan
• plan-pal-e-agency Phase 12 — "consolidated to 5-agent model" but docs never updated
• agent-workflow — the authoritative 5-agent SOP
• agent-spawn-conventions — currently shows 9-agent model (stale)

Phase F13: Context Intelligence — Behavioral Memory + Dynamic State

Goal: Separate behavioral knowledge (feedback/user memories — always relevant, stable) from state knowledge (project status — changes constantly, already in pal-e-docs) so session startup context is current, relevant, and doesn't truncate.

Owner: Betty Sue + Dev agent

Repo: forgejo_admin/claude-custom (hooks + memory), forgejo_admin/pal-e-docs (API if changes needed)

Depends on: phase-pal-e-docs-f12-semantic-search-recovery (Ollama must be healthy for F13b)

Scope

Hypothesis: Session startup context has two problems: (1) MEMORY.md is 76% stale project state duplicated from pal-e-docs (224 lines, truncating at 200). (2) SessionStart hook injects ~4,000 tokens including all 9 plan TOCs (~1,800 tokens / 45% of injection) when most sessions touch 1-2 projects. Fix both by separating behavioral knowledge (always relevant) from state knowledge (query dynamically).

Evidence (2026-03-15 analysis): SessionStart hook makes 25 API calls. Plan TOCs dominate: 9 plans × ~200 tokens each. MEMORY.md has "262 notes" when we have 500+, references completed phases as "IN PROGRESS." The hook already queries pal-e-docs for everything — adding one semantic search call is marginal cost. Design constraint: fail-open. If vectors are down, fall back to current static behavior. Zero risk.

F13a: MEMORY.md diet (no vector dependency). Audit all 44 topic files + inline sections. Categorize as behavioral (keep) vs state (remove). Remove state content that has a pal-e-docs equivalent. Verify the remaining MEMORY.md is under 100 lines and only contains feedback, user preferences, and repo location shortcuts. Test: start a new session and verify Betty Sue still has the behavioral guardrails.

F13b: Smart startup injection (two sub-steps). Sub-step 1 (no vector dependency): trim plan TOCs by board state — only inject TOCs for projects with in_progress board items. This is a tag-based query, saves ~1,200 tokens immediately. Sub-step 2 (depends on F12): add semantic search call using in-progress board item titles as the query. Inject top 10-15 blocks as a "dynamic briefing" section. Fail-open: if Ollama is down, skip silently — you still get the static injection. Repo: forgejo_admin/claude-custom (session-start-context.sh).

F13c: Verification round. PARTIALLY COMPLETED (2026-03-16). Simulation test ran the hook directly: Dynamic Briefing section appeared with 10 results. Findings: (1) "Browse UX Enhancements" (completed plan) took 5/10 slots — per-slug cap needed. (2) Completed/deferred notes surfacing alongside active work — status filter needed. (3) Results are broad enough for enterprise overview but too noisy for focused work. Key discovery: Lucas runs 4 concurrent sessions from ~/pal-e-platform, each focused on a different project. The briefing is shared across all 4 sessions (same cwd = same hook output). This means the Dynamic Briefing should be a short enterprise dashboard (what's hot), not deep project context. Project-specific depth comes when Lucas says "focus on X" and Betty Sue does a targeted query. See feedback_session_workflow.md.

F13d: Briefing quality tuning — DEFERRED (awaiting F13c real-world data). Three proposed jq-level fixes: (1) per-slug cap, (2) status filter, (3) total cap. But each has tradeoffs that can't be validated without real usage. Per-slug cap of 1 vs 2 — the Woodpecker experiment showed 2 relevant results from one SOP. Status filter risks excluding incidents (null status). Total cap of 8 is intuition, not measurement. Decision: let the briefing bake across 3+ real sessions before tuning. F13c verification will generate the data. F13d becomes a data-driven pass, not premature optimization. See feedback_session_workflow.md for the 4-concurrent-session workflow that informed this design.

Deliverables

• F13a: MEMORY.md under 100 lines — behavioral only. DONE. 224 → 60 lines.
• F13b-1: Trim plan TOCs by board state. DONE. PR #114 merged. ~1,200 tokens saved.
• F13b-2: Vector-powered startup briefing. DONE. PR #116 merged. Dynamic Briefing section live.
• F13c: Verification round. IN PROGRESS. Simulation complete. 3-session live verification remaining — observe, document, then inform F13d.
• F13d: Briefing quality tuning. DEFERRED. Awaiting F13c real-world data. Premature optimization without production usage.

Related

• plan-pal-e-docs — parent plan (capability lives here: vectors, API, semantic search)
• plan-pal-e-agency — cross-cutting: this phase changes the operating model (how Betty Sue bootstraps, what memory means, session context architecture). Tracked on board-pal-e-agency as well.
• phase-pal-e-docs-f12-semantic-search-recovery — prerequisite (Ollama must be healthy for F13b)
• template-ticket — ticket labels could become additional query dimensions for vector search
• Boards: board-pal-e-docs (item #97) + board-pal-e-agency (item #98) — cross-cutting ticket

Phase F12: Semantic Search Recovery

Goal: Restore semantic search to working state and add alerting so Ollama/embedding failures are detected within 10 minutes instead of silently rotting.

Owner: Dev agent

Repo: forgejo_admin/pal-e-docs, forgejo_admin/pal-e-platform, forgejo_admin/pal-e-deployments

Depends on: None (Ollama and pgvector already deployed from Act 2 Phase 6a)

Scope

The semantic_search MCP tool returns 503. Root cause diagnosed (2026-03-15): Ollama pod is healthy (running 6 days, 0 restarts) but the qwen3-embedding:4b model is NOT loaded. The 10Gi PVC was recreated 6 days ago and only chat models (qwen3.5:4b, qwen3:4b) were pulled. Embedding worker has 152 errors, 0 successful embeddings. embedding_queue_depth reads 0 because failed blocks are marked error, not pending — this is important for alerting strategy.

F12-1: Fix Ollama model persistence. Swap PVC for hostPath volume mount (e.g. /var/lib/ollama) in the Ollama Terraform deployment. This ensures models survive any k8s lifecycle event (pod restart, deployment recreate, terraform apply). Then pull qwen3-embedding:4b (~3GB). Repos: pal-e-platform (Terraform), pal-e-deployments (if kustomize overlay). Hardware: GTX 1070 (8GB VRAM), model fits comfortably alongside chat models.

F12-2: Backfill stale embeddings. Query SELECT embedding_status, count(*) FROM blocks GROUP BY embedding_status to assess damage. Reset error blocks to pending. Run python -m pal_e_docs.embedding_worker --backfill. Verify semantic_search returns results.

F12-3: Add alerting. The worker exposes Prometheus metrics on :8001/metrics. IMPORTANT: embedding_queue_depth is NOT sufficient — it reads 0 during failures because blocks get marked error after 3 retries. The correct alerts are: rate(embedding_errors_total[5m]) > 0 → warning (active failures), and embedding_total == 0 for > 10 minutes while embedding_errors_total is increasing → critical (complete embedding failure). Add Prometheus scrape config for the worker. Route to existing Slack/Telegram pipeline (Phase 16 infra).

Deliverables

• semantic_search MCP tool returns results (not 503)
• All blocks have embedding_status = completed or skipped (zero pending/error)
• Prometheus alert fires within 10 minutes if embeddings stop processing

Related

• plan-pal-e-docs — parent plan
• plan-pal-e-platform — alerting infrastructure (Phase 16)
• phase-pal-e-docs-design-overhaul — sibling phase (F11, in progress)

Goal: Close the loop — agent actions automatically trigger the next step without Betty Sue manually intervening. status:qa auto-spawns QA agent. Merge auto-updates sprint board.

Owner: Betty Sue (Claude config development per sop-claude-config-development)

Repo: forgejo_admin/claude-custom (symlinked as ~/.claude/)

Forgejo Issue: TBD

Architecture

Phases 3 and 4 make the workflow work manually — hooks set labels, Betty Sue runs skills to sync boards. Phase 5 makes it automatic — hooks trigger the next agent in the chain without Betty Sue initiating.

Trigger	Automation	What Happens
Dev submits PR (status:qa set by Phase 3 hook)	Auto-QA trigger	QA agent spawned automatically to review the PR
PR merged	Auto-board sync	Sprint item moved to done, plan phase updated
QA sets status:needs-fix	Auto-dev respawn	Dev agent respawned with fix instructions (stretch goal)

Design Considerations

• Hooks must be lightweight — spawn a subagent for heavy work, don't block the hook
• Auto-QA trigger must pass the PR number and issue number to the QA agent
• Auto-board sync must identify which sprint item corresponds to the merged PR
• All auto-spawns must follow agent-spawn-conventions (plan slug, boundary statement)
• Consider a "manual mode" flag to disable auto-triggers during debugging

Implementations

1. Auto-QA trigger (PostToolUse on mcp__forgejo__submit_pr):

• After Phase 3's label-on-pr hook sets status:qa, inject context telling Betty Sue to spawn QA
• Or: directly spawn QA subagent from the hook (if hooks can spawn agents)
• Fallback: PostToolUse injects "status:qa set — run /review-pr owner/repo#N" as additionalContext

2. Auto-board sync — ABSORBED by plan-pal-e-agency Phase 11:

• DONE — Delivered by Agency Phase 11e (board-item-on-merge.sh hook, PR #98 on claude-custom)
• Post-merge hook calls pal-e-docs API to move board item to done column
• Session-start auto-sync also deployed (Agency Phase 11d)

3. Auto-dev respawn (stretch goal):

• When QA sets status:needs-fix, auto-spawn dev agent with fix instructions
• Only viable if QA comment clearly describes what needs fixing
• Defer to Phase 6 or a future plan if too complex

Steps

1. Determine whether hooks can spawn subagents or only inject context
2. Implement auto-QA trigger (extend label-on-pr.sh or new hook)
3. Implement auto-board sync (extend post-mcp-merge-rebase.sh)
4. Add manual mode flag (.claude-no-auto-trigger file disables auto-spawns)
5. Test full cycle: issue → dev → PR → auto-QA → verdict → merge → auto-board-sync
6. Evaluate auto-dev-respawn feasibility

Deliverable: Dev submits PR → QA automatically reviews → verdict auto-sets label → merge auto-updates board. The full loop runs with minimal Betty Sue intervention.

Depends on: Phase 3 (hooks set labels), Phase 4 (skill exists to sync boards).

Goal: Rename repos to match new architecture. pal-e-docs → pal-e-api, pal-e-docs-mcp → pal-e-mcp, pal-e-docs-sdk → pal-e-sdk.

Owner: Betty Sue (coordination), Dev agent (code changes)

Repo: All pal-e-docs ecosystem repos + claude-custom (hooks reference MCP tool names)

Depends on: pal-e-app working against current API (renames shouldn't block new work)

Scope

• Forgejo API repo renames
• ArgoCD application updates
• k8s manifest image references
• Python package name changes (import paths)
• MCP server config key change (affects ALL tool name prefixes)
• claude-custom hooks that pattern-match on mcp__pal-e-docs__*
• Agent profiles, spawn conventions
• CLAUDE.md files across repos

Related

• plan-pal-e-docs — parent plan

Goal: Capture token usage per item, per sprint, per activity category. Feed into DORA correlation.

Owner: Dev agent

Repo: pal-e-docs

Issue: TBD

Model:

• TokenUsage — id, sprint_item_id (FK nullable), sprint_id (FK nullable), repo_slug, activity (enum: planning/development/review/documentation), input_tokens (int), output_tokens (int), session_id (string, nullable), agent_type (string, nullable — betty-sue/dev/qa), recorded_at (datetime)

API routes:

• POST /token-usage — record token usage
• GET /token-usage/summary — aggregate by sprint, repo, activity
• GET /sprints/{slug}/token-usage — token breakdown for a sprint

Integration points:

• Hooks log token counts per agent spawn
• DORA exporter pulls token metrics for Grafana
• Sprint retro: review token spend breakdown from previous sprint

Deliverable: Token usage tracked per sprint item. Summary API shows cost per plan/phase/issue and per sprint.

Goal: Auto-discover items and keep boards in sync with source systems. Eliminate manual board maintenance.

Owner: Dev agent

Repo: pal-e-docs

Depends on: Phase 1 (Board Data Model) — COMPLETED

Scope

Sub-phase 5b-1: Plan/Phase Sync (internal)

Issue: forgejo_admin/pal-e-docs #165 (CLOSED) — PR #166 merged 2026-03-14. POST /boards/{slug}/sync endpoint + update_note hook. 16 tests, all 513 pass.
SDK: forgejo_admin/pal-e-docs-sdk #28 (CLOSED) — PR #29 merged 2026-03-14. sync_board(slug) method added, SDK v0.4.0 published.
MCP: forgejo_admin/pal-e-docs-mcp #37 (CLOSED) — PR #38 merged 2026-03-14. sync_board MCP tool added, MCP v0.3.0.
5b-1 COMPLETE — full stack: API → SDK v0.4.0 → MCP v0.3.0. Needs session restart to activate.

• POST /boards/{slug}/sync — scans board for plan items, auto-creates BoardItems for child phases, maps note status → board column
• Hook in update_note — when a phase note's status changes, find matching BoardItem by note_slug and move to the correct column
• Status → Column mapping: not-started→backlog, in-progress→in_progress, completed→done, deferred→done
• Duplicate prevention: skip phases already on the board (existing unique constraint on note_slug per board)
• No new dependencies — purely internal to pal-e-docs DB

Sub-phase 5b-2: Forgejo Issue Sync (external)

Issue: forgejo_admin/pal-e-docs #170 (CLOSED) — PR #171 merged 2026-03-14. POST /boards/{slug}/sync-issues endpoint + Forgejo API client + config extension + k8s env vars. 9 tests, all passing.
Pre-deploy: forgejo-api-token key needed in pal-e-docs-secrets k8s secret.

• POST /boards/{slug}/sync-issues — pull open issues from Forgejo repos via API
• Match issues to existing BoardItems by forgejo_issue_url
• New issues auto-create as backlog BoardItems
• Closed issues auto-move to Done
• Needs: Forgejo API token in env, project → repo mapping

Sub-phase 5b-3: Stale Detection

Issue: TBD

• Flag items whose source was closed/completed outside the board
• Flag items stuck in a column for too long
• Add stale_at field to BoardItem (schema migration)
• Periodic sweep (cron-like, similar to embedding worker pattern)

Deliverable

Adding a plan to a board auto-populates its child phases. update_note(status=...) auto-moves the corresponding board item. Forgejo issues sync into the board. Status changes propagate bidirectionally. All boards stay current with zero manual maintenance.

Related

• plan-pal-e-docs — parent plan
• phase-pal-e-docs-board-data-model — Phase 1 (prerequisite)
• phase-pal-e-docs-sprint-board-component — Phase 3 (Kanban UI)

Goal: Validate all new frontend features with E2E tests, audit design quality, and harden edge cases.

Owner: Betty Sue (coordination) + Dev agent (code)

Repo: forgejo_admin/pal-e-app

Depends on: F6 (private notes), F8 (note editing), F9 (board CRUD) — all COMPLETED

Scope

F10a: Auth E2E Tests + Hardening

• Playwright tests: signin redirect, role display, FAB visibility, POST /api/notes 401 for anon
• Auth check verification on PUT /api/notes/[slug], POST/PATCH/DELETE board item proxies
• Private notes: verify lock icon renders, Quick-Jot private toggle works

F10b: Design Audit + Critique

• Run /audit on edit form, board CRUD UI, private notes UI
• Run /critique for UX quality and AI slop detection
• Lighthouse audit on key pages via Chrome DevTools
• Screenshot validation of new features

F10c: Hardening + Polish

• Address audit/critique findings
• Edge cases: empty states, error handling, text overflow
• Final spacing/alignment/consistency pass
• Lock in validated behavior with additional E2E tests

Related

• plan-pal-e-docs — parent plan
• phase-pal-e-docs-private-notes — F6, dependency
• phase-pal-e-docs-note-editing — F8, dependency
• phase-pal-e-docs-board-item-management — F9, dependency

Goal: Fix outstanding infra bugs and harden CI pipelines.

Owner: Dev agent

Repo: Multiple — see child TODOs

Depends on: None — independent of feature work

Scope

Collects outstanding TODOs and bugs. See child notes:

• todo-fix-mcp-pypi-publish — MCP PyPI publish pipeline failure
• todo-migration-testing-ci-pal-e-docs — Alembic migration testing in CI
• bug-woodpecker-smoke-test-empty-logs — Woodpecker smoke test failure
• todo-pal-e-docs-deployment-reliability — Zero-downtime deploy improvements
• todo-argocd-rewire-deployments-repo — ArgoCD rewire to pal-e-deployments

Related

• plan-pal-e-docs — parent plan

Goal: Enable authenticated users to create and delete board items from the browser, and secure the existing move proxy.

Owner: Dev agent

Repo: forgejo_admin/pal-e-app

Depends on: Phase F5 (auth) — COMPLETED

Scope

• Auth check on existing PATCH (move) proxy — was completely unprotected
• POST proxy: src/routes/api/boards/[slug]/items/+server.ts for creating items (authenticated)
• DELETE proxy + handler on src/routes/api/boards/[slug]/items/[id]/+server.ts (authenticated)
• "+" create button in column headers (authenticated only) with create modal
• "x" delete button on cards with confirmation dialog (authenticated only)
• createBoardItem() and deleteBoardItem() functions in api.ts
• Optimistic UI updates for create and delete (same pattern as existing move)

Deliverables

• PR #31 MERGED — feat: board item management (create, delete + auth on move)
• Issue #28 closed
• 4 files changed
• QA found 2 blockers (inconsistent auth pattern in deleteBoardItem, forgejo_issue_url not whitelisted in POST proxy) — both fixed

QA Nits (Epilogue)

• Create flow is not truly optimistic (waits for API response)
• deleteSubmitting state effectively dead code
• ITEM_TYPES hardcoded — could drift from backend
• Hover-based delete button may have sticky hover on touch devices

Related

• plan-pal-e-docs — parent plan
• phase-pal-e-docs-private-notes — F6, sibling phase
• phase-pal-e-docs-note-editing — F8, sibling phase

Goal: Allow authenticated users to edit existing notes from the browser.

Owner: Dev agent

Repo: forgejo_admin/pal-e-app

Depends on: Phase F5 (auth) — COMPLETED

Scope

• PUT proxy: src/routes/api/notes/[slug]/+server.ts — authenticated, forwards to backend PUT /notes/{slug}
• Edit page: /notes/[slug]/edit with form for title, body (raw HTML textarea), note_type (all 16 types), dynamic status per note_type, project dropdown, tags (comma-separated), parent_slug
• Edit button on NoteLayout component (visible only to authenticated users)
• updateNote(slug, data) function in api.ts
• Session data plumbed through +page.server.ts to NoteLayout via isAuthenticated prop

Deliverables

• PR #30 MERGED — feat: note editing (edit form + PUT proxy + Edit button)
• Issue #27 closed
• 7 files changed (498 additions, 4 deletions)
• QA approved with 3 nits (non-blocking)

QA Nits (Epilogue)

• Use API response slug for redirect after save (future-proofs slug editing)
• E2E tests for edit flow
• Rebase overlap cleanup (cosmetic)

Related

• plan-pal-e-docs — parent plan
• phase-pal-e-docs-private-notes — F6, sibling phase
• phase-pal-e-docs-frontend-auth — F5, dependency

Phase F6: Private Notes Enforcement

Status: COMPLETED

Priority: HIGHEST — security gap (now closed)

Backend (pal-e-docs) — PR #179 MERGED

• Issue #178 closed
• New file: src/pal_e_docs/auth.py — reusable get_is_authenticated() FastAPI dependency
• Filtering on: list_notes, get_note, search_notes, semantic_search, all sub-resource endpoints (toc, blocks, revisions, compiled, links)
• Write protection: PUT and DELETE require auth when API key configured
• is_public added to NoteSearchResult and SemanticSearchResult schemas
• 30 new tests (554 total passing)

Frontend (pal-e-app) — PR #29 MERGED

• Issue #26 closed
• X-PaleDocs-Token header in apiFetch() via PAL_E_DOCS_API_KEY env var
• Private toggle in QuickJot modal (sets is_public=false)
• Lock icon on private notes in note lists and search results
• is_public forwarded through note creation proxy
• k8s/deployment.yaml updated with PAL_E_DOCS_API_KEY secret ref

Deployment Note

PAL_E_DOCS_API_KEY env var must be set on both pal-e-docs and pal-e-app. SOPS secret k8s/pal-e-auth-secrets.enc.yaml needs the actual key value added.

Goal: Activate the dormant embedding pipeline and semantic search, giving every agent contextual awareness across the full 260+ note knowledge base.

Owner: Dev agent

Repo: forgejo_admin/pal-e-docs

Depends on: None (all infrastructure already built — pgvector, Ollama, embedding worker code, search API, SDK, MCP tools)

Scope

The entire semantic search stack was built during Act 2 but left dormant (replicas: 0). This phase activates it:

1. Scale embedding worker — change k8s/embedding-worker.yaml replicas from 0 to 1
2. Verify image currency — ensure the manifest image tag matches a build that contains embedding_worker.py. Update if stale.
3. Verify connectivity — worker must reach Ollama at http://ollama.ollama.svc.cluster.local:11434 and Postgres via PALDOCS_DATABASE_URL
4. Initial backfill — 5,643 blocks with embedding_status='pending' need embedding. Worker has --backfill mode or will process via LISTEN/NOTIFY loop.
5. Verify search modes — confirm /search?mode=semantic and /search?mode=hybrid return results via API
6. Verify MCP tool — confirm semantic_search() MCP tool returns ranked results

Progress (2026-03-14)

• PR #155 merged — replicas 0→1, image tag updated. Embedding worker running.
• PR #161 merged — Fixed SQLAlchemy text() parameter binding bug: :query_vec::vector → CAST(:query_vec AS vector). Semantic search SQL now works. Issue #160 closed.
• SDK v0.3.0 published — to Forgejo PyPI. MCP server venv updated. MCP process needs restart to load new SDK.
• Backfill in progress — 266/5,921 blocks completed (~4.5%). Batch size patched to 50, poll interval to 10s for ~10x speedup. ETA ~1 hour.
• Remaining — verify search endpoints return results after backfill progresses further; verify MCP tool after session restart.

Key Context

• Embedding worker: src/pal_e_docs/embedding_worker.py (610 lines, production-ready)
• K8s manifest: k8s/embedding-worker.yaml (replicas: 1, same image as API with different entrypoint)
• Search service: src/pal_e_docs/services/search.py (RRF fusion — keyword + semantic)
• Model: qwen3-embedding:4b (2560-dim vectors, 3.5GB VRAM, loaded in Ollama)
• DB state: ~5,639 pending, 16 skipped, ~266 completed (actively backfilling)
• ArgoCD reads from pal-e-docs/k8s/ — push to main triggers deploy

Deliverables

• Embedding worker running in production (1 replica) ✓
• All embeddable blocks have embedding_status='completed' — in progress
• Hybrid search returns meaningful results via API and MCP tool — SQL fix merged, pending verification

Related

• plan-pal-e-docs — parent plan
• phase-pal-e-docs-5a-embedding-dimension-fix — sub-phase (completed)
• bug-mcp-silent-load-failure — semantic search could help agents find recovery SOPs
• plan-2026-03-09-template-rendering — sibling capability (template rendering)

Goal: Fix vector dimension mismatch so embedding worker can store qwen3-embedding:4b output (2560-dim) in pgvector column.

Owner: Dev agent

Repo: forgejo_admin/pal-e-docs

Depends on: phase-pal-e-docs-activate-semantic-search (parent — worker is deployed but erroring)

Problem

The blocks.embedding column is vector(768) but qwen3-embedding:4b now produces 2560-dim vectors. The model was likely updated upstream since Phase 6a verification. Worker logs show: expected 768 dimensions, not 2560. All blocks are marked as error status.

Fix

• Alembic migration: ALTER TABLE blocks ALTER COLUMN embedding TYPE vector(2560)
• Update any code/config that hardcodes 768 (search for 768 in models, schemas, tests)
• Reset errored blocks back to pending: UPDATE blocks SET embedding_status = 'pending' WHERE embedding_status = 'error'
• Verify worker starts processing successfully after deploy

Related

• phase-pal-e-docs-activate-semantic-search — parent phase
• plan-pal-e-docs — grandparent plan

Goal: Remove the dead Jinja2 frontend from the pal-e-docs backend now that SvelteKit serves all routes.

Owner: Dev agent

Repo: forgejo_admin/pal-e-docs

Depends on: phase-pal-e-docs-note-renderer

Problem

SvelteKit (pal-e-app) now renders all note types from the blocks API. The Jinja2 frontend (/browse/* routes) is dead code still deployed in the backend. ~320 lines of routing + ~460 lines of templates + dependencies.

Fix

• Delete src/pal_e_docs/routes/frontend.py
• Delete src/pal_e_docs/templates/ directory (base.html, note.html, landing.html, projects.html, project_notes.html, tags.html, tag_notes.html, repos.html, login.html)
• Remove Jinja2Templates import and setup
• Remove frontend.router from the FastAPI app includes
• Remove session auth middleware if only used by frontend (check if API uses it too)
• Remove autolink.py, sanitize.py, wrap_tables.py if only consumed by frontend routes (check if blocks/sync.py or API routes use them)
• Remove Jinja2 and itsdangerous (sessions) from dependencies if no longer needed
• Run tests: pytest tests/ -v

Related

• phase-pal-e-docs-note-renderer — parent phase
• plan-pal-e-docs — parent plan

Goal: Remove dead listNoteSlugs() export from api.ts after slug cache replaced it.

Owner: Dev agent

Repo: forgejo_admin/pal-e-app

Depends on: phase-pal-e-docs-note-renderer

Problem

QA nit from PR #9 review: listNoteSlugs() at src/lib/api.ts is exported but never imported. It was replaced by getCachedSlugs() in src/lib/slugCache.ts.

Fix

• Remove listNoteSlugs() function from src/lib/api.ts
• Verify no other imports reference it
• Run npm run check && npm run build

Related

• phase-pal-e-docs-note-renderer — parent phase
• plan-pal-e-docs — parent plan

Goal: Build SvelteKit block-based rendering for all note types and remove the Jinja2 frontend entirely.

Owner: Dev agent

Repo: forgejo_admin/pal-e-app (primary), forgejo_admin/pal-e-docs (Jinja2 removal)

Depends on: phase-pal-e-docs-app-scaffold, phase-pal-e-docs-sprint-board-component

Scope

Absorbs the original Phase 4 (Note Renderer) and Phase 9 (Jinja Sunset) into a single deliverable. The Jinja2 frontend is ~320 lines of Python routing + ~460 lines of templates. The block API already exists. The gap is smaller than the plan assumed — no reason to maintain two frontends in parallel.

Deliverables

• 7 block renderer components — HeadingBlock, ParagraphBlock, TableBlock, ListBlock, CodeBlock, MermaidBlock, BlockRenderer (dispatcher). All render from blocks API JSON.
• /notes/[slug] route — fetches blocks from API, renders with block components. Breadcrumb, metadata badges, TOC sidebar, child notes sidebar, anchor links on headings.
• /notes listing route — search, type-grouped display, tag/project/note_type filters.
• /projects and /projects/[slug] routes — project list + detail with notes grouped by type.
• /tags and /tags/[name] routes — tag cloud + filtered note listing.
• /repos route — repos grouped by project.
• Autolink support — <code>slug-ref</code> patterns in paragraph/list blocks auto-link to /notes/{slug}. Server-side slug cache with 60s TTL.
• Landing page — overview dashboard with projects, boards, and top tags.
• DOMPurify sanitization — all {@html} inputs sanitized via isomorphic-dompurify. Defense-in-depth.
• Shared color system — src/lib/colors.ts with 16-type color map extracted from duplicated constants.
• PR #9 merged — 30 files changed, +2609/-183. Closes Issue #8.
• Jinja2 removal NOT YET DONE — SvelteKit serves all routes. Jinja2 templates still in pal-e-docs backend (separate repo, separate PR). Tracked as follow-up.

Out of Scope

• Auth (login/logout) — deferred, tracked by pal-e-docs Issue #2
• Dropping html_content column — keep as cache for now, remove after search migration
• In-browser editing — future phase

Key Architectural Decision

SvelteKit renders from blocks, not from html_content. The blocks table (5,197 rows, 6 types) is the source of truth. html_content is a denormalized cache maintained by recompile() — kept for search compatibility but not consumed by the frontend.

Related

• plan-pal-e-docs — parent plan
• phase-pal-e-docs-jinja-sunset — absorbed into this phase
• phase-pal-e-docs-sprint-board-component — board kanban (already built, pattern to follow)

Goal: Absorbed into phase-pal-e-docs-note-renderer (Phase 4: Block Renderer + Jinja2 Sunset).

Owner: n/a

Repo: n/a

Depends on: n/a

Scope

This phase was merged into Phase 4. The Jinja2 frontend is small enough (~780 lines total) that building the SvelteKit replacement and removing Jinja2 should happen as one deliverable rather than maintaining two frontends in parallel.

Related

• phase-pal-e-docs-note-renderer — absorbing phase
• plan-pal-e-docs — parent plan

Goal: Design and build the interactive kanban board component. Playground-first — nail the UX before wiring to production.

Owner: Lucas + Betty Sue (design), Dev agent (build)

Repo: forgejo_admin/html-playground (design), forgejo_admin/pal-e-app (promote)

Depends on: phase-pal-e-docs-app-scaffold (for promotion), board API (for real data)

Scope

• Kanban board: 7 columns (backlog→done), cards with title/points/labels, drag-and-drop — PR #6
• Board tabs with item counts, navigate between project boards — PR #6
• Card type differentiation: plan=gold, phase=green, issue=blue, todo=red, project=purple, repo=lavender — PR #6
• Desktop HTML5 drag-and-drop + mobile touch long-press + tap-to-move fallback — PR #6
• Server-side API proxy for browser PATCH calls (sanitized error responses, validated inputs) — PR #6
• Dark theme across all pages — PR #6
• Optimistic local state updates on drag-and-drop — PR #6
• Deferred: Drill-down (click plan → see phases), add/remove items, inline point editing

Related

• plan-pal-e-docs — parent plan
• phase-pal-e-docs-board-data-model — provides the API

Goal: Create the pal-e-app repo with SvelteKit scaffold and Docker Compose dev environment connecting to pal-e-docs API.

Owner: Dev agent

Repo: forgejo_admin/pal-e-app (new)

Depends on: None — connects to existing API

Scope

• SvelteKit project with adapter-node, TypeScript — PR #2
• Docker Compose: postgres + pal-e-api + pal-e-app (dev server) — PR #2
• Board list + detail pages with typed API client — PR #2
• Woodpecker CI pipeline (check/lint/build) — PR #2
• k8s manifests (deployment, service, kustomization) + CI build-and-push — PR #5
• Service onboarding: namespace, Harbor project, Woodpecker secrets, ArgoCD — tofu apply + manual

Related

• plan-pal-e-docs — parent plan

Phase: Board Data Model

Goal: Replace sprints with boards. One permanent kanban board per project. Drop sprint tables entirely.

Owner: Dev agent

Repo: forgejo_admin/pal-e-docs (DB + API), forgejo_admin/pal-e-docs-mcp (MCP tools)

Depends on: Phase 0 (Project Taxonomy Cleanup) — clean project list is prerequisite

Scope

Data Model

boards table:

Column	Type	Notes
id	int PK	auto
slug	varchar(200) unique	Convention: board-{project-slug}
name	varchar(200)	Display name
project_id	FK → projects.id, unique	One board per project. NOT NULL.
created_at	datetime	server_default=now()
updated_at	datetime	server_default=now(), onupdate=now()

board_items table:

Column	Type	Notes
id	int PK	auto
board_id	FK → boards.id, CASCADE	NOT NULL
item_type	varchar(20)	Denormalized from note_type or "issue". Values: plan, phase, issue, repo, project, todo
column	varchar(20)	7 values: backlog, todo, next_up, in_progress, qa, needs_approval, done
position	int	Order within column. Default 0.
note_slug	varchar(500) nullable	Points to a pal-e-docs note
forgejo_issue_url	varchar(500) nullable	Points to a Forgejo issue
title	varchar(500) nullable	Display name (derived from note/issue title)
points	int nullable	Velocity tracking
labels	text nullable	Comma-separated labels
created_at	datetime	server_default=now()
updated_at	datetime	server_default=now(), onupdate=now()

API Endpoints

Method	Path	Description
GET	/boards	List all boards (unified view across projects)
POST	/boards	Create board (requires project slug)
GET	/boards/{slug}	Get board with item counts
PATCH	/boards/{slug}	Update board name
DELETE	/boards/{slug}	Delete board (reject if items exist)
GET	/boards/{slug}/items	List items (filter by column, item_type)
POST	/boards/{slug}/items	Add item to board
PATCH	/boards/{slug}/items/{id}	Update item (move column, change points)
DELETE	/boards/{slug}/items/{id}	Remove item from board
PATCH	/boards/{slug}/items/bulk	Bulk move items between columns
GET	/boards/backlog/items	Cross-board backlog view

Migration

• Create boards + board_items tables
• Drop sprints + sprint_items tables (no data migration — Sprint 3 data discarded)
• Remove sprint enums (SprintStatus, SprintItemType, SprintColumn)

Decisions

Decision	Rationale
Keep item_type (denormalized)	Enables filtering ("show me just phases") without joining to notes table. Set at add-time from note's note_type or "issue" for Forgejo issues.
Keep all 7 columns	qa and needs_approval are critical workflow statuses for the PR review-fix loop.
Keep labels field	Used for DORA instrumentation (status:approved, etc.)
Hard cut from sprints	No migration of Sprint 3 data. Drop tables. Clean start.
Board slug convention: board-{project-slug}	Predictable, human-readable. Auto-generated on board creation.
project_id UNIQUE on boards	Enforces one board per project at the DB level.

Sub-phases

• 1a: DB + API — Tables, Alembic migration (drop sprints, create boards), all API endpoints, tests. Repo: pal-e-docs.
• 1b: MCP tools — Replace 25 sprint MCP tools with board equivalents. Repo: pal-e-docs-mcp.
• 1c: SDK — Update pal-e-docs-sdk with board operations. Repo: pal-e-docs-sdk.

Related

• plan-pal-e-docs — parent plan
• plan-2026-03-01-pal-e-sprints — predecessor (completed, sprint tables being replaced)
• phase-pal-e-docs-sprint-board-component — Phase 3, the SvelteKit UI that renders these boards
• feedback_one_plan_per_project — one plan per project, one board per project

Phase: Project Taxonomy Cleanup

Goal: Clean project hierarchy so every active project follows the new template. One plan per project, one board per project. Prerequisite for Phase 1 (Board Data Model) — boards don't work if the project taxonomy is garbage.

Owner: Betty Sue (main session)

Repo: pal-e-docs (API change for delete_project), pal-e-docs-mcp (new tool)

Depends on: Nothing

Scope

Completed (2026-03-13)

• Created conventions: convention-todo-lifecycle (TODO graduation rules), template-project-page (Vision/Plan/Board/Status/Architecture/Repos/Inbox)
• Consolidated pal-e-platform: 1 active + 4 deferred plans + 4 stubs → 1 unified plan-pal-e-platform with 13 phases. 4 orphan TODOs parked under phases. Project page rewritten to new template.
• Consolidated pal-e-docs: 3 active plans → 1 unified plan-pal-e-docs with 10 phases. 6 TODOs parked. Project page rewritten.
• Merged pal-e-config → pal-e-agency: 13 notes moved (6 completed plans, 1 deferred plan, 1 SOP, 2 conventions, 2 open TODOs). All pal-e-config content now lives under pal-e-agency.
• Moved pal-e-services → pal-e-platform: 4 notes (service-onboarding-sop, deployment-lessons, namespace-conventions, argocd-image-updater). pal-e-services is a repo under pal-e-platform, not its own project.
• Deleted 18 stale notes: 5 legacy pal-e (GitHub-era), 1 babylist, 2 pal-e-services stale, 10 pal-e-config stale (old project pages, archived repo pages, done TODOs)
• Saved feedback: pal-e-platform is the axiom project (project=repo exception, DORA and observability live at foundation)

Remaining: Subphase — delete_project endpoint + empty shell cleanup

Forgejo Issue: forgejo_admin/pal-e-docs #144

• DONE — Add DELETE /projects/{slug} to src/pal_e_docs/routes/projects.py — PR #145 merged 2026-03-13. Issue #144 closed.
• Add delete_project tool to pal-e-docs-mcp (follow-up issue)
• Deploy new image with delete_project endpoint
• Delete 7 empty project shells: ai-agency, claude-config, babylist, pal-e-sprints, pal-e, pal-e-services, pal-e-config
• Verify: list_projects returns only 7 active projects (pal-e-platform, pal-e-docs, pal-e-agency, westside-basketball, pal-e-world, posts, private)

Westside Basketball alignment

• Project page already updated to new template by Lucas
• Tryout prep plan needs status update (tryout was 2026-03-13)
• Confirm all basketball TODOs are properly parented

Related

• convention-todo-lifecycle — created this session
• template-project-page — created this session
• phase-pal-e-docs-board-data-model — Phase 1, depends on clean taxonomy

Goal: Betty Sue has skill commands for sprint management — creating items, syncing board state from labels, linking PRs, and sprint status. Skill encapsulates MCP tool sequences into reusable commands.

Owner: Betty Sue (Claude config development per sop-claude-config-development)

Repo: forgejo_admin/claude-custom (symlinked as ~/.claude/)

Forgejo Issue: TBD

Architecture

Skills encapsulate multi-step MCP workflows into single commands. Each skill command is a recipe that calls MCP tools in sequence. The skill file defines the steps; the agent (Betty Sue) executes them.

Layer	What	Example
Skill command	User-invocable workflow	/sprint-sync — read labels on all sprint items, move board columns to match
MCP tools	Individual API calls the skill orchestrates	mcp__forgejo__list_issues, mcp__pal-e-docs__move_sprint_item
Hooks	Enforcement that fires on tool events	PostToolUse after merge → remind Betty Sue to move sprint item to done

Skill Commands to Implement

• /sprint-sync — Read Forgejo labels on all sprint items' issues, update board columns to match label state using the label-to-column mapping from agent-workflow
• /sprint-status — Summary of all boards: what's in each column, what's blocked, what moved since last check
• /sprint-add — Create sprint item from Forgejo issue URL. Calls add_sprint_item() with title convention from template-sprint-item
• /sprint-kickoff — For all items in next_up, spawn dev agents with Forgejo issue URLs. Follows agent-spawn-conventions.

Hook: Post-Merge Sprint Update

• Extend existing PostToolUse on mcp__forgejo__merge_approved_pr
• Inject context: "PR merged. If this issue has a sprint item, move it to done and update the plan phase."
• This is a reminder hook (like remind-update-docs.sh), not automatic — Betty Sue decides whether to act

Steps

1. Review sop-claude-config-development and existing skill file patterns
2. Create skills/sprint-sync/SKILL.md
3. Create skills/sprint-status/SKILL.md
4. Create skills/sprint-add/SKILL.md
5. Create skills/sprint-kickoff/SKILL.md
6. Extend post-merge hook with sprint item reminder
7. Create skill notes in pal-e-docs for each command
8. Test each command against Sprint 1 data

Deliverable: Betty Sue can /sprint-sync to update boards from labels, /sprint-status for a quick view, /sprint-add to onboard issues, /sprint-kickoff to start work on next_up items.

Depends on: Phase 3 (hooks set labels that /sprint-sync reads).

Goal: Agents automatically signal workflow state via Forgejo labels at every stage transition. Enforced by hooks — not dependent on agent memory.

Owner: Betty Sue (Claude config development per sop-claude-config-development)

Repo: forgejo_admin/claude-custom (symlinked as ~/.claude/)

Forgejo Issue: TBD

Architecture: Three Enforcement Layers

Layer	What	Enforcement
Hooks (PostToolUse)	Set labels + comment on issue automatically when tools fire	Strong — can't be skipped, fires regardless of agent prompt
Skills (/review-pr)	Structured workflow with parseable verdict output	Medium — agent follows recipe, hook parses output
Profiles (dev.md, qa.md)	Mention labels so agents understand workflow context	Weak — awareness only, not enforcement

Key insight: Hooks are the enforcement layer, not prompts. The forgejo-helper.sh already has curl patterns + credential loading. PostToolUse hooks run as shell scripts with full API access regardless of agent permissions. Agents don't need set_label MCP tools — the hooks handle it.

MCP Gap (discovered scope)

The forgejo-mcp server has NO set_label or comment_on_issue tools. This is why hooks are the right approach for now — they bypass the gap. A TODO for forgejo-mcp should be created to add these tools properly.

Hook Implementations

1. PostToolUse on mcp__forgejo__create_issue_and_branch:

• Extract owner, repo, issue number from tool input
• curl: set status:in-progress label on the issue
• Inject context: "Label status:in-progress set on issue #N"

2. PostToolUse on mcp__forgejo__submit_pr:

• Extract owner, repo from tool input; extract issue number from branch name or PR body
• curl: set status:qa label on the parent issue (replace any existing status label)
• curl: comment on the issue with PR URL ("PR #N submitted: [url]")
• Inject context: "Label status:qa set + PR linked on issue #N"
• Extends existing remind-mcp-review-loop.sh — or chains after it

3. PostToolUse on mcp__forgejo__comment_on_pr:

• Parse the comment body for verdict: look for "VERDICT: APPROVED" or "VERDICT: NOT APPROVED"
• If APPROVED: curl set status:approved label on parent issue, curl comment approval summary on issue
• If NOT APPROVED: curl set status:needs-fix label on parent issue, curl comment required fixes on issue
• If no verdict found: no-op (not all PR comments are review verdicts)

Skill Update: /review-pr

• Update skill-review-pr note to require VERDICT line in exact format: ### VERDICT: APPROVED or ### VERDICT: NOT APPROVED
• This makes the verdict parseable by the PostToolUse hook
• QA continues to comment on PRs (existing capability); hook mirrors findings to the issue

Profile Updates: dev.md + qa.md

• Add awareness section: "Hooks automatically set Forgejo labels when you use MCP tools"
• Dev: mention that status:in-progress and status:qa are set by hooks after create_issue_and_branch and submit_pr
• QA: mention that status:approved/status:needs-fix is set by hook based on VERDICT line in PR comment
• These are informational — the hooks enforce regardless

Helper Function Additions: forgejo-helper.sh

• forgejo_set_label() — set a label on an issue (replace existing status: labels)
• forgejo_comment_on_issue() — comment on an issue (not a PR)
• forgejo_get_issue_number_from_branch() — extract issue # from branch name pattern

Steps

1. Add helper functions to forgejo-helper.sh
2. Create label-on-branch.sh — PostToolUse hook for create_issue_and_branch
3. Create label-on-pr.sh — PostToolUse hook for submit_pr (chains with existing remind-mcp-review-loop.sh)
4. Create label-on-verdict.sh — PostToolUse hook for comment_on_pr
5. Register hooks in settings.json
6. Update skill-review-pr note — require parseable VERDICT format
7. Update dev.md and qa.md — awareness of label hooks
8. Test: spawn dev agent on a real issue, verify labels set automatically
9. Test: spawn QA agent, verify verdict parses and label sets

Deliverable: Every submit_pr automatically sets status:qa. Every QA verdict automatically sets status:approved or status:needs-fix. Every branch creation sets status:in-progress. All enforced by hooks — zero agent memory required.

Depends on: Phase 1 (labels exist on repos) — COMPLETED. Phase 2 (SOPs document the protocol) — COMPLETED.

Goal: SOPs document the full sprint workflow — label protocol, agent behavior, board sync — before any implementation begins.

Owner: Betty Sue (pal-e-docs notes, no repo code)

Repo: N/A — pal-e-docs notes only

Forgejo Issue: N/A (Betty Sue executed directly — docs work)

Deliverables (2026-03-03):

1. agent-workflow updated:
   • Added rule 6: "Agents signal status via labels"
   • Expanded "The Flow" from 8 to 12 steps — includes Sprint Item creation, label signaling, board sync
   • Added "Label Signaling Protocol" section — status labels table with DORA data column, type labels, rules
   • Added "Sprint Board Sync" section — label-to-column mapping table
2. pr-lifecycle updated:
   • Label steps added to Stages 1-4 (type labels at creation, status:in-progress at branch, status:qa at PR, status:approved/needs-fix at review)
   • Stage 5 added: Sprint Board Sync (Betty Sue reads labels, syncs columns, links PRs)
   • Stage 8 expanded: post-merge includes sprint item move to done, plan phase update, issue close
   • Mermaid diagram updated with QA agent and Betty Sue as participants
   • Documented QA comments on issues (not PRs) convention
3. template-sprint-item created:
   • Design principle: sprint items are commitment wrappers, not issues
   • Fields: Forgejo Issue URL, Title, Column
   • Label-to-column mapping table
   • Betty Sue's workflow: create, sync, link PR, close
   • Title convention: "{repo}: {short description}"

Depends on: Phase 1 (labels exist to reference in SOPs) — COMPLETED.

Goal: Standard status and type labels exist on all Forgejo repos, enabling agents to signal workflow state.

Owner: Betty Sue (Forgejo API calls, no repo code)

Repo: N/A — Forgejo API across all repos

Forgejo Issue: N/A (Betty Sue executed directly — no repo code involved)

Labels created:

Category	Label	Color	Purpose
Status	status:in-progress	#1d76db (blue)	Dev agent is actively working
Status	status:qa	#e4a224 (orange)	PR submitted, awaiting QA review
Status	status:needs-fix	#d93f0b (red)	QA found issues, back to dev
Status	status:approved	#0e8a16 (green)	QA passed, awaiting merge approval
Type	type:feature	#5319e7 (purple)	New functionality
Type	type:bug	#d93f0b (red)	Bug fix
Type	type:devops	#666666 (gray)	Infrastructure/CI/config work

Deliverables (2026-03-03):

• 7 labels created across 29 Forgejo repos (202 labels created, 1 skipped as pre-existing)
• All repos under forgejo_admin/ now have identical label sets
• Labels verified via Forgejo API — all returned HTTP 201

Depends on: Nothing — this was the foundation.

Goal: Expand sprint schema for five boards, human review gate, and item estimation.

Owner: Dev agent

Repo: forgejo_admin/pal-e-docs + forgejo_admin/pal-e-docs-mcp

Scope

1. repo/project item_types + needs_approval column — PR #67 merged (squash). Forgejo issue #66 (closed). DONE.
2. Points field on sprint items — PR #69 merged (squash). Nullable integer points on SprintItem. Forgejo issue #68 (closed). DONE.
3. MCP tool updates — PR #32 merged (squash, pal-e-docs-mcp). Forgejo issue #11 (closed). DONE. QA nits tracked as #33 and #34.

Decisions

Decision	Rationale
Points on items only, not plans/phases	Plans are containers, phases are organizational. Items (issues) are the unit of work. Velocity = sum of pointed items completed per sprint.
Points field is optional (nullable integer)	Not all items need points. Unpointed items are valid (e.g. backlog items not yet estimated).
Fibonacci scale (1/2/3/5/8)	Standard estimation scale. Calibrate as we go.
Separate PR for points (Option B)	PR #67 was already scoped. Don't add scope to unreviewed PRs.
Sprints = committed scope, not timebox	A sprint is a set of well-scoped items we commit to. Not a fixed timeline. Keep pushing until done, then close.

Status

• PR #67 (repo/project + needs_approval): MERGED. Issue #66 closed.
• PR #69 (points field): MERGED. Issue #68 closed.
• PR #32 (MCP tools update, pal-e-docs-mcp): MERGED. Issue #11 closed. QA nits: #33 (clear points/labels), #34 (verify bulk points).

Depends on: Phase 1 (tables + API) — COMPLETED

Goal: Sprint and SprintItem models with full CRUD API + MCP tools for Betty Sue to manage boards.

Owner: Dev agent

Repo: pal-e-docs + pal-e-docs-mcp

Forgejo Issues: forgejo_admin/pal-e-docs #64 (tables+API, merged), forgejo_admin/pal-e-docs-mcp #8 (MCP tools, PR #9 merged 2026-03-02)

Models:

• Sprint — id, name, slug, goal, start_date, end_date, status (planning/active/completed/archived), created_at
• SprintItem — id, sprint_id (FK, nullable for backlog), item_type (enum: plan/phase/issue), note_slug (nullable — for plans/phases), forgejo_issue_url (nullable — for issues), repo_slug (nullable — for issues), column (enum: backlog/todo/next_up/in_progress/qa/done), position (int), title_cache (string), created_at, updated_at

API routes (DEPLOYED):

• GET/POST /sprints
• GET/PATCH /sprints/{slug}
• DELETE /sprints/{slug}
• GET /sprints/{slug}/items?item_type=plan|phase|issue — the three boards
• POST /sprints/{slug}/items — add item to sprint
• PATCH /sprints/{slug}/items/{id} — move column/position
• PATCH /sprints/{slug}/items/bulk — multi-move
• DELETE /sprints/{slug}/items/{id}
• GET /sprints/backlog/items — items not in any active sprint

MCP tools (DEPLOYED — PR #9 merged 2026-03-02):

• create_sprint, get_sprint, list_sprints, update_sprint
• add_sprint_item, move_sprint_item, remove_sprint_item
• get_sprint_board — returns items filtered by item_type, grouped by column
• get_backlog, bulk_move_items

Key files: models.py, schemas.py, routes/sprints.py, main.py, alembic migration (pal-e-docs); tools/sprints.py (pal-e-docs-mcp)

Deliverable: Betty Sue can create a sprint, add plans/phases/issues to it, move them between columns, and query any of the three boards. VERIFIED — tools live in Claude Code session.

Goal: Unify keyword search (tsvector) and semantic search (pgvector) into a single endpoint with hybrid ranking, so agents get the best of both signals in one query.

Owner: Dev agent

Repo: forgejo_admin/pal-e-docs

Depends on: phase-postgres-6d-semantic-search (COMPLETED)

Scope

• Add mode parameter to GET /notes/search endpoint — values: keyword (default, current behavior), semantic, hybrid
• Implement hybrid ranking using Reciprocal Rank Fusion (RRF) — combines tsvector ts_rank and cosine similarity without needing score normalization
• Configurable alpha parameter for weighting between keyword and semantic relevance (default: 0.5)
• Results include score metadata so agents can assess relevance
• Backward compatible — omitting mode or using mode=keyword returns identical results to current behavior
• The /notes/semantic-search endpoint remains for now (deprecation is a separate decision)

Deliverables

• (to be filled after completion)

Related

• phase-postgres-6-vector-search — parent phase
• phase-postgres-6d-semantic-search — prerequisite (semantic search API)
• phase-postgres-5-fulltext-search — prerequisite (tsvector infrastructure)
• plan-2026-02-26-tf-modularize-postgres — parent plan

Goal: Add integration tests for the SDK semantic_search method to verify the full round-trip: SDK → API → Ollama → pgvector → response.

Owner: Dev agent

Repo: forgejo_admin/pal-e-docs-sdk

Depends on: phase-postgres-6d-semantic-search deliverable 2 (SDK method, PR #20)

Problem

The SDK's semantic_search method has unit tests (mock httpx) but no integration tests against a live instance. Semantic search has a unique dependency chain (SDK → API → Ollama → pgvector) that unit tests can't verify. The existing search_notes method has integration tests — semantic_search should too.

Fix

• Add integration tests to tests/integration/test_search.py (or new file) following the existing search_notes integration test pattern
• Verify: results returned, response shape has block-level fields (anchor_id, similarity, content_snippet), similarity scores are ranked

Related

• phase-postgres-6d-semantic-search — parent phase
• plan-2026-02-26-tf-modularize-postgres — parent plan

Goal: Add a semantic search endpoint so agents can find related knowledge by meaning (cosine similarity over pgvector embeddings), then expose it through the SDK and MCP tool.

Owner: Dev agent

Repo: forgejo_admin/pal-e-docs (API), forgejo_admin/pal-e-docs-sdk (SDK), forgejo_admin/pal-e-docs-mcp (MCP)

Depends on: phase-postgres-6c (async embedding pipeline — embeddings must exist in blocks table)

Why

Phase 6a deployed Ollama with GPU. Phase 6b added pgvector schema. Phase 6c built the embedding pipeline and backfilled 5K+ blocks. But there's no way to query those embeddings yet. This phase closes the loop — agents can ask a natural language question and get ranked, relevant blocks back without reading every document.

Scope

Three deliverables across three repos, executed sequentially (each depends on the previous):

#	Deliverable	Repo	Forgejo Issue	Status
1	API endpoint: GET /notes/semantic-search	pal-e-docs	#137	COMPLETED (PR #138)
2	SDK method: client.semantic_search(query, limit)	pal-e-docs-sdk	#18	COMPLETED (PR #20)
3	MCP tool: semantic_search	pal-e-docs-mcp	#29	COMPLETED (PR #30)

Architecture

Query flow: Agent calls MCP tool → SDK calls API → API embeds query via Ollama → cosine similarity search on blocks.embedding → return ranked blocks with note context.

The API endpoint mirrors GET /notes/search (tsvector) but operates at block granularity. Key differences:

• Queries the blocks table (not notes), joining to notes for context
• Uses pgvector <=> cosine distance operator (HNSW index: ix_blocks_embedding)
• Requires an Ollama call to embed the query text before searching
• Returns block-level results: anchor_id, block_type, content snippet, similarity score

Deliverables

• (filled after completion)

Related

• phase-postgres-6-vector-search — parent phase
• plan-2026-02-26-tf-modularize-postgres — parent plan
• decision-phase6-vector-search-architecture — embedding model research + architectural decisions
• phase-postgres-6c — embedding pipeline (prerequisite)

Goal: Clean up documentation debt accumulated during Act 2, harden SOPs for the four-agent model, ensure all notes are clean and well-attributed before Phase 6 vectorization, and automate post-merge documentation updates.

Owner: Betty Sue + Dottie

Repos: claude-custom (hooks/skills), pal-e-docs (app + doc content), pal-e-docs-mcp (API improvements)

Depends on: Phase 7e (compiled pages) — COMPLETED

Parent phase: Phase 7 (Block-Structured Content Model)

Critical context: Phase 6 (vector search) will embed blocks. Dirty data = dirty embeddings. This phase ensures every note has proper type, hierarchy, project, and anchor_ids before vectorization begins.

Sub-Phase Status

#	Sub-Phase	Slug	Status
7f-1	Deprecate issue-creator + issue-gate	phase-7f-1-deprecate-issue-creator	COMPLETED — PR #58 merged (claude-custom)
7f-2	Agent spawn requirements schema	phase-7f-2-agent-spawn-schema	COMPLETED
7f-3	Template drift fix (issue migration)	phase-postgres-7f-3-template-drift	COMPLETED
7f-4	Note attribute augmentation	phase-postgres-7f-4-attribute-augmentation	COMPLETED — 16-type taxonomy, 262 notes typed, issue archival (49 deleted), API enum (PR #116), project field (PR #118), Dottie audit (23 findings). Absorbed 7f-5 and 7f-6 deliverables.
7f-5	Documentation cleanup + TODO triage	absorbed by 7f-4	COMPLETED — 49 issue notes deleted, 22 TODO statuses fixed, 3 orphans resolved, pg_dump + JSON backup
7f-6	SOP review and consolidation	absorbed by 7f-4	COMPLETED — Dottie audit covered all 14 SOPs + 12 conventions. enforcement-architecture + sop-litestream-restore fixed. 1 empty convention deleted.
7f-7	Post-merge automation hook	phase-postgres-7f-7-post-merge-automation	COMPLETED — PR #72 merged (claude-custom). /update-docs slash command deployed. Old skills/update-docs/SKILL.md removed.

Why This Phase

Act 2 moved fast and docs drifted. Phase notes are stale, orphaned notes exist, SOPs don't match the four-agent model, and post-merge documentation is a manual SOP that gets skipped. This phase makes the knowledge base as clean as the code.

Added context (2026-03-08): Analysis revealed 83 untyped notes, 239 notes without parents, and ~307 notes with blocks that have null anchor_id (from the original backfill). The list_notes API also doesn't include the project field in summaries, making it impossible to compute orphan counts in one query. All of this must be fixed before Phase 6 vectorization.

Execution note (2026-03-08): 7f-4 session used aggressive parallelization (5 agents: 1 Dottie, 2 Dev, 2 QA). Dottie's full 262-note audit naturally covered 7f-5 (doc cleanup + TODO triage) and 7f-6 (SOP review) deliverables in a single pass. Plan structure assumed sequential execution; actual execution compressed three subphases into one.

Deliverables

1. Note attribute augmentation (7f-4)

Every note must have clean, queryable metadata before vectorization.

• Type all 83 untyped notes — Done: 262 notes, 16 types, zero nulls
• Re-save all notes — Done: parser re-run assigns anchor_ids
• Assign project — Done: 0 null projects
• Assign parents — Done: 3 orphans resolved
• Add project field to list_notes API summaries — Done: PR #118

2. Documentation cleanup + TODO triage (7f-5) — absorbed by 7f-4

• Delete old issue notes — Done: 49 deleted
• Review all 49 TODOs for staleness — Done: 22 statuses fixed by Dottie audit
• Ensure all notes have appropriate parents — Done: 3 orphans resolved, 0 null projects
• Backup Postgres before bulk cleanup — Done: pg_dump + JSON in MinIO

3. SOP review and consolidation (7f-6) — absorbed by 7f-4

• Review all 13 active SOPs for consistency with four-agent model — Done: Dottie audit + manual fixes
• Ensure issue scoping is documented — Done: agent-spawn-conventions updated
• Clean up any contradictions between SOPs — Done: enforcement-architecture, sop-litestream-restore fixed
• Verify all conventions are current — Done: 1 empty convention deleted

4. Post-merge automation (7f-7)

• /update-docs slash command — Done: commands/update-docs.md (PR #72)
• Old skill removed — Done: skills/update-docs/SKILL.md deleted (PR #72)
• Command deployed — Done: copied to ~/.claude/commands/

Acceptance Criteria

• Zero notes with null note_type — DONE (262 notes, 16 types)
• Zero blocks with null anchor_id — IN PROGRESS (re-save running)
• Every note assigned to a project — DONE (0 null projects)
• Zero orphaned notes without documented reason — DONE
• All TODOs reviewed — DONE (22 statuses fixed)
• SOPs consistent with four-agent model — DONE
• list_notes API includes project in summaries — DONE (PR #118)
• Post-merge hook fires automatically — DONE (/update-docs command + reminder hook)
• Knowledge base ready for Phase 6 vectorization — READY (pending anchor re-save completion)

Related

• sop-post-merge-docs — the SOP being automated
• skill-update-docs — the existing skill to be upgraded
• agent-workflow — must reflect four-agent model
• sop-postgres-restore — backup before cleanup
• todo-sveltekit-frontend-migration — depends on this phase completing
• phase-postgres-6-vector-search — blocked until this phase delivers clean data

Goal: Make blocks the canonical source of truth and optimize session injection to use block-level tools instead of full note reads. Estimated ~90% token reduction at session startup.

Owner: Dev agent (7e-1, 7e-2), Betty Sue (7e-3)

Repos: pal-e-docs (7e-1, 7e-1a, 7e-2), claude-custom (7e-3)

Depends on: Phase 7d (block API must exist) — COMPLETED

Parent phase: Phase 7 (Block-Structured Content Model)

Status: COMPLETED — all sub-phases done.

Sub-Phases

#	Sub-Phase	Repo	Status	Deliverable
7e-1	Source-of-Truth Cutover	pal-e-docs	COMPLETED	Blocks canonical — note writes parse to blocks first, then recompile. PR #110.
7e-1a	QA Nits Cleanup	pal-e-docs	COMPLETED	Redundant assignment fix, test helper hygiene. PR #114.
7e-2	Compiled Page API	pal-e-docs	COMPLETED	GET /notes/{slug}/compiled endpoint. PR #113. SDK + MCP follow-on deferred.
7e-3	Session Injection + Block-First Convention	claude-custom + pal-e-docs	COMPLETED	Hook injects plan TOCs (PR #68). Convention note, agent personalities, SOP updated. 91% token reduction measured.

What Was Delivered

• 7e-1: Extracted recompile() and parse_and_store_blocks() into shared blocks/sync.py. create_note() and update_note() now parse to blocks first, then recompile. 14 new tests, 503 total passing. PR #110.
• 7e-1a: QA nits — redundant html_content assignment, test helper session hygiene, detached ORM fix. PR #114.
• 7e-2: GET /notes/{slug}/compiled endpoint with CompiledPageOut schema (slug, title, html, toc_json, content_hash, block_count, compiled_at). 8 new tests. PR #113.
• 7e-3: Block-first established as platform convention:
  • Convention note: convention-block-first-access
  • Agent personalities updated: agent-betty-sue, agent-dottie — Knowledge Access sections added
  • SOP updated: agent-workflow — Rule 7 (block-first knowledge access) added
  • Session hook: session-start-context.sh injects plan TOCs inline. PR #68.
  • Re-backfill: 58 gap notes populated with blocks (307 total notes now have valid blocks)

Measured Results

Scenario	Before	After	Savings
Session startup (6 plans)	~11,640 tokens	~1,032 tokens	91.1%
Read one plan section	~2,360 tokens (full note)	~200 tokens (one section)	~92%
Update one plan section	~2,360 tokens (full note round-trip)	~100 tokens (block update)	~96%

Lessons Learned

• Merged ≠ deployed ≠ data consistent. 7e-1 fixed future writes but couldn't retroactively fix notes created between the 7c backfill and deployment. 58 notes had no blocks. Re-backfill was essential before 7e-3 could work.
• Test before shipping infrastructure changes. Testing the TOC endpoint revealed 2 of 6 plans had empty TOCs. Would have shipped broken hook without testing.
• Convention shifts need more than code. 7e-3 started as "change the hook" but became 4 deliverables: convention note, agent personalities, SOP, hook. The pattern must be encoded everywhere agents get their instructions.

Related

• convention-block-first-access — the convention established by 7e-3
• decision-7e3-block-first-access — decision record with rationale
• phase-postgres-7d-api-mcp-tools — block API (prerequisite, COMPLETED)
• phase-postgres-8-mcp-optimization — SDK + MCP tools (prerequisite, COMPLETED)
• benchmark-phase7-block-baseline — baseline token measurements
• plan-2026-03-01-pal-e-sprints-frontend — sprint frontend consumes compiled pages (7e-2 SDK/MCP deferred until then)

Goal: Decompose real plans. Measure token savings vs baselines. Prove it works.

Status: COMPLETE — 2026-03-02

Done:

• Decomposed Note Decomposition plan into 5 child phase notes
• Decomposed pal-e-sprints plan into 3 child phase notes
• Decomposed Knowledge System Consolidation plan into 6 child phase notes
• Decomposed Platform Observability plan into 5 child phase notes
• All 4 active plans now decomposed (19 total child phases created)
• All parent plans slimmed to ~2KB summaries pointing to child phases
• Proved queries work: list_notes(note_type="phase", status="in-progress") = 1KB/1 call (was 193KB/12 calls)
• Proved phase update works: update_note(slug, status) = 0.5KB/1 call (was 39KB/2 calls)

Measured Results:

Story	Before	After	Savings
Update phase status	39KB, 2 calls	0.5KB, 1 call	98.7%
Query in-progress phases	193KB, 12 calls	1KB, 1 call	99.5%
Read plan summary	15KB	2KB	86.7%

Remaining: PR #63 deploy + browser verification (tracked separately — not blocking plan completion).

Goal: Add typed SDK methods for all sprint API endpoints, enabling the Phase 8f MCP rewrite to cover sprint management -- Betty Sue's primary daily workflow.

Owner: Dev agent

Repo: forgejo_admin/pal-e-docs-sdk

Depends on: 8a (SDK core)

Why

Sprint management is Betty Sue's most frequent workflow. Every session starts with checking the board, every phase completion moves items. The current MCP tools (10 tools in pal-e-docs-mcp/tools/sprints.py) use raw httpx. Without SDK coverage, the Phase 8f MCP rewrite can't cover sprints, leaving an inconsistent architecture and no integration test coverage for sprint operations.

Agent Workflows This Enables

Workflow	When	SDK Methods Used
Sprint planning	Start of sprint	create_sprint, add_sprint_item × N
Session check-in	Every session start	list_sprints(status=), get_sprint_board(item_type=, column=)
Work tracking	During session	move_sprint_item, update_sprint_item
Backlog grooming	Between sprints	get_backlog, add_sprint_item, remove_sprint_item
Sprint close	End of sprint	update_sprint(status=completed), bulk_move_items

API → SDK → MCP Mapping

#	API Endpoint	SDK Method	MCP Tool (8f)
1	GET /sprints	list_sprints(status=)	list_sprints
2	POST /sprints	create_sprint(...)	create_sprint
3	GET /sprints/{slug}	get_sprint(slug)	get_sprint
4	PATCH /sprints/{slug}	update_sprint(slug, ...)	update_sprint
5	DELETE /sprints/{slug}	delete_sprint(slug)	None (destructive, no MCP by design)
6	GET /sprints/backlog/items	get_backlog(item_type=)	get_backlog
7	GET /sprints/{slug}/items	list_sprint_items(slug, item_type=, column=)	get_sprint_board
8	POST /sprints/{slug}/items	add_sprint_item(slug, ...)	add_sprint_item
9	PATCH /sprints/{slug}/items/{id}	update_sprint_item(slug, item_id, ...)	move_sprint_item (subset)
10	DELETE /sprints/{slug}/items/{id}	delete_sprint_item(slug, item_id)	remove_sprint_item
11	PATCH /sprints/{slug}/items/bulk	bulk_move_items(slug, items)	bulk_move_items

Implementation Notes

• update_sprint uses PATCH (not PUT like notes) -- only send non-None fields
• update_sprint_item uses PATCH with explicit null handling for points and labels (server uses model_fields_set)
• delete_sprint and delete_sprint_item return None (204)
• create_sprint has required fields: name, slug, status. Optional: goal, start_date, end_date
• add_sprint_item has validation: plan/phase/todo require note_slug, issue requires forgejo_issue_url

Deliverables

• src/pal_e_docs_sdk/sprints.py -- SprintsMixin with 11 methods
• tests/test_sprints.py -- httpx-mocked unit tests covering all methods
• client.py updated -- SprintsMixin in PalEDocsClient MRO

Related

• plan-2026-03-01-pal-e-sprints -- the sprint backend plan
• phase-postgres-8-mcp-optimization -- parent phase (SDK + MCP Rewrite)
• plan-2026-03-03-sprint-workflow-automation -- agent behavior built on sprint backend

Goal: Apply the _UNSET sentinel pattern to update_sprint optional fields (goal, start_date, end_date) so callers can explicitly clear them to null, matching the pattern already used in update_sprint_item.

Owner: Dev agent

Repo: forgejo_admin/pal-e-docs-sdk

Depends on: 8d (sprint mixin merged)

Problem

update_sprint_item uses a sentinel (_UNSET = object()) for points and labels, allowing callers to distinguish "don't send this field" from "clear this field to null." But update_sprint uses plain None defaults for goal, start_date, end_date, so there's no way to explicitly clear those fields. This is an asymmetry in the API surface.

Fix

• Change update_sprint optional fields to use _UNSET sentinel
• Add tests verifying explicit null is sent when None is passed

Related

• phase-postgres-8d-sdk-sprints -- parent phase where this was identified
• QA finding on PR #8

Goal: Add integration tests that run the SDK against the live pal-e-docs service, verifying all 8 endpoint families work end-to-end. These tests become the foundation for Phase 8g (CI smoke tests).

Owner: Dev agent

Repo: forgejo_admin/pal-e-docs-sdk

Depends on: 8b, 8c, 8d (all completed)

Scope

8 endpoint families × key methods = ~20-30 integration tests in tests/integration/. Read-only tests against known production data. No destructive operations (no delete, no create that leaves garbage).

Endpoint Families

Family	Mixin	Key Methods to Test
Notes	NotesMixin	get_note, list_notes
Search	SearchMixin	search_notes
Tags	TagsMixin	list_tags
Projects	ProjectsMixin	list_projects, get_project
Links	LinksMixin	get_note_links
Repos	ReposMixin	list_repos
Blocks	BlocksMixin	get_note_toc, get_note_blocks, get_section
Sprints	SprintsMixin	list_sprints, get_sprint, get_sprint_board, get_backlog

Baseline Assertions

• Notes count > 270
• Blocks count > 5000 (Phase 7c backfill)
• Search for "CNPG" returns sop-secrets-management
• TOC for the plan note has > 8 headings
• Sprint 2 exists and has items

Test Infrastructure

• tests/integration/conftest.py — live_client fixture using PALDOCS_BASE_URL env var
• pytest.ini or pyproject.toml marker: integration so unit tests still run fast without the env var
• Run command: PALDOCS_BASE_URL=https://pal-e-docs.tail5b443a.ts.net pytest tests/integration/ -v

Related

• phase-postgres-8-mcp-optimization — parent phase with example tests
• qa-phase7c-backfill-2026-03-07 — baseline data the tests verify

Goal: Get pal-e-docs-sdk published to Forgejo PyPI so the MCP server can depend on it as a registry package.

Owner: Dev agent

Repo: forgejo_admin/pal-e-docs-sdk

Depends on: 8e (SDK code complete and tested)

Scope

The SDK repo has a .woodpecker.yaml with lint + test + publish steps, but the repo was never activated in Woodpecker. The publish pipeline has never run. The package is not on Forgejo PyPI (14 packages listed, pal-e-docs-sdk not among them). This sub-phase activates the pipeline and verifies end-to-end publish.

Blocks: 8f-2 — MCP server's pyproject.toml can't resolve pal-e-docs-sdk>=0.1.0 without this.

Progress

• Woodpecker activated — repo ID 26, responding to push/pull_request events
• Secrets configured — paldocs_base_url repo secret created; global PyPI secrets already available
• PR #15 merged — ruff formatting fix. QA approved. Squash merged to main.
• Forgejo issue #14 — created by dev agent for the formatting fix
• Pipeline #4 running — push-to-main with publish step. Awaiting completion.

Remaining

• Verify pipeline #4 passes (lint + test + publish)
• Verify pal-e-docs-sdk v0.1.0 appears on Forgejo PyPI
• Verify pip install from Forgejo PyPI works

Deliverables

• Woodpecker repo activation (ID 26)
• Repo secret: paldocs_base_url
• PR #15 — ruff formatting fix (merged)
• Forgejo issue #13 (original), #14 (formatting fix by dev agent)

Related

• phase-postgres-8f-mcp-rewrite — parent sub-phase
• todo-forgejo-pypi — Forgejo PyPI pattern (status: done)
• phase-postgres-8f2-mcp-rewrite-core — blocked by this

Goal: Rewrite server.py, rewrite all 26 existing tools to SDK wrappers, add 7 new tools (6 block + delete_sprint). Achieve 32/32 SDK coverage. Bump version to fix publish pipeline.

Owner: Dev agent

Repo: forgejo_admin/pal-e-docs-mcp

Depends on: 8f-1 (SDK must be published and importable)

Scope

server.py changes

1. Replace import httpx with from pal_e_docs_sdk import PalEDocsClient, PalEDocsError, NotFoundError, ValidationError, ServerError
2. get_client() → get_sdk() — returns PalEDocsClient instead of httpx.Client
3. _ok(response: httpx.Response) → _ok(data: Any) — takes parsed data from SDK, returns json.dumps(data, indent=2). Returns {"ok": true} for None.
4. _error_response() — catch PalEDocsError hierarchy instead of httpx.HTTPStatusError. Extract exc.status_code and exc.detail.

pyproject.toml changes

1. Replace httpx>=0.27 with pal-e-docs-sdk>=0.1.0
2. Bump version from 0.1.0 → 0.2.0 (fixes publish pipeline #31 failure)
3. Add Forgejo PyPI index configuration

26 existing tools rewritten

Each tool: validate/transform MCP params → get_sdk().method() → _ok(result). Try/except catches SDK exceptions.

Simple (~5 lines): get_note, delete_note, get_note_revisions, get_note_links, list_projects, list_tags, list_repos, get_sprint, list_sprints, remove_sprint_item, get_backlog, get_sprint_board (12 tools)

Param bridging (~8-10 lines): create_note, update_note, search_notes, update_note_links, create_sprint, update_sprint, add_sprint_item, move_sprint_item, bulk_move_items, list_notes, create_project, create_repo, update_repo (14 tools)

7 new tools

Tool	SDK Method	Purpose
get_note_toc	get_note_toc(slug)	Browse note heading structure. ~200 tokens vs ~5000.
list_blocks	list_blocks(slug)	List all blocks with types and anchors.
get_section	get_section(slug, anchor_id)	Read one heading + content blocks. The surgical read.
update_block	update_block(slug, anchor_id, ...)	Edit one block without rewriting the note.
create_block	create_block(slug, ...)	Insert a block at a position.
delete_block	delete_block(slug, anchor_id)	Remove a block.
delete_sprint	delete_sprint(slug)	Full sprint lifecycle. DB is backed up.

New file: tools/blocks.py + tools/__init__.py update

6 block tools in new file. Register in register_all_tools().

Deliverables

• To be filled after completion

Related

• phase-postgres-8f-mcp-rewrite — parent sub-phase
• phase-postgres-8f1-sdk-publish — must be done first
• phase-postgres-8f3-param-alignment — verifies the param bridging done here

Goal: Verify and resolve all parameter mismatches between MCP tool signatures and SDK method signatures. Ensure no existing agent workflow breaks.

Owner: Dev agent

Repo: forgejo_admin/pal-e-docs-mcp

Depends on: 8f-2 (tools must be rewritten first)

Scope

MCP tools were designed for AI agents (string params, CSV lists, optional everything). SDK methods were designed for Python developers (typed params, list[str], some required). The rewrite in 8f-2 introduced translation layers in the MCP wrappers. This sub-phase verifies all translations are correct, backward-compatible, and handles edge cases.

Audit Results (2026-03-07)

Betty Sue audited every MCP tool on origin/main (commit 2c41b7a) against every SDK method signature. Found 8 documented mismatches (all implemented correctly) plus 5 additional items.

8 Documented Mismatches — All Verified

#	MCP Tool	Mismatch	Resolution	Verified
1	search_notes	MCP query → SDK q	Passed as positional arg to get_sdk().search_notes(query, ...)	YES
2	create_note / update_note	MCP content → SDK html_content	html_content=content in both tools	YES
3	create_note / update_note	MCP project → SDK project_slug	project_slug=project in both tools	YES
4	create_note / update_note	MCP tags CSV → SDK list[str]	[t.strip() for t in tags.split(",")]	YES
5	update_note_links	MCP target_slugs CSV → SDK list[str]	[s.strip() for s in target_slugs.split(",")]	YES
6	create_sprint	SDK requires status, MCP optional	status=status or "planning"	YES
7	add_sprint_item	SDK requires position; labels CSV→list	position=0 hardcoded; [l.strip() for l in labels.split(",")]	YES
8	bulk_move_items	MCP items JSON string → SDK list[dict]	json.loads(items) with JSONDecodeError handling	YES

5 Additional Findings

#	Type	Tool	Finding	Risk
9	Translation	update_sprint	Uses _UNSET sentinel from SDK for goal, start_date, end_date. Passes None for name and status (correct — SDK uses None for "don't send" on those).	LOW — correctly implemented
10	Translation	move_sprint_item → update_sprint_item	MCP tool name move_sprint_item maps to SDK method update_sprint_item. Also uses _UNSET sentinel for labels.	LOW — correct but undocumented name mapping
11	Missing param	add_sprint_item	SDK has points param, MCP doesn't expose it. Not a bug — just not exposed to agents yet.	NONE — intentional omission for now
12	Edge case	create_note	Old MCP sent "tags": [] when tags not provided. New MCP sends tags=None to SDK. If API treats missing tags differently from empty list, this is a behavioral regression.	MEDIUM — needs live test
13	Edge case	add_sprint_item	Labels uses if labels else None (falsy check). Empty string "" treated as "no labels" — correct, but differs from if labels is not None pattern elsewhere.	LOW — empty string is never a valid label input

Backward Compatibility Rules

• No MCP tool param names change
• No required params become optional or vice versa (except adding defaults for newly-required SDK params)
• CSV string convention stays — it's the agent interface contract
• Error response format unchanged: {"error": true, "status_code": N, "detail": ...}

Verification Plan

• Live test #12: Call create_note without tags, verify the API receives it correctly and no tags are applied. Compare with old behavior ("tags": []).
• CSV edge cases: Trailing commas, whitespace, empty strings for tools #4, #5, #7.
• Sentinel handling: Verify update_sprint only sends explicitly-provided fields (not null for unset sentinel fields).
• Test with actual MCP tool invocations via Claude — the real consumer.

Issue Scope (for Forgejo issue)

Items #12 is the only one that may require a code change. Items #9-11, #13 are documentation/verification only. The 8 documented mismatches are verified-correct and need no changes.

Recommended issue deliverables:

1. Live test for #12 (tags=None vs tags=[])
2. Fix if behavioral regression confirmed
3. CSV edge case tests for #4, #5, #7 (trailing comma, whitespace)
4. Document #10 (method name mapping) in code comment

Deliverables

• To be filled after completion

Related

• phase-postgres-8f-mcp-rewrite — parent sub-phase
• phase-postgres-8f2-mcp-rewrite-core — the rewrite these translations live in

Goal: Address non-blocking QA nits from PR #23 review (Phase 8f-2).

Owner: Dev agent

Repo: forgejo_admin/pal-e-docs-mcp

Depends on: 8f-2 (PR #23 merged)

Problem

QA review of PR #23 found 4 non-blocking nits. 1 was a false positive (nit 1 — __init__.py exists). 2 are worth fixing. 1 is text-only (corrected in phase note).

Fix

• Nit 2: Add .claude/ to .gitignore — Safety measure to prevent worktree artifacts from being staged.
• Nit 4: Rename l → lbl in sprints.py — Lines 162 and 199 use l as loop variable in CSV split comprehensions, triggering E741 ambiguous variable name lint. Rename to lbl and remove noqa comments.

Not fixing:

• Nit 1 (false positive — __init__.py already exists)
• Nit 3 (tool count text — corrected in phase note, not a code issue)

Deliverables

• To be filled after completion

Related

• phase-postgres-8f-mcp-rewrite — parent sub-phase
• phase-postgres-8f2-mcp-rewrite-core — PR #23 that surfaced these nits

Goal: Rewrite all 26 MCP tools to wrap SDK methods instead of raw httpx. Add 7 new tools (6 block + delete_sprint). Achieve 32/32 SDK method coverage. Reduce tool code from ~794 lines to ~250 lines.

Owner: Dev agent

Repo: forgejo_admin/pal-e-docs-mcp

Depends on: 8e (integration tests verify SDK works against live service)

Vision

The MCP server is the capability boundary of the AI Agency. Agents can only do what MCP tools allow. Today, 6 block SDK methods exist with no MCP tools — agents can't do block-level operations. This phase removes that bottleneck and delivers the primitives that skills (sprint-sync, update-docs, implement-phase) will compose into token-efficient workflows.

After 8f: every SDK method has an MCP tool. 100% coverage. The skill design space opens up — skills can browse TOCs, read individual sections, update single blocks instead of downloading and rewriting entire notes.

Sub-Phases

#	Sub-Phase	Slug	What	Status
8f-1	SDK Publish Pipeline	phase-postgres-8f1-sdk-publish	Activate pal-e-docs-sdk in Woodpecker, verify publish to Forgejo PyPI, configure MCP server to resolve SDK from registry	COMPLETED
8f-2	MCP Rewrite Core	phase-postgres-8f2-mcp-rewrite-core	Rewrite server.py + all 26 existing tools + add 7 new tools. PR #23 merged. v0.2.0 published.	COMPLETED
8f-3	Param Alignment Audit	phase-postgres-8f3-param-alignment	Verified 13 param translations (8 documented + 5 discovered). Fixed tags=None edge case. 25 tests. PR #25 merged.	COMPLETED
8f-4	QA Nits Cleanup	phase-postgres-8f4-qa-nits	.gitignore + l→lbl E741 rename. Batched into PR #25.	COMPLETED

SDK Coverage Target: 32/32

Mixin	SDK Methods	MCP Tools Before	MCP Tools After
NotesMixin (6)	list, get, create, update, delete, revisions	6/6	6/6
SearchMixin (1)	search_notes	1/1	1/1
BlocksMixin (6)	get_note_toc, list_blocks, get_section, update_block, create_block, delete_block	0/6	6/6
SprintsMixin (11)	list, create, get, update, delete, backlog, list_items, add_item, update_item, delete_item, bulk_move	10/11	11/11
LinksMixin (2)	get_note_links, update_note_links	2/2	2/2
ProjectsMixin (2)	list, create	2/2	2/2
ReposMixin (3)	list, create, update	3/3	3/3
TagsMixin (1)	list_tags	1/1	1/1
Total	32	25/32	32/32

Architectural Changes

1. server.py: get_client() → get_sdk() — Swap httpx.Client for PalEDocsClient from SDK
2. server.py: _ok(response) → _ok(data) — Takes parsed dict/list from SDK, not httpx.Response. Follows woodpecker-mcp pattern.
3. server.py: _error_response() — Catches PalEDocsError and subclasses (NotFoundError, ValidationError, ServerError) instead of httpx.HTTPStatusError
4. pyproject.toml — Replace httpx>=0.27 with pal-e-docs-sdk>=0.1.0. Configure Forgejo PyPI index.
5. tools/__init__.py — Add blocks module registration

Param Translation Map (13 items — audited 2026-03-07)

See phase-postgres-8f3-param-alignment for the full audit. All 13 verified correct or fixed. Edge case #12 (tags=None) fixed in PR #25. CSV hardening (trailing comma filter) applied across notes.py, sprints.py, links.py.

Reference Pattern

woodpecker-mcp wrapping woodpecker-sdk is the proven pattern. Key differences: _ok(data: Any) instead of _ok(response: httpx.Response), SDK client instead of httpx.Client, typed exceptions instead of HTTP status errors.

Skill Impact (delivered by 8f, consumed by 7f + Epilogue)

8f delivers the block-level primitives. Downstream phases rewire skills to use them:

Skill	Current Pattern	Enabled by 8f	Rewired in
/update-docs	get_note ×4 (~20K tokens)	get_section ×4 (~2K tokens)	7f
/implement-phase	get_note ×4 (~20K tokens)	get_toc + get_section (~1.4K tokens)	Epilogue item 3
/sprint-sync	No block need	No change needed	N/A
Session injection	4× get_note (~8.7K tokens)	get_toc + get_section (~400 tokens)	Epilogue item 3

Related

• phase-postgres-8-mcp-optimization — parent phase
• phase-postgres-8e-integration-tests — proves SDK works against live service
• phase-postgres-7d-api-mcp-tools — block API endpoints the new tools wrap
• phase-postgres-7f-doc-cleanup-sop — consumes block tools for skill rewrites
• phase-postgres-epilogue-cleanup — item 3 consumes block tools for session upgrade
• todo-forgejo-pypi — Forgejo PyPI pattern (established, SDK not yet published)

Goal: Add a post-deploy smoke test step to the pal-e-docs Woodpecker pipeline that automatically verifies the live service is healthy after every deploy to main.

Owner: Dev agent

Repo: forgejo_admin/pal-e-docs-sdk (smoke module), forgejo_admin/pal-e-docs (pipeline step)

Depends on: 8f (SDK published on Forgejo PyPI, all endpoints covered)

Scope

Two deliverables across two repos:

1. Smoke test module in pal-e-docs-sdk — src/pal_e_docs_sdk/smoke_test.py. Runnable as python -m pal_e_docs_sdk.smoke_test. Hits 5 key endpoints, asserts minimum counts, exits 0/1/2. Includes retry loop for ArgoCD sync delay.
2. Pipeline step in pal-e-docs — new smoke-test step in .woodpecker.yaml after update-deployment-tag. Installs SDK from Forgejo PyPI, runs smoke module against internal service URL.

This completes Phase 8 (SDK + MCP Rewrite + Integration Tests). After 8g, the full stack has: typed SDK → integration tests → MCP tools → post-deploy smoke tests.

Why

Today there is zero automated verification that a deploy actually works. The Phase 5 deployment outage (incident-phase5-deployment-outage-2026-03-06) was discovered by manually curling endpoints. The pipeline that builds should be the pipeline that verifies — don't call it done until you've proven it works.

Design Decisions

Decision	Rationale
Smoke module lives in SDK repo	Uses SDK methods directly. Published with the package. Runnable as python -m pal_e_docs_sdk.smoke_test.
Pipeline step lives in pal-e-docs repo	That's where .woodpecker.yaml is. The step installs SDK and runs the module.
Internal service URL	http://pal-e-docs.pal-e-docs.svc.cluster.local:8000. No Tailscale/TLS dependency. Pipeline runs in-cluster.
Retry loop in smoke module	ArgoCD sync is async (30s-90s after tag update). Module waits 30s initial, then retries up to 5 times at 15s intervals. Total window: ~105s.
Health verification, not version check	Verify the service is up and returning correct data. No /version endpoint needed. Simpler, sufficient.
In-pipeline verification (Option A)	Enterprise pattern. The pipeline that builds is the pipeline that verifies. Tight feedback loop. No detection delay.

Smoke Test Endpoints

Check	SDK Call	Assertion	What It Proves
API up + DB connected	list_notes()	count > 200	FastAPI serving, SQLAlchemy connected, notes table populated
Full-text search	search_notes("postgres")	results > 0	tsvector index working, search endpoint functional
Block content	get_note_toc("plan-2026-02-26-tf-modularize-postgres")	headings >= 5	Blocks table populated, TOC endpoint functional
Sprint tables	list_sprints()	count >= 1	Sprint schema intact, endpoint functional
Tags	list_tags()	count > 5	Tags table, lightweight health check

Smoke Module Design

# pal_e_docs_sdk/smoke_test.py
"""Post-deploy smoke test. Run as: python -m pal_e_docs_sdk.smoke_test

Env vars:
  PALDOCS_BASE_URL  — service URL (default: http://localhost:8000)

Exit codes:
  0 — all checks passed
  1 — one or more checks failed
  2 — could not connect after retries
"""
import sys, time
from pal_e_docs_sdk import PalEDocsClient

MAX_RETRIES = 5
RETRY_DELAY = 15  # seconds
INITIAL_WAIT = 30  # seconds — ArgoCD sync time

def run() -> bool:
    client = PalEDocsClient()
    notes = client.list_notes()
    assert len(notes) > 200, f"Expected >200 notes, got {len(notes)}"
    results = client.search_notes("postgres")
    assert len(results) > 0, "Search returned no results"
    toc = client.get_note_toc("plan-2026-02-26-tf-modularize-postgres")
    assert len(toc) >= 5, f"Expected >=5 TOC entries, got {len(toc)}"
    sprints = client.list_sprints()
    assert len(sprints) >= 1, "No sprints found"
    tags = client.list_tags()
    assert len(tags) > 5, f"Expected >5 tags, got {len(tags)}"
    return True

def main():
    time.sleep(INITIAL_WAIT)
    for attempt in range(1, MAX_RETRIES + 1):
        try:
            run()
            print(f"Smoke test PASSED (attempt {attempt})")
            sys.exit(0)
        except ConnectionError:
            if attempt < MAX_RETRIES:
                print(f"Attempt {attempt}/{MAX_RETRIES}: connection failed, retrying...")
                time.sleep(RETRY_DELAY)
        except AssertionError as e:
            print(f"Smoke test FAILED: {e}")
            sys.exit(1)
    print(f"Could not connect after {MAX_RETRIES} attempts")
    sys.exit(2)

Pipeline Step

# In pal-e-docs/.woodpecker.yaml, after update-deployment-tag:
  - name: smoke-test
    image: python:3.12-slim
    environment:
      PALDOCS_BASE_URL: "http://pal-e-docs.pal-e-docs.svc.cluster.local:8000"
      FORGEJO_PYPI_URL: "http://forgejo-http.forgejo.svc.cluster.local/api/packages/forgejo_admin/pypi/simple/"
    commands:
      - pip install --index-url $$FORGEJO_PYPI_URL pal-e-docs-sdk
      - python -m pal_e_docs_sdk.smoke_test
    when:
      - event: push
        branch: main

Execution Order

Two repos means two PRs in sequence:

1. PR on pal-e-docs-sdk: Add smoke_test.py + __main__.py wiring. Bump version to 0.2.0. Merge → publishes to PyPI.
2. PR on pal-e-docs: Add smoke-test step to .woodpecker.yaml. Merge → next deploy triggers smoke test.

Risks

• ArgoCD sync delay: If sync takes longer than 105s window, smoke test exits 2. Can tune INITIAL_WAIT and MAX_RETRIES.
• Forgejo PyPI in-cluster access: Pipeline already uses forgejo-http.forgejo.svc.cluster.local for git clone. PyPI should work the same way.
• SDK version mismatch: Smoke test installs latest SDK. If SDK has breaking change, smoke fails even though API is fine. Low risk — we control both.

Deliverables

• To be filled after completion

Related

• phase-postgres-8-mcp-optimization — parent phase
• phase-postgres-8f-mcp-rewrite — SDK must be published (done)
• phase-postgres-8e-integration-tests — smoke test is a subset of integration tests, tuned for post-deploy
• incident-phase5-deployment-outage-2026-03-06 — the incident that motivates this

Goal: Expose block-level read/write operations via new API endpoints and MCP tools. Enable agents to read one section, update one section, and navigate via TOC — without touching the full document.

Owner: Dev agent

Repos: pal-e-docs (API endpoints), pal-e-docs-mcp (MCP tools)

Depends on: Phase 7c (blocks populated in DB)

Parent phase: Phase 7 (Block-Structured Content Model)

Why This Phase

Blocks exist in the database but agents can't use them yet. This phase adds the API and MCP surface that makes block-level access real. This is where the token savings become measurable.

New API Endpoints

Endpoint	Method	What It Does
/notes/{slug}/toc	GET	Returns heading blocks only — note's table of contents with anchor IDs
/notes/{slug}/blocks	GET	Returns all blocks for a note (ordered by position)
/notes/{slug}/blocks/{anchor_id}	GET	Returns a single block (or section: heading + content blocks until next heading)
/notes/{slug}/blocks/{anchor_id}	PUT	Updates a single block's content. Triggers recompile of compiled_page.
/notes/{slug}/blocks	POST	Insert a new block at a given position. Triggers recompile.
/notes/{slug}/blocks/{anchor_id}	DELETE	Remove a block. Triggers recompile.

New MCP Tools (pal-e-docs-mcp)

Tool	Wraps	Token Impact
get_note_toc(slug)	GET /notes/{slug}/toc	~50 tokens vs ~2,360 for get_note (plan avg)
get_block(slug, anchor_id)	GET /notes/{slug}/blocks/{anchor_id}	~200 tokens vs ~2,360 for get_note
update_block(slug, anchor_id, content)	PUT /notes/{slug}/blocks/{anchor_id}	~100 tokens vs ~2,360 for update_note
create_block(slug, block_type, content, after_anchor)	POST /notes/{slug}/blocks	Targeted insertion without full rewrite
delete_block(slug, anchor_id)	DELETE /notes/{slug}/blocks/{anchor_id}	Targeted deletion without full rewrite

Backward Compatibility

• get_note continues to return html_content as before
• update_note with html_content continues to work — internally re-parses into blocks and recompiles
• New tools are additive — agents can gradually adopt block-level access
• On block write (update/create/delete): recompile compiled_pages.html and update html_content on the note (keeps both in sync)

Acceptance Criteria

• All 6 API endpoints working with tests
• All 5 MCP tools deployed and functional
• get_note_toc returns heading structure for a plan in ~50 tokens
• get_block returns one section of a plan in ~200 tokens
• update_block updates one section without touching others
• Block writes trigger recompile of compiled_pages and html_content
• Existing get_note/update_note behavior unchanged

Benchmark Target

Run Phase 7 benchmark re-test after this phase ships. Compare against benchmark-phase7-block-baseline:

• Targeted read: 2,360 tokens → ~200 tokens (target: 92% reduction)
• Targeted update: 2,360 tokens → ~100 tokens (target: 96% reduction)
• TOC navigation: 2,360 tokens → ~50 tokens (target: 98% reduction)

Related

• phase-postgres-7c-backfill-migration — blocks must be populated
• phase-postgres-8-mcp-optimization — Phase 8 builds on these tools
• benchmark-phase7-block-baseline — baseline for re-test

Goal: Replace HTML blob storage with typed content blocks. Enable compiled pages, per-section search, stable anchors, deterministic rendering, and flexible note hierarchy.

Owner: Dev agent

Repo: pal-e-docs, pal-e-docs-mcp

Depends on: Phase 5 (full-text search) — COMPLETED

Status: IN PROGRESS — 7a, 7b, 7c, 7d COMPLETED. 7f-1, 7f-2, 7f-3 COMPLETED. 7e NEXT.

Why

HTML blobs are opaque. You can't search within them meaningfully, can't deep-link to sections, can't reuse content across pages, can't generate a TOC, and can't embed per-section for AI retrieval. Blocks fix all of this. See benchmark-phase7-block-baseline for the quantitative case.

Key Data (from baseline)

• 256 notes, 1.09M chars (~272K tokens total corpus)
• 84% have 4+ sections — would benefit from block-level access
• Plans avg 9,441 chars — the largest type, most read, biggest savings target
• 6 orphaned docs can't nest under phases due to type restriction
• Estimated savings: 92% per targeted read, 96% per update, 95% session startup

Sub-Phases

#	Sub-Phase	Slug	Depends On	Status	Deliverable
7a	Schema + Hierarchy Relaxation	phase-postgres-7a-schema-hierarchy	Phase 5	COMPLETED	blocks + compiled_pages tables, any-to-any hierarchy
7b	Parser + Compiler	phase-postgres-7b-parser-compiler	7a	COMPLETED	HTML→blocks parser (6 types), blocks→HTML compiler, 121 tests. PR #97, #99.
7c	Backfill Migration	phase-postgres-7c-backfill-migration	7a, 7b	COMPLETED	274 notes → 5,197 blocks + 274 compiled pages. QA verified. See qa-phase7c-backfill-2026-03-07.
7d	Block API + MCP Tools	phase-postgres-7d-api-mcp-tools	7c	COMPLETED	6 API endpoints (toc, list, get_section, update, create, delete), 6 MCP tools, recompilation on write
7e	Compiled Page Architecture	phase-postgres-7e-compiled-pages	7d	NOT STARTED	Source-of-truth cutover (7e-1) + session injection optimization (7e-3). 7e-2 (compiled page API) DEFERRED.
7f	Doc Cleanup + SOP Hardening	phase-postgres-7f-doc-cleanup-sop	7e	IN PROGRESS (7f-1, 7f-2, 7f-3 COMPLETED)	Doc debt cleanup, post-merge automation, SOP review

Note: The original 7e (Per-Block Search + Hashing, phase-postgres-7e-block-search-optimization) has been renumbered. The sub-phases above reflect the current sequence.

Dependency Chain

graph LR
    P5[Phase 5 DONE] --> P7a[7a Schema
+ Hierarchy
DONE]
    P7a --> P7b[7b Parser
+ Compiler
DONE]
    P7a --> P7c[7c Backfill
DONE]
    P7b --> P7c
    P7c --> P7d[7d Block API
+ MCP Tools
DONE]
    P7d --> P7e[7e Compiled
Pages]
    P7e --> P7f[7f Doc Cleanup
+ SOP]
    P7e --> P6[Phase 6
pgvector]

User Stories

#	Story	Sub-Phase
A3	As an agent, I can read one section of a note without fetching the entire document	7d ✓
A4	As an agent, I can update one section without rewriting the entire document	7d ✓
A5	As an agent, I can see a note's TOC and jump to the right section	7d ✓
K1	Concept docs, benchmarks, incidents nest under the phase they belong to	7a + 7c ✓
H1	As Lucas, I can see a table of contents on long documents	7c + browse frontend

Backward Compatibility

html_content stays as a computed/cached field populated by the compiler. Existing MCP tools that read/write html_content continue to work unchanged. New tools work with blocks directly. Zero-breaking-change migration.

Related

• qa-phase7c-backfill-2026-03-07 — QA report for the backfill run
• benchmark-phase7-block-baseline — quantitative baseline before blocks
• decision-phase6-vector-search-architecture — per-block embedding depends on blocks
• concept-phase5-database-side-intelligence — the database-side intelligence pattern this extends

Goal: Build a typed Python SDK for pal-e-docs, rewrite the MCP server to wrap it, and establish integration tests that verify the full stack against the live service. Eliminate raw httpx calls, add post-deploy smoke tests, and cut tokens per knowledge interaction by 90%+.

Owner: Dev agent

Repos: pal-e-docs-sdk (new), pal-e-docs-mcp (rewrite), pal-e-docs (API — no changes needed)

Depends on: Phase 7d (block API endpoints deployed)

Why

The current MCP server (pal-e-docs-mcp) is a raw httpx passthrough — 26 tools making untyped HTTP calls with ad-hoc error handling. This has three problems:

• No integration tests. We discovered a failed deploy today by manually curling endpoints. There's no automated verification that the live service works.
• No reusability. The HTTP client logic is locked inside MCP tool functions. Scripts, CLI tools, and other services can't use it.
• No type safety. Responses are json.dumps(response.json()) — raw dicts, no validation, no IDE support.

The SDK pattern (proven with woodpecker-sdk, forgejo-sdk) fixes all three: typed client → integration tests → thin MCP wrapper.

Architecture

FastAPI app (pal-e-docs)
    ↑
pal-e-docs-sdk (typed Python client)    ← integration tests run here
    ↑
pal-e-docs-mcp (thin @mcp.tool wrappers)
    ↑
AI agents (Betty Sue, Dottie, etc.)

Sub-Phases

#	Sub-Phase	Deliverable	Depends On
8a	SDK Core	New repo pal-e-docs-sdk. Client class, auth, error handling, base HTTP layer, typed exceptions. Published to Forgejo PyPI.	Nothing
8b	SDK: Notes + Search + Tags + Projects + Links + Repos	Typed methods for all existing API endpoints. Pydantic response models. Covers the 21 current MCP tools.	8a
8c	SDK: Blocks + TOC + Sections	Typed methods for the 6 new block API endpoints from Phase 7d. get_note_toc(), get_block(), update_block(), create_block(), delete_block().	8a, 7d deployed
8d	SDK: Sprints	Typed methods for sprint endpoints (create, get, list, update, add/move/remove items, board, backlog, bulk_move).	8a
8e	Integration Test Suite	SDK tests against the live service. Covers all endpoint families. Runnable locally and in CI. Baseline assertions (e.g. "blocks table has >5000 rows").	8b, 8c, 8d
8f	MCP Rewrite	Rewrite all pal-e-docs-mcp tools to wrap SDK methods instead of raw httpx. Add new block MCP tools (get_note_toc, get_block, update_block, create_block, delete_block). Tools become 3-5 lines each.	8b, 8c, 8d
8g	Deploy Pipeline Smoke Tests	New smoke-test step in pal-e-docs .woodpecker.yaml — runs after deploy, hits key endpoints via SDK, fails pipeline if service is broken.	8e

Dependency Chain

graph LR
    P7d[Phase 7d DONE
Block API] --> P8a[8a SDK Core]
    P8a --> P8b[8b SDK: Notes
Search, Tags, etc.]
    P8a --> P8c[8c SDK: Blocks
TOC, Sections]
    P8a --> P8d[8d SDK: Sprints]
    P8b --> P8e[8e Integration
Tests]
    P8c --> P8e
    P8d --> P8e
    P8b --> P8f[8f MCP
Rewrite]
    P8c --> P8f
    P8d --> P8f
    P8e --> P8g[8g Deploy
Smoke Tests]

SDK Design

Client Class

from pal_e_docs_sdk import PalEDocsClient

client = PalEDocsClient(
    base_url="https://pal-e-docs.tail5b443a.ts.net",
    timeout=30.0,
)

# Typed responses — Pydantic models, not raw dicts
toc = client.get_note_toc("plan-2026-02-26-tf-modularize-postgres")
# Returns: list[TocEntry]

section = client.get_section("plan-2026-02-26-tf-modularize-postgres", "vision")
# Returns: Section(heading=BlockOut(...), content_blocks=[...])

results = client.search_notes("CNPG credentials secrets")
# Returns: list[SearchResult] with slug, headline, rank

Error Handling

from pal_e_docs_sdk.exceptions import NotFoundError, ValidationError

try:
    note = client.get_note("nonexistent-slug")
except NotFoundError:
    print("Note not found")
except ValidationError as e:
    print(f"Invalid request: {e.detail}")

MCP Tool After Rewrite (8f)

# Before (raw httpx):
@mcp.tool()
def get_note(slug: str) -> str:
    try:
        resp = get_client().get(f"/notes/{slug}")
        return _ok(resp)
    except Exception as exc:
        return _error_response(exc)

# After (SDK wrapper):
@mcp.tool()
def get_note(slug: str) -> str:
    return _ok(get_sdk().get_note(slug))

Integration Test Examples (8e)

# tests/integration/test_notes.py
def test_get_note_returns_content(live_client):
    note = live_client.get_note("plan-2026-02-26-tf-modularize-postgres")
    assert note.slug == "plan-2026-02-26-tf-modularize-postgres"
    assert len(note.html_content) > 0
    assert note.note_type == "plan"

def test_toc_returns_headings(live_client):
    toc = live_client.get_note_toc("plan-2026-02-26-tf-modularize-postgres")
    assert len(toc) >= 8
    assert toc[0].anchor_id == "vision"
    assert toc[0].level == 3

def test_blocks_populated(live_client):
    blocks = live_client.list_blocks("plan-2026-02-26-tf-modularize-postgres")
    assert len(blocks) > 20
    assert blocks[0].block_type == "heading"

def test_search_returns_ranked_results(live_client):
    results = live_client.search_notes("CNPG credentials")
    assert len(results) > 0
    assert "sop-secrets-management" in [r.slug for r in results]

Smoke Test Pipeline Step (8g)

# In .woodpecker.yaml, after update-deployment-tag:
- name: smoke-test
  image: python:3.12-slim
  environment:
    PALDOCS_BASE_URL: https://pal-e-docs.tail5b443a.ts.net
  commands:
    - pip install pal-e-docs-sdk
    - python -m pal_e_docs_sdk.smoke_test
  when:
    - event: push
      branch: main

Before vs After (unchanged — still valid)

# BEFORE: "What's our secrets strategy for CNPG?" (12 calls, ~15,000 tokens)
list_notes(tags="sop,active")           # 11 results, no content
get_note("agent-workflow")              # irrelevant, ~3,000 tokens wasted
get_note("pr-lifecycle")                # irrelevant, ~2,000 tokens wasted
get_note("sop-secrets-management")      # found it, ~5,000 tokens
... repeat for other SOPs until found

# AFTER: same question (2 calls, ~700 tokens)
search_notes("CNPG credentials secrets strategy")
→ [{slug: "sop-secrets-management", anchor: "sops-path", snippet: "Encrypt with Age..."}]

get_block("sop-secrets-management", "sops-path")
→ Just the SOPS procedure section (~200 tokens)

Cross-Cutting Optimizations (also delivered in 8f)

• Response size limits: Add max_tokens param to search tools. Truncate long responses with "... (truncated, use get_block for full section)"
• Batch queries: get_notes(slugs="sop-a,sop-b,sop-c") — fetch multiple note summaries in one call instead of N calls
• Context-aware responses: Search results include anchor IDs so the agent can jump directly to the relevant section
• Deprecation notices: Discourage raw html_content in update_note; prefer update_block

Success Metrics

• Average token cost per knowledge lookup: ~15,000 → <1,000
• Average token cost per note update: ~5,000 → <500
• Post-deploy verification: 0 checks → automated smoke test on every deploy
• MCP tool line count: ~50 lines/tool → ~5 lines/tool
• Integration test coverage: 0% → all endpoint families covered

New Repo Setup (8a)

Item	Value
Repo	forgejo_admin/pal-e-docs-sdk
Package	pal-e-docs-sdk on Forgejo PyPI
Python	≥3.12
Dependencies	httpx, pydantic
Dev deps	pytest, ruff
CI	Woodpecker — test + publish to PyPI on main push

Related

• phase-postgres-7d-api-mcp-tools — block API endpoints this SDK wraps
• qa-phase7c-backfill-2026-03-07 — baseline data the integration tests verify
• plan-2026-02-28-woodpecker-sdk-mcp — the pattern this follows (SDK → MCP)
• todo-forgejo-pypi — PyPI registry for publishing

Goal: Add per-block tsvector search indexing and content hashing for compiled pages. This is the bridge between Phase 7 (blocks) and Phase 6 (embeddings) — once blocks have their own search vectors, they can also have their own embedding vectors.

Owner: Dev agent

Repo: pal-e-docs

Depends on: Phase 7d (block API working)

Parent phase: Phase 7 (Block-Structured Content Model)

Why This Phase

Phase 5 added tsvector search at the note level. With blocks, we can now search at the section level — "find the section about credentials" returns a specific block, not a whole note. This is also the prerequisite for Phase 6: the embedding vector(768) column will go on the blocks table, right next to the tsvector column.

Deliverables

1. Per-Block Search Vector

• Add search_vector tsvector column to blocks table
• Add GIN index on blocks.search_vector
• Trigger: auto-update search_vector when block content changes
• Weight: block content (B), parent note title (A) — so searching "postgres plan" still ranks blocks from postgres-related notes higher

2. Section-Level Search API

• Update GET /notes/search to optionally return block-level results
• Or add GET /blocks/search?q=... endpoint
• Response: slug, note title, anchor_id, block_type, snippet, rank
• Agent can jump directly from search result to get_block(slug, anchor_id)

3. Content Hashing

• compiled_pages.content_hash = SHA-256 of all block content
• On note update: compare hash before recompiling. Skip recompile if unchanged.
• On block write: always recompile (single block changed = new hash)
• Saves CPU on bulk operations and prevents unnecessary revision creation

4. Update search_notes MCP Tool

• Add optional granularity param: "note" (default, backward compat) or "block"
• Block-level results include anchor_id so agent can fetch just that section

Acceptance Criteria

• Block-level search returns section-level results with anchor IDs
• Search for "credentials" returns the specific section of sop-secrets-management that discusses credentials, not the whole note
• Content hashing prevents unnecessary recompiles
• search_notes MCP tool supports both note and block granularity
• Backfill: all existing blocks have search_vectors populated

Bridge to Phase 6

After this phase, the blocks table has: content jsonb, search_vector tsvector, and will gain embedding vector(768) in Phase 6. The same table, progressively smarter — the database-side intelligence pattern at work.

Related

• phase-postgres-7d-api-mcp-tools — blocks API must be working
• phase-postgres-6-vector-search — this phase unblocks per-block embeddings
• phase-postgres-5-fulltext-search — note-level search pattern we're extending to blocks
• concept-phase5-database-side-intelligence — the architectural pattern

Goal: Convert all 256 existing notes from monolithic html_content to typed blocks. Populate compiled_pages with compiled HTML + TOC. One-time backfill.

Owner: Dev agent

Repo: pal-e-docs

Depends on: Phase 7a (tables exist), Phase 7b (parser + compiler)

Parent phase: Phase 7 (Block-Structured Content Model)

Forgejo Issue: #100

PR: #101 (MERGED)

Status: IN PROGRESS — Deliverable 1 (migration script) complete. Deliverables 2-3 (run against production + validation) pending.

Why This Phase

The parser and compiler are proven by unit tests in 7b. Now we run them against the full corpus and populate the blocks table. This is a one-time data migration — the most critical step in Phase 7.

Deliverables

1. Migration script: For each note, run the parser on html_content, store resulting blocks in the blocks table with correct positions and anchor IDs. COMPLETE — PR #101 merged.
2. Compiled pages: For each note, compile blocks back to HTML, generate TOC JSON, compute content hash, store in compiled_pages. PENDING — requires running script against production.
3. Validation report: Compare compiled_pages.html vs original html_content for all 256 notes. Flag any semantic differences. PENDING — requires running script against production.
4. Nest orphaned docs: After hierarchy relaxation (7a), set parent_note_id for the 6 identified orphans.

Migration Strategy

• Run as a one-time Alembic data migration or standalone script
• html_content stays populated (backward compat — existing MCP tools still read it)
• Blocks are additive — they coexist with html_content, not replace it
• Use kubectl exec + kubectl cp pattern (port-forward is unreliable on k3s)

Acceptance Criteria

• All 256 notes have blocks in the blocks table
• All 256 notes have a compiled_pages entry
• Round-trip validation: compiled HTML is semantically equivalent to original for 95%+ of notes
• Remaining notes (if any) have documented differences with manual review
• 6 orphaned docs nested under their logical parents
• Existing API / MCP behavior unchanged

Expected Block Counts

Based on baseline data (avg 7.7 headings/note, plus paragraphs/tables/lists between them):

• Estimated ~15-25 blocks per note average
• Total estimated blocks: ~4,000-6,500
• This is well within Postgres performance for indexed queries

Related

• phase-postgres-7a-schema-hierarchy — tables must exist
• phase-postgres-7b-parser-compiler — parser + compiler must be proven
• benchmark-phase7-block-baseline — corpus metrics

Goal: Build the two core library functions: parse HTML into typed blocks, and compile blocks back into deterministic HTML with stable anchor IDs.

Owner: Dev agent

Repo: pal-e-docs

Depends on: Phase 7a (schema must exist for block types)

Parent phase: Phase 7 (Block-Structured Content Model)

Completion Summary

Forgejo Issue: #96

PR: #97 (merged)

Bug fix PR: #99 (merged) — fixed mermaid <br/> stripping and heading inline <code> loss. Forgejo issue #98.

Deliverables: Parser (6 block types: heading, paragraph, table, code, list, mermaid), compiler (deterministic HTML + stable anchor IDs), 121 tests (105 original + 16 regression).

QA: Both PRs approved. PR #97 had 5 non-blocking nits; PR #99 fixed 2 of them.

Level 2 validation: Real-data round-trip test against 268 live notes. 99.3% semantic match (2 bugs fixed by PR #99). Remaining diffs are by design: anchor ID additions (112 notes) and table whitespace normalization (~129 notes).

Why This Phase

The parser and compiler are the heart of the block system. They must be correct, deterministic, and handle all existing content. This phase is pure library code — no DB writes, no API changes, no behavior change. Fully testable in isolation.

Deliverables

1. HTML-to-Blocks Parser

Takes html_content (string) and returns a list of typed block dicts.

Must handle all content found in the 256 existing notes (see benchmark-phase7-block-baseline):

Block Type	HTML Pattern	Content JSONB	Notes in Corpus
heading	<h2>, <h3>, <h4>	{"level": 2, "text": "..."}	229 notes (89%)
paragraph	<p>...</p>	{"html": "..."}	~256 notes
table	<table>...</table>	{"headers": [...], "rows": [...]}	118 notes (46%)
code	<pre><code>...</code></pre>	{"language": "...", "content": "..."}	72 notes (28%)
list	<ul>, <ol>	{"ordered": false, "items": [...]}	239 notes (93%)
mermaid	<pre class="mermaid">	{"definition": "..."}	37 notes (14%)
callout	TBD — currently no callout pattern in corpus	{"type": "info", "content": "..."}	0 (future use)

2. Blocks-to-HTML Compiler

Takes a list of blocks and produces deterministic HTML with stable anchor IDs.

• Deterministic: Same blocks → same HTML every time. No random IDs.
• Stable anchor IDs: Each heading block generates an anchor from its text (slugified). Example: <h3 id="acceptance-criteria">Acceptance Criteria</h3>
• Round-trip safe: compile(parse(html)) ≈ html (semantically equivalent, may normalize whitespace/formatting)

Edge Cases to Handle

• Paragraphs between headings (group with preceding heading or as standalone block?)
• Nested lists (items containing sub-lists)
• Tables inside other elements
• Inline code vs code blocks
• Empty content / notes with no headings (27 notes)
• HTML entities and special characters
• The nh3 sanitizer may have altered some HTML patterns

Acceptance Criteria

• Parser handles all 7 block types
• Round-trip test: parse then compile 20 representative notes, verify semantic equivalence
• Mermaid blocks preserved exactly (whitespace-sensitive)
• Table structure preserved (headers vs body rows)
• Anchor IDs are deterministic and unique within a note
• Unit tests for each block type + edge cases

Design Decision: Grouping Strategy

Open question: how do we group content under headings?

• Option A: Flat blocks. Every HTML element is its own block. A heading is one block, the paragraph after it is another. Simple, but no "section" concept.
• Option B: Section blocks. A heading + everything until the next heading at the same or higher level = one "section" block. More useful for get_block("acceptance-criteria") returning the heading + its content.

Recommendation: Option A (flat) with section grouping at query time. Store flat blocks but provide a "get section" query that returns a heading block + all blocks until the next heading. This keeps storage simple and grouping flexible.

Related

• phase-postgres-7a-schema-hierarchy — prerequisite (block types defined in schema)
• benchmark-phase7-block-baseline — content type distribution in the corpus
• html-style-guide — HTML patterns used in existing notes

Goal: Create the blocks and compiled_pages tables. Relax the parent-child hierarchy so any note type can nest under any other.

Owner: Dev agent

Repo: pal-e-docs

Depends on: Phase 5 (COMPLETED)

Parent phase: Phase 7 (Block-Structured Content Model)

Why First

The tables must exist before any parser, compiler, or migration code can run. The hierarchy relaxation is a simple constraint removal that immediately unblocks nesting 6 orphaned docs — value delivered on day one with zero risk.

Deliverables

1. Alembic migration: blocks table

   blocks
     id          serial PK
     note_id     FK → notes
     position    integer
     block_type  varchar (heading/paragraph/code/table/mermaid/list/callout)
     content     jsonb
     anchor_id   varchar (deterministic, generated from content)
     created_at  timestamp
     updated_at  timestamp
   

2. Alembic migration: compiled_pages table

   compiled_pages
     id            serial PK
     note_id       FK → notes (unique)
     html          text
     toc_json      jsonb
     content_hash  varchar(64)
     compiled_at   timestamp
   

3. Relax parent_note_id constraint: Remove the validation that only phase notes can have a parent and that parents must be plan type. Any note type can have a parent of any type.
4. SQLAlchemy models: Block and CompiledPage models with relationships to Note.

Acceptance Criteria

• Tables exist in Postgres with correct columns, indexes, and FKs
• Hierarchy relaxation works: update_note(slug="concept-phase5-database-side-intelligence", parent_slug="phase-postgres-5-fulltext-search") succeeds
• All 6 orphaned docs can be nested under their logical parents
• Existing behavior unchanged — blocks/compiled_pages tables are empty, no reads/writes touch them yet
• All existing tests pass

Immediate Value

After this phase ships, Betty Sue can nest the 6 orphaned docs (see benchmark-phase7-block-baseline). No parser needed — just a constraint removal.

Estimated Scope

1 Alembic migration, 2 SQLAlchemy models, 1 validation change. Small, clean PR.

Related

• phase-postgres-7-block-content — parent phase
• benchmark-phase7-block-baseline — 6 orphaned docs identified
• doc-pal-e-docs-schema — current schema reference

Goal: Address QA nits from PR #101 before running the backfill against production.

Owner: Dev agent

Repo: pal-e-docs

Parent: Phase 7c (Backfill Migration)

Nit Fixes

1. Empty content hash sentinel

When compiled_html is empty, _content_hash returns "" instead of None (column is nullable). Use None for empty content — it's the honest answer: "no content, no hash."

2. sys.exit(1) in run_backfill

Replace sys.exit(1) with raise RuntimeError("DATABASE_URL not set"). Let __main__ handle the exit. Makes the function importable and testable.

Not Fixing

Nit 3 (client fixture pattern) — inherited codebase convention. Not attributable to this PR. Would be a broader test infrastructure refactor.

Related

• phase-postgres-7c-backfill-migration — parent phase

Goal: Add full-text search to pal-e-docs using Postgres tsvector. Expose via API and MCP tool. Dramatically reduce token usage for AI queries.

Owner: Dev agent

Repos: pal-e-docs (API + migration), pal-e-docs-mcp (search MCP tool)

Depends on: Phase 3 (Postgres migration) — COMPLETED

Progress

Deliverable	Status	Details
PR #84: tsvector + search endpoint	MERGED	tsvector column, GIN index, trigger, GET /notes/search
PR #93: image fix + RollingUpdate + CI commit-back	MERGED	Correct SHA, zero-downtime deploys, auto image tag updates
PR #19 (pal-e-docs-mcp): search_notes tool	MERGED	MCP tool wrapping search endpoint
Search API live	DONE	10 ranked results for ?q=postgres
CI commit-back	DONE	Woodpecker auto-updates deployment.yaml after build
Benchmark re-test	DONE	55% fewer API calls, 71% fewer tokens vs baseline

Acceptance Criteria

• Search returns ranked results with snippets — VERIFIED
• search_notes() MCP tool works — VERIFIED
• tsvector auto-updates on create/update — VERIFIED
• Deployment uses RollingUpdate — VERIFIED

Key Decisions

• Postgres trigger for tsvector (always in sync, no app code)
• Weighted search: title (A) > content (B) > slug (C)
• Separate /notes/search endpoint (not a filter on list_notes)
• RollingUpdate over Recreate (SQLite constraint gone with Postgres)
• CI commit-back for image tags (no manual SHA management)

Token Impact

Before: 12+ MCP calls, ~11K tokens per 5 queries. After: 55% fewer calls, 71% fewer tokens. Validated by benchmark.

Related Notes

• incident-phase5-deployment-outage-2026-03-06 — outage root cause + timeline
• concept-argocd-ghost-override — what ghost overrides are and prevention
• concept-phase5-database-side-intelligence — why intelligence lives in Postgres
• concept-phase5-self-hosted-rag — Act 2 RAG architecture vision
• benchmark-phase5-knowledge-baseline — baseline measurements before search

Goal: pal-e-docs switches from SQLite to the already-running CNPG Postgres cluster. App code migrates to Postgres dialect, k8s manifests updated, Litestream removed, data migrated.

Owner: Dev agent

Repos: pal-e-docs (primary), pal-e-platform (Terraform — DB secret in app namespace)

Issues:

• forgejo_admin/pal-e-platform #22 — Terraform DB secret (Part A)
• forgejo_admin/pal-e-docs #76 — Code + manifests + data migration (Parts B/C/D)

Architecture (verified 2026-03-06)

Key facts discovered during pre-issue research:

Component	Current State
CNPG Cluster	pal-e-postgres running in postgres namespace. Healthy. Postgres 17.4, 1 instance, 5Gi storage.
Database	paledocs database, owned by paledocs user. Bootstrapped by CNPG initdb.
Credentials	paledocs-db-credentials secret in postgres namespace (manual kubectl). Contains username + password.
Connection endpoint	pal-e-postgres-rw.postgres.svc.cluster.local:5432
ArgoCD Application	Sources directly from pal-e-docs/k8s/ (NOT a deployments overlay). Auto-sync + prune + self-heal.
Current app secrets	pal-e-docs-secrets (manual kubectl), litestream-creds (manual kubectl), harbor-creds (Terraform)
WAL archiving	Configured but failing (ContinuousArchivingFailing). Phase 4 concern, not blocking.
SOPS+Age	Age keypair exists in Salt pillar but is NOT deployed to ArgoCD. No SOPS decryption wired up. Future work.

Secrets Strategy

Pattern: Terraform-managed k8s secret — matches how harbor-creds, cnpg-s3-creds, and other platform secrets are managed today.

Add a kubernetes_secret_v1 resource to pal-e-platform/terraform/main.tf that creates a paledocs-db-url secret in the pal-e-docs namespace containing the full Postgres DSN. The password is sourced from a new tfvar (stored in k3s.tfvars, gitignored, sourced from Salt pillar).

Future: When SOPS+Age is wired into ArgoCD, migrate this secret to SOPS-encrypted YAML in the repo. Document as tech debt.

Connection String

postgresql://paledocs:<password>@pal-e-postgres-rw.postgres.svc.cluster.local:5432/paledocs

Steps

Part A: Terraform — DB secret in app namespace (pal-e-platform #22)

1. Add variable "paledocs_db_password" to terraform/variables.tf (sensitive, string)
2. Add kubernetes_secret_v1.paledocs_db_url to terraform/main.tf — creates secret paledocs-db-url in pal-e-docs namespace with key DATABASE_URL containing the full DSN
3. Add value to terraform/k3s.tfvars
4. Run tofu plan + tofu apply

Part B: App code — SQLite → Postgres (pal-e-docs #76, PR 1)

1. Update src/pal_e_docs/config.py: add database_url: str | None = None setting. When set, takes precedence over database_path.
2. Update src/pal_e_docs/database.py: use database_url if set, otherwise fall back to SQLite path. Remove SQLite-specific pragma listener when using Postgres.
3. Update alembic/env.py: use database_url setting when available, fall back to SQLite for local dev.
4. Add psycopg2-binary to dependencies.
5. Fix SQLite-isms in migration files: (CURRENT_TIMESTAMP) → sa.func.now(), boolean defaults, CHECK constraints.
6. Test locally against Postgres.

Part C: k8s manifests — deployment update (pal-e-docs #76, PR 2)

1. Update k8s/deployment.yaml: replace env var, remove Litestream containers, remove volumes
2. Update k8s/kustomization.yaml: remove pvc.yaml and litestream-configmap.yaml
3. Delete k8s/pvc.yaml and k8s/litestream-configmap.yaml

Part D: Data migration (one-time, maintenance window)

1. Data migration script in scripts/migrate_sqlite_to_postgres.py
2. Lucas runs Alembic + migration during maintenance window
3. Deploy PR 2 after verification

Deployment Sequence (CRITICAL)

1. Merge PR 1 (code) → ArgoCD deploys. App still uses SQLite.
2. Lucas runs tofu apply on pal-e-platform (creates DB secret)
3. Lucas runs alembic upgrade head against Postgres
4. Lucas runs data migration script
5. Merge PR 2 (manifests) → ArgoCD deploys. App switches to Postgres.

Risks

• Data migration window: Short downtime while SQLite data is loaded into Postgres. Sessions fail-open.
• Alembic dialect: Existing migrations have SQLite-isms (3 patterns identified). Must be fixed.
• ArgoCD prune: Auto-prune will delete PVC when removed from kustomization. Data migration must be verified BEFORE merging PR 2.
• Cross-namespace: No NetworkPolicy blocking. Future-proof with egress rule if policies are added.

Depends on

Phase 2b (platform cleanup) — COMPLETED.

See also

• sop-secrets-management — documents the Terraform secret pattern
• sop-litestream-restore — will become obsolete after this phase

Goal: Skills and hooks use note_type/status parameters instead of tag-based queries.

Owner: Agent (worktree, claude-custom repo)

Priority: Low — only needed after tag cleanup is complete. Tag-based queries work fine today.

Goal: Every note has a note_type, status, and project. All projects have page_note_id wired. Redundant tags retired.

Owner: Main session (API calls)

Priority: Low — cosmetic cleanup. Tags work today.

Depends on: plan-2026-03-01-note-decomposition Phase 2 (schema must exist before data migration)

Goal: Infrastructure-sensitive notes are private. Repos visibility leak on landing page is fixed.

Status: COMPLETE (2026-03-02)

Delivered:

1. Reviewed all is_public: true notes. (2026-03-01)
2. 13 infra-sensitive notes in pal-e-platform made private. (2026-03-01)
3. Public: plans, project pages, SOPs, architecture docs kept public.
4. Repos query filter by project is_public — PR #59 merged (2026-03-02). Forgejo issue #58 closed.
5. Verified from unauthenticated browser — private notes hidden, private project repos hidden.

Goal: Add note_type + status columns to notes, create issues table, add repos page_note_id, update API routes and MCP tools with new query parameters.

Status: ABSORBED into plan-2026-03-01-note-decomposition

This phase was promoted to plan-2026-02-28-schema-api-mcp, which was subsequently absorbed into the decomposition plan. The decomposition plan adds parent_note_id + position columns alongside note_type + status, plus composition rendering. Issues table deferred to a future plan.

Goal: Define the canonical note_type enum, status values per type, revised tag taxonomy, and README convention. This is the spec everything else builds on.

Owner: Main session (docs only)

Status: COMPLETE

Delivered: Updated note-conventions with canonical note_type enum (10 values — bug merged into issue), status-per-type table, revised tag taxonomy (21 type tags + 9 lifecycle tags + 4 scope tags retiring, 13+ topic tags kept), README convention. Marked tagging-conventions deprecated.

Goal: Plan pages render child phases inline. Monolithic plans unchanged.

Completed: 2026-03-02 (PR #63, 2 QA rounds, 252 tests)

Forgejo: forgejo_admin/pal-e-docs PR #63, issue #62

Scope: routes/frontend.py, templates/note.html, templates/base.html, tests/test_composition_rendering.py

QA fix: Cartesian product from multiple joinedload on collections — switched to subqueryload.

Goal: MCP tools expose note_type, status, parent_slug, position.

Completed: 2026-03-02 (PR #6 on pal-e-docs-mcp, 2 QA rounds)

Forgejo: forgejo_admin/pal-e-docs-mcp PR #6, issue #5

Deliverables: list_notes/create_note/update_note all accept new params. Renamed html_content→content, project_slug→project to match model instincts.

Goal: Add 4 columns to notes table. Validation. API filters.

Completed: 2026-03-02 (PR #61, 2 QA rounds, 240 tests)

Forgejo: forgejo_admin/pal-e-docs PR #61

Incident: ~10 min outage from SQLite DDL auto-commit. See incident-2026-03-02-sqlite-migration-crash-pr61.

Deliverables: Alembic migration (4 columns + index), model (self-referential FK), Pydantic (NoteType Literal, 11 values), route validation (VALID_STATUSES, ALLOWED_PARENT_TYPES), 68 new tests.

Goal: Measure today's token costs for 6 user stories. Write the decomposition spec.

Completed: 2026-03-02

Deliverables:

• Baseline measurements: update phase = 39KB/2 calls, spawn agent = 19KB waste, query in-progress = 193KB/12 calls, create plan = 24KB/2 calls, elaborate phase = 40KB/2 calls
• Updated note-conventions with phase note_type, decomposition section, baselines + targets
• Updated template-plan

Verdict: APPROVED

Re-review after refinements. All five actionable findings from review-1432-2026-06-14 have been addressed. One deferred finding (missing arch-infra note) remains non-blocking. The issue is agent-ready.

Previous Findings — Disposition

1. [SCOPE] Cross-repo note — FIXED. Issue body now has a prominent "Note:" under the Repo section: "This issue is filed on pal-e-services for historical reasons (original triage). All file targets are in pal-e-platform. The agent must clone pal-e-platform, not pal-e-services."
2. [BODY] outputs.tf promoted — FIXED. File Targets now explicitly lists terraform/modules/ops/outputs.tf as a definite restore target with exact output name (ollama_namespace). Verified: pre-removal file at 7872dac~1 contained exactly that output.
3. [BODY] Backfill command specified — FIXED. AC 8 added: kubectl exec deployment/pal-e-docs-embedding-worker -n pal-e-docs -- python -m pal_e_docs.embedding_worker --backfill.
4. [LABEL] Type corrected — FIXED. Issue ### Type is now "Feature". Board labels show type:feature.
5. [LABEL] Titles aligned — FIXED. Board item and Forgejo issue both read "Restore Ollama Helm release to ops module (embedding pipeline broken)".
6. [SCOPE] Missing arch-infra note — DEFERRED. No arch-infra note exists. Acknowledged as non-blocking by the caller. Does not prevent agent execution.

Template Completeness

• [x] Type — Feature
• [x] Lineage — standalone, references removal commit 7872dac
• [x] Repo — ldraney/pal-e-platform (terraform/modules/ops/main.tf), cross-repo note present
• [x] User Story — platform operator, Ollama restored, embedding worker functional
• [x] Context — thorough history of deploy, removal, and current state
• [x] File Targets — 2 modify targets (main.tf, outputs.tf) + don't-touch list
• [x] Feature Flag — none (correct for infra work)
• [x] Acceptance Criteria — 8 items, all verifiable
• [x] Test Expectations — 3 items with run command
• [x] Constraints — 6 items, specific and actionable
• [x] Checklist — present
• [x] Related — references project, commits, related issue

Traceability

• [x] story:superuser-query label — "I can query the knowledge base by meaning (semantic search)"
• [x] story note verified — found in project-pal-e-docs user-stories section, row 1
• [x] arch:infra label — infrastructure component
• [ ] arch note DEFERRED — no arch-infra note exists. Non-blocking per caller.
• [x] Forgejo issue — ldraney/pal-e-services#114, open
• [x] Cross-repo placement documented — Note in Repo section directs agent to clone pal-e-platform

File Targets

• [x] terraform/modules/ops/main.tf — verified: file exists (213 lines). Ollama resources (namespace + helm_release, ~70 lines) were removed between nvidia_device_plugin (line 26) and embedding_worker_metrics (line 28). Pre-removal config confirmed at 7872dac~1.
• [x] terraform/modules/ops/outputs.tf — verified: file exists, is empty. Pre-removal version at 7872dac~1 had output "ollama_namespace". Now listed as definite restore target in issue.

Don't-touch targets verified:

• [x] terraform/main.tf — module "ops" call at line 123, moved{} blocks present. No Ollama references remain. Correct to leave untouched.
• [x] terraform/modules/ops/variables.tf — no Ollama variables existed before removal (confirmed identical at 7872dac~1). Correctly excluded from file targets.
• [x] NVIDIA / embedding-worker-metrics resources — present in current main.tf, must not be modified.

Repo Placement

RESOLVED. Issue remains on pal-e-services (historical triage) but now has a prominent cross-repo note directing the agent to clone pal-e-platform. Agent spawn will not be confused.

Dependencies

• #1434 (Scale embedding worker to 0) — alternative stopgap. Becomes unnecessary if #1432 succeeds. Not a blocker.
• #1433 (pg_stat_statements + Grafana) — independent, no dependency.
• NVIDIA device plugin — already deployed in ops module. Issue correctly notes depends_on relationship. Not a blocker.
• Embedding worker — downstream consumer. Config at src/pal_e_docs/config.py:11 hardcodes ollama.ollama.svc.cluster.local:11434. Will self-heal once Ollama is reachable.

Acceptance Criteria

8 AC items, all verifiable:

• [x] AC 1-3: namespace + helm_release + output restored — verifiable via tofu plan
• [x] AC 4: add-only plan — verifiable via tofu plan
• [x] AC 5: tofu apply succeeds — verifiable (requires cluster access)
• [x] AC 6: pods running — verifiable via kubectl
• [x] AC 7: embedding worker connectivity — verifiable via logs
• [x] AC 8: embedding backfill — now specifies exact kubectl exec command

Blast Radius

• pal-e-docs embedding worker — direct consumer. Will start working once Ollama is reachable. No code changes needed.
• pal-e-docs semantic search — degraded to keyword-only. Will improve as backfill processes blocks.
• No other services reference Ollama — grep across pal-e-deployments and pal-e-services/terraform found zero Ollama references.
• GPU contention — Ollama will claim the GPU. Acknowledged in issue's Decision section.

Decomposition Assessment

No decomposition needed.

• 2 file targets in 1 repo — under threshold
• 8 AC but work is essentially a single git-restore operation — under 5 minutes
• Single agent pass is appropriate

Recommendations

No action needed.

All five actionable findings resolved. Deferred item (arch-infra note) tracked separately and does not block execution.

Verdict: NEEDS_REFINEMENT

The issue body is thorough and well-structured. Five fixable issues prevent READY status: repo placement mismatch, missing architecture note, type label mismatch on board, incomplete file targets (outputs.tf), and board title mismatch with Forgejo issue title.

Template Completeness

• [x] Type — Feature
• [x] Lineage — standalone, references removal commit 7872dac
• [x] Repo — ldraney/pal-e-platform (terraform/modules/ops/main.tf)
• [x] User Story — platform operator, Ollama restored, embedding worker functional
• [x] Context — thorough history of deploy, removal, and current state
• [x] File Targets — 3 modify targets + 3 don't-touch targets
• [x] Feature Flag — none (correct for infra work)
• [x] Acceptance Criteria — 7 items
• [x] Test Expectations — 4 items with run command
• [x] Constraints — 6 items, specific and actionable
• [x] Checklist — present
• [x] Related — references project, commits, related issue

Traceability

• [x] story:superuser-query label — "I can query the knowledge base by meaning (semantic search)"
• [x] story note verified — found in project-pal-e-docs user-stories section, row 1
• [x] arch:infra label — infrastructure component
• [ ] arch note MISSING — [SCOPE] No arch-infra note exists in pal-e-docs. Create architecture note documenting the infra layer (ops module, NVIDIA plugin, Ollama, embedding worker metrics).
• [x] Forgejo issue — ldraney/pal-e-services#114, open
• [ ] Repo mismatch — [SCOPE] Issue filed on pal-e-services but all work targets pal-e-platform. Should be filed on pal-e-platform or documented why it lives on pal-e-services.

File Targets

• [x] terraform/modules/ops/main.tf — verified: file exists (213 lines). Ollama namespace + helm_release were surgically removed between nvidia_device_plugin (line 6-26) and embedding_worker_metrics (line 28-53). Git history at 7872dac~1 confirms the exact config to restore (namespace + helm_release, ~70 lines).
• [x] terraform/modules/ops/variables.tf — verified: file exists. No Ollama variables existed before removal (confirmed via git show 7872dac~1). No changes needed here.
• [ ] terraform/modules/ops/outputs.tf — ISSUE: [BODY] File exists but is EMPTY. The pre-removal version had output "ollama_namespace" that should be restored. Issue body says to check "if outputs existed" but doesn't explicitly list this as a target. The output existed and should be mentioned as a definite restore target.

Don't-touch targets verified:

• [x] terraform/main.tf — confirmed: module "ops" call at line 123, moved{} blocks exist for non-Ollama resources. No Ollama references remain. Correct to leave untouched.
• [x] NVIDIA / embedding-worker-metrics resources — confirmed in current main.tf, should not be modified.

Repo Placement

MISMATCH. The Forgejo issue is filed on ldraney/pal-e-services but the issue body says the work is in ldraney/pal-e-platform (terraform/modules/ops/main.tf). The agent will need to clone pal-e-platform, not pal-e-services. This could cause confusion during agent spawn. Either move the issue to pal-e-platform or add a prominent note explaining the cross-repo placement.

Dependencies

• #1434 (Scale embedding worker to 0) — alternative stopgap. Becomes unnecessary if #1432 succeeds. Not a blocker.
• #1433 (pg_stat_statements + Grafana) — independent, no dependency.
• NVIDIA device plugin — already deployed and managed by ops module. Issue correctly notes depends_on relationship. Not a blocker.
• Embedding worker — downstream consumer. Already deployed but failing due to missing Ollama. Will self-heal once Ollama is reachable. Confirmed: pal_e_docs/config.py hardcodes ollama.ollama.svc.cluster.local:11434.

Acceptance Criteria

7 AC items, all verifiable:

• [x] AC 1-2: namespace + helm_release restored — verifiable via tofu plan output
• [x] AC 3: add-only plan — verifiable via tofu plan
• [x] AC 4: tofu apply succeeds — verifiable (requires cluster access)
• [x] AC 5: pods running — verifiable via kubectl
• [x] AC 6: embedding worker connectivity — verifiable via logs
• [x] AC 7: embedding backfill — verifiable but vague. No specific command given. Agent may need guidance on how to trigger backfill (the embedding_worker.py has a run_backfill function invoked via CLI arg).

AC 7 could be clearer: specify python -m pal_e_docs.embedding_worker --backfill or equivalent command.

Blast Radius

• pal-e-docs embedding worker — direct consumer. Config hardcodes the Ollama service URL. Will start working immediately once Ollama is reachable. No code changes needed in pal-e-docs.
• pal-e-docs semantic search — degraded to keyword-only while embeddings are missing. Will gradually improve as backfill processes blocks.
• No other services reference Ollama. The westside-ai-assistant that originally used it was decommissioned. Grep across pal-e-deployments found zero Ollama references.
• GPU contention — Ollama will claim the GPU. If other GPU workloads are added later, contention may occur. Issue acknowledges this in the Decision section.

Decomposition Assessment

No decomposition needed.

• 2-3 file targets in 1 repo — under threshold
• 7 AC but work is essentially a single git-restore operation — under 5 minutes
• Single agent pass is appropriate

Recommendations

• [SCOPE] Repo placement: Issue is on pal-e-services but work targets pal-e-platform. Either move the issue to pal-e-platform or add a note explaining cross-repo placement. Agent spawn must clone pal-e-platform.
• [SCOPE] Create architecture note arch-infra documenting the ops module components (NVIDIA plugin, Ollama, embedding worker metrics, TF state backup).
• [BODY] outputs.tf: Add explicit mention that outputs.tf needs the ollama_namespace output restored (confirmed it existed at 7872dac~1). Currently the issue says "if outputs existed" — they did.
• [BODY] AC 7 (backfill): Specify the exact backfill command. The embedding worker supports --backfill mode per embedding_worker.py.
• [LABEL] Board item type mismatch: Board label is type:bug but issue ### Type is Feature. Update board label to type:feature.
• [LABEL] Board title mismatch: Board says "Redeploy Ollama" but Forgejo title is "Restore Ollama Helm release to ops module". Align titles.

Verdict: APPROVED

Round 2 review of board item #972 (Forgejo forgejo_admin/pal-e-platform#278). Round 1 verdict was NEEDS_REFINEMENT (review-972-2026-04-11). All round 1 findings are resolved or explicitly accepted. Scope is now single-repo, two-new-files, additive-only, and fits the 5-minute rule.

Round 1 Findings — Resolution Check

#	Round 1 finding	Round 2 status	Verified by
1	[FALSE POSITIVE] claim that arch-domain-pal-e-docs does not exist	Refuted — confirmed live	get_note(slug="arch-domain-pal-e-docs") → id=1410, note_type=architecture, project=pal-e-docs, created 2026-04-10, status=active. Round 1 search missed it.
2	[REAL] wrong file targets (terraform/k3s-funnels.tf does not exist)	Resolved	Round 2 pivoted to Option B. Verified precedent ~/pal-e-deployments/overlays/pal-e-production/prod/ingress.yaml exists (7-line Ingress using ingressClassName: tailscale + tailscale.com/funnel: "true"). Target files in the new overlay are plausible and do not collide with any existing file.
3	[REAL] decomposition needed (5-minute rule)	Resolved	Scope shrunk to Step 1 only. Single repo (pal-e-deployments), 2 new files, 8 ACs (all curl/kubectl verifiable), no SDK/MCP/frontend changes. Steps 2-7 filed as forgejo_admin/pal-e-platform#280 (verified open).
4	[REAL] arch:k8s-deploy has no backing arch note	Accepted as known debt	Ticket explicitly acknowledges the gap, cites sibling tickets #234/#613/#973 also using the label, and defers a proper arch-deployment-pal-e-docs note as out-of-scope. Consistent with the traceability triangle convention's allowance for foundational-work gaps.
5	[REAL] deferred decisions in ticket body	Resolved	All redirect/decommission/swap choices moved to follow-up #280. This ticket has no scoping deferrals — every acceptance criterion is concrete.
6	[REAL] same-namespace ingress backend constraint	Trivially satisfied	New Ingress and existing pal-e-docs Service both live in the pal-e-docs namespace. Verified via ~/pal-e-deployments/overlays/pal-e-docs/prod/kustomization.yaml which renames the base Service to pal-e-docs.

Template Completeness

• [x] Type — Feature
• [x] Lineage — covers both discovery context and round 1 refutation
• [x] Repo — forgejo_admin/pal-e-deployments
• [x] User Story — reader-browse, correctly traced to project-pal-e-docs
• [x] Architecture — arch:notes + arch:k8s-deploy (latter flagged as debt)
• [x] Context — current-state table + target-state table, clear before/after
• [x] Rationale — preserved verbatim from round 1 for decision audit trail
• [x] File Targets — two new files with precedent path for templating
• [x] Acceptance Criteria — 8 concrete, verifiable
• [x] Test Expectations — 4 smoke tests including regression on existing hostname
• [x] Constraints — reversibility explicit, "do not touch" list complete
• [x] Checklist — standard
• [x] Related — dependency, follow-up, arch note, convention, precedent path, round 1 review

Traceability

• [x] story:reader-browse label — "I can browse public notes, plans, and project pages in a web UI without authentication." Verified in project-pal-e-docs user-stories table (row 5).
• [x] story note verified — foundation is live at project-pal-e-docs#user-stories
• [x] arch:notes label — maps to the notes component row in arch-domain-pal-e-docs (id 1410). The new funnel exposes the FastAPI surface that serves note-shaped resources, so the label is load-bearing.
• [x] arch note verified — arch-domain-pal-e-docs id=1410 exists (refutes round 1 false positive)
• [!] arch:k8s-deploy label — no backing note. Accepted as known debt per ticket body and per sibling-ticket precedent (#234, #613, #973). Tracked for future arch-deployment-pal-e-docs. Not a blocker for this ticket.
• [x] Forgejo issue — pal-e-platform#278, state=open

File Targets

• [x] overlays/pal-e-docs-api/prod/kustomization.yaml — NEW. Parent dir does not exist yet (verified: ~/pal-e-deployments/overlays/ lists 14 overlays, no pal-e-docs-api). Creating a new overlay directory is the correct pattern and matches how pal-e-production, pal-e-streamlit, westside-email, etc. are structured.
• [x] overlays/pal-e-docs-api/prod/ingress.yaml — NEW. The template reference (overlays/pal-e-production/prod/ingress.yaml) exists and is 16 lines — literally just Ingress with ingressClassName: tailscale, tailscale.com/funnel: "true", and a defaultBackend.service ref. Copy-edit-commit is a <5-minute task.
• [x] Unmanaged pal-e-docs-funnel — correctly flagged as "do not touch". Verified: ~/pal-e-deployments/overlays/pal-e-docs/prod/ contains kustomization.yaml, deployment-patch.yaml, embedding-worker.yaml, harbor-creds.enc.yaml — no ingress.yaml, confirming the existing funnel is not managed by this overlay. Adding a new overlay next to it is safe and non-overlapping.
• [x] Backend service ref pal-e-docs in namespace pal-e-docs — verified via overlays/pal-e-docs/prod/kustomization.yaml which renames the base Service to pal-e-docs. Port resolves at dev time via kubectl get svc -n pal-e-docs pal-e-docs (base service.yaml uses 8000). Not a scoping gap — one-command lookup.

Repo Placement

Correct. Issue is filed on forgejo_admin/pal-e-platform (the bootstrap repo, matching where the #278/#280/#234/#613 tickets live) but explicitly names forgejo_admin/pal-e-deployments as the implementation repo. The PR will open against pal-e-deployments. This is the standard split in this org: platform holds the meta-tickets, deployments holds the kustomize code.

Dependencies

• Soft dep on pal-e-api#256 (CORS middleware) — ticket correctly notes that Step 1 does not require CORS (no browser-side fetches change) but flags it as a prerequisite for later steps. Not a blocker for #278.
• Unblocks follow-up #280 — verified open. Steps 2-7 depend on the additive funnel being live.
• Board item #972 is not blocked by any other in-flight item in in_progress based on the board listing.

Acceptance Criteria

All 8 ACs are concrete and verifiable by a dev agent without judgment calls. The ArgoCD sync check and the dual-ingress check give clean go/no-go signals. The cert smoke test acknowledges Tailscale cert provisioning latency implicitly (the AC is phrased as "after Tailscale provisions the cert"). The MCP smoke test being explicitly marked as "smoke test only, not a permanent migration" is exactly right — prevents scope creep into Step 3.

Blast Radius

Minimal and well-contained.

• Additive only: creates one new Ingress object in one namespace, zero modifications to existing resources.
• Reversible: kubectl delete ingress pal-e-docs-api-funnel -n pal-e-docs (explicitly called out in ticket Constraints).
• No SDK/MCP/frontend/CORS changes in this PR — all deferred to follow-up.
• The existing pal-e-docs-funnel remains unmanaged and untouched, so there is zero risk to current MCP, SDK, and CLAUDE.md consumers.
• Sibling overlay pattern (pal-e-production-funnel) has been in production for 7 days with no issues — precedent is battle-tested.

Decomposition Assessment

No decomposition needed. Against the 5-minute rule:

• Files: 2 new files in 1 repo (limit: >3 files across >2 repos). Well under.
• Acceptance criteria: 8 ACs (limit: >5). Slightly over the nominal threshold, BUT all 8 are mechanical verifications of the same single change (kustomize create → ArgoCD sync → kubectl get → curl). They are not independent work units — they are verification facets of one atomic change. Splitting would be artificial.
• Estimated agent work: Copy precedent ingress.yaml (7 lines), change hostname, change service name, create kustomization.yaml referencing ingress.yaml, commit, PR. Realistic estimate: 3-5 minutes for the agent, plus ArgoCD sync + Tailscale cert provisioning wall-clock (not agent wall-clock).
• Repos: 1 (pal-e-deployments). Limit: >2. Well under.

Round 2 decomposition is exactly the right grain. Further splitting would be muda.

Round 1 Findings Not Yet Addressed

None. Every round 1 finding is either resolved (#2, #3, #5, #6), refuted with evidence (#1), or explicitly accepted as known debt with a forwarding path (#4).

Minor Observations (non-blocking)

• [LABEL] Board item #972 title on board-pal-e-docs still reads "Swap hostname routing — pal-e-docs serves frontend, api.pal-e-docs serves API" (the round 1 framing). The Forgejo issue title has been updated to "Hostname swap step 1 — add additive api.pal-e-docs funnel via pal-e-deployments kustomize". Consider updating the board item display title to match — but this is metadata hygiene, not a scope issue, and should not block advancement.
• Round 1 review note review-972-2026-04-11 is referenced in the ticket body but a search of pal-e-docs returns no note with that slug. Not blocking — the round 1 findings are preserved verbatim in the ticket Lineage section, which is the load-bearing artifact.

Recommendation

APPROVED. Ticket is ready to advance backlog → todo. No blockers.

• [LABEL] (optional, non-blocking) Update board item #972 display title on board-pal-e-docs to match the current Forgejo issue title.

All other round 1 findings are resolved. Dispatch to dev when Ava is ready.

Verdict: APPROVED

Round 2 of board item #973 (forgejo_admin/pal-e-platform#279). All four [BODY] refinements from review-973-2026-04-11 (round 1) are applied. Housekeeping scope is clean, dependencies are explicit, and the ticket fits comfortably in a single agent pass. Advance backlog → todo. (Execution order still gated on #278 per spawn prompt guidance, but review gate is satisfied.)

Round 1 Findings Verification

#	Round 1 Finding	Resolution in r2 body	Status
1	[BODY] pal-e-app#87 is already closed — treat as pointer-comment-only, not state change	What Broke table row marks #87 as already closed (2026-03-28). Per-Ticket Action section says "NO state change. Add a single pointer comment." AC#2 says "pal-e-app#87 (already closed) receives one pointer comment citing #278 — state unchanged." Test Expectation confirms "state remains closed (was closed 2026-03-28; this housekeeping pass does not reopen it)."	FIXED
2	[BODY] Cite #278 by full URL / number in Related section	Related section now lists forgejo_admin/pal-e-platform#278 explicitly with a parenthetical describing its role as "the canonical hostname swap ticket." Body references #278 by number throughout Per-Ticket Action and Expected Behavior.	FIXED
3	[BODY] Drop AC #5 (feedback_naming_convention update) as out of scope	AC list no longer mentions feedback_naming_convention at all. AC count is now 4. Lineage section explicitly acknowledges: "(3) AC dropping the feedback_naming_convention lesson-capture (out of scope; that's a memory file, not a pal-e-docs note)."	FIXED
4	[BODY] Clarify AC #4 "no new tickets" vs "if anyone cares to file it" tension	Per-Ticket Action for #255 and #257 now says "Do not file a new Keycloak rename ticket from this housekeeping pass — that decision belongs to whoever executes #278." AC#4 explicitly says "Forward-facing decisions about Keycloak client rename, namespace rename, or frontend validation are explicitly deferred under #278 — they are NOT this ticket's responsibility and are NOT filed as fresh tickets here." The "if anyone cares" language is gone.	FIXED

Template Completeness

• [x] Type (Bug)
• [x] Lineage (includes explicit round-1 delta summary)
• [x] Repo
• [x] What Broke (now with a 5-row per-item state table)
• [x] Repro Steps
• [x] Expected Behavior (distinguishes close-as-wontfix from pointer-comment-only)
• [x] Environment
• [x] Per-Ticket Action (per-item decisions, wontfix rationale, deferral language)
• [x] Acceptance Criteria (4 ACs — #5 dropped per round 1)
• [x] Test Expectations (verification queries that will be machine-checked)
• [x] Constraints (tool choices named)
• [x] Checklist
• [x] Related (cites #278, #256, arch-domain-pal-e-docs, review-973-2026-04-11)
• [ ] User Story / Architecture sections not in body — labels carry the triangle on the board item (story:superuser-maintain, arch:k8s-deploy). Acceptable per bug-template conventions.

Traceability

• [x] story:superuser-maintain label — verified on board item #973. Housekeeping closures are superuser maintenance via MCP.
• [x] arch:k8s-deploy label — present on board item. Conceptually valid. Note (non-blocking): no dedicated arch-k8s-deploy note exists in pal-e-docs. Closest backing note is arch-domain-pal-e-docs. Creating a dedicated arch note is still out of scope for this housekeeping ticket. Round 1 already flagged this as a future separate ticket; not re-raising for r2.
• [x] scope:discovered label — correct (discovered during 2026-04-11 routing review with Lucas).
• [x] type:bug label — matches the body's "### Type Bug" header.
• [x] Forgejo issue URL — forgejo_admin/pal-e-platform#279, state=open, verified via API 2026-04-11.
• [ ] Forgejo issue labels are empty (body-only labeling). Still not a blocker; triangle lives on board item. [LABEL] recommendation is optional polish, not required for approval.

File Targets

N/A — this ticket operates entirely on Forgejo issues and pal-e-docs board items via MCP. All targets are identifier-based (issue numbers, board item IDs). Re-verified as of 2026-04-11:

• [x] pal-e-platform#234 — state=open. Target valid.
• [x] pal-e-platform#255 — state=open. Target valid.
• [x] pal-e-platform#257 — state=open. Target valid.
• [x] pal-e-app#87 — redirects to pal-e-production#87, state=closed (closed_at 2026-03-28T17:01:43Z). Body correctly treats this as pointer-comment-only.
• [x] pal-e-app#88 — redirects to pal-e-production#88, state=open. Target valid. Note: the forgejo_admin/pal-e-app URL now 301s to pal-e-production; the dev agent should expect curl -L or use the canonical repo name when operating. Not a blocker — the MCP update_issue / comment_on_issue tools follow redirects.
• [x] Board items #510 and #513 — both confirmed present on board-pal-e-docs, column backlog, linking to the correct pal-e-app issue URLs.

Repo Placement

OK. pal-e-platform is the correct umbrella repo for a cross-cutting housekeeping pass that closes tickets in both pal-e-platform and pal-e-app/pal-e-production. No repo code is touched.

Dependencies

Single dependency: forgejo_admin/pal-e-platform#278 (hostname swap), board item #972. State: open, backlog. The spawn prompt correctly gates execution on #278 landing first — this is an execution-order constraint, not a review-gate constraint. Review gate (backlog→todo) passes. Scheduling constraint (todo→in_progress) is a separate decision for Ava when #278 is in at least in_progress.

No circular dependencies. No new dependencies introduced in r2.

Acceptance Criteria

4 ACs, each machine-verifiable:

• [x] AC#1 — "four tickets closed as wontfix with a comment citing #278 by full URL" — verifiable via Forgejo API.
• [x] AC#2 — "pal-e-app#87 receives one pointer comment, state unchanged" — verifiable via issue API + comments endpoint.
• [x] AC#3 — "board items #510 and #513 removed from board-pal-e-docs" — verifiable via list_board_items.
• [x] AC#4 — "no new tickets filed by this pass; forward-facing work deferred under #278" — verifiable by absence + explicit deferral language in body.

Test Expectations section adds 5 concrete verification queries the QA agent can run directly. Strong.

Blast Radius

Low. All operations are reversible in Forgejo (reopen + re-add board item) and touch no code, no CI, no runtime services. The only residual risk — closing a ticket whose intent is still live — is addressed by the per-ticket action table and the explicit deferral-under-#278 language. Round 1's "intent-survives-rename" concern is now resolved by the "do not file new tickets from this pass" instruction.

Decomposition Assessment

No decomposition needed. 5-minute rule check:

• File targets: 0 (API-only)
• Acceptance criteria: 4 (under the 5-AC threshold)
• Estimated agent work: ~2-3 minutes — 4 update_issue calls (close+wontfix), 5 comment_on_issue calls (4 closing comments + 1 pointer comment on #87), 2 remove_board_item calls. All independent and idempotent.
• Repos touched: 1 umbrella (pal-e-platform) + cross-repo API calls (not a decomposition trigger).

Housekeeping ticket remains flat and well-scoped for a single agent pass.

Recommendation

APPROVED. No action needed in the body. All four round 1 [BODY] fixes are cleanly applied and verifiable in the current issue text. Advance board item #973 from backlog to todo.

Execution-order reminder (not a review gate, but relevant for Ava's scheduling): do not dispatch dev work on #973 until #278 is in at least in_progress, per the original spawn prompt.

Optional non-blocking polish (do NOT hold the ticket for these):

• [LABEL] (optional) Mirror board labels onto the Forgejo issue itself for consistency across surfaces.
• [SCOPE] (future) File a separate backlog ticket if arch:k8s-deploy is going to keep appearing on tickets, to create an arch-k8s-deploy note. Still not this ticket's job.

Verdict: NEEDS_REFINEMENT

Housekeeping ticket to close 5 obsolete rename-trail issues and remove 2 board items. Scope is sound in direction and reasoning, but one of the five listed tickets is already closed, and there are two small accuracy issues to fix before the ticket can move to todo. Once corrected this is a clean single-agent close-out job (well under 5 minutes).

Template Completeness

• [x] Type (Bug)
• [x] Lineage
• [x] Repo
• [x] What Broke (with per-ticket table)
• [x] Repro Steps
• [x] Expected Behavior
• [x] Environment
• [x] Investigation / Decision Per Ticket (wontfix rationale each)
• [x] Acceptance Criteria
• [x] Related
• [ ] User Story + Architecture sections missing from body — the bug template allows implicit story/arch via board labels, and story:superuser-maintain + arch:k8s-deploy are present on the board item (scope:discovered), so this is acceptable and not blocking.

Traceability

• [x] story:superuser-maintain label on board item — verified in project-pal-e-docs user-stories table (Superuser CRUD via MCP, not direct SQL). Housekeeping closures are exactly that kind of maintenance.
• [x] arch:k8s-deploy label on board item — conceptually valid (touches deployment topology). Note: no dedicated arch-k8s-deploy note exists in pal-e-docs; the closest backing note is arch-domain-pal-e-docs. Creating a dedicated arch-k8s-deploy note is beyond this ticket's scope (housekeeping, not architecture). [SCOPE] — file a separate backlog ticket later if the arch:k8s-deploy label is going to keep being used across multiple issues.
• [x] scope:discovered label — correct, this came out of the 2026-04-11 routing review with Lucas.
• [x] Forgejo issue — forgejo_admin/pal-e-platform#279, open, URL valid.
• [x] Forgejo labels on issue itself — empty. Not a blocker (board item carries the triangle) but worth a [LABEL] mirror for consistency if convention requires.

File Targets

N/A — no file targets. This ticket acts on Forgejo issues and board items via MCP tools (mcp__forgejo__update_issue, mcp__forgejo__comment_on_issue, mcp__pal-e-docs__remove_board_item). One exception: the last AC asks for a note added to feedback_naming_convention — see Accuracy Issues below.

Repo Placement

OK. pal-e-platform is the correct home — the work spans tickets in multiple repos (pal-e-platform, pal-e-app→pal-e-production) but the umbrella action is cross-cutting housekeeping owned by the platform repo. Closures are API-level, no repo code touched.

Dependencies

Depends on forgejo_admin/pal-e-platform#278 (hostname swap). The ticket body references "the canonical hostname swap ticket" in Related but does not cite the number. This is the only dependency; it is live on the board as item #972, backlog, not in progress. The "after the dust settles" framing from the spawn prompt is sound: if #278 discovers that one of the five obsolete tickets still has salvageable intent at the new topology, that intent survives as a new ticket rather than a revival. No circular dependency. No other ticket blocks this one.

Acceptance Criteria

Each AC is machine-verifiable:

• [x] Closing comments — verifiable via curl GET /issues/{n}/comments
• [x] State = closed + wontfix label — verifiable via issue API
• [x] Board items removed — verifiable via list_board_items(board-pal-e-docs)
• [x] "No new tickets filed by this pass" — verifiable by absence
• [x] feedback_naming_convention note updated — but see Accuracy Issues, the referenced note may not exist under that exact slug; needs slug confirmation

Blast Radius

Low. Closing wontfix issues and removing board items is reversible in Forgejo and pal-e-docs MCP. No CI triggered, no code changed, no downstream consumers affected. The only risk is mistaking a still-actionable ticket for an obsolete one — addressed by the per-ticket decision table in the body and double-checked below.

Per-Ticket Verification

Fetched each target via Forgejo API as of 2026-04-11:

• pal-e-platform#234 (ImagePullBackOff) — state=open. Body references pal-e-docs-app namespace and Harbor image paths that no longer exist. Closing rationale is sound: pod is gone, namespace is gone, image path is obsolete. Close as wontfix. No salvageable intent at current topology (the "fix ImagePullBackOff" intent died with the namespace).
• pal-e-platform#255 (Keycloak client rename pal-e-docs-app → pal-e-app) — state=open. Direction is obsolete on both sides. Closing rationale is sound. Flag: the underlying intent — "the Keycloak client ID should match the canonical deployment name" — is still relevant. If the Keycloak client is currently named pal-e-app or pal-e-docs-app but the deployment is pal-e-production, this is live drift that Lucas may want fixed as part of #278 (hostname swap) or as a new standalone ticket. The body of #279 already covers this in its own decision note ("separate ticket if anyone cares to file it") — which conflicts with AC #4 ("no new tickets filed by this pass"). Not a blocker but worth calling out: intent-survives-rename means someone should decide whether to spin up a new Keycloak-rename ticket against the current deployment name, or explicitly defer.
• pal-e-platform#257 (Namespace rename pal-e-docs-app → pal-e-app) — state=open. Same analysis as #255: direction obsolete on both sides, underlying intent ("namespace should match deployment identity") is subsumed by the hostname-swap ticket #278 which already owns the k8s topology reshape. Close as wontfix. Intent covered by #278.
• pal-e-app#87 (Rename pal-e-app → pal-e-docs-app) — state=CLOSED. Already closed on 2026-03-28T17:01:43Z. The ticket body of #279 lists this as one of the 5 to close, but it is already in the desired state. Any closing comment added now must acknowledge the ticket is already closed and only needs a pointer comment, not a state change. Board item #510 still needs removal regardless.
• pal-e-app#88 (Validate session 2026-03-28 merges — 4 PRs) — state=open. Body is about validating pipelines #98-#101 and PRs #83-#86 from a session on the old pal-e-app repo. The repo is gone (redirects to pal-e-production). Validation target is moot. Close as wontfix. Board item #513 needs removal.

Board Item Verification

• [x] Board item #510 — present on board-pal-e-docs, backlog, title "Rename pal-e-app → pal-e-docs-app", links to pal-e-app/issues/87. Ready to remove.
• [x] Board item #513 — present on board-pal-e-docs, backlog, title "Validate: pal-e-app (4 PRs, clone failure)", links to pal-e-app/issues/88. Ready to remove.

Accuracy Issues (must fix before todo)

1. [BODY] pal-e-app#87 is already closed (2026-03-28). The per-ticket decision table and Investigation section both imply #87 is currently open. Update the body to acknowledge the existing closed state: "Already closed on 2026-03-28 — add a pointer comment only, no state change needed. Board item #510 still requires removal."
2. [BODY] Related section cites "the canonical hostname swap ticket" without a number. Add the explicit reference: forgejo_admin/pal-e-platform#278. The dev agent closing the tickets will paste this link into each closing comment; the link must be unambiguous in the source ticket.
3. [BODY] AC #5 references feedback_naming_convention but this slug is not confirmed to exist. The memory index mentions feedback_naming_convention.md (a local memory file, not a pal-e-docs note). The last AC should clarify whether the lesson goes into (a) the user's memory file, (b) a new pal-e-docs note, or (c) is dropped entirely as out-of-scope for a housekeeping pass. Recommendation: drop this AC. Lessons about rename trails belong in a separate docs ticket, not bolted onto a closure pass — otherwise the housekeeping ticket quietly grows into a two-agent job.
4. [SCOPE] Intent-survives-rename tension in AC #4. The decision notes for #255 and #257 say "separate ticket if anyone cares to file it" while AC #4 says "no new tickets filed by this pass". Resolve: explicitly defer any Keycloak/namespace rename-to-current-topology work to a follow-up under #278, and drop the "if anyone cares to file it" language so the agent doesn't interpret it as optional scope creep.

Decomposition Assessment

No decomposition needed. Applying the 5-minute rule:

• File targets: 0 (API-only operations)
• Acceptance criteria: 5 (under the 5-AC threshold; AC #5 should be dropped per accuracy issue #3, bringing it to 4)
• Estimated agent work: ~2-3 minutes for a single agent — four mcp__forgejo__update_issue calls (close+wontfix for #234, #255, #257, #88), one mcp__forgejo__comment_on_issue pointer on the already-closed #87, five closing comments total, and two mcp__pal-e-docs__remove_board_item calls for #510 and #513. All operations are independent and idempotent.
• Repos touched: 1 (pal-e-platform for the umbrella ticket, plus cross-repo API calls — not true decomposition triggers)

Housekeeping tickets are inherently flat. One agent, one pass, done.

Recommendation

• [BODY] Note that pal-e-app#87 is already closed (2026-03-28); only a pointer comment + board item removal is needed.
• [BODY] Cite forgejo_admin/pal-e-platform#278 explicitly in the Related section as "the canonical hostname swap ticket".
• [BODY] Drop or clarify AC #5 (feedback_naming_convention update) — the slug is not a confirmed pal-e-docs note, and the lesson belongs in a separate docs ticket.
• [BODY] Reconcile AC #4 with the per-ticket decision notes: explicitly defer any Keycloak/namespace rename-to-current-topology intent to follow-up work under #278, rather than leaving "file a new ticket if anyone cares" language in the body.
• [SCOPE] Optional: flag for Ava that if the Keycloak client ID currently drifts from the pal-e-production deployment name, a forward-facing Keycloak rename ticket should be queued under #278 — separate decision, not this ticket's job.
• Depends on #278 — confirm spawn prompt guidance (land this after the hostname swap dust settles) is respected on the board; do not advance #973 past todo until #278 is in at least in_progress.

Verdict: NEEDS_REFINEMENT

Board item: #971 on board-pal-e-docs (backlog)
Forgejo issue: forgejo_admin/pal-e-api#256
Type: Bug (Lucas-authored)
Review date: 2026-04-11

Template Completeness

Routed to template-issue-bug. All required sections present.

• [x] Type — Bug
• [x] Lineage — standalone, surfaced during westside-emails note creation
• [x] Repo — forgejo_admin/pal-e-api
• [x] What Broke — clear root cause with CORSMiddleware git-log evidence
• [x] Repro Steps — 5 steps including shell curl repro
• [x] Expected Behavior
• [x] Environment — cluster, ingresses, repos, frontend config var
• [x] Acceptance Criteria — 9 ACs, all testable
• [x] Related — arch-westside-emails, #217 rename, file:line refs

Traceability

• [x] story:reader-browse label — "Reader browses public notes, plans, and project pages in a web UI without authentication"
• [x] story note verified — exists in project-pal-e-docs user-stories table (row 5). This bug directly gates that story: the new pal-e-production hostname is the reader-facing surface and it cannot fetch any data today.
• [x] arch:notes-api label — refers to the API-routes abstraction layer (routers registered in main.py), distinct from the notes entity component in arch-domain-pal-e-docs
• [ ] arch note MISSING — no arch-notes-api note exists. arch-domain-pal-e-docs Components table lists notes (entity/table layer) but has no API-routes component entry. [SCOPE] Create arch-notes-api note (or add a "notes-api" / "routes layer" row to arch-domain-pal-e-docs Components table) documenting the FastAPI router layer. Non-blocking for fix — noted per skill.
• [x] Forgejo issue — URL valid, issue open (created 2026-04-11T20:37:20Z)
• [x] type:bug label — matches issue type
• [x] scope:discovered label — matches Lineage

File Targets

• [x] src/pal_e_docs/main.py — verified. File exists. Line 49 is the FastAPI(...) instantiation as claimed. Router include_router calls are lines 51-58, so "add CORSMiddleware before router includes" is accurate (insert between line 49 and 51).
• [x] CORSMiddleware absence verified — Grep "CORSMiddleware" across ~/pal-e-docs returns zero files. Middleware has never existed in this repo, matching the ticket claim.
• [x] tests/ directory exists with test_health.py, conftest.py, and 17+ other test files — good home for a new test_cors.py or test addition to satisfy AC #7.
• [x] ~/pal-e-app/src/lib/api-client.ts:16 — not reviewed on filesystem (referenced only for context on whether credentialed requests are sent; dev agent should confirm to decide allow_credentials).

Repo Placement

Correct. ~/pal-e-docs is the local checkout of forgejo_admin/pal-e-api (confirmed via git remote -v). Fix is single-repo, single-file. No cross-repo split needed.

Dependencies

Downstream blocker: Board item #972 ("Swap hostname routing — pal-e-docs serves frontend, api.pal-e-docs serves API", forgejo_admin/pal-e-platform#278) depends on this ticket. Without CORS middleware, the hostname swap in #972 will either (a) leave the frontend broken again post-swap or (b) force the swap design to route API and frontend under the same hostname to avoid CORS entirely. The #972 design decision is coupled to whether CORS is fixed first.

The issue body does not mention #972 in the Related section. [BODY] recommendation below.

Upstream blockers: none. No items in in_progress touch main.py or CORS config.

Acceptance Criteria

9 ACs, all testable by an agent after implementation:

• AC1-4: code-level (middleware added, env var driven, default origins, methods/headers) — verifiable by reading the diff
• AC5-6: runtime verification via curl with Origin + preflight OPTIONS — concrete commands, reproducible
• AC7: new test in tests/ — concrete, tests/ exists, pytest infra in place
• AC8: browser render check — validation step, not blocking merge but testable
• AC9: CI deploy via existing Woodpecker — no new infra
• AC10: no regression for non-browser callers — verifiable by existing test suite

One nuance: AC4 says allow_credentials=True "only if the frontend sends credentialed requests." This is a conditional decision the dev agent must make by reading ~/pal-e-app/src/lib/api-client.ts. Acceptable — it's explicit and testable.

Blast Radius

Low.

• Single file (main.py), single middleware registration, purely additive.
• No other FastAPI app in the pal-e-api repo (only one main.py).
• CORS headers on responses are ignored by non-browser clients (curl, SDK, MCP) — no regression risk for existing callers.
• allow_origins is env-var gated (PAL_E_DOCS_CORS_ORIGINS), so non-prod environments can extend origins without code change — good pattern, matches the env-var approach already in config.py.
• No sibling service with the same bug: pal-e-api is the only FastAPI service in this project. basketball-api and others are separate architectures and out of scope.

Decomposition Assessment

5-minute rule check:

• File targets: 1 (main.py) + 1 test file addition. Well under the >3 files across >2 repos threshold.
• Acceptance criteria count: 9. Above the soft ">5 ACs" threshold, but 6 of the 9 ACs are trivial verifications of a single middleware add (methods, headers, credentials, preflight response, regression). They are not distinct work units.
• Estimated agent work: 3-5 minutes — add middleware + env var + 1 config setting + 1 test + 1 curl verification. Single commit, single PR.

No decomposition needed. Fits cleanly in a single agent pass.

Recommendation

• [BODY] Add #972 / forgejo_admin/pal-e-platform#278 to the Related section with a note: "Blocks #972 — hostname swap design depends on whether CORS is fixed first." Non-blocking for fix, but improves traceability.
• [SCOPE] Create an arch-notes-api architecture note (or add a "notes-api / API routes layer" row to arch-domain-pal-e-docs Components table) so the arch:notes-api label has a backing entity. Current arch-domain-pal-e-docs only documents the data/entity layer (notes, blocks, etc.), not the FastAPI router layer. Non-blocking for this fix — dev can proceed — but the backing note gap should be filled as a separate backlog item by Ava.

Neither recommendation blocks dev dispatch. Both are documentation/traceability cleanups. If Ava chooses to move #971 straight to todo after a minor [BODY] tweak and file the arch note as a separate issue, that's appropriate — the scope and fix plan are solid.

Summary

Scope is sound. File target, line reference, git-log claim, and tests/ infra all verified. ACs are testable and concrete. Blast radius is minimal. Ticket is ready to implement once the two minor traceability gaps are noted — one line in the issue body and one new arch note tracked as a follow-up scope item.

Verdict: APPROVED

Round 2 re-review after refinement. All four round-1 blockers resolved. Ticket is READY to move backlog → todo.

Round 1 Blocker Resolution

• [x] [SCOPE] arch-blocks backing note — RESOLVED. arch-domain-pal-e-docs created 2026-04-10 with a blocks row in the Components table covering SQLAlchemy Block, halfvec embeddings, mermaid-skip policy, and the (note_id, anchor_id) uniqueness that enables get_section. Ticket Architecture section now points at this note.
• [x] [SCOPE] arch-notes backing note — RESOLVED. Same arch-domain-pal-e-docs note has a notes row covering SQLAlchemy Note, the html_content legacy vs blocks-authoritative split, and explicitly calls out the missing note_type index as the opportunity this ticket fills (“opportunity for partial index — see ticket pal-e-api#252”). Forward reference is wired.
• [x] [LABEL] arch:notes vs arch:notes-api — RESOLVED. Verified sibling backlog item #908 points at Forgejo issue pal-e-api#251 titled “Create arch-landing-site architecture note for westside-landing”. Its arch:notes-api label refers to the API-routes layer (westside landing-site API). This ticket’s arch:notes refers to the notes DB entity row in arch-domain-pal-e-docs. Different components at different abstraction layers, not a spelling conflict. Ticket body documents the distinction explicitly.
• [x] [BODY] Non-deterministic EXPLAIN ACs — RESOLVED. AC #5 and #6 now prescribe SET enable_seqscan = off; before the EXPLAIN, with a paragraph explaining why (planner may legitimately prefer Seq Scan at 25-row scale; disabling seqscan is the deterministic idiom to verify the partial index is query-planner-visible). Checklist item updated to match.

Template Completeness

• [x] Type (Feature)
• [x] Lineage (includes round-1 review reference — good provenance)
• [x] Repo (with rename-artifact note preserved)
• [x] User Story
• [x] Architecture (new section, names both arch:blocks and arch:notes with pointer to arch-domain-pal-e-docs)
• [x] Context
• [x] File Targets (with explicit exclusions)
• [x] Acceptance Criteria (7 items, all verifiable)
• [x] Test Expectations
• [x] Constraints
• [x] Checklist
• [x] Related

Traceability

• [x] story:superuser-query label — Superuser query path
• [x] story note verified — row present in project-pal-e-docs user-stories table: “I can query the knowledge base by meaning (semantic search)…”
• [x] arch:blocks label — backing component verified in arch-domain-pal-e-docs Components table
• [x] arch:notes label — backing component verified in arch-domain-pal-e-docs Components table (and forward-references this ticket by number)
• [x] area:db label — appropriate
• [x] Forgejo issue — pal-e-api#252 open, refined body matches ticket brief

File Targets

• [x] alembic/versions/<next>_add_mermaid_and_architecture_partial_indexes.py — verified. Current Alembic head is t0o1p2q3r4s5_drop_legacy_boards_table.py (confirmed via Forgejo API listing of alembic/versions/). New migration’s down_revision must chain to this slug. Ticket explicitly instructs the agent to re-verify via alembic heads before writing, which is the right belt-and-suspenders.
• [x] Exclusion of src/pal_e_docs/models.py preserved from round 1 — still correct (SQLAlchemy Index can’t express partial WHERE clauses cleanly).

Repo Placement

OK. pal-e-api is correct; the pal_e_docs package name inside pal-e-api is a known rename artifact, documented in the ticket body.

Dependencies

• [x] Current Alembic head satisfied (t0o1p2q3r4s5, no pending migrations).
• [x] No in_progress board items on board-pal-e-docs touch the blocks or notes schema.
• [x] Backing arch note now exists (arch-domain-pal-e-docs) — no longer blocked.

Acceptance Criteria

7 criteria. All verifiable by an agent post-implementation:

• Two DDL statements with exact index names matching the ix_<table>_<columns> convention and partial predicates.
• Downgrade symmetry (drops both).
• alembic heads chain verification.
• Two EXPLAIN assertions with SET enable_seqscan = off — now deterministic at any data volume.
• Migration applies against current prod schema (dev overlay gate).

Slightly over the 5-AC caution threshold (7), but all 7 are tightly coupled to a single migration file with no independent subtasks. Splitting would produce pointless ceremony. Holding the round-1 judgment: single-pass work.

Blast Radius

Minimal. Pure additive DDL. Partial indexes cost near-zero bytes (~25+25 rows). One file created, one repo, no application code changes, no downstream consumers. Rollback is trivial. blocks.content json→jsonb still explicitly deferred. Unchanged from round 1.

Decomposition Assessment

No decomposition needed.

• Discrete changes: 1 (single migration file)
• Files touched: 1 created, 0 modified
• Repos touched: 1 (pal-e-api)
• Acceptance criteria: 7 (over the 5-AC threshold, but cohesive — one file, one concern, no independent subtasks)
• Estimated agent work: ~3–5 minutes
• No parallelizable subtasks

Recommendation

No action needed. Move backlog → todo. Ticket is READY for dev dispatch.

Drift Note (not a blocker)

Round 1 noted that skill-review-ticket format says “Decomposition” but the template-review hook requires “Decomposition Assessment.” This review uses “Decomposition Assessment” to match the hook. Skill-vs-hook drift is a separate dogfooding ticket; not in scope for this review.

Verdict: NEEDS_REFINEMENT

Scope is technically solid and executable in a single agent pass. Correct repo placement, verified file targets, idiomatic Alembic pattern, testable AC. Blocked on two missing backing architecture notes (traceability triangle) and one label-spelling reconciliation.

Template Completeness

• [x] Type (Feature)
• [x] Lineage
• [x] Repo
• [x] User Story
• [x] Context (strong — explains semantic-documentation motivation vs performance)
• [x] File Targets (with explicit exclusions)
• [x] Acceptance Criteria (6 items, all verifiable)
• [x] Test Expectations (up/down round-trip + EXPLAIN)
• [x] Constraints (partial-index pattern, naming convention, jsonb out of scope)
• [x] Checklist
• [x] Related

Traceability

• [x] story:superuser-query label — Superuser query path
• [x] story note verified — found in project-pal-e-docs user-stories section (row: "I can query the knowledge base by meaning...")
• [x] arch:blocks label present
• [ ] arch-blocks note MISSING — [SCOPE] Create architecture note arch-blocks for the blocks-table component
• [x] arch:notes label present
• [ ] arch-notes note MISSING — [SCOPE] Create architecture note arch-notes for the notes-table component
• [!] Label spelling inconsistency — sibling backlog ticket #908 (pal-e-api) uses arch:notes-api; this ticket uses arch:notes. Confirm canonical label before creating backing notes to avoid two arch notes for the same component.
• [x] Forgejo issue — https://forgejo.tail5b443a.ts.net/forgejo_admin/pal-e-api/issues/252 (open)

File Targets

• [x] alembic/versions/<next>_add_mermaid_and_architecture_partial_indexes.py — verified: alembic/versions/ exists in forgejo_admin/pal-e-api. Current head is t0o1p2q3r4s5 (drop_legacy_boards_table). New migration's down_revision must chain to this.
• [x] Ticket explicitly excludes src/pal_e_docs/models.py edits — verified correct: SQLAlchemy's Index(...) in __table_args__ does not express WHERE clauses for partial indexes. Existing convention in models.py (e.g. ix_blocks_note_id_position, ix_blocks_anchor_id) matches the ix_<table>_<columns> naming the ticket prescribes.
• [x] Block model has block_type: Mapped[str] at models.py:221; Note model has note_type: Mapped[str | None] at models.py:112. Both columns exist and the types match the ticket's assumptions.

Repo Placement

OK. Initially flagged as a potential repo-placement bug because the task brief said "models.py is in ~/pal-e-docs." Verified on Forgejo: schema source lives at forgejo_admin/pal-e-api/src/pal_e_docs/models.py (the Python package is named pal_e_docs inside the pal-e-api repo — a naming artifact from the pal-e-docs→pal-e-api repo rename, board item #439). Alembic also lives in pal-e-api. Ticket is filed against the correct repo. No split across repos needed.

Dependencies

• [x] Current alembic head t0o1p2q3r4s5 — satisfied (no pending migrations on main)
• [x] No blocking in_progress items on board-pal-e-docs touch the blocks or notes schema — satisfied
• [!] arch-blocks and arch-notes backing notes — pending ([SCOPE] above)

Acceptance Criteria

All six AC are verifiable by an agent post-implementation:

• Index existence: introspect pg_indexes or \d blocks / \d notes
• EXPLAIN plans: verifiable, though at 23K blocks / 900 notes PostgreSQL may still prefer Seq Scan for the architecture-notes case (900 rows is tiny). Ticket body should note: if planner chooses Seq Scan, use SET enable_seqscan = off to force the partial index and confirm it is usable. Otherwise AC #4 and #5 may fail non-deterministically at current scale.
• Round-trip: alembic upgrade head && alembic downgrade -1 && alembic upgrade head — real command, runnable in test DB.

Blast Radius

Minimal. Pure additive DDL. Partial indexes cost ~25 rows for mermaid, ~20 for architecture (near-zero bytes). One file created, one repo, no application code changes, no downstream consumers. Rollback is trivial (alembic downgrade -1 drops both indexes). blocks.content json→jsonb migration is explicitly deferred to separate scope. No sibling pattern exists elsewhere — this is a one-off declaration, not a bug being fixed in multiple places.

Decomposition Assessment

No decomposition needed.

• Discrete changes: 1 (single migration file)
• Files touched: 1 created, 0 modified
• Repos touched: 1 (pal-e-api)
• Acceptance criteria: 6 (under the 5-criterion caution threshold — all verifiable via a single agent session)
• Estimated agent work: ~3 minutes (well under the 5-minute rule)
• No independent subtasks to parallelize

Recommendation

1. [SCOPE] Create architecture note arch-blocks (or the canonical label spelling) documenting the blocks table as a first-class query surface. Should reference that mermaid is a partial-index query path.
2. [SCOPE] Create architecture note arch-notes (or arch-notes-api — reconcile with #908's arch:notes-api label first) documenting the notes table. Should reference that architecture-type lookups are a partial-index query path.
3. [LABEL] Reconcile canonical arch label spelling: arch:notes (this ticket) vs arch:notes-api (#908). If canonical is arch:notes-api, update this ticket's label to match before moving to todo.
4. [BODY] Add a sentence to Acceptance Criteria noting that if PostgreSQL planner chooses Seq Scan over the partial index at current scale, the agent should verify with SET enable_seqscan = off to confirm the index is usable (idiomatic partial-index verification).

Once the two arch notes exist and the label spelling is reconciled, this ticket is READY. File targets, decomposition, repo placement, and the story leg of traceability are already confirmed.

Verdict: BLOCK

Template Completeness

• [x] Type — Feature
• [x] Lineage — board, story, arch, enables
• [x] Repo — forgejo_admin/pal-e-api
• [x] User Story — PM wants validation column between needs_approval and done
• [x] Context — explains gap between SOP and API
• [x] File Targets — 3 targets listed
• [x] Acceptance Criteria — 5 criteria
• [x] Test Expectations — 4 test items + run command
• [x] Constraints — 3 constraints listed
• [x] Checklist — 6 items
• [x] Related — sop-board-workflow, convention-validation-checkpoints

All template sections present and well-formed.

Traceability

• [x] story:superuser-maintain — present on board item
• [x] arch:board-api — present on board item
• [x] Forgejo issue — forgejo_admin/pal-e-api#241, open

File Targets

• [x] src/pal_e_docs/schemas.py — ALREADY DONE: BoardColumnType Literal at line 226 already includes "validation" (line 233)
• [x] src/pal_e_docs/routes/boards.py — ALREADY DONE: All board routes already handle the validation column via the existing BoardColumn enum
• [x] alembic/ — ALREADY DONE: Migration r8m9n0o1p2q3_add_validation_board_column.py exists
• [x] src/pal_e_docs/models.py (not listed in issue but relevant) — ALREADY DONE: BoardColumn enum includes validation = "validation" at line 30

All file targets verified — but the work has already been completed.

Repo Placement

Correct repo (pal-e-api). However, the Constraints section notes the MCP SDK docstring needs updating — that lives in pal-e-mcp (separate repo). The MCP docstrings are stale: list_board_items (line 127-129), create_board_item (line 170-171), and update_board_item (line 268-269) enumerate columns without validation. This is a separate ticket for pal-e-mcp.

Dependencies

• [x] Board item #522 (Validate: alembic upgrade head — NoteTypes + validation column, pal-e-api#232) — satisfied, in done
• [x] Board item #524 (Fix 12 failing board_sync tests blocking CI, pal-e-api#233) — satisfied, in done

Both prior items completed the exact work this ticket describes.

Acceptance Criteria

All 5 acceptance criteria are already satisfied in the current codebase:

• update_board_item(column="validation") — works, tested in test_board_item_validation_column
• create_board_item(column="validation") — works, BoardColumnType Literal accepts it
• list_board_items(column="validation") — works, tested in test_board_item_filter_validation_column
• sync_board handles new column — works, BoardColumn enum used throughout
• Existing board items unaffected — confirmed, migration is no-op on VARCHAR

Blast Radius

MCP tool docstrings in pal-e-mcp are stale — three tool descriptions (list_board_items, create_board_item, update_board_item) enumerate column values without validation. Agents relying on MCP tool descriptions may not discover the column exists. This is real discovered scope for a separate ticket.

Decomposition Assessment

N/A — the work is already complete. No implementation needed. The ticket should be closed as duplicate rather than executed.

• Discrete changes: 0 (already done)
• Estimated agent time: 0 minutes
• Independent subtasks: none

Recommendation

1. [SCOPE] Close pal-e-api#241 as duplicate. The validation column already exists in the model enum (models.py:30), schema Literal (schemas.py:233), alembic migration (r8m9n0o1p2q3), and has passing tests (test_note_type_enum.py). This work was completed as part of #232/#233.
2. [BODY] Create a new Forgejo issue on forgejo_admin/pal-e-mcp for the stale MCP docstrings — 3 tool descriptions missing "validation" in their column value lists (list_board_items line 127, create_board_item line 170, update_board_item line 268).

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type -- Task
• [~] Lineage -- present but embedded in Scope, not its own header
• [ ] Repo -- MISSING. No ### Repo section. Should be forgejo_admin/pal-e-app (and arguably forgejo_admin/pal-e-platform)
• [x] User Story -- present (embedded in Scope)
• [ ] Context -- MISSING as separate section. Background merged into Scope
• [x] Scope -- present (replaces File Targets for Task type)
• [x] Acceptance Criteria -- present (7 items)
• [~] Test Expectations -- present but embedded in Scope, not its own header
• [x] Constraints -- present
• [ ] Checklist -- MISSING
• [x] Related -- present

Traceability

• [x] story:reader-browse label -- reader browsing experience validation
• [x] arch:frontend label -- frontend architecture component
• [x] Forgejo issue -- forgejo_admin/pal-e-app#88, open

All three legs present. However, arch:frontend only covers the validation target, not the root cause (cross-namespace k8s networking = arch:ci-pipeline or arch:k8s-deploy).

File Targets

N/A -- Task type uses Scope section instead of File Targets.

Repo Placement

MISMATCH. Issue is filed on pal-e-app but the investigation comment identifies cross-namespace networking as root cause. The fix involves kube-proxy, CoreDNS, NetworkPolicies, and iptables -- all pal-e-platform domain. The ticket conflates two concerns:

1. Infrastructure fix (cross-namespace networking) -- belongs in pal-e-platform
2. Frontend validation (4 merged PRs render correctly) -- correctly in pal-e-app

The investigation comment itself says: "This is likely the same root cause as pal-e-deployments k8s API unreachable -- both are cross-namespace connectivity failures."

Dependencies

• Board item #515 (board-pal-e-platform, backlog): Validate: pal-e-deployments (k8s API unreachable) -- same root cause per investigation comment. Neither can proceed until networking is fixed.
• Board item #411 (board-pal-e-platform, in_progress): Bug: Harbor connectivity timeout from Woodpecker CI agent -- related cross-namespace networking failure. Potentially the same underlying issue.
• Board item #512 (board-pal-e-platform, backlog): Validate: pal-e-platform (3 merged + #222 pending) -- also blocked by same networking issue.

Dependencies are NOT documented in the issue scope. The investigation comment identifies the connection but the ticket does not formally declare blockers.

Acceptance Criteria

7 ACs -- exceeds 5-rule threshold. Assessment:

• AC 1-2 (diagnosis): Testable by an agent pulling logs and documenting findings
• AC 3 (ArgoCD sync): Testable via kubectl
• AC 4 (browser rendering): Requires manual spot-check -- not agent-automatable
• AC 5-7 ("Pipeline verified", "Deployment confirmed", "Features validated"): Vague and redundant with ACs 1-4. Not independently testable.

Blast Radius

HIGH. Cross-namespace networking failure affects ALL Woodpecker pipelines cloning from Forgejo, not just pal-e-app. Every service with CI is impacted. The referenced commits are:

• 992faf3 -- "refactor: modularize terraform monolith into 9 domain modules (#199)" -- confirmed in pal-e-platform
• 6f80d16 -- "fix: allow argocd namespace ingress to forgejo (#202)" -- confirmed in pal-e-platform

Both are infrastructure changes that could have altered NetworkPolicy or routing behavior platform-wide.

Decomposition

NEEDS DECOMPOSITION. 7 ACs across 3 repos (pal-e-app, pal-e-platform, pal-e-deployments), mixing diagnosis with verification. Two distinct work streams:

1. Ticket A (pal-e-platform): Diagnose and fix cross-namespace networking. Blocks everything else. Should consolidate with item #411 and #515.
2. Ticket B (pal-e-app): Validate 4 merged PRs render correctly. Can only proceed after Ticket A resolves.

Current scope exceeds 5-minute agent rule. Recommend decomposition via template-board or splitting into two focused Forgejo issues.

Recommendation

• [BODY] Add missing ### Repo, ### Context, and ### Checklist sections
• [BODY] Remove redundant ACs 5-7 ("Pipeline verified", "Deployment confirmed", "Features validated") -- they duplicate ACs 1-4
• [BODY] Add explicit blocker note: "Blocked by cross-namespace networking fix (see board-pal-e-platform items #411, #512, #515)"
• [LABEL] Add scope:blocked label to board item until networking is resolved
• [SCOPE] Clarify ownership: is this ticket responsible for fixing networking, or only for validating AFTER networking is fixed? Investigation comment suggests diagnosis belongs here, but the fix is a platform concern.
• [DECOMPOSE] Split into 2 tickets: (1) platform networking fix (consolidate with #411/#512/#515), (2) pal-e-app frontend validation (post-fix). Current scope spans 3 repos and 7 ACs.

Verdict: READY

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- Standalone, kanban unification
• [x] Repo -- forgejo_admin/pal-e-api (corrected from v2)
• [x] User Story -- Platform owner, legacy table removal
• [x] Context -- Final cleanup after consumer migration
• [x] File Targets -- 4 source files + 8 test files + alembic migration
• [x] Cross-Repo Blast Radius -- pal-e-app 2 files, alias approach documented
• [x] Acceptance Criteria -- 6 items, all verifiable
• [x] Test Expectations -- pytest command specified
• [x] Constraints -- Pre-migration backup, consumer confirmation, cross-repo note
• [x] Checklist -- Standard 3 items
• [x] Related -- project-pal-e-docs, unlocks recursive kanban
• [x] Notes for Betty Sue -- arch:board-api label request

Traceability

• [x] story:kanban-daily-review label -- kanban unification story
• [ ] arch:board-api label -- MISSING on board item #318. Issue body notes it needs adding. Recommend adding before moving to next_up.
• [x] Forgejo issue -- forgejo_admin/pal-e-api#199, open

File Targets

Source files:

• [x] src/pal_e_docs/models.py -- verified: Board class at line 235, board_id on BoardItem at line 257
• [x] src/pal_e_docs/schemas.py -- verified: BoardCreate at line 231, BoardUpdate at line 236
• [x] src/pal_e_docs/routes/boards.py -- verified: 703 lines, heavily Board/board_id-dependent throughout
• [x] alembic/versions/ -- verified: directory exists, existing migrations present

Test files (all 8 verified to exist):

• [x] tests/test_boards.py
• [x] tests/test_board_sync.py
• [x] tests/test_board_issue_sync.py
• [x] tests/test_private_projects_boards.py
• [x] tests/test_pagination_activity.py
• [x] tests/test_note_type_enum.py
• [x] tests/test_retype_migration.py
• [x] tests/conftest.py

Cross-repo (pal-e-app):

• [x] src/lib/api-client.ts -- verified: board_id: number; at line 40
• [x] src/routes/+page.svelte -- verified: boardMap[item.board_id] at line 139

Repo Placement

OK. Issue filed on forgejo_admin/pal-e-api (correct). Cross-repo impact on pal-e-app documented with backward-compat alias approach. pal-e-docs-sdk and pal-e-mcp have zero board_id references -- no blast radius there.

Dependencies

• Board item #314 "Add 'board' to NoteType" -- done
• Board item #315 "Add board_note_id FK + data migration" -- done
• Board item #316 "Update board API for board notes" -- done
• Board item #317 "Update MCP + SDK + hooks for board-as-note" -- done

All prerequisite migration tickets are in the done column. Dependency chain is satisfied.

Acceptance Criteria

6 AC, all agent-verifiable. Test command pytest tests/ -v is real. AC #4 now correctly reflects the alias+deprecation-header approach (contradiction from v2 resolved). No missing criteria.

Blast Radius

Checked pal-e-app (2 files, documented), pal-e-docs-sdk (0 refs), pal-e-mcp (0 refs). The backward-compat alias prevents breaking pal-e-app. A follow-up pal-e-app ticket to migrate off the alias is implied but not yet created -- acceptable as discovered scope after this PR lands.

Decomposition

13 files across 1 repo, 6 AC. Estimated agent time: borderline (large refactor of 700-line routes file + migration + 8 test files). However, the changes are tightly coupled -- dropping the Board model, rewriting routes, and updating tests MUST land atomically to avoid broken intermediate states. A database migration cannot be split across PRs. No decomposition needed -- atomic scope justifies the size.

V2 Fix Verification

• [x] Repo header corrected: forgejo_admin/pal-e-api (was pal-e-docs)
• [x] Phantom notes.py removed from File Targets
• [x] AC #4 rewritten: alias + X-Deprecated-Field header (was contradictory removal)
• [x] Notes for Betty Sue section added with arch:board-api label request

Recommendation

• [LABEL] Add arch:board-api label to board item #318 before moving to next_up (per Notes for Betty Sue)

All v2 issues resolved. Scope is solid. One housekeeping label remains.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — Feature
• [x] Lineage — Standalone, kanban unification
• [x] Repo — present (but stale, see Recommendation)
• [x] User Story — clear, well-formed
• [x] Context — thorough, explains motivation and unlocks
• [x] File Targets — present with source + test + migration breakdown
• [x] Acceptance Criteria — 6 items
• [x] Test Expectations — present with run command
• [x] Constraints — present, includes rollback guidance
• [x] Checklist — present
• [x] Related — present
• [x] Cross-Repo Blast Radius — bonus section, well-documented

Traceability

• [x] story:kanban-daily-review label — present on board item #318
• [ ] arch:X label — missing. Recommend arch:board-api to match sibling tickets (#315, #316, #327)
• [x] Forgejo issue — forgejo_admin/pal-e-api#199, open

File Targets

Source files:

• [x] src/pal_e_docs/models.py — verified: Board model at line 235, board_id on BoardItem at line 257, board_note_id at line 260 (dual-FK state confirmed)
• [x] src/pal_e_docs/schemas.py — verified: BoardCreate at line 231, BoardUpdate at line 236, board_id at line 242
• [x] src/pal_e_docs/routes/boards.py — verified: ~15 board_id refs + ~122 Board refs (issue says "126 board_id/Board refs" — close enough, actual combined is ~137)
• [ ] src/pal_e_docs/routes/notes.py — ISSUE: ticket claims "2 board_id refs" but grep finds 0 board_id refs and 0 Board model refs. File imports BoardItem and references BoardItem.note_slug but has no Board table dependency. Remove from file targets or clarify what "minor" change is intended.
• [x] alembic/versions/ — new migration needed (verified alembic dir exists)

Test files (8):

• [x] All 8 test files verified — exact match: test_boards.py, test_board_sync.py, test_board_issue_sync.py, test_private_projects_boards.py, test_pagination_activity.py, test_note_type_enum.py, test_retype_migration.py, conftest.py

Cross-repo (pal-e-app):

• [x] src/lib/api-client.ts line 40 — verified: board_id: number;
• [x] src/routes/+page.svelte line 139 — verified: boardMap[item.board_id]

Repo Placement

ISSUE: ### Repo header says forgejo_admin/pal-e-docs but the repo was renamed to forgejo_admin/pal-e-api (board item #439, done). The Forgejo issue is correctly filed on pal-e-api. The ### Repo line in the issue body is stale.

Python package remains pal_e_docs so file paths are correct.

Cross-repo impact (pal-e-app) is documented. No separate pal-e-app Forgejo issue exists yet — ticket says alias handles backward compat. Acceptable if alias is implemented; otherwise pal-e-app issue needed.

Dependencies

All three predecessor tickets are done:

• #315 — Add board_note_id FK + data migration (done)
• #316 — Update board API for board notes (done)
• #317 — Update MCP + SDK + hooks for board-as-note (done)

No blocking items in in_progress. SDK and MCP have zero board_id references — clean.

Acceptance Criteria

Contradiction found: AC #4 says "API response schemas no longer include board_id field" but the Cross-Repo Blast Radius section says "Alias board_note_id as board_id in API responses for backward compatibility." These contradict each other:

• If we alias (keep board_id in responses), AC #4 fails
• If we remove board_id from responses (AC #4 passes), pal-e-app breaks immediately

This needs a human decision: either rewrite AC #4 to account for the alias, or remove the alias strategy and create a coordinated pal-e-app ticket.

Remaining AC are verifiable by an agent via pytest + manual API calls.

Blast Radius

• pal-e-app: 2 files, 2 references — documented in issue. Handled by alias (if alias is kept) or follow-up ticket (if alias is dropped).
• pal-e-docs-sdk: 0 board_id references — clean.
• pal-e-mcp: 0 board_id references — clean.
• claude-custom: 1 doc reference (update-docs.md line 119) — MCP tool parameter name, not a code consumer. No action needed.

Decomposition

14 files across 1 repo. 6 AC. Borderline on the 5-minute rule.

However, the work is atomic and cohesive — you either drop the table or you don't. Test changes are mechanical (board_id to board_note_id). The migration is a single DDL. Splitting would create an artificial intermediate state harder to reason about than doing it in one pass.

No decomposition needed. Single agent pass is appropriate.

Recommendation

• [BODY] Fix repo header: ### Repo should say forgejo_admin/pal-e-api (not forgejo_admin/pal-e-docs)
• [BODY] Fix notes.py claim: remove src/pal_e_docs/routes/notes.py from file targets or clarify — grep finds 0 board_id/Board refs in that file
• [SCOPE] Resolve AC #4 vs alias contradiction: either rewrite AC #4 to say "API response schemas use board_note_id as the canonical field; board_id returned as deprecated alias" OR remove alias strategy and create a pal-e-app coordination ticket
• [LABEL] Add arch:board-api label to board item #318

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — Feature
• [x] Lineage — Standalone, board-pal-e-docs kanban MVP
• [x] Repo — forgejo_admin/pal-e-app
• [x] User Story — present, clear
• [x] Context — present
• [x] File Targets — present
• [x] Acceptance Criteria — 4 items
• [x] Test Expectations — 3 items
• [x] Constraints — present (no Tailwind, copy-paste from playground)
• [x] Checklist — present
• [x] Related — present

Traceability

• [x] story:kanban-daily-review — daily review workflow
• [ ] arch:X label — MISSING. Work touches frontend board component. Should be arch:frontend. Consistent gap across all kanban-daily-review items.
• [x] Forgejo issue — forgejo_admin/pal-e-app#47, open

File Targets

• [x] src/routes/boards/[slug]/+page.svelte — verified: exists (31k), contains board component with drag-and-drop, column rendering, item management
• [x] src/app.css — verified: exists (35k), contains design tokens and column color vars
• [ ] src/routes/boards/[slug]/+page.server.ts — STALE REFERENCE: listed in "Files NOT to touch" but file no longer exists. App migrated to adapter-static + client-side fetching (board item #414, done). Issue body needs update to remove this reference.

Repo Placement

OK. Issue filed on forgejo_admin/pal-e-app, all file targets are in pal-e-app. Single-repo scope.

Dependencies

• BLOCKER: Board item #297 (Playground: kanban prototype, issue #46) is in_progress. This ticket explicitly depends on playground approval. Cannot move to next_up until #297 reaches done and Lucas approves the playground design.
• Board item #474 (Port: board page, issue #72) is done — the current board page already ported from playground. This ticket would replace/enhance that work.

Acceptance Criteria

• "Board view matches playground-approved design" — requires human visual comparison, not agent-automatable. Suggest adding: "screenshot comparison posted on PR"
• "Real API data renders correctly" — testable, but no specific test command given
• "Drag-and-drop works with optimistic updates" — testable manually, no automated test infrastructure for DnD in this repo
• "Auth gating: board mutations require login" — testable, matches existing pattern in the codebase

Test Expectations reference "visual comparison" and manual interaction. No automated test commands specified — acceptable given frontend visual work, but agent verification will be limited to build success + no TypeScript errors.

Blast Radius

• src/app.css is shared across all routes (35k). Merging CSS vars from playground could affect other pages if var names collide or existing vars are modified.
• src/lib/columns.ts and src/lib/colors.ts are imported by the board page — changes to column handling could affect the boards list page (src/routes/boards/+page.svelte).
• No other board-specific components exist outside the boards route.

Decomposition

2 file targets, 1 repo, 4 acceptance criteria — under thresholds. However, the existing +page.svelte is 31k and this is a full design replacement with drag-and-drop + optimistic updates + auth gating. Estimated agent time: borderline 5 minutes. Single agent pass is feasible if playground CSS is finalized, but tight. No decomposition needed if scope stays to "copy playground HTML + wire data bindings."

Recommendation

• [LABEL] Add arch:frontend label to board item #298
• [BODY] Remove stale reference to src/routes/boards/[slug]/+page.server.ts in "Files NOT to touch" — file no longer exists after adapter-static migration
• [BODY] Add note that playground kanban board item #297 must be done before this moves to next_up
• [SCOPE] Clarify: does "replace with playground-approved design" mean full rewrite of the 31k +page.svelte, or incremental CSS/layout changes on top of the existing ported board page (#72)?

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- Standalone, discovered during worktree lifecycle session
• [x] Repo -- forgejo_admin/pal-e-app
• [x] User Story -- As a platform operator...
• [x] Context -- Naming convention evolution explained
• [x] File Targets -- Blast radius list provided (but see issues below)
• [x] Acceptance Criteria -- 7 criteria listed
• [x] Test Expectations -- 3 expectations
• [x] Constraints -- Coordination + maintenance window noted
• [x] Checklist -- Present
• [x] Related -- project-pal-e-docs + feedback_naming_convention referenced

All template sections present. Template is complete.

Traceability

• [x] story:superuser-maintain -- board item has this label
• [x] arch:naming -- board item has this label
• [x] Forgejo issue -- forgejo_admin/pal-e-app#87, open
• [x] scope:cross-repo -- correctly flagged on board item

Traceability triangle complete.

File Targets

• [x] Forgejo repo name -- exists at forgejo_admin/pal-e-app, confirmed via API
• [x] Harbor image -- confirmed: harbor.tail5b443a.ts.net/pal-e-app/app referenced in k8s/deployment.yaml and pal-e-deployments overlay
• [ ] ArgoCD app reference in pal-e-services -- ISSUE: no pal-e-app references exist in pal-e-services/terraform/. This file target is WRONG.
• [x] Kustomize overlay in pal-e-deployments -- confirmed: overlays/pal-e-app/prod/ exists with kustomization.yaml, ingress.yaml, deployment-patch.yaml, harbor-creds.enc.yaml
• [ ] Tailscale funnel hostname -- NOT VERIFIED: no pal-e-app funnel found in pal-e-services or pal-e-platform terraform. Needs clarification.
• [x] Woodpecker CI repo reference -- confirmed: .woodpecker.yaml references forgejo_admin/pal-e-app, Harbor repo pal-e-app/app, overlay pal-e-app
• [x] Local directory -- confirmed: ~/pal-e-app exists
• [x] MEMORY.md repo locations -- confirmed: 3 references to pal-e-app in MEMORY.md
• [x] Board items with pal-e-app issue URLs -- confirmed: 15+ board items reference forgejo_admin/pal-e-app issues

Undocumented file targets found:

• [ ] MISSING: pal-e-platform/terraform/modules/monitoring/main.tf -- Blackbox exporter target (http://pal-e-app.pal-e-app.svc.cluster.local:3000)
• [ ] MISSING: pal-e-platform/scripts/woodpecker-update-tag-step.yaml -- CI overlay mapping
• [ ] MISSING: pal-e-platform/scripts/test-update-kustomize-tag.sh -- test Harbor image refs
• [ ] MISSING: pal-e-app/package.json -- package name
• [ ] MISSING: pal-e-app/e2e/*.spec.ts -- e2e test URLs
• [ ] MISSING: pal-e-app/src/lib/keycloak.ts -- client config
• [ ] MISSING: pal-e-app/playwright.config.ts -- base URL
• [ ] MISSING: k8s namespace -- currently pal-e-app.pal-e-app.svc.cluster.local implies namespace = pal-e-app

Repo Placement

Issue filed on forgejo_admin/pal-e-app (correct as primary target). Changes span 4+ repos:

• forgejo_admin/pal-e-app -- repo rename + internal refs
• forgejo_admin/pal-e-deployments -- kustomize overlay rename
• forgejo_admin/pal-e-platform -- monitoring TF + CI scripts
• forgejo_admin/claude-custom -- MEMORY.md

Each repo should get its own Forgejo issue per convention (one ticket = one agent = one PR).

Dependencies

• Board item #434 ("Delete stale pal-e-app overlay") marked done but overlay still exists locally -- verify if completed or local staleness.
• Items #440 (SDK rename) and #441 (MCP rename) are done -- serve as precedent for rename pattern.
• Item #444 (claude-custom + docs for renames) is done but MEMORY.md still shows old refs -- local may be stale.
• Phase #37 (Repo Renames) is done -- this rename is a remaining piece.
• 4 items in next_up reference pal-e-app issues (#69-#74) -- URLs break if Forgejo does not auto-redirect.

Acceptance Criteria

7 criteria listed. Most verifiable. Missing criteria:

• Monitoring TF updated
• CI scripts updated
• Keycloak client config verified
• k8s namespace decision documented

Blast Radius

• Monitoring: Blackbox exporter URL breaks if service name changes
• CI scripts: hardcoded pal-e-app overlay references in pal-e-platform
• k8s namespace: if namespace changes, ALL internal DNS changes
• Keycloak OIDC: possible client ID + redirect URI changes
• Tailscale funnel: hostname + TLS cert may change
• Board items: 15+ items store raw pal-e-app issue URLs

Decomposition

NEEDS DECOMPOSITION: 10+ file targets across 4+ repos. 7 acceptance criteria. Estimated agent time 30+ minutes. Requires maintenance window for coordinated execution.

Recommend decomposition via template-board into 5-7 tickets:

1. Forgejo repo rename (admin action)
2. pal-e-deployments overlay rename (single PR)
3. pal-e-platform monitoring + CI script updates (single PR)
4. pal-e-app internal refs -- package.json, k8s manifests, Woodpecker, e2e configs (single PR, done pre-rename or as part of rename)
5. claude-custom MEMORY.md update (single PR)
6. pal-e-docs board item URL fixup (MCP bulk update)
7. Keycloak client config update (if applicable)

Recommendation

• [BODY] Remove "ArgoCD app reference in pal-e-services" from File Targets -- no pal-e-app references exist in pal-e-services
• [BODY] Add missing file targets: pal-e-platform/terraform/modules/monitoring/main.tf, pal-e-platform/scripts/woodpecker-update-tag-step.yaml, pal-e-platform/scripts/test-update-kustomize-tag.sh, plus internal app files (package.json, keycloak.ts, playwright.config.ts, e2e specs)
• [BODY] Add missing acceptance criteria: monitoring TF updated, CI scripts updated, Keycloak client verified, k8s namespace decision documented
• [SCOPE] Clarify: does the k8s namespace change from pal-e-app to pal-e-docs-app? Massive blast radius on service DNS.
• [SCOPE] Clarify: is pal-e-app registered as a Keycloak OIDC client? If so, client ID + redirect URIs need updating.
• [SCOPE] Clarify: what is the Tailscale funnel hostname? Is it pal-e-app.tail5b443a.ts.net?
• [DECOMPOSE] 10+ file targets across 4+ repos, 7 AC -- split into 5-7 tickets via template-board. One ticket per repo minimum, plus admin actions.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] All 11 required sections present.

Traceability

• [x] story:reader-browse — [x] arch:frontend — [x] Forgejo issue pal-e-app#74, open

File Targets

• [x] src/routes/graph/+page.svelte — CORRECT. Does not exist yet. New route. Playground graph.html exists as source.
• [ ] src/routes/graph/+page.ts — DOES NOT FIT PATTERN. No +page.ts files in the app. Wrong file target.

Dependencies

• #68 resolved.
• Ticket says "note links API" — need to verify REST endpoint exists (MCP has get_note_links, but agent needs a REST route).

Acceptance Criteria

4 criteria, testable. SVG force-directed layout is the most complex port. Playground graph.html has ~200+ lines of JS for force simulation. Borderline for 5-minute rule but feasible as copy-paste port.

Blast Radius

• New route — low blast radius.
• Sidebar in +layout.svelte may need a /graph nav link added. Ticket doesn't mention this.

Recommendation

1. Remove +page.ts from file targets.
2. Verify note-links REST API endpoint exists in pal-e-api.
3. Add sidebar nav link update to scope (or create discovered-scope issue).
4. Note: force-directed layout JS may need Svelte adaptation.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] All 11 required sections present.

Traceability

• [x] story:reader-browse — [x] arch:frontend — [x] Forgejo issue pal-e-app#73, open

File Targets

• [ ] src/routes/notes/[slug]/+page.svelte — WRONG PATH. Project pages live at src/routes/projects/[slug]/+page.svelte. Ticket says "note_type=project-page" but projects have a dedicated route at /projects/{slug} that loads via listProjects API.
• [x] src/routes/projects/[slug]/+page.svelte — actual target. Shows project notes, board link, note type breakdown.
• [!] "May need project-specific layout component" — vague. Current page is self-contained.

Dependencies

#68 resolved. Project page imports from $lib/colors and $lib/columns.

Acceptance Criteria

3 criteria. "Architecture diagram section renders" — this is net-new functionality (current page has no architecture section). Needs clarification on how diagrams are stored.

Blast Radius

Low — /projects list and sidebar nav link to projects. Must continue working.

Recommendation

1. Fix file target: should be src/routes/projects/[slug]/+page.svelte.
2. Replace vague "May need" with a concrete decision.
3. Clarify how architecture diagrams are stored and rendered (blocks? mermaid? inline HTML?).

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] All 11 required sections present.

Traceability

• [x] story:reader-browse — [x] arch:frontend — [x] Forgejo issue pal-e-app#72, open

File Targets

• [ ] src/routes/notes/[slug]/+page.svelte — WRONG PATH. Board pages live at src/routes/boards/[slug]/+page.svelte. The note detail page redirects board notes to /boards/{slug}. Ticket points to the wrong file.
• [x] src/routes/boards/[slug]/+page.svelte — actual target. Full kanban with drag-drop, column filtering, item CRUD.
• [!] "Existing board components" — vague. Board is one large Svelte file, not a component library.

Dependencies

#68 resolved. Board page imports from $lib/colors and $lib/columns.

Acceptance Criteria

3 criteria — missing: "Drag-and-drop still functional" and "Board item CRUD preserved." Existing board is feature-rich. Restyle must not regress.

Blast Radius

High — board item management (create/move/delete) is used actively by kanban workflow.

Recommendation

1. Fix file target: should be src/routes/boards/[slug]/+page.svelte.
2. Add acceptance criteria for drag-drop and CRUD preservation.
3. Clarify "existing board components" — single file, not component library.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] All 11 required sections present.

Traceability

• [x] story:reader-browse — [x] arch:frontend — [x] Forgejo issue pal-e-app#71, open

File Targets

• [x] src/routes/notes/[slug]/+page.svelte — EXISTS. Renders via NoteLayout with blocks, TOC, child notes, parent breadcrumb.
• [ ] src/routes/notes/[slug]/+page.ts — DOES NOT EXIST. Wrong file target.

Dependencies

• #68 resolved.
• Ticket says "Reuse existing BlockRenderer" — component is actually NoteLayout.svelte at src/lib/components/NoteLayout.svelte. Block rendering in src/lib/components/blocks/. Name "BlockRenderer" does not exist as a component.

Acceptance Criteria

4 criteria, testable. "All block types render via existing BlockRenderer" — wrong component name.

Blast Radius

• Note detail has board redirect: note_type === 'board' sends to /boards/{slug}. Must preserve.
• /notes/[slug]/edit links back to detail. Must not break edit flow.

Recommendation

1. Remove +page.ts from file targets.
2. Fix component name: "BlockRenderer" should be "NoteLayout" ($lib/components/NoteLayout.svelte) + block components from $lib/components/blocks/.
3. Add constraint: preserve note_type === 'board' redirect.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — [x] Lineage — [x] Repo — [x] User Story — [x] Context — [x] File Targets — [x] Acceptance Criteria — [x] Test Expectations — [x] Constraints — [x] Checklist — [x] Related

Traceability

• [x] story:reader-browse — board item label present
• [x] arch:frontend — board item label present
• [x] Forgejo issue — pal-e-app#70, open

File Targets

• [x] src/routes/notes/+page.svelte — EXISTS. Currently has type-colored cards with filter bar. Clean port target.
• [ ] src/routes/notes/+page.ts — DOES NOT EXIST. App uses client-side fetching. Wrong file target.

Repo Placement

OK

Dependencies

#68 resolved. Existing page imports typeColor from $lib/colors (still exists).

Acceptance Criteria

4 criteria, testable. This is a restyle of an existing page, not greenfield. Ticket should note that.

Blast Radius

Low — standalone page.

Recommendation

1. Remove src/routes/notes/+page.ts from file targets.
2. Add context that page already exists with filtering — this is a restyle, not new build.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type
• [x] Lineage
• [x] Repo
• [x] User Story
• [x] Context
• [x] File Targets
• [x] Acceptance Criteria
• [x] Test Expectations
• [x] Constraints
• [x] Checklist
• [x] Related

Traceability

• [x] story:reader-browse — board item label present
• [x] arch:frontend — board item label present
• [x] Forgejo issue — pal-e-app#69, open

File Targets

• [!] src/routes/+page.svelte — EXISTS but ambiguity: there is ALSO src/routes/dashboard/+page.svelte (a board-centric dashboard). Ticket says "replace current home with dashboard from playground" but doesn't acknowledge the existing /dashboard route. Which one survives?
• [ ] src/routes/+page.ts — DOES NOT EXIST. App uses client-side fetching via onMount, not SvelteKit load functions. No +page.ts files exist anywhere in the routes. Wrong file target.

Repo Placement

OK — issue filed on pal-e-app, work is in pal-e-app.

Dependencies

• #68 (CSS + sidebar foundation) — closed, done on board. Resolved.
• Note: colors.ts still exists despite #68 scope saying to delete it. Current home page does NOT import it, but nearby files do.

Acceptance Criteria

4 criteria, all testable. Should clarify what happens to the /dashboard route.

Blast Radius

The existing /dashboard route may become orphaned or redundant. No ticket addresses this.

Recommendation

1. Remove src/routes/+page.ts from file targets — data fetching stays in onMount.
2. Clarify what happens to src/routes/dashboard/+page.svelte — delete? keep? merge?

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type
• [x] Lineage
• [x] Repo
• [x] User Story
• [x] Context
• [x] File Targets
• [x] Acceptance Criteria
• [x] Test Expectations
• [x] Constraints
• [x] Checklist
• [x] Related

Traceability

• [ ] story:X label — missing. Board item #282 has no story label. This is foundational MCP tooling, so arguably acceptable, but a story like story:superuser-maintain or story:agent-write would complete the triangle.
• [ ] arch:X label — missing. Should be arch:mcp to match the component being modified.
• [x] Forgejo issue — forgejo_admin/pal-e-mcp#45, open

File Targets

• [ ] src/pal_e_docs_mcp/tools/boards.py — ISSUE: path is stale. Repo was renamed from pal-e-docs-mcp to pal-e-mcp; package is now pal_e_mcp. Correct path: src/pal_e_mcp/tools/boards.py
• [x] update_board_item function — verified at line 207 (issue says ~line 209, close enough). Confirmed: title parameter is absent. create_board_item already has it (line 163). Pattern to follow is clear.
• [x] SDK support — verified. ~/pal-e-docs-sdk/src/pal_e_sdk/boards.py lines 106 and 139 both accept title. No SDK changes needed.

Repo Placement

Issue is filed on forgejo_admin/pal-e-mcp (redirects from old name pal-e-docs-mcp). Correct — only the MCP tool layer needs the change. SDK and API already support title. Single-repo fix.

Dependencies

• Board item #281 (pal-e-docs#192, sync_board title drift detection) is the companion issue in backlog. No dependency — they were intentionally split. This ticket can proceed independently.
• No blockers in in_progress column that affect this work.

Acceptance Criteria

3 criteria, all verifiable by an agent. Test command pytest tests/ -k update_board_item is real — tests/test_param_alignment.py has a TestUpdateBoardItem class with 5 existing tests that exercise column, labels, whitespace, trailing comma, and omitted fields. New tests for title would follow the same pattern.

Blast Radius

• create_board_item already has title — no drift.
• bulk_move_board_items does not support title, but it is specifically a column-move batch tool. No concern.
• No downstream consumers affected. The change is additive and backward compatible.

Recommendation

Two fixes needed before READY:

1. Update file path in issue body: Change src/pal_e_docs_mcp/tools/boards.py to src/pal_e_mcp/tools/boards.py. The repo rename means the old path will confuse the implementing agent.
2. Add traceability labels to board item #282: Add arch:mcp at minimum. Consider adding a story label (e.g. story:agent-write).

Also note: the ### Repo field says forgejo_admin/pal-e-docs-mcp which redirects but should be updated to forgejo_admin/pal-e-mcp for clarity.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- references pal-e-docs-playground#1
• [x] Repo -- forgejo_admin/pal-e-app
• [x] User Story -- well-formed As/I want/So that
• [x] Context -- thorough background
• [x] File Targets -- present with read-only and do-not-touch sections
• [x] Acceptance Criteria -- 6 criteria listed
• [x] Test Expectations -- N/A acknowledged (review ticket)
• [x] Constraints -- present
• [x] Checklist -- present
• [x] Related -- present with story and board references

Traceability

• [x] story:reader-browse label -- matches user story for note browsing
• [x] arch:frontend label -- correct, this is frontend alignment work
• [x] Forgejo issue -- forgejo_admin/pal-e-app#65, open

File Targets

• [x] ~/pal-e-docs-playground/*.html -- verified: 6 HTML files exist (index.html, notes.html, note.html, note-board.html, note-project.html, graph.html)
• [x] ~/pal-e-docs-playground/app.css -- verified: exists
• [x] ~/pal-e-app/src/app.css -- verified: exists
• [x] ~/pal-e-app/src/lib/components/blocks/ -- verified: 7 files (BlockRenderer.svelte + 6 type-specific components)
• [x] ~/pal-e-app/src/routes/ -- verified: exists with dashboard, notes, boards, projects, repos, search, tags routes
• [ ] ~/pal-e-app/src/lib/api.ts -- WRONG PATH: file does not exist. Actual path is ~/pal-e-app/src/lib/api-client.ts
• [x] ~/pal-e-docs/src/pal_e_docs/routes/ -- verified: exists with notes.py, boards.py, blocks.py, projects.py, tags.py, repos.py, links.py, health.py

Repo Placement

OK -- filed on pal-e-app which is the primary consumer. File targets correctly span three repos (pal-e-docs-playground, pal-e-app, pal-e-docs) which is appropriate for a cross-repo alignment review.

Dependencies

• Board item #422 (pal-e-docs-playground#1 -- "Playground: note detail page prototype") is in todo column with same labels. The issue Lineage says this ticket follows that playground prototype. If playground#1 is incomplete, this review may be premature or scoped to only the pages that exist.
• Board item #93 (Phase F11: Design System Overhaul) is in_progress with story:reader-browse. Active design work could change what the alignment review finds.
• Board item #297 (Playground: kanban prototype) is in_progress. Kanban board page may evolve during this review.
• Dependencies are not documented in the issue scope. The Lineage section mentions the playground prerequisite but does not flag these as blocking risks.

Acceptance Criteria

• Criterion 1 ("Every @data field maps to a real API response field") -- Testable by an agent. Can compare data contracts against API response schemas.
• Criterion 2 ("Every @api endpoint exists in backend") -- Testable. However, already partially falsifiable: the playground index.html references GET /api/boards/items?column=in_progress but the actual endpoint is GET /boards/activity?column=in_progress. The notes list endpoint has no sort parameter -- it always sorts by updated_at desc by default. The graph page has no corresponding backend API endpoint at all.
• Criterion 3 ("Block types match BlockRenderer dispatch, 6 types, no callouts") -- Contradicts the playground data contract at note.html:18 which lists "callout" as a block type. The playground CSS also has callout styles (.block--callout, .callout-label, variants). The BlockRenderer handles 6 types (heading, paragraph, code, table, list, mermaid) with no callout. This contradiction should be resolved in the issue scope.
• Criterion 4 ("Gap list produced") -- Agent-verifiable as a deliverable.
• Criterion 5 ("Search page spec added to playground") -- This is a code change, not a review. The issue says "Read-only review -- no code changes" in Constraints, but this criterion requires creating a new playground page. Contradiction.
• Criterion 6 ("Alignment doc written") -- Agent-verifiable as a deliverable.

Blast Radius

• The wrong API client path (api.ts vs api-client.ts) is a minor issue but if an agent follows the ticket literally, it will fail to find the file.
• The callout block type discrepancy between playground and app needs resolution -- either the playground contract is aspirational (add callout support later) or the playground is wrong. If callout is needed, that is new scope for the port.
• The graph page has no backend endpoint. The existing /notes/{slug}/links endpoint returns per-note links, not a full graph. Building a graph API would be significant new scope not captured here.
• The existing pal-e-app already has a search route, but the playground does not have a search page. The ticket flags this gap correctly but mixing "add search page to playground" with "review alignment" conflates review and implementation scope.

Recommendation

Four issues to fix before READY:

1. Fix file path: Change ~/pal-e-app/src/lib/api.ts to ~/pal-e-app/src/lib/api-client.ts in File Targets.
2. Resolve callout contradiction: Acceptance criterion 3 says "no callouts" but the playground data contract and CSS include callouts. Clarify whether the review should flag callout as a gap or confirm its exclusion.
3. Remove or split search page criterion: Acceptance criterion 5 ("Search page spec added to playground") is a code change that contradicts the "Read-only review -- no code changes" constraint. Either remove it from this ticket and create a separate issue, or remove the no-code-changes constraint.
4. Document dependency risk: Board item #422 (playground#1) is still in todo. If this review depends on a complete playground, that dependency should be explicit. If it can proceed with the 6 existing pages, state that.

Verdict: READY

Re-review after full rewrite. Original issue (pal-e-app#62) had 6 blocking issues. All 6 resolved in claude-custom#174.

Previous Issues -- Resolution Status

1. Wrong repo -- FIXED. Issue now filed on forgejo_admin/claude-custom#174 (correct repo).
2. 11 missing .md files -- FIXED. All 11 hook files, 5 agent files, 2 skill files, 2 root files listed with specific rename instructions.
3. 3 MEMORY.md files -- FIXED. All 3 MEMORY.md files listed plus "Individual memory .md files referencing old repo names."
4. Blast radius in minio-sdk -- FIXED. ~/minio-sdk/CLAUDE.md explicitly listed under "Other repos' CLAUDE.md files."
5. Architecture diagrams unspecified -- FIXED. project-pal-e-docs listed with "architecture diagrams (3 Mermaid diagrams reference pal-e-docs-mcp node and pal-e-docs namespace)." Acceptance criteria includes "Architecture diagrams updated with new names."
6. Acceptance criteria gaps -- FIXED. 8 concrete acceptance criteria with specific grep commands. 4 test expectations with runnable commands.

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- traces to pal-e-app#62 (moved)
• [x] Repo -- forgejo_admin/claude-custom
• [x] User Story -- "As the platform / I want all cross-references updated / So that hooks, agents, docs, and memory files reflect the new names"
• [x] Context -- explains three renames, clarifies MCP prefix stays unchanged
• [x] File Targets -- comprehensive: 11 hooks, 5 agents, 2 skills, 2 root, 3 memory, 4 pal-e-docs notes, 3 other repos' CLAUDE.md, plus explicit "NOT touch" list
• [x] Acceptance Criteria -- 8 items with grep verification commands
• [x] Test Expectations -- 4 items with runnable commands
• [x] Constraints -- 5 constraints including MCP prefix preservation
• [x] Checklist -- 6 items covering PR, notes, memory, other repos, tests
• [x] Related -- 4 items: 3 prerequisite issues + deferred phase

Traceability

• [x] story:superuser-maintain label -- present on board item #444
• [x] arch:convention label -- present on board item #444
• [x] Forgejo issue -- forgejo_admin/claude-custom#174, open

File Targets

claude-custom hooks (11 files):

• [x] hooks/session-start-context.sh -- verified: contains PAL_E_DOCS_URL (12 occurrences)
• [x] hooks/check-note-template.sh -- verified: contains PAL_E_DOCS_URL (2 occurrences)
• [x] hooks/check-pr-template.sh -- verified: contains PAL_E_DOCS_URL (2 occurrences)
• [x] hooks/check-issue-template.sh -- verified: contains PAL_E_DOCS_URL (2 occurrences)
• [x] hooks/board-item-on-merge.sh -- verified: contains PAL_E_DOCS_URL (3 occurrences)
• [x] hooks/session-start-board-sync.sh -- verified: contains PAL_E_DOCS_URL (2 occurrences)
• [x] hooks/cleanup-worktrees.sh -- verified: contains $HOME/pal-e-docs, $HOME/pal-e-docs-sdk, $HOME/pal-e-docs-mcp
• [x] hooks/block-dottie-code-writes.sh -- verified: contains /home/ldraney/pal-e-docs-sdk/* and /home/ldraney/pal-e-docs-mcp/*
• [x] hooks/inject-subagent-context.sh -- verified: prose references to "pal-e-docs" (repo context in agent descriptions)
• [x] hooks/stop-doc-checkin.sh -- verified: prose references to "pal-e-docs"
• [x] hooks/remind-review-loop.sh -- verified: prose references to "pal-e-docs"

claude-custom agents (5 files):

• [x] agents/betty-sue.md -- verified: exists, references pal-e-docs
• [x] agents/dev.md -- verified: exists, references pal-e-docs
• [x] agents/qa.md -- verified: exists, references pal-e-docs
• [x] agents/dottie.md -- verified: exists, references pal-e-docs
• [x] agents/penny.md -- verified: exists, references pal-e-docs

claude-custom skills (2 files):

• [x] skills/review-ticket/SKILL.md -- verified: exists, references pal-e-docs
• [x] skills/plan/SKILL.md -- verified: exists, references pal-e-docs

claude-custom root (2 files):

• [x] CLAUDE.md -- verified: exists, references pal-e-docs
• [x] README.md -- verified: exists, references pal-e-docs

Memory files (3 MEMORY.md + individual files):

• [x] ~/.claude/projects/-home-ldraney-pal-e-platform/memory/MEMORY.md -- verified: contains ~/pal-e-docs, ~/pal-e-docs-sdk, ~/pal-e-docs-mcp (lines 103-105, 127)
• [x] ~/.claude/projects/-home-ldraney-pal-e-docs/memory/MEMORY.md -- verified: contains pal-e-docs-mcp reference (line 69)
• [x] ~/.claude/projects/-home-ldraney-pal-e-services/memory/MEMORY.md -- verified: contains pal-e-docs-mcp reference (line 5)
• [x] Individual files -- verified: feedback_naming_convention.md contains old repo names

pal-e-docs notes (via MCP):

• [x] project-pal-e-docs repos table -- verified: still shows old names (pal-e-docs, pal-e-docs-mcp, pal-e-docs-sdk with "planned rename" notes)
• [x] project-pal-e-docs architecture diagrams -- verified: 3 Mermaid diagrams reference pal-e-docs-mcp node name and pal-e-docs namespace
• [x] worktree-workflow remote conventions table -- verified: still lists pal-e-docs, pal-e-docs-sdk, pal-e-docs-mcp as repo names
• [x] convention-sveltekit-spa -- verified: no old repo name references found (clean)

Other repos' CLAUDE.md (3 files):

• [x] ~/pal-e-app/CLAUDE.md -- verified: exists, references "pal-e-docs API" and PAL_E_DOCS_API_URL
• [x] ~/pal-e-services/CLAUDE.md -- verified: exists, no pal-e-docs references found (clean)
• [x] ~/minio-sdk/CLAUDE.md -- verified: contains "Follow pal-e-docs-sdk patterns" (line 53)

Repo Placement

OK. Issue filed on forgejo_admin/claude-custom -- correct, since the primary work is in claude-custom. The issue clearly documents that pal-e-docs notes are updated via MCP (not file writes), other repos' CLAUDE.md files are secondary targets, and memory files are in ~/.claude/. Multi-repo scope is well-documented and appropriate for a single coordinating issue.

Dependencies

• Board item #439 (pal-e-docs#217 -- API rename) -- backlog on board-pal-e-docs. PREREQUISITE.
• Board item #440 (pal-e-docs-sdk#38 -- SDK rename) -- backlog on board-pal-e-docs. PREREQUISITE.
• Board item #441 (pal-e-docs-mcp#50 -- MCP rename) -- backlog on board-pal-e-docs. PREREQUISITE.
• Constraints section correctly states: "All three repo renames must complete before this ticket starts."
• All three prerequisites are on the same board (board-pal-e-docs) and currently in backlog.

Acceptance Criteria

All 8 criteria are machine-verifiable:

• [x] 4 grep commands with expected 0-match results -- agent can run these
• [x] 1 pal-e-docs project page check -- agent can verify via MCP
• [x] 1 architecture diagrams check -- agent can verify via MCP get_section
• [x] 1 session start check -- agent can verify by starting a fresh session
• [x] 1 hooks check -- agent can verify by triggering hooks

Test expectations include 4 items with runnable commands. All verifiable.

Blast Radius

Minor observation (not blocking): The ~/pal-e-app/CLAUDE.md references PAL_E_DOCS_API_URL as an env var and pal-e-docs-api.tail5b443a.ts.net as a Tailscale funnel hostname. These are infrastructure-level references (env var name, DNS hostname) that may or may not change with the repo rename. The issue lists ~/pal-e-app/CLAUDE.md as a target with "repo references" but does not specify whether PAL_E_DOCS_API_URL and the Tailscale funnel hostname should change. The implementing agent can determine this from context -- the env var refers to the API service, not the repo, and may intentionally keep the "pal-e-docs" project branding even after the repo is renamed to pal-e-api. This is a judgment call for the implementer, not a scope gap.

No unidentified blast radius. Grep across claude-custom, memory files, and referenced repos confirms the issue's file targets are comprehensive.

Recommendation

No action needed. The rewrite addresses all 6 issues from the previous review. File targets are comprehensive and verified against the filesystem and pal-e-docs. Acceptance criteria are machine-testable. Dependencies are documented and all sit on the same board. Repo placement is correct. This ticket is ready to move from backlog to todo.