pal-e-docs

Epilogue: Post-Plan Cleanup

phase-postgres-epilogue-cleanup Phase

Project

Epilogue: Post-Plan Cleanup

Work that should happen immediately after the main Act 2 phases (5-8) are complete, before the plan is marked completed. These are process improvements discovered during execution that don't belong in any technical phase but must not be forgotten.

Items

1. Migrate worktree location to /tmp [RESOLVED — SOP rewrite 2026-03-13]

Update the worktree workflow SOP to use /tmp/claude-worktrees/[repo]/[branch] instead of ~/[repo]/.worktrees or ~/[repo]/.claude/worktrees.
Benefits:
  • /tmp auto-cleans on reboot — no manual cleanup needed
  • Worktrees are session-scoped anyway (10+ PRs/day make stale worktrees inevitable)
  • Eliminates the class of bugs where stale worktrees accumulate in repo directories
Tracked: todo-worktree-tmp-migration
Related: worktree-workflow, sop-claude-config-development, todo-worktree-cleanup

2. Enforce local main freshness after PR merge [RESOLVED — SOP rewrite 2026-03-13]

Ensure SOPs and claude config enforce keeping local main up to date (git pull) in ~/[repo] after every PR merge. This prevents the stale worktree problem that wasted 40K+ tokens in a single session.
Related: todo-worktree-staleness-prevention, sop-claude-config-development

3. Upgrade Betty Sue's session injection [RESOLVED — 7e-3]

Once blocks + TOC tools exist (Phase 7d), rewrite the session startup to use get_toc() + targeted get_block() instead of 4 full get_note() calls. Target: ~400 tokens instead of ~8,750. This is the single biggest token savings opportunity.
Depends on: Phase 7d (Block API + MCP Tools)

4. Upgrade Dottie's config

Create proper claude-custom agent config (dottie.md) with tool restrictions.
See: todo-dottie-claude-config

5. Agent spawn reasoning documentation [RESOLVED — 2026-03-13]

Document the pattern: why we spawn agents (context preservation), when to use Dottie vs Dev vs QA, and how the four-agent model distributes work. Update agent-spawn-conventions to include Dottie spawn patterns.

6. Post-merge hook automation reference [RESOLVED — 7f-7]

Formalize in Phase 7f. The sop-post-merge-docs SOP should be MCP-wrapped in a mandatory hook skill. See phase-postgres-7f-doc-cleanup-sop.

7. Sprint backend plan completion

Complete remaining phases of plan-2026-03-01-pal-e-sprints (Phase 2: Auto-Population & Sync, Phase 3: Token Metrics). These depend on Phase 8 MCP optimization. Must be proven before the sprint frontend activates.
Depends on: Phase 8

8. Sprint Frontend Setup

Activate and execute plan-2026-03-01-pal-e-sprints-frontend once Act 2 phases (5-8) are complete. The sprint frontend depends on the compiled page architecture from Phase 7 and the optimized MCP tools from Phase 8. SvelteKit board UI at sprints.tail5b443a.ts.net — interactive kanban for the 5 sprint boards.
Depends on: Phase 8 (MCP Tool Optimization)
Plan: plan-2026-03-01-pal-e-sprints-frontend

