spec-first-copilot 0.6.0-beta.9 → 0.7.0

package/templates/.github/adapters/naming.md

@@ -1,241 +1,241 @@
-# Naming Templating Engine
-
-> Motor trivial que transforma os templates em `sfw.config.yml > naming.*`
-> em strings finais (títulos Confluence, nomes de pasta, etc.).
->
-> **Função pura, zero dependência externa.** Implementável em qualquer
-> linguagem em ~15 linhas. Este documento é a especificação que
-> adapters/skills/bootstrap seguem.
-
----
-
-## Por que existe
-
-Antes da decisão do adapter layer, títulos eram hardcoded em string literal
-no código das skills:
-
-```
-title = `out_${scope}_PRD`;    // ← hardcoded em 5 lugares
-```
-
-Isso forçava:
-1. Qualquer mudança de convenção → tocar N arquivos
-2. Times com outra convenção (ex: `[PRD] scope`) não conseguiam usar SFW
-3. Testes precisavam mockar strings mágicas
-
-Agora a convenção vive em **um** arquivo (`sfw.config.yml`) e é aplicada via
-templating engine centralizado.
-
----
-
-## Placeholders suportados
-
-| Placeholder | O que substitui | Fonte |
-|-------------|-----------------|-------|
-| `{scope}` | Nome do item no Input (ex: `app_barbearia`, `feat_login`) | Argumento da skill |
-| `{type}` | Tipo do artefato (ex: `PRD`, `SDD`, `Progresso`) | Contexto da skill |
-
-**Nenhum outro placeholder é aceito no MVP.** Expansões futuras entram por
-proposta explícita (ex: `{phase}`, `{repo}`, `{timestamp}`).
-
-**O Input NÃO usa naming templating.** O usuário nomeia livremente os items
-no backend (Confluence, filesystem, etc.). O agent lê o nome tal qual está.
-Naming só é aplicado no Output (o que o agent GERA).
-
----
-
-## Templates no manifest
-
-O `sfw.config.yml` define 2 templates de output:
-
-| Template | Onde | Exemplo |
-|----------|------|---------|
-| `output_container` | Subpasta/page-mãe por scope no Output | `"out_{scope}"` → `out_app_barbearia` |
-| `output_artifact` | Nome do artefato dentro do container | `"{scope} - {type}"` → `app_barbearia - PRD` |
-
-**`output_container`** é o agrupador. No Confluence vira uma page-mãe com
-children; no filesystem vira uma pasta.
-
-**`output_artifact`** é o item individual (PRD, SDD, Progresso). No
-Confluence é title de uma child page; no filesystem é nome de arquivo
-(adapter adiciona `.md` automaticamente).
-
-**Por que `{scope}` no `output_artifact`?** No Confluence, titles são
-unique per SPACE — sem `{scope}`, duas features teriam `PRD` e `SDD` com
-mesmo título e colidiria. No filesystem não colide porque vive dentro de
-pastas diferentes, então o user pode configurar `output_artifact: "{type}"`
-se preferir limpar redundância.
-
----
-
-## Contrato da função
-
-```typescript
-/**
- * Aplica templating de nome.
- *
- * @param template  String com placeholders {scope}, {type}
- * @param vars      Objeto com os valores — chaves que não aparecem no template
- *                  são ignoradas (não é erro)
- * @returns         String final, pronta pra uso como título/nome
- * @throws          NamingTemplateError se o template contém placeholder desconhecido
- *                  OU se um placeholder usado não tem valor em vars
- */
-function applyNaming(template: string, vars: {
-  scope?: string;
-  type?: string;
-}): string
-```
-
-### Regras invioláveis
-
-1. **Placeholder desconhecido lança erro.**
-   `"{type} {module}"` → `NamingTemplateError: unknown placeholder "{module}"`.
-   Nunca retorna a string literal `{module}` — isso vazaria inconsistência pros backends.
-
-2. **Placeholder sem valor lança erro.**
-   Template `"{scope} - {type}"` com `vars = { type: "PRD" }`
-   → `NamingTemplateError: placeholder {scope} required but not provided`.
-
-3. **Chaves extras em `vars` são ignoradas.**
-   Não é erro passar `vars.scope = "x"` pra um template que só usa `{type}`.
-   Isso permite que as skills passem o objeto cheio sem se preocupar com qual
-   template está sendo aplicado.
-
-4. **Substituição é literal — sem escape.**
-   Se o `scope` tem caracteres especiais pro backend (ex: `/` no filesystem,
-   `>` no Confluence), é responsabilidade do adapter sanitizar **depois** do
-   apply. Naming engine não conhece constraints de backend.
-
-5. **Case-sensitive.** `{Scope}` ≠ `{scope}`. Não normaliza.
-
-6. **Não suporta lógica.** Sem `{scope|upper}`, sem condicionais. Zero magic.
-
----
-
-## Pseudo-código de referência
-
-```typescript
-const PLACEHOLDER_RE = /\{(\w+)\}/g;
-const KNOWN = new Set(["scope", "type"]);
-
-function applyNaming(template: string, vars: Record<string, string | undefined>): string {
-  // 1. Detecta placeholders usados no template
-  const used = new Set<string>();
-  for (const m of template.matchAll(PLACEHOLDER_RE)) {
-    used.add(m[1]);
-  }
-
-  // 2. Valida placeholders desconhecidos
-  for (const p of used) {
-    if (!KNOWN.has(p)) {
-      throw new NamingTemplateError(
-        `unknown placeholder "{${p}}" in template "${template}" (supported: ${[...KNOWN].join(", ")})`
-      );
-    }
-  }
-
-  // 3. Valida valores ausentes
-  for (const p of used) {
-    if (vars[p] === undefined || vars[p] === "") {
-      throw new NamingTemplateError(
-        `placeholder {${p}} required but not provided`
-      );
-    }
-  }
-
-  // 4. Substitui
-  return template.replace(PLACEHOLDER_RE, (_, key) => vars[key]!);
-}
-```
-
----
-
-## Exemplos (matriz de casos)
-
-| Template | vars | Resultado | OK? |
-|----------|------|-----------|-----|
-| `out_{scope}` | `{scope:"app_barbearia"}` | `out_app_barbearia` | ✅ |
-| `{scope} - {type}` | `{scope:"app_barbearia", type:"PRD"}` | `app_barbearia - PRD` | ✅ |
-| `{type}` | `{type:"SDD"}` | `SDD` | ✅ (filesystem dentro de subpasta) |
-| `[{type}] {scope}` | `{type:"PRD", scope:"feat_login"}` | `[PRD] feat_login` | ✅ |
-| `{type}/{scope}` | `{type:"docs", scope:"arch"}` | `docs/arch` | ✅ (adapter sanitiza `/` depois) |
-| `{scope} - {type}` | `{type:"PRD"}` | — | ❌ `NamingTemplateError: placeholder {scope} required` |
-| `{type} {module}` | `{type:"PRD"}` | — | ❌ `NamingTemplateError: unknown placeholder "{module}"` |
-| `hello world` | `{}` | `hello world` | ✅ (sem placeholders) |
-| `out_{scope}` | `{scope:""}` | — | ❌ (string vazia é tratada como ausente) |
-
----
-
-## Uso nas skills — matriz de quais templates usam quais placeholders
-
-| Skill / operação | Template consumido | Placeholders usados |
-|------------------|-------------------|---------------------|
-| `/sf-load` busca scope no Input | Nenhum — usa o nome do item **tal qual está** no backend | — |
-| `/sf-extract` publica PRD | `output_container` + `output_artifact` (type=PRD) | `{scope}`, `{type}` |
-| `/sf-design` publica SDD | `output_container` + `output_artifact` (type=SDD) | `{scope}`, `{type}` |
-| `/sf-plan` publica Progresso | `output_container` + `output_artifact` (type=Progresso) | `{scope}`, `{type}` |
-| `/sf-load` grava scope folder local | `output_container` (reuso pro path local) | `{scope}` |
-
-Skills **sempre** passam `{ scope, type }` cheio — o engine ignora o que o
-template não usa.
-
-**`/sf-load` não formata Input** — só lê o nome real do item via
-`adapter.listChildren()` e busca match exato com o argumento da skill.
-
----
-
-## Fluxo ponta-a-ponta (exemplo)
-
-Config:
-```yaml
-naming:
-  output_container: "out_{scope}"
-  output_artifact: "{scope} - {type}"
-```
-
-Cenário: `/sf-start app_barbearia` → `/sf-extract` → `/sf-design` → `/sf-plan`
-
-| Passo | Template usado | vars | Resultado |
-|-------|---------------|------|-----------|
-| `/sf-load` busca item no Input | nenhum | — | Encontra page "app_barbearia" pelo nome |
-| `/sf-load` grava local | `output_container` | `{scope:"app_barbearia"}` | Pasta `workspace/Input/out_app_barbearia/` |
-| `/sf-extract` cria container no Output | `output_container` | `{scope:"app_barbearia"}` | Page/pasta `out_app_barbearia` |
-| `/sf-extract` publica PRD | `output_artifact` | `{scope:"app_barbearia", type:"PRD"}` | `app_barbearia - PRD` (dentro do container) |
-| `/sf-design` publica SDD | `output_artifact` | `{scope:"app_barbearia", type:"SDD"}` | `app_barbearia - SDD` |
-| `/sf-plan` publica Progresso | `output_artifact` | `{scope:"app_barbearia", type:"Progresso"}` | `app_barbearia - Progresso` |
-
-Resultado no Confluence:
-```
-Output (page-mãe)
-└── out_app_barbearia (container)
-    ├── app_barbearia - PRD
-    ├── app_barbearia - SDD
-    └── app_barbearia - Progresso
-```
-
-Resultado no filesystem:
-```
-workspace/Output/
-└── out_app_barbearia/
-    ├── app_barbearia - PRD.md
-    ├── app_barbearia - SDD.md
-    └── app_barbearia - Progresso.md
-```
-
----
-
-## Onde vive o código da engine
-
-Tom do MVP: implementação inline dentro do adapter layer, não arquivo próprio.
-Cada adapter que precisa formatar título chama `applyNaming(template, vars)`.
-Quando a implementação real for escrita (pós-P0.2), avaliar se extrai pra
-`lib/naming.ts` ou mantém como função no registry.
-
----
-
-## Referências
-
-- Schema do manifest: `sfw.config.yml.example` (raiz do projeto)
-- Interface do adapter: `.github/adapters/interface.md`
-- Erros: `.github/adapters/errors.md` — `NamingTemplateError` é subclasse de `ValidationError`
+# Naming Templating Engine
+
+> Motor trivial que transforma os templates em `sfw.config.yml > naming.*`
+> em strings finais (títulos Confluence, nomes de pasta, etc.).
+>
+> **Função pura, zero dependência externa.** Implementável em qualquer
+> linguagem em ~15 linhas. Este documento é a especificação que
+> adapters/skills/bootstrap seguem.
+
+---
+
+## Por que existe
+
+Antes da decisão do adapter layer, títulos eram hardcoded em string literal
+no código das skills:
+
+```
+title = `out_${scope}_PRD`;    // ← hardcoded em 5 lugares
+```
+
+Isso forçava:
+1. Qualquer mudança de convenção → tocar N arquivos
+2. Times com outra convenção (ex: `[PRD] scope`) não conseguiam usar SFW
+3. Testes precisavam mockar strings mágicas
+
+Agora a convenção vive em **um** arquivo (`sfw.config.yml`) e é aplicada via
+templating engine centralizado.
+
+---
+
+## Placeholders suportados
+
+| Placeholder | O que substitui | Fonte |
+|-------------|-----------------|-------|
+| `{scope}` | Nome do item no Input (ex: `app_barbearia`, `feat_login`) | Argumento da skill |
+| `{type}` | Tipo do artefato (ex: `PRD`, `TRD`, `Progresso`) | Contexto da skill |
+
+**Nenhum outro placeholder é aceito no MVP.** Expansões futuras entram por
+proposta explícita (ex: `{phase}`, `{repo}`, `{timestamp}`).
+
+**O Input NÃO usa naming templating.** O usuário nomeia livremente os items
+no backend (Confluence, filesystem, etc.). O agent lê o nome tal qual está.
+Naming só é aplicado no Output (o que o agent GERA).
+
+---
+
+## Templates no manifest
+
+O `sfw.config.yml` define 2 templates de output:
+
+| Template | Onde | Exemplo |
+|----------|------|---------|
+| `output_container` | Subpasta/page-mãe por scope no Output | `"out_{scope}"` → `out_app_barbearia` |
+| `output_artifact` | Nome do artefato dentro do container | `"{scope} - {type}"` → `app_barbearia - PRD` |
+
+**`output_container`** é o agrupador. No Confluence vira uma page-mãe com
+children; no filesystem vira uma pasta.
+
+**`output_artifact`** é o item individual (PRD, TRD, Progresso). No
+Confluence é title de uma child page; no filesystem é nome de arquivo
+(adapter adiciona `.md` automaticamente).
+
+**Por que `{scope}` no `output_artifact`?** No Confluence, titles são
+unique per SPACE — sem `{scope}`, duas features teriam `PRD` e `TRD` com
+mesmo título e colidiria. No filesystem não colide porque vive dentro de
+pastas diferentes, então o user pode configurar `output_artifact: "{type}"`
+se preferir limpar redundância.
+
+---
+
+## Contrato da função
+
+```typescript
+/**
+ * Aplica templating de nome.
+ *
+ * @param template  String com placeholders {scope}, {type}
+ * @param vars      Objeto com os valores — chaves que não aparecem no template
+ *                  são ignoradas (não é erro)
+ * @returns         String final, pronta pra uso como título/nome
+ * @throws          NamingTemplateError se o template contém placeholder desconhecido
+ *                  OU se um placeholder usado não tem valor em vars
+ */
+function applyNaming(template: string, vars: {
+  scope?: string;
+  type?: string;
+}): string
+```
+
+### Regras invioláveis
+
+1. **Placeholder desconhecido lança erro.**
+   `"{type} {module}"` → `NamingTemplateError: unknown placeholder "{module}"`.
+   Nunca retorna a string literal `{module}` — isso vazaria inconsistência pros backends.
+
+2. **Placeholder sem valor lança erro.**
+   Template `"{scope} - {type}"` com `vars = { type: "PRD" }`
+   → `NamingTemplateError: placeholder {scope} required but not provided`.
+
+3. **Chaves extras em `vars` são ignoradas.**
+   Não é erro passar `vars.scope = "x"` pra um template que só usa `{type}`.
+   Isso permite que as skills passem o objeto cheio sem se preocupar com qual
+   template está sendo aplicado.
+
+4. **Substituição é literal — sem escape.**
+   Se o `scope` tem caracteres especiais pro backend (ex: `/` no filesystem,
+   `>` no Confluence), é responsabilidade do adapter sanitizar **depois** do
+   apply. Naming engine não conhece constraints de backend.
+
+5. **Case-sensitive.** `{Scope}` ≠ `{scope}`. Não normaliza.
+
+6. **Não suporta lógica.** Sem `{scope|upper}`, sem condicionais. Zero magic.
+
+---
+
+## Pseudo-código de referência
+
+```typescript
+const PLACEHOLDER_RE = /\{(\w+)\}/g;
+const KNOWN = new Set(["scope", "type"]);
+
+function applyNaming(template: string, vars: Record<string, string | undefined>): string {
+  // 1. Detecta placeholders usados no template
+  const used = new Set<string>();
+  for (const m of template.matchAll(PLACEHOLDER_RE)) {
+    used.add(m[1]);
+  }
+
+  // 2. Valida placeholders desconhecidos
+  for (const p of used) {
+    if (!KNOWN.has(p)) {
+      throw new NamingTemplateError(
+        `unknown placeholder "{${p}}" in template "${template}" (supported: ${[...KNOWN].join(", ")})`
+      );
+    }
+  }
+
+  // 3. Valida valores ausentes
+  for (const p of used) {
+    if (vars[p] === undefined || vars[p] === "") {
+      throw new NamingTemplateError(
+        `placeholder {${p}} required but not provided`
+      );
+    }
+  }
+
+  // 4. Substitui
+  return template.replace(PLACEHOLDER_RE, (_, key) => vars[key]!);
+}
+```
+
+---
+
+## Exemplos (matriz de casos)
+
+| Template | vars | Resultado | OK? |
+|----------|------|-----------|-----|
+| `out_{scope}` | `{scope:"app_barbearia"}` | `out_app_barbearia` | ✅ |
+| `{scope} - {type}` | `{scope:"app_barbearia", type:"PRD"}` | `app_barbearia - PRD` | ✅ |
+| `{type}` | `{type:"TRD"}` | `TRD` | ✅ (filesystem dentro de subpasta) |
+| `[{type}] {scope}` | `{type:"PRD", scope:"feat_login"}` | `[PRD] feat_login` | ✅ |
+| `{type}/{scope}` | `{type:"docs", scope:"arch"}` | `docs/arch` | ✅ (adapter sanitiza `/` depois) |
+| `{scope} - {type}` | `{type:"PRD"}` | — | ❌ `NamingTemplateError: placeholder {scope} required` |
+| `{type} {module}` | `{type:"PRD"}` | — | ❌ `NamingTemplateError: unknown placeholder "{module}"` |
+| `hello world` | `{}` | `hello world` | ✅ (sem placeholders) |
+| `out_{scope}` | `{scope:""}` | — | ❌ (string vazia é tratada como ausente) |
+
+---
+
+## Uso nas skills — matriz de quais templates usam quais placeholders
+
+| Skill / operação | Template consumido | Placeholders usados |
+|------------------|-------------------|---------------------|
+| `/sf-load` busca scope no Input | Nenhum — usa o nome do item **tal qual está** no backend | — |
+| `/sf-extract` publica PRD | `output_container` + `output_artifact` (type=PRD) | `{scope}`, `{type}` |
+| `/sf-extract` publica TRD | `output_container` + `output_artifact` (type=TRD) | `{scope}`, `{type}` |
+| `/sf-plan` publica Progresso | `output_container` + `output_artifact` (type=Progresso) | `{scope}`, `{type}` |
+| `/sf-load` grava scope folder local | `output_container` (reuso pro path local) | `{scope}` |
+
+Skills **sempre** passam `{ scope, type }` cheio — o engine ignora o que o
+template não usa.
+
+**`/sf-load` não formata Input** — só lê o nome real do item via
+`adapter.listChildren()` e busca match exato com o argumento da skill.
+
+---
+
+## Fluxo ponta-a-ponta (exemplo)
+
+Config:
+```yaml
+naming:
+  output_container: "out_{scope}"
+  output_artifact: "{scope} - {type}"
+```
+
+Cenário: `/sf-start app_barbearia` → `/sf-extract` → `/sf-design` → `/sf-plan`
+
+| Passo | Template usado | vars | Resultado |
+|-------|---------------|------|-----------|
+| `/sf-load` busca item no Input | nenhum | — | Encontra page "app_barbearia" pelo nome |
+| `/sf-load` grava local | `output_container` | `{scope:"app_barbearia"}` | Pasta `workspace/Input/out_app_barbearia/` |
+| `/sf-extract` cria container no Output | `output_container` | `{scope:"app_barbearia"}` | Page/pasta `out_app_barbearia` |
+| `/sf-extract` publica PRD | `output_artifact` | `{scope:"app_barbearia", type:"PRD"}` | `app_barbearia - PRD` (dentro do container) |
+| `/sf-extract` publica TRD | `output_artifact` | `{scope:"app_barbearia", type:"TRD"}` | `app_barbearia - TRD` |
+| `/sf-plan` publica Progresso | `output_artifact` | `{scope:"app_barbearia", type:"Progresso"}` | `app_barbearia - Progresso` |
+
+Resultado no Confluence:
+```
+Output (page-mãe)
+└── out_app_barbearia (container)
+    ├── app_barbearia - PRD
+    ├── app_barbearia - TRD
+    └── app_barbearia - Progresso
+```
+
+Resultado no filesystem:
+```
+workspace/Output/
+└── out_app_barbearia/
+    ├── app_barbearia - PRD.md
+    ├── app_barbearia - TRD.md
+    └── app_barbearia - Progresso.md
+```
+
+---
+
+## Onde vive o código da engine
+
+Tom do MVP: implementação inline dentro do adapter layer, não arquivo próprio.
+Cada adapter que precisa formatar título chama `applyNaming(template, vars)`.
+Quando a implementação real for escrita (pós-P0.2), avaliar se extrai pra
+`lib/naming.ts` ou mantém como função no registry.
+
+---
+
+## Referências
+
+- Schema do manifest: `sfw.config.yml.example` (raiz do projeto)
+- Interface do adapter: `.github/adapters/interface.md`
+- Erros: `.github/adapters/errors.md` — `NamingTemplateError` é subclasse de `ValidationError`