Koder Design: facets as cross-cutting tags, not single-membership content trees

proposed

Koder Design — Facets as cross-cutting tags

Status

*roposed*— 20260512, em revisão pelo owner.

Continuação de design-RFC-001 (umbrella programme) e design-RFC-002 (responsiveness SDK). Resolve uma fricção de IA emergente quando o portal cresceu: a navegação sidebar trata SEÇÕES e FACETS como duas listas paralelas, mas as duas servem propósitos diferentes — o que causa confusão na home (default lands em Visual, visualmente subordinado a SEÇÕES).

Summary

Migrar *ACETS*da impl atual (1:1 spec-group → facet, hardcoded em internal/kinds/facet.go::Facets[].SpecGroups) para *ag system cross-cutting* cada spec declara em frontmatter facets: [...] (0..n facets), e cada Facet page é um *isting dinâmico*das specs com aquela tag. Multimembership passa a ser natural; specgroups voltam a ser apenas convenção de path.

Background

design-RFC-001 (revised 20260510) estabelece Koder Design como umbrella em 5 facets — Visual, Code, Data, Interface, System. A intenção declarada no comentário do código:

"Facets are orthogonal — a spec may touch more than one but is mapped to its primary facet here." — tools/design-gen/internal/kinds/facet.go::14

A impl atual hardcoda 1:1 (spec-group → primary facet) por simplicidade, mas essa simplificação:

  1. *ente sobre conteúdo.*kpkg/format.kmd toca Data **System;

    ipc/protocol.kmd toca Interface **Code; multi-tenancy/contract.kmd toca Data **System; identity/login-resolution.kmd toca Data **Interface. Forçar escolha única é desonesto editorialmente.

  1. *copla facets ao path.*Para mover uma spec entre facets, é

    preciso ou (a) reorganizar o diretório (mv specs/foo specs/bar), ou (b) editar facet.go. Schema rígido.

  1. *loqueia tagging future-proof.*Quando o KDS quiser adicionar

    uma 6ª dimensão (by-product, by-skill, by-maturity), todo o sistema de spec-groups precisa ser repensado.

  1. *ausa o bug de navegação.*A home (/<locale>/) é a Visual

    landing porque Visual tem URLPath: "" no array Facets. Quem chega na home não está numa "welcome page" — está implicitamente no Visual facet. Sidebar destaca Visual corretamente, mas o usuário não espera isso (esperava chegar numa raiz neutra). Fix conceitual: home distinta de Visual.

Proposta

Schema de frontmatter

Adicionar campo opcional facets: aos specs em `metadocsstack/specs

Source: ../home/koder/dev/koder/meta/docs/stack/rfcs/design-RFC-003-facets-as-cross-cutting-tags.kmd