7f-4 Alignment Audit Report

report-7f4-alignment-audit Doc

active doc

Project

7f-4 Alignment Audit Report

Date: 2026-03-08
Auditor: Dottie
Phase: phase-postgres-7f-4-attribute-augmentation, deliverable #5
Scope: 263 notes across 16 note types

Summary Statistics

Metric	Count
Total notes audited	263
TOCs checked	263 (all types sampled; SOPs, conventions, agents, templates, plans, phases checked exhaustively)
Content sections reviewed	SOPs (14), conventions (12), agents (5), templates (10) = 41 deep reads
Critical findings	3
Medium findings	12
Low findings	8
Total findings	23

Dimension 1: Structural Quality

Notes with ZERO Headings (Empty TOC)

These notes have no headings at all, meaning block-first convention (convention-block-first-access) cannot navigate them via get_note_toc + get_section.

Convention (1 note) — CRITICAL

Slug	Issue	Suggested Fix
<code>convention-dockerfile-pypi-pattern</code>	Completely empty content (0 bytes). Title exists but body is blank. Tagged as active.	Either populate with the Dockerfile/PyPI pattern content or delete as abandoned stub. This is an active convention with no content — agents cannot reference it.

Phase (21 notes) — MEDIUM

These are pre-template legacy phases from older plans. They lack the Goal/Scope/Related heading structure required by template-phase. All are from plans created before the phase template was enforced (pre-2026-03-03).

Parent Plan	Empty-TOC Phases
<code>plan-2026-02-25-platform-observability</code>	<code>phase-observability-1-project-page</code>, <code>phase-observability-2-verify-baseline</code>, <code>phase-observability-3-alerting</code>, <code>phase-observability-4-dashboard</code>, <code>phase-observability-5-architecture</code>
<code>plan-2026-03-01-note-decomposition</code>	<code>phase-note-decomp-1-baseline</code>, <code>phase-note-decomp-2-schema</code>, <code>phase-note-decomp-3-mcp</code>, <code>phase-note-decomp-4-composition</code>, <code>phase-note-decomp-5-dogfood</code>
<code>plan-2026-03-01-pal-e-sprints</code>	<code>phase-sprints-1-tables-api</code>, <code>phase-sprints-2-issue-sync</code>, <code>phase-sprints-3-token-metrics</code>
<code>plan-2026-02-28-knowledge-system-consolidation</code>	<code>phase-knowledge-1-convention</code>, <code>phase-knowledge-2-schema</code>, <code>phase-knowledge-3-data-migration</code>, <code>phase-knowledge-4-privacy</code>, <code>phase-knowledge-5-skills</code> (h4 only, no h3)
<code>plan-2026-02-26-tf-modularize-postgres</code>	<code>phase-postgres-1-tf-modularize</code>, <code>phase-postgres-2-deploy-cnpg</code>, <code>phase-postgres-2b-cleanup-platform</code>
<code>plan-2026-03-03-sprint-workflow-automation</code>	<code>phase-2026-03-03-1-forgejo-labels</code>, <code>phase-2026-03-03-2-sop-updates</code>

Suggested fix: Backfill these with minimal Goal/Scope/Related sections if the plan is still active. For completed/deferred plans, accept as legacy. Prioritize the 3 postgres phases (active plan) and 3 sprint phases (active plan).

Singleton Types (2 notes) — LOW

Slug	Type	Issue
<code>priv-1</code>	journal	Empty TOC. Private journal entry — acceptable for freeform type.
<code>post-1</code>	post	Empty TOC. Blog post — acceptable for freeform type.

Todo Notes (7 notes) — LOW

Lightweight todo notes from early in the project. These are quick-capture notes without heading structure:

todo-rename-deployments-repo
todo-parent-profile-page
todo-outreach-strategy
todo-coach-west-partnership
todo-pale-branding-stripe
todo-donation-link-website
todo-fox-news-story

Suggested fix: Todos are lightweight by design. No action unless promoting to a plan/issue.

Phase Template Compliance

The template-phase requires two shapes: (1) Feature phases need Goal/Scope/Related, (2) Bug-fix phases need Problem/Fix/Related. Of 59 phases:

36 phases have proper heading structure matching the template
21 phases have empty TOCs (listed above)
2 phases have h4-only headings (phase-knowledge-5-skills, phase-2026-03-03-4-betty-sue-skill, phase-2026-03-03-3-agent-configs, phase-2026-03-03-5-hooks, phase-sprints-schema-expansion) — these have content under h4 but no h3 sections, so get_section at h3 level returns nothing useful

Dimension 2: Content Accuracy

SOPs (14 notes)

