Phase 7f: Doc Cleanup + SOP Hardening

phase-postgres-7f-doc-cleanup-sop Phase

Project

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	<code>phase-7f-1-deprecate-issue-creator</code>	<strong>COMPLETED</strong> — PR #58 merged (claude-custom)
7f-2	Agent spawn requirements schema	<code>phase-7f-2-agent-spawn-schema</code>	<strong>COMPLETED</strong>
7f-3	Template drift fix (issue migration)	<code>phase-postgres-7f-3-template-drift</code>	<strong>COMPLETED</strong>
7f-4	Note attribute augmentation	<code>phase-postgres-7f-4-attribute-augmentation</code>	<strong>COMPLETED</strong> — 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	<em>absorbed by 7f-4</em>	<strong>COMPLETED</strong> — 49 issue notes deleted, 22 TODO statuses fixed, 3 orphans resolved, pg_dump + JSON backup
7f-6	SOP review and consolidation	<em>absorbed by 7f-4</em>	<strong>COMPLETED</strong> — Dottie audit covered all 14 SOPs + 12 conventions. enforcement-architecture + sop-litestream-restore fixed. 1 empty convention deleted.
7f-7	Post-merge automation hook	<code>phase-postgres-7f-7-post-merge-automation</code>	<strong>COMPLETED</strong> — PR #72 merged (claude-custom). <code>/update-docs</code> slash command deployed. Old <code>skills/update-docs/SKILL.md</code> 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)

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