9. Non-heading block anchor_ids [RESOLVED — PR #120 + nits]

The pal-e-docs parser only generates anchor_id for heading blocks. Non-heading blocks (paragraphs, lists, tables) get anchor_id: null, making them un-targetable by update_block and delete_block. Fix: generate anchor_ids for all block types + re-backfill.
Tracked: todo-block-anchor-ids
Related: phase-postgres-7-block-content, convention-block-first-access
9a. Test seed anchor_id cleanup [DONE — PR #125, issue #123]
Test seed helpers in test_blocks_api.py and test_compiled_page_api.py create Block objects with anchor_id=None, contradicting the invariant from PR #120. Update seeds to use {block_type}-{position} pattern.
Tracked: todo-test-seed-anchor-ids | Forgejo: forgejo_admin/pal-e-docs #123
9b. Harden anchor_id to NOT NULL [DONE — PR #127, issue #124]
DB column blocks.anchor_id remains nullable=True after PR #120. Add Alembic migration to SET NOT NULL — pushes enforcement from application layer to schema level. Must run after PR #120 migration and after issue #123 (test seed cleanup).
Tracked: todo-anchor-id-not-null | Forgejo: forgejo_admin/pal-e-docs #124 | Depends on: #123
9c. MCP block tool content type fix [DONE — PR #27, issue #26]
MCP tools create_block and update_block type the content parameter as string, but the pal-e-docs API expects a dict. Agents must fall back to curl to create/update blocks. Fix the Pydantic schema in pal-e-docs-mcp.
Tracked: todo-mcp-block-content-type | Forgejo: forgejo_admin/pal-e-docs-mcp #26

10. Jinja2 template rendering for plan creation [IN PROGRESS — see plan-2026-03-09-template-rendering]

Plan creation burns ~3000 output tokens hand-writing repetitive HTML. Phase boilerplate (Slug/Goal/Owner/Repo/Issue) is repeated per phase. Jinja2 templates would let agents provide structured data instead of raw HTML, cutting plan creation tokens by 60-70%. Options: server-side rendering in pal-e-docs API, client-side rendering in /plan skill, or hybrid.
Tracked: todo-jinja2-plan-templates
Related: template-plan, template-phase, check-note-template.sh

11. Remove Litestream infrastructure [RESOLVED — PR #31, Issue #30]

Litestream was the SQLite backup solution (WAL replication to MinIO). Replaced entirely by CNPG's native PostgreSQL WAL archiving in Phase 3. Four orphan Terraform resources remain in pal-e-platform/terraform/main.tf:
  • minio_s3_bucket.litestream_backups
  • minio_iam_user.litestream
  • minio_iam_policy.litestream_write
  • minio_iam_user_policy_attachment.litestream
Also remove stale SOP: sop-litestream-restore (documents restoring from Litestream backups that no longer exist).
Repo: pal-e-platform (TF resources), pal-e-docs (SOP note)
Related: sop-litestream-restore, phase-postgres-3-migrate-pal-e-docs

12. DORA Benchmark — Before/After Knowledge Engine

Compare before/after metrics for the Knowledge Engine plan. Act 2 built the foundation for DORA-measurable AI agency operations: structured knowledge (blocks, search, semantic), automated workflows (hooks, SOPs, agent conventions), and sprint tracking. Measure the impact across all four DORA metrics.
  • Baseline: benchmark-phase5-knowledge-baseline (11 calls / ~44K chars / ~11K tokens for 5 queries)
  • After: Measure same queries with block-first access, semantic search, hybrid ranking — expect 80-90% token reduction
  • Lead Time: Compare plan-to-merge cycle times before and after structured knowledge + agent conventions
  • Token-based sprint measurement: Traditional sprints measure time (2-week cycles). AI agent sprints should measure tokens consumed per deliverable — tokens are the true cost unit. Integrate token tracking into the pointing system so we can measure velocity in tokens/point, not hours/point
  • Depends on: Platform observability plan (Grafana dashboards), sprint workflow automation (DORA instrumentation)
  • worktree-workflow — current worktree SOP (needs update)
  • sop-claude-config-development — claude config conventions
  • todo-worktree-staleness-prevention — related TODO on staleness
  • todo-worktree-cleanup — related TODO on cleanup
  • todo-worktree-tmp-migration — child TODO for item 1
  • todo-dottie-claude-config — child TODO for item 4
  • agent-spawn-conventions — update target for item 5
  • phase-postgres-7f-doc-cleanup-sop — Phase 7f (doc cleanup + SOP hardening)
  • plan-2026-03-01-pal-e-sprints — sprint backend plan (item 7)
  • plan-2026-03-01-pal-e-sprints-frontend — sprint frontend plan (item 8)
  • sop-postgres-restore — backup procedures
  • sop-litestream-restore — stale SOP to remove (item 11)