<?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-29-1-catalog-languages-states-and-reserved-unknown/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-09-29-1-catalog-languages-states-and-reserved-unknown/</id>
  <title>ADR: Catalog languages — four states and the reserved unknown value</title>
  <updated>2026-09-29T00: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-29-1-catalog-languages-states-and-reserved-unknown/"/>
  <summary>Accepted: catalog.languages keeps absent, empty and recognised states and gains a reserved unknown value, with a regenerate-only precedence bypass and tech-agnostic doctrine.</summary>
  <content type="html">&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-09-29&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (operator). Design reviewed by the mission’s pre-planning, post-spec and
post-tasks adversarial squad lenses.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5284&quot;&gt;#5284&lt;/a&gt; (planning and
context for non-Python projects), &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5283&quot;&gt;#5283&lt;/a&gt; (mission
review), &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/4614&quot;&gt;#4614&lt;/a&gt; (stale languages survive
regeneration), under umbrella &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/2330&quot;&gt;#2330&lt;/a&gt;.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;A Zig consumer got Python guidance in planning context, a failing review gate, and a stale
&lt;code dir=&quot;auto&quot;&gt;catalog.languages: [python]&lt;/code&gt; that survived every regeneration.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;catalog.languages&lt;/code&gt; carries a load-bearing contract from
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/3292&quot;&gt;#3292&lt;/a&gt;: absent means “admit every artifact”,
an empty list means “admit none”.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/2395&quot;&gt;#2395&lt;/a&gt; decided that runtime reads treat the
compiled value as authoritative over the interview transcript.&lt;/li&gt;
&lt;li&gt;No state expressed “the project declared a language Spec Kitty does not recognise”.&lt;/li&gt;
&lt;li&gt;Operator policy (#2330): doctrine is tech-agnostic; unknown languages are advised to extend their
local charter; languages are never added one by one.&lt;/li&gt;
&lt;li&gt;Governing principle (operator, 2026-09-29): charter and doctrine components are language- and
stack-agnostic wherever possible; a language- or framework-specific component declares that
specificity in its metadata (today &lt;code dir=&quot;auto&quot;&gt;applies_to_languages&lt;/code&gt;). When a project is configured for a
language or stack, matching and suggested activation consider both the generic and the matching
specific doctrine and charter packs.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;catalog.languages&lt;/code&gt; has four states:&lt;/p&gt;






























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;State&lt;/th&gt;&lt;th&gt;Stored form&lt;/th&gt;&lt;th&gt;Language-scoped artifacts admitted&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;No signal&lt;/td&gt;&lt;td&gt;absent or null&lt;/td&gt;&lt;td&gt;all (unchanged)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Admit none&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;[]&lt;/code&gt; (hand-edited only)&lt;/td&gt;&lt;td&gt;none (unchanged)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Recognised&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;[python, ...]&lt;/code&gt;&lt;/td&gt;&lt;td&gt;overlapping ones only&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Unknown&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;[unknown]&lt;/code&gt;&lt;/td&gt;&lt;td&gt;none; unscoped artifacts still load, and one advisory is rendered&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Reserved &lt;code dir=&quot;auto&quot;&gt;unknown&lt;/code&gt; value.&lt;/strong&gt; Spec Kitty writes &lt;code dir=&quot;auto&quot;&gt;[unknown]&lt;/code&gt; when the languages/frameworks answer
is a real declaration that names no recognised language. Placeholders and the shipped default
answer mean no signal, never &lt;code dir=&quot;auto&quot;&gt;unknown&lt;/code&gt;. A recognised language in that answer always wins over
&lt;code dir=&quot;auto&quot;&gt;unknown&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Declared answer wins (operator decision D1, 2026-09-29).&lt;/strong&gt; When the languages/frameworks answer
is a real declaration (non-empty, not the shipped default, not a placeholder), languages resolve
from THAT ANSWER ALONE: the built-in detector hits in it UNION the doctrine-vocabulary whole-word
hits in it, else &lt;code dir=&quot;auto&quot;&gt;unknown&lt;/code&gt;. So &lt;code dir=&quot;auto&quot;&gt;Python and Twig&lt;/code&gt; resolves to &lt;code dir=&quot;auto&quot;&gt;python, twig&lt;/code&gt;, while &lt;code dir=&quot;auto&quot;&gt;Zig&lt;/code&gt; stays
&lt;code dir=&quot;auto&quot;&gt;unknown&lt;/code&gt; even when the testing answer mentions &lt;code dir=&quot;auto&quot;&gt;pytest&lt;/code&gt;. The other answers are scanned, with the
built-in detector only, when the languages/frameworks answer is absent, default or a placeholder.
The built-in detector list is frozen (no per-language additions, C-001); the vocabulary is read
from installed doctrine (built-in, org and project packs). A token attached to a preceding
&lt;code dir=&quot;auto&quot;&gt;word-&lt;/code&gt; (for example &lt;code dir=&quot;auto&quot;&gt;librespot-java&lt;/code&gt;, or the &lt;code dir=&quot;auto&quot;&gt;TypeScript&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;React-TypeScript&lt;/code&gt;) does not count.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Regenerate-only precedence bypass.&lt;/strong&gt; Only the regenerate path (&lt;code dir=&quot;auto&quot;&gt;charter generate&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;--from-interview&lt;/code&gt;, the default, and
&lt;code dir=&quot;auto&quot;&gt;charter activate --resynthesize&lt;/code&gt;, which calls it) re-derives languages from the interview and
replaces the compiled value, including a hand edit. Runtime reads and non-interview recompiles keep compiled-first precedence, so #2395 and
#3292 stay intact.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;unknown&lt;/code&gt; is reserved in artifact scopes.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;spec-kitty charter validate&lt;/code&gt; rejects it at authoring time,
and it is stripped from both sides of the scope match at runtime. &lt;code dir=&quot;auto&quot;&gt;any&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;all&lt;/code&gt; remain rejected
at authoring and are treated as unscoped at runtime.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Advice, not language tables.&lt;/strong&gt; The context renders one advisory pointing to the how-to
“Extend your charter for an unsupported language” whenever no installed doctrine is scoped to the
resolved languages (operator decision D2, 2026-09-29). That covers &lt;code dir=&quot;auto&quot;&gt;unknown&lt;/code&gt; and also recognised
languages without shipped specialist guidance, for example Rust, Swift or Ruby, while the stored
&lt;code dir=&quot;auto&quot;&gt;Languages:&lt;/code&gt; value is still shown as recorded. &lt;code dir=&quot;auto&quot;&gt;lacks_specialist_guidance&lt;/code&gt; in
&lt;code dir=&quot;auto&quot;&gt;charter.activation.language_scope&lt;/code&gt; is the single authority for this decision. The dead-code gate reports
&lt;code dir=&quot;auto&quot;&gt;MISSION_REVIEW_DEAD_CODE_NOT_APPLICABLE&lt;/code&gt; (skip, &lt;code dir=&quot;auto&quot;&gt;pass_with_notes&lt;/code&gt;) for change sets it does not
support.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;No shipped doctrine is Go-scoped after the tactic de-scoping below, so a Go project has no specialist
guidance either; C# and C++ are not whole words and resolve to &lt;code dir=&quot;auto&quot;&gt;unknown&lt;/code&gt;. Installed doctrine (an
org or project pack) that declares a language brings that language into the vocabulary.&lt;/li&gt;
&lt;li&gt;A recognised language without installed specialist guidance (Rust, for example) records
&lt;code dir=&quot;auto&quot;&gt;Languages: rust&lt;/code&gt; and still sees the advisory.&lt;/li&gt;
&lt;li&gt;Follow-up, not delivered here: stack and framework metadata on doctrine components and
language-aware activation suggestions, tracked in #5364.&lt;/li&gt;
&lt;li&gt;A framework-only answer (for example &lt;code dir=&quot;auto&quot;&gt;Django&lt;/code&gt;) is labelled &lt;code dir=&quot;auto&quot;&gt;unknown&lt;/code&gt;; the advisory tells the user
to extend their charter.&lt;/li&gt;
&lt;li&gt;A plain &lt;code dir=&quot;auto&quot;&gt;charter generate&lt;/code&gt; replaces a hand-edited &lt;code dir=&quot;auto&quot;&gt;catalog.languages&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;--no-from-interview&lt;/code&gt; keeps it.&lt;/li&gt;
&lt;li&gt;Tactic de-scoping (operator directive 2026-09-29): three built-in tactics that are
language-independent (&lt;code dir=&quot;auto&quot;&gt;dependency-hygiene&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;chain-of-responsibility-rule-pipeline&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;secure-regex-catastrophic-backtracking&lt;/code&gt;) are now unscoped and language-neutral. Built-in tactics
are language-neutral; language-specific guidance lives in explicitly language-specific styleguides,
toolguides and profiles, or in the local charter.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;unknown&lt;/code&gt; value is reserved, so no artifact may target it.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;alternatives-considered&quot;&gt;Alternatives Considered&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;A separate status field.&lt;/strong&gt; Two fields to keep consistent; rejected.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Reuse &lt;code dir=&quot;auto&quot;&gt;[]&lt;/code&gt; for unknown.&lt;/strong&gt; Loses the advisory signal and collides with the hand-edited admit-none
meaning; rejected.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Modification-time precedence between interview and compiled value.&lt;/strong&gt; Fragile under git; rejected.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;An explicit reset flag.&lt;/strong&gt; Undiscoverable; rejected.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Growing a per-language table.&lt;/strong&gt; Contradicts the tech-agnostic policy; rejected.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
