472f585f7c
* 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>
Documentação do GSD Core
A documentação está organizada em quatro quadrantes: tutoriais ajudam você a aprender na prática, guias de instruções resolvem tarefas específicas, referência apresenta fatos autorizados, e explicação explora conceitos e decisões de design.
Versões por idioma: English · Português (pt-BR) · 日本語 · 简体中文
Tutorials
- Seu primeiro projeto — da instalação à primeira fase entregue, um caminho garantido
- Integrando uma base de código existente — leve o GSD Core a um repositório já existente
How-to guides
- Instalar no seu ambiente de execução — passos de instalação específicos para cada um dos 15 ambientes de execução suportados
- Discutir uma fase — registrar decisões de implementação antes do início do planejamento
- Planejar uma fase — executar pesquisa, decompor o trabalho e verificar a qualidade do plano
- Executar uma fase — rodar planos em ondas paralelas com subagentes com contexto renovado
- Verificar e entregar — revisar o trabalho concluído, diagnosticar falhas e criar o PR
- Rodar fases de forma autônoma — usar o modo autônomo para execução de fases sem supervisão
- Lidar com tarefas rápidas e ágeis — usar
/gsd-quicke/gsd-fastpara trabalho avulso fora do ciclo de fases - Configurar perfis de modelo — alternar entre níveis de modelo: qualidade, equilibrado e econômico
- Configurar revisão entre IAs — configurar uma segunda IA para revisar o código produzido pelo agente principal
- Trabalhar em paralelo com workstreams — executar linhas de trabalho independentes simultaneamente usando workstreams
- Isolar trabalho com workspaces — usar workspaces para isolar mudanças experimentais ou arriscadas
- Depurar uma execução com falha — diagnosticar e recuperar de execuções de fase quebradas ou incompletas
- Explorar e esboçar — usar
/gsd-spikee/gsd-sketchpara trabalho exploratório antes de comprometer com um plano - Projetar uma fase de UI — usar o ciclo de fase de UI para trabalho de frontend e visual
- Conduzir o GSD a partir de uma issue do rastreador — iniciar uma fase a partir de uma issue do GitHub, Linear ou Jira
- Migrar do GSD 2 — atualizar um projeto GSD 2 existente para o GSD Core
- Atualizar o GSD — executar novamente o instalador para obter a versão mais recente
- Recuperar e solucionar problemas — corrigir problemas comuns, reconstruir contexto e desinstalar
Referência
- Comandos — todos os comandos com flags e exemplos
- Configuração — schema completo de configuração, perfis de modelo, estratégias de branching git
- Ferramentas CLI — API programática
gsd-tools.cjspara workflows e agentes - Funcionalidades — índice completo de funcionalidades
- Inventário — skills instaladas e mapa de superfície
- Schema do STATE.md — referência campo a campo para
.planning/STATE.md - Schema do CONTEXT.md — referência campo a campo para
.planning/phases/<N>/CONTEXT.md - Schema do PLAN.md — referência campo a campo para
.planning/phases/<N>/PLAN.md - Artefatos de planejamento — todos os arquivos
.planning/e seus papéis
Explicação
- Engenharia de contexto — como a degradação de contexto se forma e como o GSD Core a previne
- O ciclo de fase — racional de design para o ciclo Discuss → Plan → Execute → Verify → Ship
- Orquestração multi-agente — como os subagentes são criados, delimitados e coordenados
- Modelo de segurança — limites de confiança, permissões e automação segura
- Arquitetura — arquitetura do sistema, modelo de agentes e fluxo de dados
- Modos de discussão — modo de suposições vs. modo de entrevista para
/gsd-discuss-phase - Monitoramento de contexto — arquitetura do hook de monitoramento da janela de contexto
- Orquestração orientada por issues — receita para conduzir o GSD a partir de uma issue do rastreador usando primitivos existentes
Relacionados
- README raiz — página inicial, início rápido e visão geral da documentação
- Changelog — histórico de versões