pal-e-docs

Phase 7f-4: Note Attribute Augmentation

phase-postgres-7f-4-attribute-augmentation Phase

active phase
Project
Goal: Every note has clean, queryable metadata before Phase 6 vectorization. Zero nulls in note_type. Every note assigned to a project. Orphans identified and placed in the hierarchy. SOPs and docs verified against reality.
Owner: Betty Sue (main session) + Dottie (alignment audit)
Repo: No repo — data work via MCP + SQL. Forgejo issues: #115 (API enum, pal-e-docs, CLOSED), #117 (list_notes project field, pal-e-docs, CLOSED), #69 (hook security, claude-custom, CLOSED).
Depends on: 7f-1, 7f-2, 7f-3 (all COMPLETED)

Scope

1. Type taxonomy (COMPLETED)

  • Established 16-type taxonomy. 5 new types added (reference, sprint, incident, journal, post) alongside existing 11.
  • Zero notes with null note_type — verified via SQL. 262 notes, 16 distinct types.

2. Issue note archival (COMPLETED)

  • 49 legacy issue-* notes deleted — migrated to Forgejo repos
  • Backup: JSON export + pg_dump pushed to MinIO: s3://backups/pal-e-docs/7f-4/
  • CNPG WAL switch forced pre-deletion for PITR
  • Created sop-note-deletion — backup-first SOP (updated with MinIO push step)
  • Filed todo-delete-note-warning-hook

3. Type assignment (COMPLETED)

  • All 34 remaining untyped notes assigned types (MCP API for skills, SQL for new types)

4. API enum expansion (COMPLETED)

  • Forgejo issue #115 — PR #116 merged (squash)
  • Added 5 new values to Pydantic Literal + status validation — existing 11 types unchanged
  • 29 new tests, all 537 tests pass. No migration needed (DB is varchar).

5. Content + SOP alignment audit (COMPLETED)

Full 263-note audit across three dimensions. Report: report-7f4-alignment-audit.
Results: 23 findings (3 critical, 12 medium, 8 low)
  • Critical: 1 empty convention (convention-dockerfile-pypi-pattern), 1 stale SOP (sop-litestream-restore content), 1 deprecated agent note still active (agent-issue-creator)
  • Medium: 21 legacy phases with empty TOCs, 6 templates without hook enforcement, 22 todos with null status, 8 todos with slug-type mismatches, 3 orphan repo-page docs
  • Low: Thin conventions, lightweight todos without headings (acceptable), journal/post empty TOCs (freeform)
Fixes applied during audit:
  • enforcement-architecture Pillar 4 — replaced deprecated Issue Creator with Dottie
  • agent-spawn-conventions — Three Agents → Four Agents, Dottie added to all tables
  • sop-litestream-restore — fixed contradictory status:deprecated + tag:active
  • block-docs-writes.sh — fixed security gap, 7→17 blocked write ops (PR #70 merged)
  • inject-subagent-context.sh — added Dottie context injection (PR #70 merged)

6. Project + parent assignment (UNBLOCKED)

  • list_notes API now includes project field — PR #118 merged. Issue #117 closed.
  • Bulk assignment work not yet started — next session can use list_notes to audit project distribution
  • Audit identified 3 orphan repo-page docs missing parent_slug

7. Anchor ID re-save (NOT STARTED)

  • Re-save ~263 notes to trigger parser, fixing null anchor_id on blocks
  • Also opportunity to restructure 21 legacy phases flagged in deliverable #5

Decisions Made

Decision Rationale
16-type taxonomy with <code>reference</code> distinct from <code>doc</code> Reference = navigation hubs. Doc = informational content. Matters for SvelteKit filetree.
SQL for new types, API catch-up later DB is varchar, no constraint. Data correctness over API deployment timing.
Backup-first deletion SOP Notes are institutional memory. Every deletion needs a recovery path.
Issue notes deleted not archived Issues live in Forgejo now. JSON + pg_dump + PITR for recovery.
<code>journal</code> and <code>post</code> as types Heading toward user-scoped private notes in SvelteKit.
Backups to MinIO bucket <code>s3://backups/</code> Local NVMe not durable. SOP updated with aws CLI push step.

Session Log

Session 1 (2026-03-08 morning)

  • Deliverables 1-3 completed (type taxonomy, issue archival, type assignment)
  • Created sop-note-deletion, filed todo-delete-note-warning-hook
  • Filed issue #115 for API enum expansion
  • Identified 6 talking points for next session

Session 2 (2026-03-08 afternoon)

Alignment audit + parallel agent execution. 11 agents spawned (2 Dottie, 4 Dev, 3 QA, 1 Explore, 1 Plan).
  • Audit: 6 drifts found between SOPs, hooks, and docs. All fixed.
  • PR #70 merged (claude-custom) — hook security: block-docs-writes.sh 7→17 ops, Dottie context injection, settings.json
  • PR #116 merged (pal-e-docs) — API enum: 5 new note types, 29 tests
  • PR #118 merged (pal-e-docs) — list_notes project field: ProjectSummary schema, 6 tests
  • Dottie audit complete: 263 notes, 23 findings → report-7f4-alignment-audit
  • MinIO: Backups pushed to s3://backups/pal-e-docs/7f-4/. SOP updated.
  • Issue triage: 8 stale claude-custom issues closed, 9 remain for deeper triage

Next Session

  • Deliverable #6: Use list_notes with new project field to audit project distribution. Bulk-assign unassigned notes.
  • Deliverable #7: Bulk re-save 263 notes (anchor ID fix). Restructure 21 legacy phases flagged by audit.
  • Audit follow-up: Address 3 critical findings (empty convention, stale SOP content, deprecated agent note). Fix 22 todos with null status. Fix 8 slug-type mismatches.
  • Claude-custom triage: Investigate remaining 9 open issues.
  • phase-postgres-7f-doc-cleanup-sop — parent phase
  • plan-2026-02-26-tf-modularize-postgres — parent plan
  • sop-note-deletion — created and updated during this phase
  • todo-delete-note-warning-hook — created during this phase
  • enforcement-architecture — updated (Issue Creator → Dottie)
  • agent-spawn-conventions — updated (Three → Four Agents)
  • report-7f4-alignment-audit — Dottie's full audit report