Slug	Severity	Finding	Suggested Fix
<code>sop-litestream-restore</code>	CRITICAL	Describes SQLite/Litestream restore. pal-e-docs migrated to Postgres in Phase 3 (completed). This SOP describes a backup system that no longer exists for the primary app.	Either archive/deprecate (pal-e-docs is now Postgres + CNPG backup) or repurpose as a generic Litestream reference if any other services still use SQLite.
<code>solo-dev-pr-workflow</code>	MEDIUM	Only has Steps section — no Related. Very thin. Doesn't reference current agent model or Forgejo.	Consolidate into <code>pr-lifecycle</code> or add Related section referencing <code>pr-lifecycle</code>, <code>pr-review-loop</code>.
<code>service-onboarding-sop</code>	MEDIUM	Minimal structure (3 headings). May not reflect current Kustomize/ArgoCD onboarding flow. References <code>var.services</code> Terraform pattern.	Review against current service onboarding reality. Cross-reference with <code>plan-2026-02-26-kustomize-service-bases</code>.
<code>sop-index</code>	LOW	Index page — should list all 14 SOPs. Verify it's current.	Audit that all 14 SOP slugs appear in the index.

SOPs verified current: sop-note-deletion, agent-workflow, sop-secrets-management, sop-postgres-restore, deployment-lessons, pr-lifecycle, sop-post-merge-docs, sop-claude-config-development, worktree-workflow, pr-review-loop.

Conventions (12 notes)

Slug	Severity	Finding	Suggested Fix
<code>convention-dockerfile-pypi-pattern</code>	CRITICAL	Empty content. Active convention with no body.	Populate or delete. See Dimension 1 above.
<code>branch-protection</code>	LOW	Minimal (3 headings). May not reflect Forgejo-specific branch protection settings currently in use.	Verify against actual Forgejo repo settings.
<code>ci-rules</code>	LOW	Very minimal (2 headings). May benefit from expansion with Woodpecker-specific CI rules.	Low priority — functional but thin.

Conventions verified current and enforced by hooks:

agent-spawn-conventions — enforced by check-agent-spawn.sh
convention-block-first-access — enforced by agent personality in session-start-context.sh
convention-subphase — enforced by check-phase-template.sh
convention-agent-skill-mcp-wiring — structural convention, enforced by inject-subagent-context.sh
html-style-guide — not hook-enforced but documented
mermaid-authoring — not hook-enforced
namespace-conventions — not hook-enforced
tagging-conventions — partially superseded by note-conventions
note-conventions — enforced by check-note-template.sh

Agent Profiles (5 notes)

Slug	Severity	Finding	Suggested Fix
<code>agent-issue-creator</code>	CRITICAL	Status is <code>deprecated</code> but has <code>active</code> tag. Content still describes the 5th agent. MEMORY.md says "issue-creator REMOVED" and "PR #58 merged". Betty Sue now creates issues directly.	Remove <code>active</code> tag. Add <code>deprecated</code> tag. Add a deprecation banner at the top referencing <code>phase-7f-1-deprecate-issue-creator</code>.
<code>agent-betty-sue</code>	OK	Correctly references Four Agents model with Dottie. Current.	None.
<code>agent-dottie</code>	OK	Correct role as librarian. Current.	None.
<code>agent-dev</code>	OK	Current. Proper MCP access boundaries.	None.
<code>agent-qa</code>	OK	Current. Proper MCP access boundaries.	None.

Templates (10 notes)

All 10 templates have proper heading structure. Cross-referenced with enforcement hooks:

Template	Hook	Status
<code>template-phase</code>	<code>check-phase-template.sh</code>	Enforced
<code>template-issue</code>	<code>check-issue-template.sh</code>	Enforced
<code>template-pr-body</code>	<code>check-pr-template.sh</code>	Enforced
<code>template-plan</code>	<code>check-note-template.sh</code>	Enforced (via note template check)
<code>template-agent</code>	No dedicated hook	Not enforced
<code>template-skill</code>	No dedicated hook	Not enforced
<code>template-project-page</code>	No dedicated hook	Not enforced
<code>template-repo-page</code>	No dedicated hook	Not enforced
<code>template-bug</code>	No dedicated hook	Not enforced
<code>template-sprint-item</code>	No dedicated hook	Not enforced

Finding (MEDIUM): 6 of 10 templates have no hook enforcement. The 4 enforced templates cover the high-traffic paths (phases, issues, PRs, plans). Low risk but worth noting for the enforcement architecture.

Dimension 3: Metadata Gaps

Project Assignment

