<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-09-21-1-kebab-canonical-doctrine-artifact-slug/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-09-21-1-kebab-canonical-doctrine-artifact-slug/</id>
  <title>ADR: kebab-case canonical doctrine artifact slug — id/slug decoupling, single slug authority, manifest-driven bundle validation</title>
  <updated>2026-09-21T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-09-21-1-kebab-canonical-doctrine-artifact-slug/"/>
  <summary>Kebab-case canonical slug for project doctrine artifacts, set by one slug_for authority and a manifest-driven bundle validator; id/slug decoupled, filename migration dropped.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Mission &lt;code dir=&quot;auto&quot;&gt;doctrine-slug-canonicalization-01M31SP9&lt;/code&gt;. Project-registered doctrine artifacts
(directives, tactics, styleguides, procedures, agent profiles) are written to disk by
three independent surfaces: the scaffolder (&lt;code dir=&quot;auto&quot;&gt;author_guidance()&lt;/code&gt;), the registration
engine (&lt;code dir=&quot;auto&quot;&gt;project_registration.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;commit_project_registration()&lt;/code&gt;), and the bundle
validator (&lt;code dir=&quot;auto&quot;&gt;charter bundle validate&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;src/charter/offering/drg/bundle.py&lt;/code&gt;). Each surface
derived a project directive’s on-disk slug/filename independently, and the derivations
disagreed:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The registration engine writes a directive’s provenance sidecar as
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;kind&gt;-&amp;#x3C;kebab-slug&gt;.yaml&lt;/code&gt;, computed inline at &lt;code dir=&quot;auto&quot;&gt;project_registration.py:187&lt;/code&gt; as
&lt;code dir=&quot;auto&quot;&gt;quote(identifier.lower().replace(&quot;_&quot;, &quot;-&quot;), safe=&quot;&quot;)&lt;/code&gt; for directives.&lt;/li&gt;
&lt;li&gt;The bundle validator’s filename parser expected a different shape and reported &lt;strong&gt;2
errors per project directive&lt;/strong&gt; validated (#4832) — the engine’s own kebab-slug output
did not round-trip through the validator’s independent parse.&lt;/li&gt;
&lt;li&gt;The validator’s recognised-kind table (&lt;code dir=&quot;auto&quot;&gt;_KIND_SUFFIX&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;_ALL_ARTIFACT_PATTERNS&lt;/code&gt;) covered
only 3 of the 5 kinds the engine actually writes sidecars for, so it also rejected the
engine’s own &lt;code dir=&quot;auto&quot;&gt;agent_profile&lt;/code&gt; sidecars outright (#4833) — and &lt;code dir=&quot;auto&quot;&gt;procedure&lt;/code&gt; was a latent
identical twin of the same bug, not yet reported but structurally present.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;No single module owned “what is the canonical slug for artifact kind K and identifier
ID” — each consumer re-derived it, and the derivations silently diverged
(DIRECTIVE_043: canonical-source-unification violation). &lt;code dir=&quot;auto&quot;&gt;charter bundle validate&lt;/code&gt; was,
in effect, validating against a slug convention none of the writers implemented.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;h3 id=&quot;d1--kebab-case-is-the-canonical-slug-id-is-preserved-and-formally-decoupled-from-slug&quot;&gt;D1 — Kebab-case is the canonical slug; &lt;code dir=&quot;auto&quot;&gt;id&lt;/code&gt; is preserved and formally decoupled from slug&lt;/h3&gt;
&lt;p&gt;The on-disk filename/slug for a project-registered artifact is &lt;code dir=&quot;auto&quot;&gt;kebab(id)&lt;/code&gt; (for
directives: lowercased, &lt;code dir=&quot;auto&quot;&gt;_&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;-&lt;/code&gt;, URL-quoted); the authored &lt;code dir=&quot;auto&quot;&gt;id&lt;/code&gt; (SCREAMING-case for
directives, e.g. &lt;code dir=&quot;auto&quot;&gt;LOVE_THY_ENEMY&lt;/code&gt;) is preserved inside the file as canonical identity.
&lt;code dir=&quot;auto&quot;&gt;id&lt;/code&gt; and slug are formally decoupled: &lt;code dir=&quot;auto&quot;&gt;id&lt;/code&gt; is identity, slug is a derived on-disk handle.
The built-in precedent (&lt;code dir=&quot;auto&quot;&gt;disciplined-refactoring.directive.yaml&lt;/code&gt; ↔
&lt;code dir=&quot;auto&quot;&gt;id: DISCIPLINED_REFACTORING&lt;/code&gt;) demonstrates that shipped built-ins already decouple a
human slug from the authored id — &lt;code dir=&quot;auto&quot;&gt;025-boy-scout-rule.directive.yaml&lt;/code&gt; ↔
&lt;code dir=&quot;auto&quot;&gt;id: DIRECTIVE_025&lt;/code&gt; is a &lt;em&gt;descriptive&lt;/em&gt; slug, not an instance of mechanical &lt;code dir=&quot;auto&quot;&gt;kebab(id)&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;kebab(&quot;DIRECTIVE_025&quot;)&lt;/code&gt; would be &lt;code dir=&quot;auto&quot;&gt;directive-025&lt;/code&gt;), so the built-in &lt;code dir=&quot;auto&quot;&gt;NNN-&lt;/code&gt;/descriptive
naming convention is not extended to project artifacts — &lt;code dir=&quot;auto&quot;&gt;slug_for&lt;/code&gt; governs only the
project-registration path.&lt;/p&gt;
&lt;h3 id=&quot;d2--single-slug_forkind-id-authority-preserving-the-engines-url-encoding&quot;&gt;D2 — Single &lt;code dir=&quot;auto&quot;&gt;slug_for(kind, id)&lt;/code&gt; authority, preserving the engine’s URL-encoding&lt;/h3&gt;
&lt;p&gt;One pure &lt;code dir=&quot;auto&quot;&gt;slug_for(kind, identifier)&lt;/code&gt; function (&lt;code dir=&quot;auto&quot;&gt;src/charter/offering/artifact_kinds.py&lt;/code&gt;,
beside &lt;code dir=&quot;auto&quot;&gt;_PATTERNS&lt;/code&gt;) is the sole slug-derivation authority, consumed by both the
scaffolder and the registration engine. It is extracted verbatim from the engine’s
existing inline expression and &lt;strong&gt;preserves &lt;code dir=&quot;auto&quot;&gt;quote(…, safe=&quot;&quot;)&lt;/code&gt;&lt;/strong&gt;: directive identifiers
lowercase/underscore-to-hyphen then URL-quote; other kinds URL-quote as-is. Dropping the
&lt;code dir=&quot;auto&quot;&gt;quote()&lt;/code&gt; wrap (an early draft’s “verbatim kebab” framing) would reintroduce a
provenance-directory path escape for a namespaced identifier such as
&lt;code dir=&quot;auto&quot;&gt;agent_profile:team/ops-responder&lt;/code&gt; and regress the existing guard at
&lt;code dir=&quot;auto&quot;&gt;tests/charter/test_project_registration.py:165-166&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;quote()&lt;/code&gt; is a no-op on
kebab/SCREAMING identifiers, so directives are unaffected by keeping it.&lt;/p&gt;
&lt;h3 id=&quot;d3--recognised-kind-set-derives-from-one-importable-direct_write_kinds-constant&quot;&gt;D3 — Recognised-kind set derives from one importable &lt;code dir=&quot;auto&quot;&gt;DIRECT_WRITE_KINDS&lt;/code&gt; constant&lt;/h3&gt;
&lt;p&gt;The validator’s kind table is extended from 3 to the full 5 registration-writing kinds
(&lt;code dir=&quot;auto&quot;&gt;directive, tactic, styleguide, procedure, agent_profile&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;agent_profile&lt;/code&gt; →
&lt;code dir=&quot;auto&quot;&gt;.agent.yaml&lt;/code&gt;), fixing #4833. The kind list itself is minted once as a module-level,
importable &lt;code dir=&quot;auto&quot;&gt;DIRECT_WRITE_KINDS&lt;/code&gt; constant (previously a function-local tuple), and every
consumer — the scanner, the manifest’s artifact-kind &lt;code dir=&quot;auto&quot;&gt;Literal&lt;/code&gt;, and the validator’s kind
table — derives from that one constant, with a parity test asserting agreement. This
closes the drift class by construction rather than by convention.&lt;/p&gt;
&lt;h3 id=&quot;d4--hybrid-manifest-driven-bundle-validation&quot;&gt;D4 — Hybrid manifest-driven bundle validation&lt;/h3&gt;
&lt;p&gt;The validator resolves &lt;em&gt;registered&lt;/em&gt; artifacts through the synthesis manifest’s
&lt;code dir=&quot;auto&quot;&gt;(kind, slug, path, provenance_path)&lt;/code&gt; records — which the manifest already captures for
every direct-write artifact, requiring no writer extension — and &lt;strong&gt;retains&lt;/strong&gt; the
filesystem walk plus filename parse for the orphan/legacy direction (an on-disk artifact
or sidecar absent from the manifest). A purely manifest-driven validator cannot detect
that class of corruption, so the hybrid shape is deliberate: manifest lookup for positive
resolution of registered artifacts, disk sweep for orphans.&lt;/p&gt;
&lt;h3 id=&quot;d5--migration-dropped-go-forward-only&quot;&gt;D5 — Migration dropped: go-forward-only&lt;/h3&gt;
&lt;p&gt;No filename migration or self-heal ships with this change. Existing repositories with
SCREAMING-case (or otherwise non-canonical) artifact filenames validate green under D4
purely because the manifest — not the filename — is now the resolution path for
registered artifacts, with authored files left untouched. A rename was rejected because
it is cosmetic (the manifest already carries the kebab slug regardless of on-disk
filename, so D3+D4 alone fix #4832 for existing repositories) and because renaming an
artifact’s file stem is not safe: &lt;code dir=&quot;auto&quot;&gt;activated_directives&lt;/code&gt; keys off the file stem
(&lt;code dir=&quot;auto&quot;&gt;kind_vocabulary.py:434&lt;/code&gt;), so a hand-authored directive whose stem does not equal its id
would be silently dropped from the activated set on rename (the #3816 failure class). A
migration would also invert the registration module’s “never mutate authored source”
invariant and require clobber/dirty-tree/crash-atomicity engineering with no existing
mechanism to lean on. Dropping the migration removes this dormant risk entirely for zero
loss of the green-validate outcome.&lt;/p&gt;
&lt;h3 id=&quot;d6--4834-kept-as-an-independent-correctness-fix&quot;&gt;D6 — &lt;code dir=&quot;auto&quot;&gt;#4834&lt;/code&gt; kept as an independent correctness fix&lt;/h3&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;_registration_records&lt;/code&gt; path/provenance-drift re-write (the early-&lt;code dir=&quot;auto&quot;&gt;continue&lt;/code&gt; at
&lt;code dir=&quot;auto&quot;&gt;project_registration.py:195&lt;/code&gt;) is kept, no longer as a migration precondition but as a
standalone fix: it guards the manifest against recording a stale path when an artifact’s
content is unchanged but its path has drifted.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Positive:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;New project artifacts are born validate-clean under the canonical slug convention —
the scaffolder, engine, and validator now agree by construction.&lt;/li&gt;
&lt;li&gt;Existing repositories with SCREAMING-filename directives validate green through the
manifest without any rename, so the fix is non-disruptive to established projects.&lt;/li&gt;
&lt;li&gt;The drift class between the three surfaces is closed by construction (DIRECTIVE_043):
a sixth registration-writing kind added later must be added to &lt;code dir=&quot;auto&quot;&gt;DIRECT_WRITE_KINDS&lt;/code&gt;
once, and the parity test fails if any consumer is missed.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;#4834&lt;/code&gt;’s stale-path/provenance drift is fixed independently of the slug convention
work, closing a latent manifest-correctness gap.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Trade-offs / follow-ups:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;A pre-existing repository’s on-disk filenames remain non-canonical (SCREAMING-case)
indefinitely unless an operator renames them by hand; this is accepted rather than
automated, per D5’s rationale.&lt;/li&gt;
&lt;li&gt;The bundle validator’s orphan/legacy-direction filesystem walk still relies on
filename parsing (D4), so a legacy artifact with an unparseable filename is reported
as an orphan rather than resolved — an accepted, pre-existing limitation of the
filesystem-walk path, not introduced by this change.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Both the post-plan brownfield adversarial point-cut (3 profile-loaded lenses:
architect-alphonso, debugger-debbie, reviewer-renata) and the post-tasks anti-laziness
point-cut (reviewer-renata, paula-patterns) reviewed this design; every contested
finding was folded into a decision or an explicit accepted-with-rationale disposition —
see &lt;code dir=&quot;auto&quot;&gt;research.md&lt;/code&gt; § Adversarial evidence for the full findings/disposition table (no
finding silently dropped).&lt;/p&gt;
&lt;h2 id=&quot;alternatives-considered&quot;&gt;Alternatives Considered&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Unquoted “verbatim kebab” &lt;code dir=&quot;auto&quot;&gt;slug_for&lt;/code&gt;.&lt;/strong&gt; Rejected — reintroduces a provenance-
directory path escape for namespaced identifiers (CRITICAL, 3-lens convergent
adversarial finding); see D2.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Filename migration/self-heal on validate or upgrade.&lt;/strong&gt; Rejected — cosmetic given D4
alone fixes #4832 for existing repos, and unsafe: risks silently dropping stem-keyed
directive activations (#3816 class) and inverts the “never mutate authored source”
invariant with no existing clobber/atomicity mechanism; see D5.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Exempting engine-written kinds from the validator’s kind check instead of extending
the table.&lt;/strong&gt; Rejected — would silently disable orphan detection for those kinds.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Purely manifest-driven bundle validation (drop the filesystem walk entirely).&lt;/strong&gt;
Rejected — cannot detect an on-disk artifact or sidecar absent from the manifest,
which is exactly the orphan/ghost corruption class the validator exists to catch.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;references&quot;&gt;References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Mission &lt;code dir=&quot;auto&quot;&gt;kitty-specs/doctrine-slug-canonicalization-01M31SP9/&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;research.md&lt;/code&gt;
(Decisions 1–6, § Adversarial evidence — post-plan brownfield and post-tasks
anti-laziness point-cuts), &lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt; (FR-004, FR-005, FR-008, NFR-002, NFR-004).&lt;/li&gt;
&lt;li&gt;Issues: #4832 (validator false-positive on project directives), #4833 (validator
rejects engine’s own &lt;code dir=&quot;auto&quot;&gt;agent_profile&lt;/code&gt; sidecars; &lt;code dir=&quot;auto&quot;&gt;procedure&lt;/code&gt; a latent twin), #4834
(&lt;code dir=&quot;auto&quot;&gt;_registration_records&lt;/code&gt; path/provenance drift), #3816 (stem-keyed activation drop
class the dropped migration would have risked), #2519 (convergence note).&lt;/li&gt;
&lt;li&gt;Implementation: &lt;code dir=&quot;auto&quot;&gt;src/charter/offering/artifact_kinds.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;DIRECT_WRITE_KINDS&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;slug_for&lt;/code&gt;), &lt;code dir=&quot;auto&quot;&gt;src/charter/offering/drg/project_scan.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;src/charter/activation/ synthesizer/manifest.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;src/charter/offering/drg/bundle.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;src/charter/activation/project_registration.py&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Directive: DIRECTIVE_043 (canonical-source-unification).&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
