pal-e-docs

Review: Convention: architecture component IDs for traceability labels

review-326-2026-03-24 Review

review ready
Project

Verdict: READY

Re-review of board item #326. Previous verdict: NEEDS_REFINEMENT. Refinements posted as comment #6624.

Template Completeness

  • [x] Type
  • [x] Lineage
  • [x] Repo
  • [x] User Story
  • [x] Context
  • [x] File Targets (expanded in comment #6624 to include template-ticket modification)
  • [x] Acceptance Criteria
  • [x] Test Expectations
  • [x] Constraints
  • [x] Checklist
  • [x] Related

File Targets

  • [x] convention-architecture-ids -- confirmed does not yet exist (pal-e-docs search returned empty). Creation is the deliverable.
  • [x] template-ticket -- exists. Label Conventions table currently defines arch:{diagram-type}. Comment #6624 adds updating this table to scope. Verified the table still contains the conflicting definition (arch:domain, arch:dataflow, arch:deployment).

Repo Placement

OK. Issue filed on forgejo_admin/pal-e-docs. Both deliverables (convention note creation, template-ticket update) are pal-e-docs notes. Correct repo.

Dependencies

  • Blocks #324 ("Enforce arch: + story: labels") -- that ticket needs this convention to define valid arch: values. Dependency documented in comment #6624.
  • Board labels not yet updated. Item #326 labels = type:feature,arch:kanban (missing blocks:324). Item #324 labels = type:feature,arch:kanban (missing depends:326). This is an operational fix, not a scope issue.
  • No other blockers. Items #323 and #325 are independent.

Acceptance Criteria

All three criteria are verifiable by an agent after implementation:
  • "Convention note exists with clear naming rules" -- agent can verify via get_note(slug="convention-architecture-ids").
  • "Examples cover all three diagram types" -- agent can read the note and check.
  • "Pattern is consistent with existing label conventions" -- now resolvable because template-ticket update is in scope. After implementation, both documents will align on arch:{component-name}.

Blast Radius

The semantic conflict between template-ticket and convention-kanban-over-plans identified in the first review is now addressed by including the template-ticket update in scope. After implementation:
  • convention-kanban-over-plans says "arch:X = which architecture component this touches" -- component granularity.
  • template-ticket Label Conventions will be updated from arch:{diagram-type} to arch:{component-name} -- component granularity.
  • New convention-architecture-ids will define the naming convention for component IDs.
  • All three documents will be consistent.
Current board usage (arch:kanban on 4 agency items) already uses component-level granularity, consistent with the proposed convention. No migration needed for existing labels.

Recommendation

Scope is solid. One operational task remains before moving to next_up:
  • Add blocks:324 to item #326 labels and depends:326 to item #324 labels. This is a board hygiene step, not a scope change.