pal-e-docs

Phase 18: Enterprise Definitions & Post-Merge Enforcement

phase-pal-e-agency-18-enterprise-definitions Phase

active phase
Project
Goal: Formalize platform vocabulary so the system is legible without narration, add nit-bundle as a 4th issue type, and close the gap between the post-merge SOP and the update-docs skill so steps can't be rationalized away.
Owner: Betty Sue (docs + convention) + Dev agent (hook/skill code changes)
Repo: pal-e-docs notes (glossary, templates, SOP) + forgejo_admin/claude-custom (hook, skill)
Depends on: None (additive to existing system)

Scope

18a: Platform Glossary (DONE)
  • Created glossary note with canonical definitions: Enterprise, Role Hierarchy, User Story, Traceability Triangle, Scoping Pipeline, Three Pillars, Continuous Kanban, Nit, Issue Types
  • Needs Lucas review — terms may need refinement
18b: Nit-Bundle Issue Template (DONE)
  • Created template-issue-nit-bundle — 4th issue type alongside Bug, Feature, Spike
  • Lifecycle: created during /update-docs → auto-syncs to board backlog → triage → segment if needed → dispatch
  • Plan Epilogue becomes provenance reference, not tracking mechanism
18c: Hook Recognizes Nit-Bundle Type
  • Add Nit-Bundle|nit-bundle case to check-issue-template.sh line 33-37
  • Currently falls through to feature template validation (wrong headings → deny)
  • Repo: forgejo_admin/claude-custom
  • 1-line change, needs Forgejo issue + PR
18d: SOP & Convention Updates
  • Update sop-post-merge-docs step 8: nits → nit-bundle Forgejo issue, Epilogue = provenance reference
  • Update convention-todo-lifecycle triage checklist: add Nit-Bundle as 4th type
  • Cross-reference glossary from relevant SOPs/conventions
18e: Align update-docs Skill with SOP
  • Add missing steps from SOP: step 2 (verify deploy), step 8 (nit-bundle creation), step 10 (cross-pillar impact)
  • Add verification-before-skip: skill must READ the artifact before claiming it's current
  • Replace "skip this step" with VERIFIED CURRENT / UPDATED / NOT APPLICABLE (reason) — no naked skips
  • Repo: forgejo_admin/claude-custom
  • Needs Forgejo issue + PR

Deliverables

# Deliverable Forgejo Issue Status
18a <code>glossary</code> note — platform vocabulary n/a (docs) DONE
18b <code>template-issue-nit-bundle</code> — 4th issue type n/a (docs) DONE
18c <code>check-issue-template.sh</code> recognizes Nit-Bundle <code>claude-custom #137</code> — PR #139 merged DONE
18d SOP + convention updates for nit-bundle workflow n/a (docs) DONE
18e <code>commands/update-docs.md</code> aligned with SOP, verification-before-skip <code>claude-custom #138</code> — PR #140 merged DONE

Acceptance Criteria

  • All 4 issue types (Feature, Bug, Spike, Nit-Bundle) pass hook validation
  • /update-docs skill has all 10 SOP steps with verification-before-skip
  • Glossary terms reviewed and approved by Lucas
  • One real nit-bundle created from existing approved PR nits (dogfood test)
  • SOP and convention notes reference glossary for canonical definitions
  • glossary — the definitions note (deliverable 18a)
  • template-issue-nit-bundle — the template (deliverable 18b)
  • sop-post-merge-docs — the SOP being updated
  • template-issue — canonical issue design principle
  • convention-todo-lifecycle — triage rules being updated
  • plan-pal-e-agency — parent plan