golem15/msd-core
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4a705cf19f2f2d22ff35878b5ce54fec334ce0ae
msd-core/docs/pt-BR/CLI-TOOLS.md
0xdhx 472f585f7c fix(#3726)!: require --confirm before milestone complete mutates (#3774) 
* fix(#3726): require --confirm before milestone complete mutates

`milestone complete <version>` is a one-way door — ROADMAP.md and
REQUIREMENTS.md archived, every phase directory in the milestone MOVED,
STATE.md rewritten — and ran unconditionally on first invocation through
every invocation path, including `query milestone.complete <version>`,
whose `query` meta-prefix reads as a read-only namespace but performs no
filtering (#167's invocation-compatibility shim + #3243's dotted-form
normalization).

The gate lives on the destructive command itself, not on the `query`
prefix (the prefix is an intentional invocation mechanism, not a
permission boundary — restricting it would break dozens of shipped
workflow callers). Without --confirm and without --dry-run the command
now refuses via error() before reading anything beyond its arg checks,
so an unconfirmed invocation is a guaranteed no-op on disk. --dry-run
still previews with no confirmation needed and is now documented in the
usage block (it was only documented for the sibling archive-quick).
--force keeps its narrow meaning — bypassing the TRUNCATED-scope and
unstarted-phase guards — and does not double as the mutation opt-in.
--confirm follows the existing `phases clear --confirm` idiom in the
same module.

complete-milestone.md's two invocations pass --confirm (the workflow has
gathered explicit user intent by that step). Existing tests get
--confirm appended — pre-change behavior is exactly confirmed behavior —
and a #3726 regression block covers: refusal + full-tree byte-identity
on both invocation forms, --force not satisfying the gate, --dry-run
still passing without confirmation, and --confirm proceeding. The
refusal tests fail against pre-fix code (negative control run).

Fixes #3726

* docs(#3726): document the --confirm requirement in CLI-TOOLS and COMMANDS

Cross-AI review of the fix diff (codex, pre-create) caught three shipped
doc sites still instructing the now-refused bare invocation: the
CLI-TOOLS.md milestone-complete synopsis + flag table, and COMMANDS.md's
two guard-override instructions (`--force` alone now refuses without
--confirm). Localized CLI-TOOLS copies already lag the English synopsis
(no --force/--dry-run either) and follow the translation pipeline, not
this fix.

* chore(#3726): set changeset fragment pr to 3774

* test(#3726): confirm-gate CI repairs — QA scenario caller + growth ack

Two CI reds from the --confirm gate, both this branch's own misses:

- tests/qa/scenarios/milestone-rollover.json invoked `milestone complete
  1.0 --force` as a JSON arg-array fixture — a caller shape the test
  sweep (which grepped runGsdTools/runSdkQuery in tests/*.cjs) never
  enumerated. Adds --confirm; the scenario's boundary-crossing contract
  is otherwise untouched.
- complete-milestone.md's +420-byte --confirm note trips the
  emitted-attribution growth ratchet. Acknowledged as a #3726 append to
  the existing complete-milestone.md entry in
  3409-unreachable-guard-arms.json (two ack sources may never name the
  same path, per that fragment's own precedent).

Local: lint-emitted-drift-ack ok; loop-walk.qa 115/115 green sandboxed.

* docs(#3726): CLI-TOOLS.md guard-override sentences say --force --confirm

Review Major 1: the truncated-window and unstarted-phase guard paragraphs
still told the reader to "Pass `--force` to override", which now refuses
(--force alone does not satisfy the confirmation gate), while the flag
table 470 lines later said the opposite. Mirror the docs/COMMANDS.md pair
so the file no longer contradicts itself.

* docs(#3726): synopsis renders --confirm and --dry-run as alternatives

Review Nit 1: `milestone complete <version> --confirm [--dry-run]` read as
"a dry run still needs --confirm", the opposite of AC 3. Render the pair
as `(--confirm | --dry-run)` in the CLI-TOOLS.md synopsis and the usage
docblock, and let the flag rows carry the rule.

* test(#3726): pass --confirm in base-added milestone fixtures; re-file the growth ack

Rebase onto next (26 commits) surfaced three tests the gate now refuses:
the #3685 write-flag contract pair in tests/milestone.test.cjs and the
`milestone complete` boundary fixture in tests/state-contract.test.cjs
all invoke the command bare. Each now passes --confirm (a mutating run is
exactly what they assert on).

The +420 byte complete-milestone.md growth ack rode on
3409-unreachable-guard-arms.json, which #3078 swept from next as fully
spent — hence the modify/delete conflict. Re-filed under a fresh fragment
named for this issue, never resurrecting the swept one.

* test(#3726): pin the present-but-falsy arm of the confirmation gate

Review Minor 1: the boundary triple covered absent and present but not
present-but-falsy. The gate is an exact-token match, so --confirm=false
and --confirm=0 refuse today — pinned (canonical + query forms, whole
.planning/ tree byte-identical) so a future `=`-aware or prefix-matching
parser cannot silently turn --confirm=false into a confirmed run of an
irreversible command.

* test(#3726): drop --confirm from dry-run-only invocations

Review Nit 2: --confirm was mass-appended to 14 pre-existing --dry-run
invocations that never needed it, so each stopped standing as incidental
proof that a preview needs no confirmation. Reverted to the pre-PR form;
the dedicated AC-3 test carries the explicit assertion.

* docs(#3726): sync the localized CLI-TOOLS synopsis with the confirm gate

REQ-I18N-02 (docs/features/internationalized-documentation.md) requires
translations to stay synchronized with the English source. The four
localized CLI-TOOLS.md guides still advertised a bare
`milestone complete <version>`, which now exits 1. Render the English
synopsis verbatim — `(--confirm | --dry-run)` plus the `[--force]` and
`[--archive-quick]` flags the translations had also fallen behind on.

* test(#3726): drop --confirm from the remaining preview-only invocations

Round 2 reverted the --confirm appends on --dry-run-only invocations in
tests/milestone.test.cjs, but four more sat in two files the sweep missed:
tests/milestone-archive.test.cjs (three) and
tests/milestone-window-single-owner.test.cjs (one).

Each is a preview run whose whole purpose is to document that a preview
mutates nothing, so `--dry-run ... --confirm` contradicted the semantics
the test exists to pin. Dropping the token restores each as incidental
proof that a preview needs no confirmation; the dedicated AC-3 test keeps
the explicit assertion.

No assertion added, relaxed, or removed — the change is four tokens.

* chore(#3726): migrate the emitted-drift ack from a fragment to a commit trailer

#3954 (ADR-3942) moved emitted-drift acknowledgments out of
tests/emitted-drift-acks/ and into git commit trailers, and the fragment
directory no longer exists on next. The reason this PR's fragment carried
moves verbatim into the Emitted-Drift-Ack-Growth trailer on this commit;
the fragment file is removed rather than resurrected.

Emitted-Drift-Ack-Growth: complete-milestone.md — #3726: +420 bytes (40186 -> 40606). The archive_milestone step's two `milestone complete` invocations now pass the required --confirm flag (the command refuses to mutate without it — the archive is irreversible), with a note explaining the flag and pointing at --dry-run for previews. Deliberate runtime-loaded workflow text for the new gate, not converter drift.

* fix(#3726): name --confirm in the version-required refusal

The documented arg-discovery path (gsd-tools.cjs top-level usage: invoke
the command without args and the error lists what is required) stopped at
`version required for milestone complete (e.g., v1.0)` — one required
argument short. Discovering --confirm took a second round trip through the
gate. The refusal now reads `… — and --confirm to mutate`, pinned by a test
that also asserts the version-less invocation leaves .planning/ untouched.

* test(#3726): pin the milestone complete docs against a silent regression

The changeset is `type: Fixed`, which the docs-required lint exempts, so
nothing in CI would notice a later edit that reinstated the bare-`--force`
override prose or dropped `--confirm` from the synopsis. Four tests in
tests/milestone.test.cjs now pin: the synopsis line in docs/CLI-TOOLS.md
and its four localized mirrors; the `--confirm` flag row; both
guard-override instructions in docs/CLI-TOOLS.md and docs/COMMANDS.md,
by guard name (a substring match on each instruction's `--force
--confirm` text); and — as an identity ratchet over the
milestone-complete sections — every `--force` sentence or clause that
lacks `--confirm`, so a new bare instruction in its own sentence or
clause fails whatever its wording. Named residual: a bare instruction
spliced into the same clause as a compliant one coalesces with it and
passes the ratchet; the by-name pins are what keep the four known
instructions from losing the pairing that way. The file is registered
in scripts/docs-guard-registry.cjs so the pin runs on the PR that
changes those docs, not only after merge.

---------

Co-authored-by: CI Rebase Check <ci@gsd-redux>
Co-authored-by: Tom Boucher <trekkie@nomorestars.com>
2026-08-29 17:00:45 -04:00

504 lines
19 KiB
Markdown
Raw Blame History

# Referência de Ferramentas CLI do GSD
> Referência para o CLI `gsd-tools` (`gsd-core/bin/gsd-tools.cjs`). Para comandos slash e fluxos de usuário, consulte a [Referência de Comandos](COMMANDS.md). Voltar ao [índice de documentação](README.md).
---
## Visão Geral
`gsd-tools.cjs` centraliza a análise de configuração, resolução de modelos, busca de fases, commits git, verificação de resumos, gerenciamento de estado e operações de templates em comandos, fluxos de trabalho e agentes do GSD.
| | |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Caminho instalado** | `gsd-core/bin/gsd-tools.cjs` |
| **Implementação** | 20 módulos de domínio em `gsd-core/bin/lib/` (o diretório é autoritativo) |
| **Status** | Principal superfície de comandos em tempo de execução para orquestração, fluxos de trabalho e automação. |
**Uso (CJS):**
```bash
node gsd-tools.cjs <command> [args] [--raw] [--cwd <path>]
```
**Flags globais (CJS):**
| Flag | Descrição |
| -------------- | ---------------------------------------------------------------------------- |
| `--raw` | Saída legível por máquina (JSON ou texto simples, sem formatação) |
| `--cwd <path>` | Substitui o diretório de trabalho (para subagentes em sandbox) |
| `--ws <name>` | Contexto de fluxo de trabalho para caminhos `.planning/workstreams/<name>` |
---
## Comandos de Estado
Gerencia `.planning/STATE.md` — a memória viva do projeto.
```bash
# Carrega configuração completa do projeto + estado como JSON
node gsd-tools.cjs state load
# Exibe o frontmatter do STATE.md como JSON
node gsd-tools.cjs state json
# Atualiza um único campo
node gsd-tools.cjs state update <field> <value>
# Obtém o conteúdo do STATE.md ou uma seção específica
node gsd-tools.cjs state get [section]
# Atualiza múltiplos campos em lote
node gsd-tools.cjs state patch --field1 val1 --field2 val2
# Incrementa o contador de planos
node gsd-tools.cjs state advance-plan
# Registra métricas de execução
node gsd-tools.cjs state record-metric --phase N --plan M --duration Xmin [--tasks N] [--files N]
# Recalcula a barra de progresso
node gsd-tools.cjs state update-progress
# Adiciona uma decisão
node gsd-tools.cjs state add-decision --summary "..." [--phase N] [--rationale "..."]
# Ou a partir de arquivos:
node gsd-tools.cjs state add-decision --summary-file path [--rationale-file path]
# Adiciona/resolve bloqueadores
node gsd-tools.cjs state add-blocker --text "..."
node gsd-tools.cjs state resolve-blocker --text "..."
# Registra continuidade da sessão
node gsd-tools.cjs state record-session --stopped-at "..." [--resume-file path]
# Início de fase — atualiza Status/Última atividade do STATE.md para uma nova fase
node gsd-tools.cjs state begin-phase --phase N --name SLUG --plans COUNT
# Sinalização de bloqueador detectável por agentes (usado por discuss-phase / fluxos de UI)
node gsd-tools.cjs state signal-waiting --type TYPE --question "..." --options "A|B" --phase P
node gsd-tools.cjs state signal-resume
```
### Snapshot de Estado
Análise estruturada do STATE.md completo:
```bash
node gsd-tools.cjs state-snapshot
```
Retorna JSON com: posição atual, fase, plano, status, decisões, bloqueadores, métricas, última atividade.
---
## Comandos de Fase
Gerencia fases — diretórios, numeração e sincronização com o roadmap.
```bash
# Localiza diretório de fase pelo número
node gsd-tools.cjs find-phase <phase>
# Calcula o próximo número de fase decimal para inserções
node gsd-tools.cjs phase next-decimal <phase>
# Adiciona nova fase ao roadmap + cria diretório
node gsd-tools.cjs phase add <description>
# Insere fase decimal após a existente
node gsd-tools.cjs phase insert <after> <description>
# Remove fase, renumera as subsequentes
node gsd-tools.cjs phase remove <phase> [--force]
# Marca a fase como concluída, atualiza estado + roadmap
node gsd-tools.cjs phase complete <phase>
# Indexa planos com ondas e status
node gsd-tools.cjs phase-plan-index <phase>
# Lista fases com filtragem
node gsd-tools.cjs phases list [--type planned|executed|all] [--phase N] [--include-archived]
```
---
## Comandos de Roadmap
Analisa e atualiza o `ROADMAP.md`.
```bash
# Extrai a seção de fase do ROADMAP.md
node gsd-tools.cjs roadmap get-phase <phase>
# Análise completa do roadmap com status em disco
node gsd-tools.cjs roadmap analyze
# Atualiza linha da tabela de progresso a partir do disco
node gsd-tools.cjs roadmap update-plan-progress <N>
```
---
## Comandos de Configuração
Lê e grava em `.planning/config.json`.
```bash
# Inicializa config.json com valores padrão
node gsd-tools.cjs config-ensure-section
# Define um valor de configuração (notação de ponto)
node gsd-tools.cjs config-set <key> <value>
# Obtém um valor de configuração
node gsd-tools.cjs config-get <key>
# Define o perfil de modelo
node gsd-tools.cjs config-set-model-profile <profile>
```
---
## Resolução de Modelos
```bash
# Obtém o modelo para um agente com base no perfil atual
node gsd-tools.cjs resolve-model <agent-name>
# A saída bruta retorna o ID/tier do modelo selecionado.
# A saída JSON também inclui o perfil e, quando o runtime ativo suporta,
# reasoning_effort.
```
Nomes de agentes: `gsd-planner`, `gsd-executor`, `gsd-phase-researcher`, `gsd-project-researcher`, `gsd-research-synthesizer`, `gsd-verifier`, `gsd-plan-checker`, `gsd-integration-checker`, `gsd-roadmapper`, `gsd-debugger`, `gsd-codebase-mapper`, `gsd-nyquist-auditor`
---
## Comandos de Verificação
Valida planos, fases, referências e commits.
```bash
# Verifica arquivo SUMMARY.md
node gsd-tools.cjs verify-summary <path> [--check-count N]
# Verifica estrutura + tarefas do PLAN.md
node gsd-tools.cjs verify plan-structure <file>
# Verifica se todos os planos têm resumos
node gsd-tools.cjs verify phase-completeness <phase>
# Verifica se @-refs + caminhos resolvem
node gsd-tools.cjs verify references <file>
# Verifica hashes de commit em lote
node gsd-tools.cjs verify commits <hash1> [hash2] ...
# Verifica must_haves.artifacts
node gsd-tools.cjs verify artifacts <plan-file>
# Verifica must_haves.key_links
node gsd-tools.cjs verify key-links <plan-file>
```
---
## Comandos de Validação
Verifica a integridade do projeto.
```bash
# Verifica numeração de fases, sincronização disco/roadmap
node gsd-tools.cjs validate consistency
# Verifica integridade de .planning/, com opção de reparo
node gsd-tools.cjs validate health [--repair]
# Verifica utilização da janela de contexto para linha de status / chamadores de hook (v1.40.0)
node gsd-tools.cjs validate context
# Utilização de contexto como superfície JSON tipada (#455)
node gsd-tools.cjs validate context --json
```
`validate context` emite um envelope estruturado com `utilization`, `status`
(`ok` / `warn` / `critical` nos limites de 60% / 70%), e uma
string `suggestion`. Os mesmos dados sustentam `/gsd-health --context`.
Passe `--json` para receber o IR tipado diretamente (útil em scripts e asserções de teste).
---
## Comandos de Template
Seleção e preenchimento de templates.
```bash
# Seleciona o template de resumo com base na granularidade
node gsd-tools.cjs template select <type>
# Preenche o template com variáveis
node gsd-tools.cjs template fill <type> --phase N [--plan M] [--name "..."] [--type execute|tdd] [--wave N] [--fields '{json}']
```
Tipos de template para `fill`: `summary`, `plan`, `verification`
---
## Comandos de Frontmatter
Operações CRUD de frontmatter YAML em qualquer arquivo Markdown.
```bash
# Extrai frontmatter como JSON
node gsd-tools.cjs frontmatter get <file> [--field key]
# Atualiza único campo
node gsd-tools.cjs frontmatter set <file> --field key --value jsonVal
# Mescla JSON no frontmatter
node gsd-tools.cjs frontmatter merge <file> --data '{json}'
# Valida campos obrigatórios
node gsd-tools.cjs frontmatter validate <file> --schema plan|summary|verification
```
---
## Comandos de Scaffold
Cria arquivos e diretórios pré-estruturados.
```bash
# Cria template CONTEXT.md
node gsd-tools.cjs scaffold context --phase N
# Cria template UAT.md
node gsd-tools.cjs scaffold uat --phase N
# Cria template VERIFICATION.md
node gsd-tools.cjs scaffold verification --phase N
# Cria diretório de fase
node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name"
```
---
## Comandos Init (Carregamento de Contexto Composto)
Carrega todo o contexto necessário para um fluxo de trabalho específico em uma única chamada. Retorna JSON com informações do projeto, configuração, estado e dados específicos do fluxo de trabalho. `init onboard [--fast] [--text]` retorna, para `/gsd-onboard`, sinais de brownfield, candidatos a docs de planning, completude do mapa de código, prontidão do mapa fast, roteamento em modo texto, estado parcial de planning e status do resumo de onboarding.
```bash
node gsd-tools.cjs init execute-phase <phase>
node gsd-tools.cjs init plan-phase <phase>
node gsd-tools.cjs init new-project
node gsd-tools.cjs init new-milestone
node gsd-tools.cjs init onboard [--fast] [--text]
node gsd-tools.cjs init quick <description>
node gsd-tools.cjs init resume
node gsd-tools.cjs init verify-work <phase>
node gsd-tools.cjs init phase-op <phase>
node gsd-tools.cjs init todos [area]
node gsd-tools.cjs init milestone-op
node gsd-tools.cjs init map-codebase
node gsd-tools.cjs init progress
# Init com escopo de fluxo de trabalho (flag `--ws`)
node gsd-tools.cjs init execute-phase <phase> --ws <name>
node gsd-tools.cjs init plan-phase <phase> --ws <name>
```
**Tratamento de payloads grandes:** Quando a saída excede ~50KB, o CLI grava em um arquivo temporário e retorna `@file:/tmp/gsd-init-XXXXX.json`. Os fluxos de trabalho verificam o prefixo `@file:` e leem do disco:
```bash
INIT=$(node gsd-tools.cjs init execute-phase "1")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
```
---
## Comandos de Milestone
```bash
# Arquiva milestone
node gsd-tools.cjs milestone complete <version> (--confirm | --dry-run) [--name <name>] [--no-archive-phases] [--force] [--archive-quick]
# Marca requisitos como concluídos
node gsd-tools.cjs requirements mark-complete <ids>
# Aceita: REQ-01,REQ-02 ou REQ-01 REQ-02 ou [REQ-01, REQ-02]
```
---
## Habilidades de Agente
Emite o bloco de habilidades para um tipo de agente específico.
```bash
# Emite bloco XML bruto de habilidades (padrão — seguro para expansão de shell)
node gsd-tools.cjs agent-skills <agent-type>
# Emite superfície JSON tipada (#455) — { agent_type, block, skills_count }
node gsd-tools.cjs agent-skills <agent-type> --json
```
A flag `--json` retorna um objeto IR tipado adequado para consumo estruturado e asserções de teste, enquanto o padrão (sem flag) preserva a saída XML bruta que as expansões de shell de fluxo de trabalho necessitam.
---
## Manifesto de Habilidades
Pré-computa e armazena em cache a descoberta de habilidades para carregamento mais rápido de comandos.
```bash
# Gera manifesto de habilidades (grava em .claude/skill-manifest.json)
node gsd-tools.cjs skill-manifest
# Gera com caminho de saída personalizado
node gsd-tools.cjs skill-manifest --output <path>
```
Retorna mapeamento JSON de todas as habilidades GSD disponíveis com seus metadados (nome, descrição, caminho de arquivo, dicas de argumentos). Usado pelo instalador e hooks de início de sessão para evitar varreduras repetidas do sistema de arquivos.
---
## Comandos Utilitários
```bash
# Converte texto em slug seguro para URL
node gsd-tools.cjs generate-slug "Some Text Here"
# → some-text-here
# Obtém timestamp
node gsd-tools.cjs current-timestamp [full|date|filename]
# Conta e lista tarefas pendentes
node gsd-tools.cjs list-todos [area]
# Verifica existência de arquivo/diretório
node gsd-tools.cjs verify-path-exists <path>
# Agrega todos os dados de SUMMARY.md
node gsd-tools.cjs history-digest
# Extrai dados estruturados de SUMMARY.md
node gsd-tools.cjs summary-extract <path> [--fields field1,field2]
# Estatísticas do projeto
node gsd-tools.cjs stats [json|table]
# Renderização de progresso (legível por humanos)
node gsd-tools.cjs progress [json|table|bar]
# Progresso como superfície JSON tipada (#455)
node gsd-tools.cjs progress --json
# Conclui uma tarefa
node gsd-tools.cjs todo complete <filename>
# Auditoria UAT — verifica todas as fases em busca de itens não resolvidos
node gsd-tools.cjs audit-uat
# Fila de auditoria entre artefatos — verifica `.planning/` em busca de itens de auditoria não resolvidos
node gsd-tools.cjs audit-open [--json]
# Migração reversa de um projeto GSD-2 para a estrutura atual (suporta `/gsd-import --from-gsd2`)
node gsd-tools.cjs from-gsd2 [--path <dir>] [--force] [--dry-run]
# Commit git com verificações de configuração
node gsd-tools.cjs commit <message> [--files f1 f2] [--amend] [--no-verify] [--respect-staged]
```
> `--no-verify`: Ignora hooks de pré-commit. Usado por agentes executores paralelos durante a execução baseada em ondas para evitar contenção de bloqueio de build (ex.: conflitos de cargo lock em projetos Rust). O orquestrador executa os hooks uma vez após cada onda ser concluída. Não use `--no-verify` durante a execução sequencial — deixe os hooks rodarem normalmente.
> `--files <paths>` **comportamento de staging**: por padrão, `--files` executa `git add -- <path>` para cada arquivo nomeado antes de commitar. Isso sobrescreve qualquer staging por hunk configurado via `git add -p`. Passe `--respect-staged` para ignorar o passo `git add` e commitar apenas o que já está no índice dentro do pathspec solicitado. Se nada estiver staged nesse escopo, o comando retorna `{ committed: false, reason: 'nothing staged' }` sem erro. O `-- <paths>` pathspec final no commit é aplicado em ambos os modos, portanto arquivos staged fora do escopo `--files` nunca são incluídos (invariante #3061).
```bash
# Busca na web (requer chave de API do Brave)
node gsd-tools.cjs websearch <query> [--limit N] [--freshness day|week|month]
```
---
## Graphify
Constrói, consulta e inspeciona o grafo de conhecimento do projeto em `.planning/graphs/`. Requer `graphify.enabled: true` em `config.json` (consulte a [Referência de Configuração](CONFIGURATION.md#graphify-settings)).
```bash
# Constrói ou reconstrói o grafo de conhecimento
node gsd-tools.cjs graphify build
# Pesquisa um termo no grafo
node gsd-tools.cjs graphify query <term>
# Exibe atualidade e estatísticas do grafo
node gsd-tools.cjs graphify status
# Exibe alterações desde a última construção
node gsd-tools.cjs graphify diff
# Grava um snapshot nomeado do grafo atual
node gsd-tools.cjs graphify snapshot [name]
```
Ponto de entrada para o usuário: `/gsd-graphify` (consulte a [Referência de Comandos](COMMANDS.md#gsd-graphify)).
---
## Arquitetura de Módulos
| Módulo | Arquivo | Exportações |
|--------|------|---------|
| Core | `lib/core.cjs` | `error()`, `output()`, `parseArgs()`, utilitários compartilhados, re-exportações de compatibilidade |
| State | `lib/state.cjs` | Todos os subcomandos `state`, `state-snapshot` |
| Phase | `lib/phase.cjs` | CRUD de fase, `find-phase`, `phase-plan-index`, `phases list` |
| Planning Workspace | `lib/planning-workspace.cjs` | Costura de planejamento: `planningDir`, `planningPaths`, roteamento de fluxo de trabalho ativo, `.planning/.lock` |
| Roadmap | `lib/roadmap.cjs` | Análise de roadmap, extração de fase, atualizações de progresso |
| Config | `lib/config.cjs` | Leitura/gravação de configuração, inicialização de seção |
| Verify | `lib/verify.cjs` | Todos os comandos de verificação e validação |
| Template | `lib/template.cjs` | Seleção de template e preenchimento de variáveis |
| Frontmatter | `lib/frontmatter.cjs` | CRUD de frontmatter YAML |
| Init | `lib/init.cjs` | Carregamento de contexto composto para todos os fluxos de trabalho |
| Milestone | `lib/milestone.cjs` | Arquivamento de milestone, marcação de requisitos |
| Commands | `lib/commands.cjs` | Diversos: slug, timestamp, todos, scaffold, stats, websearch |
| Model Profiles | `lib/model-profiles.cjs` | Tabela de resolução de perfis |
| UAT | `lib/uat.cjs` | Auditoria UAT/verificação entre fases |
| Profile Output | `lib/profile-output.cjs` | Formatação de perfil do desenvolvedor |
| Profile Pipeline | `lib/profile-pipeline.cjs` | Pipeline de análise de sessão |
| Graphify | `lib/graphify.cjs` | Construção/consulta/status/diff/snapshot do grafo de conhecimento (suporta `/gsd-graphify`) |
| Learnings | `lib/learnings.cjs` | Extrai aprendizados de artefatos de fases/SUMMARY (suporta `/gsd-extract-learnings`) |
| Audit | `lib/audit.cjs` | Manipuladores de fila de auditoria de fase/milestone; helper `audit-open` |
| GSD2 Import | `lib/gsd2-import.cjs` | Importador de migração reversa de projetos GSD-2 (suporta `/gsd-import --from-gsd2`) |
| Intel | `lib/intel.cjs` | Índice de inteligência de código consultável (suporta `/gsd-map-codebase --query`) |
---
## Roteamento CLI do Revisor
`review.models.<cli>` mapeia um sabor de revisor para um comando shell invocado pelo fluxo de trabalho de revisão de código. Defina via [`/gsd-config --integrations`](COMMANDS.md#gsd-config) ou diretamente:
```bash
node gsd-tools.cjs config-set review.models.codex "codex exec --model gpt-5"
node gsd-tools.cjs config-set review.models.gemini "gemini -m gemini-2.5-pro"
node gsd-tools.cjs config-set review.models.opencode "opencode run --model claude-sonnet-4"
node gsd-tools.cjs config-set review.models.claude "" # limpa — retorna ao modelo da sessão
```
Os slugs são validados contra `[a-zA-Z0-9_-]+`; slugs vazios ou contendo caminhos são rejeitados. Consulte [`docs/CONFIGURATION.md`](CONFIGURATION.md#code-review-cli-routing) para a referência completa do campo.
## Tratamento de Segredos
As chaves de API configuradas via `/gsd-settings` (`brave_search`, `firecrawl`, `exa_search`) são gravadas em texto simples em `.planning/config.json`, mas são mascaradas (`****<last-4>`) em toda saída de `config-set` / `config-get`, tabela de confirmação e prompt interativo. Consulte `gsd-core/bin/lib/secrets.cjs` para a implementação do mascaramento. O próprio arquivo `config.json` é o limite de segurança — proteja-o com permissões do sistema de arquivos e mantenha-o fora do git (`.planning/` está no gitignore por padrão).
---
## Relacionados
- [Comandos](COMMANDS.md)
- [Configuração](CONFIGURATION.md)
- [Arquitetura](ARCHITECTURE.md)
- [índice de documentação](README.md)
Reference in New Issue View Git Blame Copy Permalink