TFD-0028: Restore Slug on Factory Artifact Folders & TFD Files

TFD-0028: Restore Slug on Factory Artifact Folders & TFD Files

Status: Accepted Date: 2026-05-28 Decision makers: CEO (Bruno) Supersedes (partial): TFD-0026 §"no slug" rule Triggered by: CEO observation — "il y a trop de numéros, je ne les reconnais pas"

Context

TFD-0026 (this morning) renamed every factory folder to {TYPE}-{NNNN}/ (no slug) to standardize on the DAE pattern and fix MAX_PATH issues. In use, the CEO finds the slugless folder names unrecognizable — 95 numeric IDs (CON-0001..CON-0016, RD-0001..RD-0034, MET-0001..MET-0008, WO-0001..WO-0010, TFD-0001..TFD-0027) are too many to hold in head.

TFD-0027 already restored the slug on client-side folders (clients/<slug>/DAE-0007-evaluation-systemes/). This TFD extends the same rule to factory-side folders and TFD files.

Decision

Folder name = {TYPE}-{NNNN}-{slug}/ for every factory artifact. TFD file name = TFD-{NNNN}-{slug}.md. Slug retained.

Format

Artifact Before TFD-0026 After TFD-0026 (morning) After TFD-0028 (now)
Consulting request REQ-CONS-001-rd-video-eval-dashboard-ux/ CON-0001/ CON-0001-rd-video-eval-dashboard-ux/
R&D request REQ-EXEC-001-auto-research-loop/ RD-0001/ RD-0001-auto-research-loop/
Methodology request REQ-METH-001-business-capability-map.../ MET-0001/ MET-0001-business-capability-map-catalog-schema/
Infrastructure request REQ-EXEC-INF-001-.../ INF-0001/ INF-0001-factory-dashboard/
Work order WO-PROD-001-stm-ea-agent/ WO-0001/ WO-0001-stm-ea-agent/
TFD TFD-001-some-slug.md TFD-0001.md TFD-0001-use-digital-talent-as-product-terminology.md

Rules

  1. TFD-0026 carries through everywhere else : type catalog (RD/CON/MET/WO/INF/DAE/TFD/CI), zero-padded 4-digit number, global sequence per type, voice-dictation contract (RD zero zero zero eight → RD-0008).
  2. Slug rule : [a-z0-9][a-z0-9-]*, lowercase, alphanumerics + hyphens, soft cap 60 chars. Derived from title: frontmatter (request.md / order.md / TFD H1). Strip diacritics.
  3. The numeric ID alone is still the canonical identifier — frontmatter id: field stays RD-0008, not RD-0008-token-efficiency-eval. Slug is part of the FOLDER NAME, not part of the ID.
  4. Voice-dictation contract preserved : "RD zero zero zero eight" → RD-0008 (the ID) → unambiguously resolves to the one folder starting RD-0008-. Tab-completion works.
  5. Cross-references : [RD-0008] and [RD-0008-token-efficiency-eval] both valid. Authoring prefers the ID-only form; the slug exists for human recognition in ls output.

Migration script

departments/methodology/nomenclature-specialist-nora/migrations/restore-slug.py performed the 95 renames in one pass:

  • 68 folder renames sourced from ci-038-id-remap.csv (original slugs from old_folder column)
  • 27 TFD renames sourced from each file's first H1
  • 2 stragglers (CON-0016, INF-0001) untracked at apply time → manual mv with shorter slugs

Consequences

Pros

  • ls departments/consulting/requests/ now reads naturally — CON-0006-client-request-intake-lifecycle/ vs CON-0006/.
  • Recognition restored without sacrificing the dictation contract or the global sequence.
  • Aligns factory-side with client-side (TFD-0027), one rule everywhere.

Cons / risks

  • Soft 60-char cap may yield ambiguous slugs in extreme cases (a "factory dashboard on factory.jacksoncreek.ca — visual operations view" became factory-dashboard after manual override — acceptable).
  • Slug duplication is possible if two artifacts get similar titles. The ID still disambiguates; humans verify in ls.
  • Cross-reference links written before TFD-0026 (using slugged paths) and broken by TFD-0026 → now work again with the new full path. Any link written between TFD-0026 morning and TFD-0028 (using ID-only path) now breaks. Cleanup via grep + replace if needed.

Acceptance criteria

  • All 95 factory artifact folders + TFD files carry their slug (commit c6ab5a1 + 2 manual mv for stragglers).
  • Migration script restore-slug.py committed at departments/methodology/.../migrations/.
  • TFD-0026 carries a "§no-slug rule superseded by TFD-0028" banner.
  • TFD-0027 §Naming carve-out for factory removed (one rule everywhere now).
  • naming-conventions.md reflects the slug-everywhere rule.
  • Spot-check at least 5 cross-references in factory-backlog / intranet still resolve.

Definition of done

  • TFD-0028 merged (this file).
  • TFD-0026 banner updated.
  • TFD-0027 carve-out removed.
  • naming-conventions.md rewritten to state slug-everywhere.
  • One grep + sed pass to fix any RD-NNNN/ or similar ID-only path references introduced between TFD-0026 and TFD-0028.