Known API limitation: list_notes returns project: null for all 263 notes in summaries. Project data exists on individual notes (verified via get_note) but is not exposed in the list endpoint. This is documented in MEMORY.md as "list_notes API missing project field" (7f-4 deliverable #6).

Impact: Cannot audit project assignment at scale without calling get_note for each of 263 notes. This audit focused on parent_slug instead.

Parent Slug Gaps

Only 70 of 263 notes (27%) have parent_slug set: 59 phases + 10 docs + 1 todo.

Types That Should NOT Have Parents (top-level by design)

Plans (40) — top-level, correct
Project pages (11) — top-level, correct
SOPs (14) — top-level, correct
Conventions (12) — top-level, correct
Templates (10) — top-level, correct
Skills (10) — top-level, correct

Types Where Parent Is Situational

Docs (21): 10 have parents, 11 orphaned. The 11 orphaned docs include 3 repo pages (repo-pal-e-docs-sdk, repo-woodpecker-mcp, repo-forgejo-mcp), 2 bug docs, and general docs like agent-paradigm, tf-environment-strategy. Repo pages should arguably be children of their project-page.
Todos (51): Only 1 has a parent. Most todos are freestanding quick-capture. Acceptable.
References (24): None have parents. References are standalone by nature. Acceptable.

Orphan Docs That Should Have Parents — MEDIUM

Slug	Suggested Parent	Reasoning
<code>repo-pal-e-docs-sdk</code>	<code>project-pal-e-docs</code>	Repo page should be child of project page
<code>repo-woodpecker-mcp</code>	<code>project-pal-e</code>	Repo page should be child of project page
<code>repo-forgejo-mcp</code>	<code>project-pal-e</code>	Repo page should be child of project page
<code>decision-agent-dottie</code>	<code>project-ai-agency</code> or a phase	Decision doc should trace to the context that produced it

Slug-Type Mismatches — MEDIUM

8 notes typed as todo have slug prefixes that don't match their type:

Slug	Current Type	Status	Suggested Fix
<code>bug-argocd-image-updater-ghost-override</code>	todo	null	Re-slug or note: was a bug discovery, resolved via <code>concept-argocd-ghost-override</code>
<code>bug-ci-ruff-format-migrate-script</code>	todo	null	If open, status should be <code>open</code>. Slug suggests bug.
<code>plan-skill-enforcement-gap</code>	todo	done	Slug starts with <code>plan-</code> but is typed todo. Rename slug to <code>todo-skill-enforcement-gap</code> or retype to plan.
<code>bug-grafana-crashloop</code>	todo	done	Resolved. Could archive.
<code>bug-update-note-ignores-project-slug</code>	todo	done	Resolved. Could archive.
<code>bug-nftables-service-running-oneshot</code>	todo	done	Resolved. Could archive.
<code>bug-plan-template-hook-large-content</code>	todo	open	Still open. Slug/type mismatch is cosmetic.
<code>bug-forgejo-mcp-missing-create-repo</code>	todo	open	Still open. Slug/type mismatch is cosmetic.

Null Status Notes — LOW

77 notes have status: null. Breakdown by type:

References (24/24) — references don't have a lifecycle, null is acceptable
Todos (22/51) — these should have status (open/done/deferred). 22 undecided.
Docs (15/21) — docs are reference-like, null acceptable for most
Skills (10/10) — skills don't have lifecycle state, null acceptable
Sprints (2/2), Incident (1), Issue (1), Journal (1), Post (1) — singleton types, null acceptable

Action: The 22 todos with null status are the main gap. Each should be triaged to open, done, or deferred.

Tag vs Status Contradictions

Slug	Status	Tags	Issue
<code>agent-issue-creator</code>	deprecated	active, agent	<code>active</code> tag contradicts <code>deprecated</code> status. Remove <code>active</code> tag.

Recommendations (Prioritized)

Critical (Fix Now)

convention-dockerfile-pypi-pattern: Populate or delete. Empty active convention is a data quality violation.
sop-litestream-restore: Mark as deprecated or repurpose. Describes a backup system no longer in use for the primary app.
agent-issue-creator: Remove active tag, add deprecation banner. Status already correct.

Medium (Fix in 7f-5 or 7f-6)

21 legacy phases with empty TOCs: Backfill minimal structure for the 6 phases under active plans. Accept legacy for completed/deferred plans.
6 unenforced templates: Document as known gap in enforcement architecture. Low risk but track for future.
3 orphan repo-page docs: Set parent_slug to appropriate project page.
8 slug-type mismatches in todos: Fix slug prefixes or retype. Cosmetic but confusing for queries.
22 todos with null status: Triage to open/done/deferred.
solo-dev-pr-workflow: Consolidate into pr-lifecycle or expand with Related section.
service-onboarding-sop: Verify against current Kustomize/ArgoCD reality.

Low (Track for Later)

7 lightweight todos without headings: Acceptable for quick-capture type. No action unless promoted.
branch-protection, ci-rules: Thin conventions. Expand when relevant.
sop-index: Verify all 14 SOPs are listed.
Journal and post empty TOCs: Freeform types, no template expected.
list_notes API project gap: Already tracked as 7f-4 deliverable #6 and Forgejo issue #115.

phase-postgres-7f-4-attribute-augmentation — parent phase
phase-postgres-7f-doc-cleanup-sop — parent of the broader cleanup effort
convention-block-first-access — the convention this audit validates against
template-phase — the template phase notes should comply with
note-conventions — slug naming and type conventions
sop-index — SOP master list to cross-reference