From ffd5370464374a5b3ffe2be526ca10d1b9280598 Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Tue, 4 Aug 2026 13:23:44 -0400 Subject: [PATCH] fix(#2903): use the command form that actually works in reader-facing docs (#3047) * fix(#2903): use the command form that actually works in reader-facing docs Docs told readers to type the colon form, which no runtime registers -- 18 of 19 runtimes use slash-hyphen and the 19th uses shell-var -- so anyone copying an example got an unrecognized command. Swept 178 occurrences across 53 files, locale mirrors included so they do not re-diverge from English. The colon form is a source-authoring token, not a user-facing one: install-time converters key on it to produce the hyphen form runtimes actually register. So the sweep is scoped, and three things are deliberately left alone: - ADRs, which are a historical record; editing their prose falsifies what was written at the time. - The legacy release-notes archive, pending a maintainer decision on whether it follows the same historical carve-out. Excluding it keeps a later reversal additive rather than a revert. - Source artifacts under commands, workflows and agents, where the colon form is load-bearing. Rewriting those would break the installed-skill guarantee across every runtime -- the single largest hazard here. The plugin namespace form is a real, separate token and survives untouched. Adds a lint enforcing exactly that boundary, since the correct form genuinely differs by directory and nothing previously caught the drift. Also fixes a hardcoded colon form in the capability-matrix generator. The sweep alone would have left the generated matrix disagreeing with the template that produces it, so the fix is at the source and the output regenerated. Co-Authored-By: Claude Opus 5 * fix(#2903): stop the sweep misquoting source frontmatter Adversarial review caught three lines where the sweep rewrote a citation of the literal YAML name: key from a source command file. That key genuinely is the colon form -- this change's own carve-out logic says source-authoring tokens keep it -- so the docs ended up misquoting the real files. One of the three is an acceptance-checklist assertion, which the sweep turned into a false statement. Restored the three citations to match their sources verbatim, surgically: where a line carried both a name: citation and a real reader-facing slash command, only the citation reverted and the command stayed corrected. The guard needed the same distinction, or it would have flagged the restoration and reddened the build: a gsd: token preceded by name: is a citation of a source token and is now permitted. The exemption is deliberately narrow -- a bare gsd: anywhere else still fails -- with a test pinning that narrowness. Also makes the detection case-insensitive. Review found /GSD:next slipped through silently; no such casing exists in the tree today, so this closes a latent gap rather than fixing a live one. Swept the whole tree for further corrupted citations: none beyond the three. Co-Authored-By: Claude Opus 5 * fix(#2903): retire the stale-next invariant and sweep next like every other command Maintainer decision on a genuine conflict between two contracts. Invariant #3054 banned the literal /gsd-next from user-facing docs because it named a retired workflow-advance command. But commands/gsd/next.md is a live command -- the state-aware smart-entry launcher -- and this issue requires docs to use the hyphen form every runtime actually registers. Both could not hold for this one command, so docs had been sidestepping the ban by keeping the colon form, which is exactly the defect this issue exists to remove. FEATURES.md already recorded the reassignment: the hyphen form "is not the retired workflow-advance command; it is reserved for the state-aware smart-entry launcher. Workflow advancement remains under /gsd-progress --next." With that reassignment the invariant's premise is obsolete and the guard now contradicts the documented command form, so it is retired with a comment recording why rather than deleted silently. next is now swept like every other command, and the earlier exemption added to the new guard is removed so nothing is special-cased. Four citations of the literal name: frontmatter key stay in colon form, because the source file really does carry name: gsd:next and a doc quoting it must reproduce it verbatim. Two of those lines were reworded to say which side is the frontmatter key and which is the slash command, since they previously conflated the two. Verified the retired scan would now genuinely fail against this tree -- the conflict was real and resolved, not dodged. Co-Authored-By: Claude Opus 5 * chore(#2903): backfill changeset pr number Co-Authored-By: Claude Opus 5 --------- Co-authored-by: Claude Opus 5 --- .changeset/noble-zebras-snooze.md | 5 + docs/CLI-TOOLS.md | 4 +- docs/COMMANDS.md | 12 +- docs/CONFIGURATION.md | 12 +- docs/FEATURES.md | 16 +- docs/INVENTORY.md | 6 +- docs/README.md | 4 +- docs/USER-GUIDE.md | 4 +- docs/cleanup-get-shit-done-cc.md | 4 +- docs/explanation/capability-overlay-model.md | 4 +- docs/explanation/capability-trust-model.md | 2 +- .../embeddable-orchestration-system.md | 2 +- docs/how-to/async-external-jobs.md | 4 +- docs/how-to/install-minimal-and-add-skills.md | 14 +- docs/how-to/run-phases-autonomously.md | 4 +- docs/how-to/turn-a-capability-off.md | 10 +- .../1192-adr-test-audit-2026-06-13.md | 2 +- docs/ja-JP/FEATURES.md | 2 +- docs/ja-JP/INVENTORY.md | 4 +- docs/ja-JP/USER-GUIDE.md | 4 +- docs/ja-JP/how-to/install-on-your-runtime.md | 4 +- docs/ja-JP/reference/context-md.md | 4 +- docs/ja-JP/reference/plan-md.md | 2 +- docs/ko-KR/INVENTORY.md | 4 +- docs/ko-KR/USER-GUIDE.md | 4 +- docs/ko-KR/how-to/install-on-your-runtime.md | 4 +- docs/ko-KR/reference/context-md.md | 4 +- docs/ko-KR/reference/plan-md.md | 2 +- .../proposals/mempalace-capability-prd-adr.md | 6 +- docs/pt-BR/CONFIGURATION.md | 6 +- docs/pt-BR/INVENTORY.md | 4 +- docs/pt-BR/USER-GUIDE.md | 4 +- docs/pt-BR/how-to/install-on-your-runtime.md | 4 +- docs/pt-BR/reference/context-md.md | 4 +- docs/pt-BR/reference/plan-md.md | 2 +- docs/reference/capability-manifest.md | 4 +- docs/reference/capability-matrix.md | 2 +- docs/reference/context-md.md | 4 +- docs/reference/plan-md.md | 4 +- docs/reference/planning-artifacts.md | 4 +- .../review-verification-capabilities.md | 6 +- .../2026-05-12-skill-surface-budget.md | 24 +- .../2026-06-27-gsd-smart-entry-design.md | 34 +-- docs/tutorials/build-your-first-capability.md | 2 +- docs/tutorials/embed-gsd-in-a-new-host.md | 2 +- docs/whats-new-1.7.0.md | 4 +- docs/zh-CN/CONFIGURATION.md | 6 +- docs/zh-CN/FEATURES.md | 2 +- docs/zh-CN/INVENTORY.md | 4 +- docs/zh-CN/USER-GUIDE.md | 4 +- docs/zh-CN/how-to/install-on-your-runtime.md | 4 +- docs/zh-CN/reference/context-md.md | 4 +- docs/zh-CN/reference/plan-md.md | 2 +- package.json | 3 +- scripts/gen-capability-matrix.cjs | 2 +- scripts/lint-docs-command-form.cjs | 195 ++++++++++++++++ tests/lint-docs-command-form.test.cjs | 213 ++++++++++++++++++ tests/repo-invariants.test.cjs | 74 ++---- 58 files changed, 582 insertions(+), 198 deletions(-) create mode 100644 .changeset/noble-zebras-snooze.md create mode 100644 scripts/lint-docs-command-form.cjs create mode 100644 tests/lint-docs-command-form.test.cjs diff --git a/.changeset/noble-zebras-snooze.md b/.changeset/noble-zebras-snooze.md new file mode 100644 index 000000000..28ef71226 --- /dev/null +++ b/.changeset/noble-zebras-snooze.md @@ -0,0 +1,5 @@ +--- +type: Fixed +pr: 3047 +--- +**Documentation now shows the command form that actually works** — reader-facing docs instructed users to type `/gsd:`, a form no runtime registers, so copying it produced an unrecognized command. All 178 occurrences across 53 files, including the Japanese, Korean, Portuguese and Chinese mirrors, now use `/gsd-`. A new lint keeps it from drifting back, while leaving the colon form intact where it is load-bearing — source artifacts, where install-time converters key on it — and preserving the genuine `/gsd-core:` plugin namespace. (#2903) diff --git a/docs/CLI-TOOLS.md b/docs/CLI-TOOLS.md index b8b204652..187af5cb7 100644 --- a/docs/CLI-TOOLS.md +++ b/docs/CLI-TOOLS.md @@ -95,7 +95,7 @@ Returns JSON with: current position, phase, plan, status, decisions, blockers, m ### Smart Entry -Read-only situation classifier used by `/gsd:next`. +Read-only situation classifier used by `/gsd-next`. ```bash node gsd-tools.cjs smart-entry # Human summary + recommended route @@ -654,7 +654,7 @@ node gsd-tools.cjs websearch [--limit N] [--freshness day|week|month] ## Update Backup and Restore -The two halves of `/gsd:update`'s user-added-file protection. `detect-custom-files` +The two halves of `/gsd-update`'s user-added-file protection. `detect-custom-files` lists files that exist inside GSD-managed directories but are absent from `gsd-file-manifest.json` — the update workflow copies those into `gsd-user-files-backup/` before the clean-install wipe. `restore-custom-files` diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index 1536f6f39..acf384afc 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -125,7 +125,7 @@ Clarify WHAT a phase delivers through Socratic questioning with quantitative amb **Edge Coverage (Step 5.5):** After the ambiguity gate passes, spec-phase runs an edge-completeness probe over each requirement. It raises only applicable categories from a closed 8-category taxonomy (boundary, adjacency, empty, encoding, ordering, precision, idempotency, concurrency), proposes one concrete candidate edge per category, and records each as `covered` / `dismissed` (reason required) / `backstop` / `unresolved` in a `## Edge Coverage` SPEC section. Unresolved applicable edges soft-gate the spec (Resolve / Write-anyway-flagged / Keep-probing); `covered` and `backstop` edges are later lifted into plan-phase `must_haves`. Under `--auto` the probe **never auto-dismisses** — it auto-covers where a defensible acceptance criterion exists, otherwise auto-backstops. -**Prohibition Coverage (Step 5.6):** After the edge probe, spec-phase runs a prohibition-completeness probe — a two-stage prose pass (adversarial recall → precision classifier) that surfaces the unwritten *must-NOT* constraints (values/safety/ethics) the spec never forbids. Each is resolved to `resolved` (a NEGATIVE acceptance criterion, carrying a `test` or `judgment` verification tier) / `dismissed` (reason required) / `unresolved`, recorded in a `## Prohibitions (must-NOT)` SPEC section. Resolved prohibitions are lifted into plan-phase `must_haves.prohibitions`; judgment-tier items soft-gate at verify time (never silent, never hard-halt) and unwired test-tier items fail closed. Under `--auto` the probe **never auto-dismisses**; canon-bound concerns (OWASP / GDPR / fairness) are referred to `/gsd:secure-phase`. +**Prohibition Coverage (Step 5.6):** After the edge probe, spec-phase runs a prohibition-completeness probe — a two-stage prose pass (adversarial recall → precision classifier) that surfaces the unwritten *must-NOT* constraints (values/safety/ethics) the spec never forbids. Each is resolved to `resolved` (a NEGATIVE acceptance criterion, carrying a `test` or `judgment` verification tier) / `dismissed` (reason required) / `unresolved`, recorded in a `## Prohibitions (must-NOT)` SPEC section. Resolved prohibitions are lifted into plan-phase `must_haves.prohibitions`; judgment-tier items soft-gate at verify time (never silent, never hard-halt) and unwired test-tier items fail closed. Under `--auto` the probe **never auto-dismisses**; canon-bound concerns (OWASP / GDPR / fairness) are referred to `/gsd-secure-phase`. **Prerequisites:** `.planning/ROADMAP.md` exists **Produces:** `{phase}-SPEC.md` (with a `## Edge Coverage` section) @@ -388,9 +388,9 @@ Create PR from completed phase work with auto-generated body. - Key decisions - Optional configured PRD-style sections from `ship.pr_body_sections` -**Ship gates (capability-driven):** `/gsd:ship` runs every active `ship:pre` gate from the capability registry. Two are on by default: +**Ship gates (capability-driven):** `/gsd-ship` runs every active `ship:pre` gate from the capability registry. Two are on by default: -- **Security** (`security` capability): blocks while `SECURITY.md` reports `threats_open > 0`. Resolve via `/gsd:secure-phase {n}`. +- **Security** (`security` capability): blocks while `SECURITY.md` reports `threats_open > 0`. Resolve via `/gsd-secure-phase {n}`. - **Broken-windows ledger** (`broken-windows` capability, issue #1950): when `workflow.windows_enforce=true` is set, blocks while `.planning/WINDOWS.md` reports any `open` entry. The ledger accumulates stubs, TODOs, skipped tests, unrun verifies, and unmet truths across phases. Resolve an entry with `gsd-tools windows fixed ` (defect resolved) or `gsd-tools windows waive ""` (justified deferral — reason is required and recorded). Inspect via `gsd-tools windows status`. Enforcement is **opt-in** (default `workflow.windows_enforce=false`): enable with `gsd config-set workflow.windows_enforce true`; tracking continues regardless. See [Custom PR Body Sections](ship-pr-body-sections.md) for onboarding, examples, and validation rules. @@ -624,7 +624,7 @@ node gsd-tools.cjs phase uat-passed 3 --raw # Machine-readable ## Navigation Commands -### `/gsd:next` +### `/gsd-next` Open the state-aware smart-entry launcher. It reads `.planning/STATE.md`, `ROADMAP.md`, verification artifacts, and git status, classifies the current situation, shows a short menu, then dispatches exactly one existing GSD command. @@ -633,12 +633,12 @@ This is a launcher/router only — it never performs project work directly. Dete **Situations detected:** no project, paused work, blockers, failed verification, first-phase setup, planning, executing, pending verification, idle stranded work, complete milestone, or unknown state. ```bash -/gsd:next # Detect state and route to the best next action +/gsd-next # Detect state and route to the best next action ``` ### `/gsd-progress` -Show status, next steps, and automatically advance to the next logical workflow step. Reads project state and determines the appropriate action. Use `/gsd:next` when you want an interactive smart-entry menu before dispatch; use `/gsd-progress --next` when you want GSD to advance directly. +Show status, next steps, and automatically advance to the next logical workflow step. Reads project state and determines the appropriate action. Use `/gsd-next` when you want an interactive smart-entry menu before dispatch; use `/gsd-progress --next` when you want GSD to advance directly. | Flag | Description | |------|-------------| diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index d28fe97cd..4bf5de961 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -359,7 +359,7 @@ All workflow toggles follow the **absent = enabled** pattern. If a key is missin | `workflow.tdd_mode` | boolean | `false` | Enable TDD pipeline as a first-class execution mode. When `true`, the planner aggressively applies `type: tdd` to eligible tasks (business logic, APIs, validations, algorithms) and the executor enforces RED/GREEN/REFACTOR gate sequence. An end-of-phase collaborative review checkpoint verifies gate compliance. Added in v1.36 | | `workflow.mvp_mode` | boolean | `false` | Persist the MVP-mode flag in config so every phase defaults to MVP framing without requiring `--mvp` on the CLI. Resolved via the precedence chain: `--mvp` CLI flag → ROADMAP.md `**Mode:** mvp` field → this config value → `false`. When `true`, the planner, executor, verifier, and discovery surfaces treat the phase as an MVP vertical slice (UI → API → DB) of one user-visible capability instead of a horizontal layer. | | `workflow.human_verify_mode` | string | `'end-of-phase'` | Controls human verification checkpoints. `'end-of-phase'` (default since #3309) suppresses `checkpoint:human-verify` tasks and embeds checks into `` blocks for end-of-phase review. `'mid-flight'` restores blocking checkpoint tasks. `checkpoint:decision` and `checkpoint:human-action` are unaffected. See [Checkpoints Reference](../gsd-core/references/checkpoints.md#checkpoint_types). | -| `workflow.context_guard_mode` | string | `'warn'` | Context exhaustion guard for `execute-phase`. Before each wave, the orchestrator self-assesses context pressure using the degradation signals defined in `context-budget.md`. `'warn'` (default) emits a warning and recommends `/gsd:pause-work` when POOR tier (70%+) is detected. `'auto'` automatically invokes `/gsd:pause-work` before the next wave. `'off'` disables the guard. Set via: `gsd config-set workflow.context_guard_mode auto`. Added in #1452. | +| `workflow.context_guard_mode` | string | `'warn'` | Context exhaustion guard for `execute-phase`. Before each wave, the orchestrator self-assesses context pressure using the degradation signals defined in `context-budget.md`. `'warn'` (default) emits a warning and recommends `/gsd-pause-work` when POOR tier (70%+) is detected. `'auto'` automatically invokes `/gsd-pause-work` before the next wave. `'off'` disables the guard. Set via: `gsd config-set workflow.context_guard_mode auto`. Added in #1452. | | `workflow.cross_ai_execution` | boolean | `false` | Delegate phase execution to an external AI CLI instead of spawning local executor agents. Useful for leveraging a different model's strengths for specific phases. Added in v1.36 | | `workflow.cross_ai_command` | string | (none) | Shell command template for cross-AI execution. Receives the phase prompt via stdin. Must produce SUMMARY.md-compatible output. Required when `cross_ai_execution` is `true`. Added in v1.36 | | `workflow.cross_ai_timeout` | number | `300` | Timeout in seconds for cross-AI execution commands. Prevents runaway external processes. Added in v1.36 | @@ -376,7 +376,7 @@ All workflow toggles follow the **absent = enabled** pattern. If a key is missin | `workflow.inline_plan_threshold` | number | `3` | Maximum number of tasks in a phase before the planner generates a separate PLAN.md file instead of inlining tasks in the prompt | | `workflow.drift_threshold` | number | `3` | Minimum number of new structural elements (new directories, barrel exports, migrations, route modules) before the codebase-drift gate takes action. The gate runs at two points: `plan:pre` (before `/gsd-plan-phase` plans — **non-blocking, warn-only**, so plans are authored against a fresh STRUCTURE.md) and `execute:wave:post` (after `/gsd-execute-phase` — honors `workflow.drift_action`). See [#2003](https://github.com/open-gsd/gsd-core/issues/2003). Added in v1.39 | | `workflow.drift_action` | string | `warn` | What to do when `workflow.drift_threshold` is exceeded **at `execute:wave:post`** (after `/gsd-execute-phase`). `warn` prints a message suggesting `/gsd-map-codebase --paths …`; `auto-remap` spawns `gsd-codebase-mapper` scoped to the affected paths. The `plan:pre` pre-check is always warn-only regardless of this setting — it never auto-spawns the mapper at plan entry. Added in v1.39 | -| `workflow.plan_drift_precheck` | boolean | `true` | Enable the non-blocking codebase-drift pre-check at `plan:pre`, before `/gsd:plan-phase` spawns the planner. Surfaces a stale STRUCTURE.md (drift over `workflow.drift_threshold`) as a warn-only advisory pointing to `/gsd:map-codebase`; never blocks planning, never spawns the mapper. Separate from the `execute:wave:post` gates so autonomous/CI runs can silence the plan-time advisory while keeping execute-time drift detection on. Added in v1.6.0. See [#1592](https://github.com/open-gsd/gsd-core/issues/1592). | +| `workflow.plan_drift_precheck` | boolean | `true` | Enable the non-blocking codebase-drift pre-check at `plan:pre`, before `/gsd-plan-phase` spawns the planner. Surfaces a stale STRUCTURE.md (drift over `workflow.drift_threshold`) as a warn-only advisory pointing to `/gsd-map-codebase`; never blocks planning, never spawns the mapper. Separate from the `execute:wave:post` gates so autonomous/CI runs can silence the plan-time advisory while keeping execute-time drift detection on. Added in v1.6.0. See [#1592](https://github.com/open-gsd/gsd-core/issues/1592). | | `workflow.build_command` | string | (none) | Shell command to build the project in the post-merge build gate (Step A of step 5.6 in execute-phase). When unset, the gate auto-detects: Xcode (`.xcodeproj` present) → `xcodebuild build`, `Makefile` with `build:` target → `make build`, Justfile → `just build`, `Cargo.toml` → `cargo build`, `go.mod` → `go build ./...`, Python → `python -m py_compile`, `package.json` with `build` script → `npm run build`. Runs with a 5-minute timeout; failure increments `WAVE_FAILURE_COUNT`. Added in v1.39 | | `workflow.test_command` | string | (none) | Shell command to run the project's test suite in the post-merge test gate (Step B of step 5.6 in execute-phase) and the regression gate. When unset, the gate auto-detects: Xcode (`.xcodeproj` present) → `xcodebuild test`, `Makefile` with `test:` target → `make test`, Justfile → `just test`, `package.json` → `npm test`, `Cargo.toml` → `cargo test`, `go.mod` → `go test ./...`, Python → `python -m pytest`. Runs with a 5-minute timeout; failure increments `WAVE_FAILURE_COUNT`. Added in v1.39 | @@ -702,8 +702,8 @@ The `plan_review.*` namespace controls the plan drift guard, which verifies that | Setting | Type | Default | Description | |---------|------|---------|-------------| -| `plan_review.source_grounding` | boolean | `true` | Enable the plan drift guard. When `true` (the default), plan review resolves every symbol reference cited in a PLAN.md against the live source tree. Plans that cite a non-existent function, class, decorator, or CLI flag produce a `needs-acknowledgement` notice before the plan is approved. Disable with `false` to skip symbol verification entirely. Toggle during setup (`/gsd:new-project`) or at any time via `/gsd:settings`. | -| `plan_review.source_grounding_authority` | enum | `grep` | Selects the resolver adapter used to verify symbol existence. Allowed values: `grep` (default — ripgrep/grep search of source files, works in any project without additional tooling), `intel` (query the `.planning/intel/api-map.json` index built by `/gsd:map-codebase`; requires `intel.enabled: true`), `treesitter` (reserved for future tree-sitter adapter), `lsp` (reserved for future LSP adapter), `scip` (reserved for future SCIP/LSIF adapter). Use `intel` when you have run `/gsd:map-codebase` and want the faster, pre-indexed lookup. All other values beyond `grep` and `intel` are reserved and have no effect in the current release. | +| `plan_review.source_grounding` | boolean | `true` | Enable the plan drift guard. When `true` (the default), plan review resolves every symbol reference cited in a PLAN.md against the live source tree. Plans that cite a non-existent function, class, decorator, or CLI flag produce a `needs-acknowledgement` notice before the plan is approved. Disable with `false` to skip symbol verification entirely. Toggle during setup (`/gsd-new-project`) or at any time via `/gsd-settings`. | +| `plan_review.source_grounding_authority` | enum | `grep` | Selects the resolver adapter used to verify symbol existence. Allowed values: `grep` (default — ripgrep/grep search of source files, works in any project without additional tooling), `intel` (query the `.planning/intel/api-map.json` index built by `/gsd-map-codebase`; requires `intel.enabled: true`), `treesitter` (reserved for future tree-sitter adapter), `lsp` (reserved for future LSP adapter), `scip` (reserved for future SCIP/LSIF adapter). Use `intel` when you have run `/gsd-map-codebase` and want the faster, pre-indexed lookup. All other values beyond `grep` and `intel` are reserved and have no effect in the current release. | ### MemPalace Settings @@ -1392,7 +1392,7 @@ Effort resolved from the cascade above reaches a runtime through one of two chan Codex `.toml`. This is fixed at install and changes only on reinstall or sync. **Invocation-time.** When GSD spawns another CLI as a subprocess — the cross-AI reviewers -in `/gsd:review` — the effort is appended to that CLI's own command line. Whether a host +in `/gsd-review` — the effort is appended to that CLI's own command line. Whether a host can receive effort this way is a declared capability (`effortSurface`, ADR-1239), not an assumption: @@ -1602,7 +1602,7 @@ This resolves `gsd-planner` → `gpt-5.6-sol` (xhigh), `gsd-executor` → `gpt-5 > **[#49](https://github.com/open-gsd/gsd-core/issues/49)** — provider-neutral model policy config surface. Resolves before legacy `model_profile_overrides`. -`model_policy` provides a simpler, provider-neutral way to configure model tiers across runtimes. It is the preferred surface for non-Anthropic runtimes where `model_profile_overrides` would require manually knowing the right model IDs. Configure it via `/gsd:settings` → Section 8 (Model Policy). +`model_policy` provides a simpler, provider-neutral way to configure model tiers across runtimes. It is the preferred surface for non-Anthropic runtimes where `model_profile_overrides` would require manually knowing the right model IDs. Configure it via `/gsd-settings` → Section 8 (Model Policy). ### Known provider preset diff --git a/docs/FEATURES.md b/docs/FEATURES.md index cb1998064..23ae9309e 100644 --- a/docs/FEATURES.md +++ b/docs/FEATURES.md @@ -969,7 +969,7 @@ continues. Drift detection cannot fail verification. | `granularity` | enum | `standard` | `coarse`, `standard`, or `fine` | | `model_profile` | enum | `balanced` | `quality`, `balanced`, `budget`, or `inherit` | | `models.` | enum | (none) | Per-phase-type tier override (`planning`, `discuss`, `research`, `execution`, `verification`, `completion`). Values: `opus`, `sonnet`, `haiku`, `inherit`. Coarse phase-level tuning that wins over `model_profile` but loses to per-agent `model_overrides`. See [CONFIGURATION.md](CONFIGURATION.md#per-phase-type-models-models--added-in-v140). Added in v1.40 | -| `granularities.` | enum | (none) | Per-phase-type granularity override (`planning`, `discuss`, `research`, `execution`, `verification`, `completion`). Values: `coarse`, `standard`, `fine`. Mirrors `models.` for granularity. See [CONFIGURATION.md](CONFIGURATION.md#core-settings). Added in v1.43 ([#68](https://github.com/open-gsd/gsd-core/issues/68)). `/gsd:plan-phase --granularity ` overrides all config-based granularity for a single invocation (takes precedence over `granularities.planning`, top-level `granularity`, and `planning.granularity`). ([#703](https://github.com/open-gsd/gsd-core/issues/703)) | +| `granularities.` | enum | (none) | Per-phase-type granularity override (`planning`, `discuss`, `research`, `execution`, `verification`, `completion`). Values: `coarse`, `standard`, `fine`. Mirrors `models.` for granularity. See [CONFIGURATION.md](CONFIGURATION.md#core-settings). Added in v1.43 ([#68](https://github.com/open-gsd/gsd-core/issues/68)). `/gsd-plan-phase --granularity ` overrides all config-based granularity for a single invocation (takes precedence over `granularities.planning`, top-level `granularity`, and `planning.granularity`). ([#703](https://github.com/open-gsd/gsd-core/issues/703)) | | `dynamic_routing.enabled` | boolean | `false` | Master switch for failure-tier escalation. When `true`, agents resolve to `tier_models[default_tier]` and escalate one tier on orchestrator-detected soft failure. Capped by `max_escalations`. See [CONFIGURATION.md](CONFIGURATION.md#dynamic-routing-with-failure-tier-escalation-dynamic_routing--added-in-v140). Added in v1.40 | | `workflow.research` | boolean | `true` | Domain research before planning | | `workflow.plan_check` | boolean | `true` | Plan verification loop | @@ -2687,7 +2687,7 @@ Users who run a memory / knowledge-base MCP server (for example, ExoCortex-style - `/gsd-config` — folds settings-advanced (`--advanced`), settings-integrations (`--integrations`), set-profile (`--profile`) - `/gsd-workspace` — folds new-workspace (`--new`), list-workspaces (`--list`), remove-workspace (`--remove`) - REQ-CONSOLIDATE-02: Six existing parents absorb wrap-up / sub-operations as flags: `/gsd-update --sync`, `/gsd-update --reapply`, `/gsd-sketch --wrap-up`, `/gsd-spike --wrap-up`, `/gsd-map-codebase --fast`, `/gsd-map-codebase --query`, `/gsd-code-review --fix`, `/gsd-progress --do`, `/gsd-progress --next`. -- REQ-CONSOLIDATE-03: `/gsd:next` is not the retired workflow-advance command; it is reserved for the state-aware smart-entry launcher. Workflow advancement remains under `/gsd-progress --next`. +- REQ-CONSOLIDATE-03: `/gsd-next` is not the retired workflow-advance command; it is reserved for the state-aware smart-entry launcher. Workflow advancement remains under `/gsd-progress --next`. - REQ-CONSOLIDATE-04: Deleted micro-skill slash forms (the bare `gsd-add-todo`, `gsd-add-backlog`, `gsd-plant-seed`, `gsd-check-todos`, `gsd-add-phase`, `gsd-insert-phase`, `gsd-remove-phase`, `gsd-edit-phase`, `gsd-new-workspace`, `gsd-list-workspaces`, `gsd-remove-workspace`, `gsd-settings-advanced`, `gsd-settings-integrations`, `gsd-set-profile`, `gsd-sketch-wrap-up`, `gsd-spike-wrap-up`, `gsd-reapply-patches`, `gsd-code-review-fix`, …) MUST resolve to "Unknown command" — no shadow stubs. - REQ-CONSOLIDATE-05: `autonomous.md` invokes `/gsd-code-review --fix` (was previously calling the deleted `gsd-code-review-fix`). @@ -2918,7 +2918,7 @@ Source commit: abc1234 (3 commits behind HEAD) | `standard` | Core plus common phase-management commands | | `full` | Complete surface; default | -**Runtime control:** `/gsd:surface` lists profile state and enables, disables, or resets skill clusters without reinstalling. +**Runtime control:** `/gsd-surface` lists profile state and enables, disables, or resets skill clusters without reinstalling. **Requirements:** - REQ-SURFACE-01: Installer MUST resolve `--profile=` and persist the active profile in `.gsd-profile`. @@ -3218,7 +3218,7 @@ Each surfaced prohibition is resolved to exactly one of three states: | `dismissed` | Not a genuine prohibition (requires a non-empty reason) | Recorded with its reason; empty dismissals are rejected | | `unresolved` | Deferred | Soft-gates the spec; surfaced as a planner assumption | -Each resolved prohibition carries a `verification` tier — `test` (a negative test can enforce it) or `judgment` (only human/LLM judgment can). At verify time, judgment-tier prohibitions route to a never-silent / never-hard-halt soft gate (autonomous emits an `unverified-prohibition — human review recommended` flag); test-tier prohibitions are enforced via the deterministic `check prohibition-enforcement` gate — green when the wired negative test / lint rule passes, hard-gate (flagged, non-green) when missing or failing, in both interactive and autonomous modes (#1259, ADR-550 D5d). Under `--auto`, the probe **never auto-dismisses**. Canon-bound concerns (OWASP / GDPR / fairness) are referred to `/gsd:secure-phase` rather than minting SPEC prohibitions (ADR-550 D6). +Each resolved prohibition carries a `verification` tier — `test` (a negative test can enforce it) or `judgment` (only human/LLM judgment can). At verify time, judgment-tier prohibitions route to a never-silent / never-hard-halt soft gate (autonomous emits an `unverified-prohibition — human review recommended` flag); test-tier prohibitions are enforced via the deterministic `check prohibition-enforcement` gate — green when the wired negative test / lint rule passes, hard-gate (flagged, non-green) when missing or failing, in both interactive and autonomous modes (#1259, ADR-550 D5d). Under `--auto`, the probe **never auto-dismisses**. Canon-bound concerns (OWASP / GDPR / fairness) are referred to `/gsd-secure-phase` rather than minting SPEC prohibitions (ADR-550 D6). The load-bearing wire is the `plan-phase` lift into `must_haves.prohibitions`, so the section is not merely documentation. @@ -3255,7 +3255,7 @@ The load-bearing wire is the `plan-phase` lift into `must_haves.prohibitions`, s **Reference:** [`gsd capability` command reference](reference/gsd-capability-command.md) · [ADR-1244](adr/1244-capability-ecosystem.md) ### 148. Smart Entry Launcher -**Command:** `/gsd:next` +**Command:** `/gsd-next` **Tool:** `gsd-tools smart-entry [--json]` @@ -3282,7 +3282,7 @@ The load-bearing wire is the `plan-phase` lift into `must_haves.prohibitions`, s **Purpose:** Express every host integration against one public, versioned contract (ADR-1239 Phase A, #1690) instead of bespoke per-host wiring, so onboarding a new host becomes additive descriptor work. -**Behavior:** The interface exposes six interface points (`command`, `dispatch`, `model`, `hooks`, `state`, `artifact`), eight negotiated axes, and a `PROTOCOL_VERSION` handshake that negotiates down to `min(host, engine)`. In 1.7.0, 14 runtimes were migrated onto the interface via imperative adapters (OpenCode #2087, Cursor #2089, Cline #2090, Hermes #2091, Qwen #2092, Kilo #2093, Trae #2094, Kimi #2095, Antigravity #2096, Augment #2097), a declarative adapter (Codex #2088), plus full lifecycle-hook wiring for CodeBuddy (#2098), GitHub Copilot (#2099), and Windsurf (#2100). Descriptors gained an `extensionEvents` vocabulary (#1946), and `/gsd:surface` now reproduces a runtime's agent output byte-for-byte from the installer's descriptors (#1575). +**Behavior:** The interface exposes six interface points (`command`, `dispatch`, `model`, `hooks`, `state`, `artifact`), eight negotiated axes, and a `PROTOCOL_VERSION` handshake that negotiates down to `min(host, engine)`. In 1.7.0, 14 runtimes were migrated onto the interface via imperative adapters (OpenCode #2087, Cursor #2089, Cline #2090, Hermes #2091, Qwen #2092, Kilo #2093, Trae #2094, Kimi #2095, Antigravity #2096, Augment #2097), a declarative adapter (Codex #2088), plus full lifecycle-hook wiring for CodeBuddy (#2098), GitHub Copilot (#2099), and Windsurf (#2100). Descriptors gained an `extensionEvents` vocabulary (#1946), and `/gsd-surface` now reproduces a runtime's agent output byte-for-byte from the installer's descriptors (#1575). **New runtimes:** ZCode (Z.ai — Agentic Development Environment for GLM-5.2, #1925), pi (`npx @opengsd/gsd-core --pi`, #2102), and a repo-local VS Code extension driven through the adapter (#2103). The retired Gemini CLI now redirects to Antigravity CLI, its official successor (#1928). @@ -3348,7 +3348,7 @@ The load-bearing wire is the `plan-phase` lift into `must_haves.prohibitions`, s ### 156. API-Coverage Gate -**Command:** `/gsd:verify-work` +**Command:** `/gsd-verify-work` **Purpose:** A phase that integrates an external API, SDK, or service can no longer seal verification without a decided coverage matrix (#1562). @@ -3362,7 +3362,7 @@ The load-bearing wire is the `plan-phase` lift into `must_haves.prohibitions`, s ### 158. Broken-Windows Ledger -**Behavior:** A cross-phase defect register at `.planning/WINDOWS.md` accumulates stubs, TODOs, skipped tests, unrun verifies, and unmet truths (#1950). `/gsd:ship` blocks while any entry is `open`; an entry can be `waived` only with a recorded reason (auditable) or marked `fixed` (removed from the blocking set). `/gsd:progress` surfaces the open + waived counts. +**Behavior:** A cross-phase defect register at `.planning/WINDOWS.md` accumulates stubs, TODOs, skipped tests, unrun verifies, and unmet truths (#1950). `/gsd-ship` blocks while any entry is `open`; an entry can be `waived` only with a recorded reason (auditable) or marked `fixed` (removed from the blocking set). `/gsd-progress` surfaces the open + waived counts. **Commands:** `gsd-tools windows status | append | waive | fixed`. diff --git a/docs/INVENTORY.md b/docs/INVENTORY.md index a9354dec5..061b501cf 100644 --- a/docs/INVENTORY.md +++ b/docs/INVENTORY.md @@ -124,7 +124,7 @@ These six routers are descriptor-only entries that the model picks first; the bo | Command | Role | Source | |---------|------|--------| -| `/gsd:next` | State-aware smart-entry launcher — reads project state, shows a contextual menu, and dispatches one existing GSD command. | [commands/gsd/next.md](../commands/gsd/next.md) | +| `/gsd-next` | State-aware smart-entry launcher — reads project state, shows a contextual menu, and dispatches one existing GSD command. | [commands/gsd/next.md](../commands/gsd/next.md) | | `/gsd-progress` | Check project progress, show context, and route to next action; use `--next` to advance automatically or `--do` to run a freeform task. | [commands/gsd/progress.md](../commands/gsd/progress.md) | | `/gsd-capture` | Capture ideas, tasks, notes, and seeds — todo (default), `--note`, `--backlog`, `--seed`, or `--list` pending todos. | [commands/gsd/capture.md](../commands/gsd/capture.md) | | `/gsd-stats` | Display project statistics — phases, plans, requirements, git metrics, timeline. | [commands/gsd/stats.md](../commands/gsd/stats.md) | @@ -435,7 +435,7 @@ Full listing: `gsd-core/bin/lib/*.cjs`. | `cjs-command-router-adapter.cjs` | Shared compatibility adapter for manifest-backed CJS command-family routers | | `clock.cjs` | Injectable clock seam (now/sleep) for deterministic lock testing | | `clusters.cjs` | Skill cluster definitions for the runtime surface module (ADR-0011 Phase 2) | -| `code-review-flags.cjs` | Typed flag parser for `/gsd:code-review`; exports `parseCodeReviewFlags(argv)` (→ `{ fix, all, auto, depth, files }`) and `resolveCodeReviewWorkflow(flags)` (→ `'code-review.md' \| 'code-review-fix.md'`); canonical dispatch seam for `--fix`/`--all`/`--auto` routing | +| `code-review-flags.cjs` | Typed flag parser for `/gsd-code-review`; exports `parseCodeReviewFlags(argv)` (→ `{ fix, all, auto, depth, files }`) and `resolveCodeReviewWorkflow(flags)` (→ `'code-review.md' \| 'code-review-fix.md'`); canonical dispatch seam for `--fix`/`--all`/`--auto` routing | | `command-aliases.cjs` | Alias/subcommand metadata for manifest-backed family routers | | `commonjs-marker.cjs` | Ownership-guarded `{"type":"commonjs"}` marker used to pin GSD's staged `.js` scripts to CommonJS; exports `classifyMarker` (absent/gsd-owned/foreign, fail-closed), `ensureCommonJsMarker`, and `removeCommonJsMarker` so install and uninstall share one predicate and never touch a user-authored `package.json` (#2544) | | `command-arg-projection.cjs` | Typed flag and positional argument projection helpers shared across command-family routers | @@ -546,7 +546,7 @@ Full listing: `gsd-core/bin/lib/*.cjs`. | `uat-predicate.cjs` | UAT-passed predicate — markdown-aware evaluation of HUMAN-UAT results; returns pass only when all required checks pass; ignores false-positive contexts (frontmatter, fenced code, blockquotes, HTML comments) | | `ui-consideration-probe.cjs` | Spec-completeness UI-consideration probe (compiled from `src/ui-consideration-probe.cts`, gitignored) — the third adapter of the `probe-core` resolution model (ADR-550 Decision 7): element-kind classification, applicable-category relevance filter, consideration proposal, `proposeElements`/`autoResolve` (propose-then-confirm + the `--auto` never-dismiss floor), and the `{explicit, backstop}` validators; delegates merge/rollup/CLI to `probe-core`; exports `classifyElement`, `applicableCategories`, `proposeConsiderations`, `proposeElements`, `autoResolve`, `analyzeCoverage`, `UI_TAXONOMY` (#1867) | | `ui-safety-gate.cjs` | Shell-free word-boundary UI token detector (#3706, #3718); reads phase-section text from stdin, exits 0 (UI found) or 1 (no UI); also deployed to `gsd-core/bin/lib/` so the GSD installer ships it to `$RUNTIME_DIR` (#448) | -| `update-context.cjs` | Pure install-context resolver for `/gsd:update` — runtime/scope/config-dir/version detection (LOCAL/GLOBAL/UNKNOWN) ported from update.md bash; backs `gsd-tools update-context` (#498) | +| `update-context.cjs` | Pure install-context resolver for `/gsd-update` — runtime/scope/config-dir/version detection (LOCAL/GLOBAL/UNKNOWN) ported from update.md bash; backs `gsd-tools update-context` (#498) | | `validate-command-router.cjs` | Thin CJS subcommand router adapter for `gsd-tools validate` | | `validate.cjs` | Pure phase variant normalization helpers (`phaseVariants`, `buildRoadmapPhaseVariants`, `buildNotStartedPhaseVariants`) used by `verify.cjs` for W006/W007 checks; no I/O, no async | | `verification-command-router.cjs` | Thin CJS subcommand router adapter for `gsd-tools verification` | diff --git a/docs/README.md b/docs/README.md index 6c4576110..38e008f83 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,7 +18,7 @@ Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md) ## How-to guides - [Install on your runtime](how-to/install-on-your-runtime.md) — runtime-specific install steps for all 16 supported runtimes -- [Install a minimal GSD and add skills later](how-to/install-minimal-and-add-skills.md) — install only the core skills, then grow the surface with profiles and `/gsd:surface` +- [Install a minimal GSD and add skills later](how-to/install-minimal-and-add-skills.md) — install only the core skills, then grow the surface with profiles and `/gsd-surface` - [Attach a plugin-provided skill to a GSD agent](how-to/attach-a-plugin-skill-to-a-gsd-agent.md) — use the `global:plugin:skill` entry form to load Claude Code plugin skills into agent prompts - [Discuss a phase](how-to/discuss-a-phase.md) — capture implementation decisions before planning begins - [Resolve edge-coverage findings](how-to/resolve-edge-coverage-findings.md) — turn the spec phase's surfaced domain-boundary edges into covered, dismissed, or backstopped spec decisions @@ -44,7 +44,7 @@ Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md) - [Drive GSD from a tracker issue](how-to/drive-gsd-from-a-tracker-issue.md) — start a phase from a GitHub, Linear, or Jira issue - [Migrate from GSD 2](how-to/migrate-from-gsd-2.md) — upgrade an existing GSD 2 project to GSD Core - [Update GSD](how-to/update-gsd.md) — re-run the installer to pick up the latest release -- [Clean up get-shit-done-cc](cleanup-get-shit-done-cc.md) — remove leftover old-package artifacts that cause a spurious `⬆ /gsd:update` indicator after migrating to `@opengsd/gsd-core` +- [Clean up get-shit-done-cc](cleanup-get-shit-done-cc.md) — remove leftover old-package artifacts that cause a spurious `⬆ /gsd-update` indicator after migrating to `@opengsd/gsd-core` - [Fix the worktree base-mismatch (exit 42) error](how-to/fix-worktree-base-mismatch.md) — resolve the branch-divergence condition that halts parallel phase execution - [Recover and troubleshoot](how-to/recover-and-troubleshoot.md) — fix common problems, rebuild context, and uninstall diff --git a/docs/USER-GUIDE.md b/docs/USER-GUIDE.md index 8c722d862..f0c87ea1e 100644 --- a/docs/USER-GUIDE.md +++ b/docs/USER-GUIDE.md @@ -562,7 +562,7 @@ claude --dangerously-skip-permissions **Needs-acknowledgement behavior.** When the guard finds a missing symbol, it emits a `needs-acknowledgement` notice in the plan review output rather than hard-blocking. You can acknowledge and proceed (the symbol may be intentionally new) or request a plan revision. The guard does not auto-reject plans — it surfaces signal for human decision. -**Works without intel.** By default the guard uses `grep`/`ripgrep` to search source files — no pre-indexing required. If you have run `/gsd:map-codebase` with `intel.enabled: true`, set `plan_review.source_grounding_authority: intel` to use the faster pre-built `api-map.json` index instead. +**Works without intel.** By default the guard uses `grep`/`ripgrep` to search source files — no pre-indexing required. If you have run `/gsd-map-codebase` with `intel.enabled: true`, set `plan_review.source_grounding_authority: intel` to use the faster pre-built `api-map.json` index instead. ```bash # Enable/disable (default: on) @@ -574,7 +574,7 @@ claude --dangerously-skip-permissions /gsd-settings plan_review.source_grounding_authority intel # pre-indexed api-map.json ``` -Toggle at project setup (`/gsd:new-project` asks during workflow preferences) or any time via `/gsd:settings` (Planning section → Drift Guard). +Toggle at project setup (`/gsd-new-project` asks during workflow preferences) or any time via `/gsd-settings` (Planning section → Drift Guard). ### Quick Bug Fix diff --git a/docs/cleanup-get-shit-done-cc.md b/docs/cleanup-get-shit-done-cc.md index c8a1adb86..e2729ceb2 100644 --- a/docs/cleanup-get-shit-done-cc.md +++ b/docs/cleanup-get-shit-done-cc.md @@ -1,6 +1,6 @@ # Cleaning Up get-shit-done-cc -Use this procedure when you see a persistent `⬆ /gsd:update` indicator in +Use this procedure when you see a persistent `⬆ /gsd-update` indicator in your statusline even though `@opengsd/gsd-core` is already up to date. It removes leftover files from the old `get-shit-done-cc` package that was renamed to `@opengsd/gsd-core` in issue [#607](https://github.com/open-gsd/gsd-core/issues/607). @@ -89,7 +89,7 @@ prefer to clean up by hand: ### 4. Verify -Open a new terminal session (or restart your AI runtime). The `⬆ /gsd:update` +Open a new terminal session (or restart your AI runtime). The `⬆ /gsd-update` indicator should no longer appear in the statusline. You can confirm the installed version with: diff --git a/docs/explanation/capability-overlay-model.md b/docs/explanation/capability-overlay-model.md index b1d95f956..ece08c822 100644 --- a/docs/explanation/capability-overlay-model.md +++ b/docs/explanation/capability-overlay-model.md @@ -67,12 +67,12 @@ before surface and config**, not after them. capability that fails any composition gate — consent included — never enters the registry the rest of GSD reads, so it cannot reach the later stages at all. 3. **Surface** decides which of the *composed* registry's skills are projected into the - host runtime. This is the install-profile and `/gsd:surface` layer — a capability's + host runtime. This is the install-profile and `/gsd-surface` layer — a capability's skills can be on the surface or held back without uninstalling it. It only ever sees capabilities that already cleared composition. 4. **Config activation** decides, per loop hook, whether it fires. A hook's `when` key (a dotted config key) gates it: a `step` or `gate` whose key is falsy does not - run. This is the `gsd capability set --gate =` and `/gsd:settings` + run. This is the `gsd capability set --gate =` and `/gsd-settings` layer — again, only for capabilities that survived composition. This document is about what `loadRegistry` does at the moment of composition — stage 2, diff --git a/docs/explanation/capability-trust-model.md b/docs/explanation/capability-trust-model.md index 7f69249ee..1e17b208f 100644 --- a/docs/explanation/capability-trust-model.md +++ b/docs/explanation/capability-trust-model.md @@ -85,7 +85,7 @@ has a window between install and first use to verify what they consented to. ### The reviewer lane: the one surface that *receives* data Three of the four disclosure classes are about code the capability gets to -**run**. A reviewer lane — one external CLI or model endpoint that `/gsd:review` +**run**. A reviewer lane — one external CLI or model endpoint that `/gsd-review` hands a plan to — is different in kind, and the difference is the reason it is disclosed at all. diff --git a/docs/explanation/embeddable-orchestration-system.md b/docs/explanation/embeddable-orchestration-system.md index a3d9e23dc..202ad9596 100644 --- a/docs/explanation/embeddable-orchestration-system.md +++ b/docs/explanation/embeddable-orchestration-system.md @@ -126,7 +126,7 @@ transport onto the same contract, not a second contract. The clearest evidence that the contract is doing its job: because every host integration is now expressed as data — a descriptor, not bespoke code — -`/gsd:surface` can reproduce a given runtime's generated agent output +`/gsd-surface` can reproduce a given runtime's generated agent output byte-for-byte from the same descriptors the installer itself consumes (#1575). Runtime output can no longer drift from what the installer produces, because there is only one source of truth for it. diff --git a/docs/how-to/async-external-jobs.md b/docs/how-to/async-external-jobs.md index 30deb2b49..847030b7b 100644 --- a/docs/how-to/async-external-jobs.md +++ b/docs/how-to/async-external-jobs.md @@ -29,7 +29,7 @@ node scripts/slurm-adapter.cjs submit \ --plan 3.1 --phase 3 \ --expected Artifacts/jobs/12345/result.h5,Artifacts/jobs/12345/metrics.json \ --verify "python -m verify.py 12345" \ - --resume "/gsd:execute-phase 3" \ + --resume "/gsd-execute-phase 3" \ -- sbatch --parsable --output=Artifacts/jobs/%j/out.log ./train.sh ``` @@ -87,7 +87,7 @@ node scripts/slurm-adapter.cjs show --job 12345 `show` prints the status and lists `submit_command`, `verification_command`, and `resume_command` for explicit confirmation. After you run the verification command yourself and confirm the `expected_artifacts` exist, write `SUMMARY.md` -and close the plan (`/gsd:execute-phase 3` reconciles and lifts the deferral). +and close the plan (`/gsd-execute-phase 3` reconciles and lifts the deferral). ## 5. Handle terminal failure diff --git a/docs/how-to/install-minimal-and-add-skills.md b/docs/how-to/install-minimal-and-add-skills.md index 53a6f772d..8223f6d1e 100644 --- a/docs/how-to/install-minimal-and-add-skills.md +++ b/docs/how-to/install-minimal-and-add-skills.md @@ -67,7 +67,7 @@ npx @opengsd/gsd-core@latest --claude --global --profile=core,audit From inside your runtime, list the current surface, the disabled clusters, and the token cost of each: ```bash -/gsd:surface list +/gsd-surface list ``` The skills are grouped into clusters you can toggle as a unit: @@ -78,25 +78,25 @@ The skills are grouped into clusters you can toggle as a unit: ## Add skills later without reinstalling -If you installed minimal and now need more, you do not have to re-run the installer. `/gsd:surface` changes the live surface and persists the change in a separate `.gsd-surface.json` file, leaving your install-time profile marker untouched. +If you installed minimal and now need more, you do not have to re-run the installer. `/gsd-surface` changes the live surface and persists the change in a separate `.gsd-surface.json` file, leaving your install-time profile marker untouched. To switch to a wider profile in place: ```bash -/gsd:surface profile standard +/gsd-surface profile standard ``` To turn on just one cluster while keeping your base profile: ```bash -/gsd:surface enable audit_review +/gsd-surface enable audit_review ``` To turn a cluster back off, or to discard all your live changes and return to the profile you installed: ```bash -/gsd:surface disable utility -/gsd:surface reset +/gsd-surface disable utility +/gsd-surface reset ``` Surface changes take effect in your next session — restart the runtime to pick them up. @@ -105,7 +105,7 @@ Surface changes take effect in your next session — restart the runtime to pick ## Add skills by reinstalling -`/gsd:surface` is the right tool for occasional, reversible adjustments. If you have decided you want the wider surface permanently, change the install-time profile instead so every future `/gsd-update` keeps it: +`/gsd-surface` is the right tool for occasional, reversible adjustments. If you have decided you want the wider surface permanently, change the install-time profile instead so every future `/gsd-update` keeps it: ```bash # Re-run the installer without --minimal to record `full` as your profile diff --git a/docs/how-to/run-phases-autonomously.md b/docs/how-to/run-phases-autonomously.md index 238ca5487..2a7967383 100644 --- a/docs/how-to/run-phases-autonomously.md +++ b/docs/how-to/run-phases-autonomously.md @@ -164,8 +164,8 @@ GSD skips already-complete phases automatically, so it is safe to re-run from an If a prior run recorded a `Deferred Verification` entry in `STATE.md`, later `/gsd-autonomous` reruns skip that phase instead of re-entering the same deferral prompt. Resume deferred work with the exact command shown in the table: ```bash -/gsd:verify-work 4 # for verification_deferred_human -/gsd:plan-phase 6 --gaps # for verification_deferred_gaps +/gsd-verify-work 4 # for verification_deferred_human +/gsd-plan-phase 6 --gaps # for verification_deferred_gaps ``` --- diff --git a/docs/how-to/turn-a-capability-off.md b/docs/how-to/turn-a-capability-off.md index 7eb17e1c9..14466da98 100644 --- a/docs/how-to/turn-a-capability-off.md +++ b/docs/how-to/turn-a-capability-off.md @@ -11,7 +11,7 @@ GSD resolves one capability state from three places: whether the capability is i > > The rest of this guide covers first-party capabilities. For installed overlays, jump to [Turn off an installed third-party capability](#turn-off-an-installed-third-party-capability). -The reliable, fully general way to change first-party capability state is the `capability` command. The `/gsd:surface` and `/gsd:settings` slash commands are convenient interactive front-ends, but they operate on **skill clusters**, not arbitrary capabilities — so reach for the CLI when you want a precise, scriptable, per-capability switch. +The reliable, fully general way to change first-party capability state is the `capability` command. The `/gsd-surface` and `/gsd-settings` slash commands are convenient interactive front-ends, but they operate on **skill clusters**, not arbitrary capabilities — so reach for the CLI when you want a precise, scriptable, per-capability switch. --- @@ -85,18 +85,18 @@ gsd capability remove my-overlay --scope project # for a project-scoped instal `--scope` defaults to `global`, so pass `--scope project` for a project install. Add `--purge-data` to also delete the overlay's persisted data. If the id is not installed in the chosen scope you get `capability "my-overlay" is not installed in scope`. (Trying to `remove` a first-party id instead reports that it cannot be removed here — use the product uninstaller, `gsd --uninstall`.) -> The `/gsd:surface` clusters described below are derived from the **built-in** capability registry, so they cover first-party skill-owning capabilities. For an installed overlay, `remove` is the off-switch. +> The `/gsd-surface` clusters described below are derived from the **built-in** capability registry, so they cover first-party skill-owning capabilities. For an installed overlay, `remove` is the off-switch. See [Remove a capability](remove-a-capability.md) for the full removal flow and [`gsd capability remove`](../reference/gsd-capability-command.md#remove) for every flag and output field. --- -## The interactive paths (`/gsd:surface` and `/gsd:settings`) +## The interactive paths (`/gsd-surface` and `/gsd-settings`) The slash commands are the interactive equivalents, useful when you are working inside an agent session rather than scripting: -- **`/gsd:surface disable `** toggles a whole skill **cluster** on or off and re-stages the surface. Its argument is validated against the fixed set of cluster names — one of `core_loop`, `audit_review`, `milestone`, `research_ideate`, `workspace_state`, `docs`, `ui`, `ai_eval`, `ns_meta`, `utility` (the command rejects anything else and lists these). A few of these names coincide with first-party skill-owning capability ids (for example `ui`), so `/gsd:surface disable ui` works — but the command does **not** accept an arbitrary capability id, including an installed overlay's id. To switch off a specific capability by id, use the CLI (`gsd capability disable ` for first-party, `gsd capability remove ` for an installed overlay). Reverse a cluster with `/gsd:surface enable `. -- **`/gsd:settings`** is the interactive prompt for GSD's workflow toggles (the `workflow.*` config keys that gate hooks). Use it to turn workflow features on or off conversationally; it writes the same config keys that `gsd capability set … --gate` writes. +- **`/gsd-surface disable `** toggles a whole skill **cluster** on or off and re-stages the surface. Its argument is validated against the fixed set of cluster names — one of `core_loop`, `audit_review`, `milestone`, `research_ideate`, `workspace_state`, `docs`, `ui`, `ai_eval`, `ns_meta`, `utility` (the command rejects anything else and lists these). A few of these names coincide with first-party skill-owning capability ids (for example `ui`), so `/gsd-surface disable ui` works — but the command does **not** accept an arbitrary capability id, including an installed overlay's id. To switch off a specific capability by id, use the CLI (`gsd capability disable ` for first-party, `gsd capability remove ` for an installed overlay). Reverse a cluster with `/gsd-surface enable `. +- **`/gsd-settings`** is the interactive prompt for GSD's workflow toggles (the `workflow.*` config keys that gate hooks). Use it to turn workflow features on or off conversationally; it writes the same config keys that `gsd capability set … --gate` writes. For anything you want to be exact about — a specific capability id, a single named gate, or a step in a script or CI job — prefer the CLI. diff --git a/docs/issueevidence/1192-adr-test-audit-2026-06-13.md b/docs/issueevidence/1192-adr-test-audit-2026-06-13.md index 26ded8e11..229e8b1be 100644 --- a/docs/issueevidence/1192-adr-test-audit-2026-06-13.md +++ b/docs/issueevidence/1192-adr-test-audit-2026-06-13.md @@ -140,7 +140,7 @@ Only entries whose adversarial verification confirmed `finalVerdict === "retire" | File | Location | Why worthless | Confirmed by verification | |---|---|---|---| -| `tests/enh-2790-skill-consolidation.test.cjs` | Lines 127–157 — 4 "has a name: field" spot-checks | Assert only `fm.name.length > 0`; `command-contract.test.cjs` already enforces the stricter `/^gsd[:-]/` prefix on all 67 files. Renaming `gsd:capture`→`capture` (the exact regression) passes these but is caught by command-contract. Cannot go red for the bug class the ADR exists to prevent. | **Yes** — verified `command-contract.test.cjs:44-54` covers these 4 files more strictly; deletion creates no coverage gap. | +| `tests/enh-2790-skill-consolidation.test.cjs` | Lines 127–157 — 4 "has a name: field" spot-checks | Assert only `fm.name.length > 0`; `command-contract.test.cjs` already enforces the stricter `/^gsd[:-]/` prefix on all 67 files. Renaming `gsd-capture`→`capture` (the exact regression) passes these but is caught by command-contract. Cannot go red for the bug class the ADR exists to prevent. | **Yes** — verified `command-contract.test.cjs:44-54` covers these 4 files more strictly; deletion creates no coverage gap. | | `tests/command-routing-hub.test.cjs` | Lines 134–137 — "constructs successfully with only cjsRegistry" | Duplicate of the construction test at 71–75; asserts only `typeof hub.dispatch === 'function'` with no dispatch. `createHub` does zero registry-dependent branching at construction. | **Yes** — verified identical assertion; populated-registry dispatch path covered by the happy-path block at line 142. | | `tests/command-routing-hub.test.cjs` | Lines 515–519 — "ERROR_KINDS.UnknownCommand === result.kind" | The identical assertion appears at 9 other sites (222, 234, 245, 256, 360, 393, 410, 422, 518). Same code path covered at 414–424. No unique setup/edge/field. | **Yes** — verified superset coverage by lines 384–424 + the constant-stability test at 521–526. | | `tests/no-cjs-sdk-handsync-tooling.test.cjs` | All 3 tests (lines 26–53) | Assert absence of `lint-shared-module-handsync.cjs` / allowlist JSON that **never existed on main** (CONTEXT.md:693 confirms). Can only go red if someone manually drops those exact files. No behavioral coverage. | **Yes** — verified the real retired artifacts (`cjs-sdk-bridge.cjs`, `sdk/`) are covered by `bug-190`; these guard ADR-text-only artifacts. | diff --git a/docs/ja-JP/FEATURES.md b/docs/ja-JP/FEATURES.md index 3f4d7dccc..9fefa6d19 100644 --- a/docs/ja-JP/FEATURES.md +++ b/docs/ja-JP/FEATURES.md @@ -2824,7 +2824,7 @@ Source commit: abc1234 (3 commits behind HEAD) | `standard` | コアに加えて一般的なフェーズ管理コマンド | | `full` | 完全なサーフェス；デフォルト | -**ランタイムコントロール:** `/gsd:surface` はプロファイル状態をリストし、再インストールなしにスキルクラスターを有効化、無効化、またはリセットします。 +**ランタイムコントロール:** `/gsd-surface` はプロファイル状態をリストし、再インストールなしにスキルクラスターを有効化、無効化、またはリセットします。 **要件:** - REQ-SURFACE-01: インストーラーは `--profile=` を解決し、アクティブなプロファイルを `.gsd-profile` に永続化しなければならない。 diff --git a/docs/ja-JP/INVENTORY.md b/docs/ja-JP/INVENTORY.md index ca861b5b5..25baa0b37 100644 --- a/docs/ja-JP/INVENTORY.md +++ b/docs/ja-JP/INVENTORY.md @@ -382,7 +382,7 @@ | `cjs-command-router-adapter.cjs` | マニフェストバックの CJS コマンドファミリールーター向けの共有互換アダプター | | `clock.cjs` | 決定論的なロックテスト向けの注入可能なクロックシーム（now/sleep） | | `clusters.cjs` | ランタイムサーフェスモジュール向けのスキルクラスター定義（ADR-0011 フェーズ 2） | -| `code-review-flags.cjs` | `/gsd:code-review` 向けの型付きフラグパーサー。`parseCodeReviewFlags(argv)`（→ `{ fix, all, auto, depth, files }`）と `resolveCodeReviewWorkflow(flags)`（→ `'code-review.md' \| 'code-review-fix.md'`）をエクスポート。`--fix`/`--all`/`--auto` ルーティングの標準ディスパッチシーム | +| `code-review-flags.cjs` | `/gsd-code-review` 向けの型付きフラグパーサー。`parseCodeReviewFlags(argv)`（→ `{ fix, all, auto, depth, files }`）と `resolveCodeReviewWorkflow(flags)`（→ `'code-review.md' \| 'code-review-fix.md'`）をエクスポート。`--fix`/`--all`/`--auto` ルーティングの標準ディスパッチシーム | | `command-aliases.cjs` | マニフェストバックのファミリールーター向けのエイリアス/サブコマンドメタデータ | | `command-arg-projection.cjs` | コマンドファミリールーター間で共有される型付きフラグと位置引数のプロジェクションヘルパー | | `command-routing-hub.cjs` | すべてのコマンドファミリールーターのモード決定（SDK vs CJS）、エラー分類、ノースロー契約を一元化する純粋結果ディスパッチハブ（#3788） | @@ -444,7 +444,7 @@ | `template.cjs` | 変数置換によるテンプレート選択と穴埋め | | `uat.cjs` | UAT ファイル解析、検証負債追跡、audit-uat サポート | | `ui-safety-gate.cjs` | シェルフリーのワード境界 UI トークン検出器（#3706、#3718）。フェーズセクションテキストを標準入力から読み込み、0（UI 発見）または 1（UI なし）で終了。GSD インストーラーが `$RUNTIME_DIR` に配布するために `gsd-core/bin/lib/` にもデプロイ（#448） | -| `update-context.cjs` | `/gsd:update` 向けの純粋なインストールコンテキストリゾルバー — ランタイム/スコープ/設定ディレクトリ/バージョン検出（LOCAL/GLOBAL/UNKNOWN）。update.md bash からポート。`gsd-tools update-context` を支える（#498） | +| `update-context.cjs` | `/gsd-update` 向けの純粋なインストールコンテキストリゾルバー — ランタイム/スコープ/設定ディレクトリ/バージョン検出（LOCAL/GLOBAL/UNKNOWN）。update.md bash からポート。`gsd-tools update-context` を支える（#498） | | `validate-command-router.cjs` | `gsd-tools validate` 向けの薄い CJS サブコマンドルーターアダプター | | `validate.cjs` | 純粋なフェーズバリアント正規化ヘルパー（`phaseVariants`、`buildRoadmapPhaseVariants`、`buildNotStartedPhaseVariants`）。`verify.cjs` の W006/W007 チェックで使用。I/O なし、非同期なし | | `verify-command-router.cjs` | `gsd-tools verify` 向けの薄い CJS サブコマンドルーターアダプター | diff --git a/docs/ja-JP/USER-GUIDE.md b/docs/ja-JP/USER-GUIDE.md index b93cda9f4..b8956005e 100644 --- a/docs/ja-JP/USER-GUIDE.md +++ b/docs/ja-JP/USER-GUIDE.md @@ -494,7 +494,7 @@ claude --dangerously-skip-permissions **needs-acknowledgement の動作。** ガードが欠損シンボルを発見すると、ハードブロックではなく `needs-acknowledgement` 通知をプランレビュー出力に出力します。承認して続行（シンボルが意図的に新規の場合）するか、プランの修正を要求できます。ガードはプランを自動拒否しません — 人間の判断のためのシグナルを提示します。 -**intel なしでも動作。** デフォルトではガードは `grep`/`ripgrep` を使用してソースファイルを検索します — 事前インデックスは不要です。`intel.enabled: true` で `/gsd:map-codebase` を実行済みの場合、`plan_review.source_grounding_authority: intel` を設定すると、より高速な事前構築済みの `api-map.json` インデックスを使用できます。 +**intel なしでも動作。** デフォルトではガードは `grep`/`ripgrep` を使用してソースファイルを検索します — 事前インデックスは不要です。`intel.enabled: true` で `/gsd-map-codebase` を実行済みの場合、`plan_review.source_grounding_authority: intel` を設定すると、より高速な事前構築済みの `api-map.json` インデックスを使用できます。 ```bash # Enable/disable (default: on) @@ -506,7 +506,7 @@ claude --dangerously-skip-permissions /gsd-settings plan_review.source_grounding_authority intel # pre-indexed api-map.json ``` -プロジェクト設定時（`/gsd:new-project` がワークフロー設定中に尋ねます）または `/gsd:settings`（Planning セクション → Drift Guard）経由でいつでも切り替えられます。 +プロジェクト設定時（`/gsd-new-project` がワークフロー設定中に尋ねます）または `/gsd-settings`（Planning セクション → Drift Guard）経由でいつでも切り替えられます。 ### クイックバグ修正 diff --git a/docs/ja-JP/how-to/install-on-your-runtime.md b/docs/ja-JP/how-to/install-on-your-runtime.md index bcd26fc82..5df24860f 100644 --- a/docs/ja-JP/how-to/install-on-your-runtime.md +++ b/docs/ja-JP/how-to/install-on-your-runtime.md @@ -8,7 +8,7 @@ GSD Core（`@opengsd/gsd-core`）を普段使いの AI コーディングラン ## インストーラーが必要な理由 -GSD Core は Claude Code のネイティブ frontmatter 形式でエージェントファイルとコマンドファイルを提供しています。サポートされている各ランタイムは、異なるスキーマ、ディレクトリ構成、コマンド呼び出し構文を要求します。インストーラーは必要な変換を実行します。たとえば OpenCode 向けのツールリストとカラー値の変換、Codex 向けの TOML エージェントエントリの書き込み、Gemini CLI 向けのすべてのコマンド本文をハイフン形式（`/gsd-update`）からコロン形式（`/gsd:update`）への書き換えなどです。 +GSD Core は Claude Code のネイティブ frontmatter 形式でエージェントファイルとコマンドファイルを提供しています。サポートされている各ランタイムは、異なるスキーマ、ディレクトリ構成、コマンド呼び出し構文を要求します。インストーラーは必要な変換を実行します。たとえば OpenCode 向けのツールリストとカラー値の変換、Codex 向けの TOML エージェントエントリの書き込み、Gemini CLI 向けのすべてのコマンド本文をハイフン形式（`/gsd-update`）からコロン形式（`/gsd-update`）への書き換えなどです。 **`agents/` や `commands/` からファイルを直接コピーしないでください。** そうするとこれらの変換がスキップされ、スキーマ検証エラーやコマンドの欠落が発生します。 @@ -50,7 +50,7 @@ CLAUDE_CONFIG_DIR=~/.claude-alt npx @opengsd/gsd-core@latest --claude --global npx @opengsd/gsd-core@latest --gemini --global ``` -スキルは `~/.gemini/` に配置されます。インストーラーはすべてのコマンド本文を Gemini のコロン名前空間（`/gsd:update`、`/gsd:config` など）に書き換えます。インストール後は Gemini CLI を再起動してください。 +スキルは `~/.gemini/` に配置されます。インストーラーはすべてのコマンド本文を Gemini のコロン名前空間（`/gsd-update`、`/gsd-config` など）に書き換えます。インストール後は Gemini CLI を再起動してください。 **インストールディレクトリの上書き:** diff --git a/docs/ja-JP/reference/context-md.md b/docs/ja-JP/reference/context-md.md index 4ae7d116b..bc2fe02e0 100644 --- a/docs/ja-JP/reference/context-md.md +++ b/docs/ja-JP/reference/context-md.md @@ -1,6 +1,6 @@ # CONTEXT.md スキーマリファレンス -フェーズごとの `CONTEXT.md` は、`/gsd:discuss-phase` 中に収集された実装上の意思決定を格納する GSD Core のキャリアファイルです。リサーチエージェントとプランニングエージェントの両方にとって主要な上流インプットです。このページではそのスキーマを説明します。[ドキュメントインデックス](../../README.md) も参照してください。 +フェーズごとの `CONTEXT.md` は、`/gsd-discuss-phase` 中に収集された実装上の意思決定を格納する GSD Core のキャリアファイルです。リサーチエージェントとプランニングエージェントの両方にとって主要な上流インプットです。このページではそのスキーマを説明します。[ドキュメントインデックス](../../README.md) も参照してください。 --- @@ -107,7 +107,7 @@ No external specs — requirements fully captured in decisions above ## SPEC.md との統合 -フェーズをディスカッションする前に `/gsd:spec-phase` が実行された場合、`check_spec` ステップが `*-SPEC.md` ファイルを見つけ `` を有効にします： +フェーズをディスカッションする前に `/gsd-spec-phase` が実行された場合、`check_spec` ステップが `*-SPEC.md` ファイルを見つけ `` を有効にします： ```markdown diff --git a/docs/ja-JP/reference/plan-md.md b/docs/ja-JP/reference/plan-md.md index eac28b4b9..d5f2a55e4 100644 --- a/docs/ja-JP/reference/plan-md.md +++ b/docs/ja-JP/reference/plan-md.md @@ -14,7 +14,7 @@ 例: `.planning/phases/03-post-feed/03-02-PLAN.md`（フェーズ3、プラン2）。 -プランは `gsd-planner` エージェント（`/gsd:plan-phase` によって起動）が生成し、`execute-phase` が使用します。通常、フェーズには1〜4つのプランが含まれます。フェーズ内のプランは実行ウェーブに割り当てられ、独立した作業が並行して実行されます。 +プランは `gsd-planner` エージェント（`/gsd-plan-phase` によって起動）が生成し、`execute-phase` が使用します。通常、フェーズには1〜4つのプランが含まれます。フェーズ内のプランは実行ウェーブに割り当てられ、独立した作業が並行して実行されます。 --- diff --git a/docs/ko-KR/INVENTORY.md b/docs/ko-KR/INVENTORY.md index a0fd8faf5..ef065385d 100644 --- a/docs/ko-KR/INVENTORY.md +++ b/docs/ko-KR/INVENTORY.md @@ -382,7 +382,7 @@ | `cjs-command-router-adapter.cjs` | 매니페스트 기반 CJS 명령어 패밀리 라우터를 위한 공유 호환성 어댑터 | | `clock.cjs` | 결정론적 잠금 테스트를 위한 주입 가능한 클록 심(now/sleep) | | `clusters.cjs` | 런타임 표면 모듈을 위한 스킬 클러스터 정의(ADR-0011 Phase 2) | -| `code-review-flags.cjs` | `/gsd:code-review`를 위한 타입 플래그 파서; `parseCodeReviewFlags(argv)` (→ `{ fix, all, auto, depth, files }`) 및 `resolveCodeReviewWorkflow(flags)` (→ `'code-review.md' \| 'code-review-fix.md'`) 내보내기; `--fix`/`--all`/`--auto` 라우팅을 위한 표준 디스패치 심 | +| `code-review-flags.cjs` | `/gsd-code-review`를 위한 타입 플래그 파서; `parseCodeReviewFlags(argv)` (→ `{ fix, all, auto, depth, files }`) 및 `resolveCodeReviewWorkflow(flags)` (→ `'code-review.md' \| 'code-review-fix.md'`) 내보내기; `--fix`/`--all`/`--auto` 라우팅을 위한 표준 디스패치 심 | | `command-aliases.cjs` | 매니페스트 기반 패밀리 라우터를 위한 별칭/하위 명령어 메타데이터 | | `command-arg-projection.cjs` | 명령어 패밀리 라우터 전반에 공유되는 타입 플래그 및 위치 인수 프로젝션 헬퍼 | | `command-routing-hub.cjs` | 모든 명령어 패밀리 라우터를 위한 모드 결정(SDK vs CJS), 오류 분류, 예외 없음 계약을 집중화하는 순수 결과 디스패치 허브(#3788) | @@ -444,7 +444,7 @@ | `template.cjs` | 변수 치환을 통한 템플릿 선택 및 채우기 | | `uat.cjs` | UAT 파일 파싱, 검증 부채 추적, audit-uat 지원 | | `ui-safety-gate.cjs` | 셸 없는 단어 경계 UI 토큰 감지기(#3706, #3718); stdin에서 단계 섹션 텍스트를 읽어 0(UI 발견) 또는 1(UI 없음) 종료; GSD 설치 프로그램이 `$RUNTIME_DIR`에 배포하도록 `gsd-core/bin/lib/`에도 배포 | -| `update-context.cjs` | `/gsd:update`를 위한 순수 설치 컨텍스트 해석기 — update.md bash에서 포팅된 런타임/범위/설정 디렉터리/버전 감지(LOCAL/GLOBAL/UNKNOWN); `gsd-tools update-context` 지원(#498) | +| `update-context.cjs` | `/gsd-update`를 위한 순수 설치 컨텍스트 해석기 — update.md bash에서 포팅된 런타임/범위/설정 디렉터리/버전 감지(LOCAL/GLOBAL/UNKNOWN); `gsd-tools update-context` 지원(#498) | | `validate-command-router.cjs` | `gsd-tools validate`를 위한 얇은 CJS 하위 명령어 라우터 어댑터 | | `validate.cjs` | 순수 단계 변형 정규화 헬퍼(`phaseVariants`, `buildRoadmapPhaseVariants`, `buildNotStartedPhaseVariants`), W006/W007 확인을 위해 `verify.cjs`에서 사용; I/O 없음, 비동기 없음 | | `verify-command-router.cjs` | `gsd-tools verify`를 위한 얇은 CJS 하위 명령어 라우터 어댑터 | diff --git a/docs/ko-KR/USER-GUIDE.md b/docs/ko-KR/USER-GUIDE.md index 8ded3c927..14a739c31 100644 --- a/docs/ko-KR/USER-GUIDE.md +++ b/docs/ko-KR/USER-GUIDE.md @@ -499,7 +499,7 @@ claude --dangerously-skip-permissions **needs-acknowledgement 동작.** 가드가 누락된 심볼을 발견하면, 하드 차단 대신 계획 검토 출력에 `needs-acknowledgement` 알림을 표시합니다. 승인 후 진행하거나(심볼이 의도적으로 새로운 것일 수 있음) 계획 수정을 요청할 수 있습니다. 가드는 계획을 자동으로 거부하지 않으며 — 사람의 결정을 위한 신호를 표시합니다. -**인텔 없이 작동.** 기본적으로 가드는 `grep`/`ripgrep`을 사용하여 소스 파일을 검색합니다 — 사전 인덱싱이 필요하지 않습니다. `intel.enabled: true`로 `/gsd:map-codebase`를 실행했다면 `plan_review.source_grounding_authority: intel`로 설정하여 더 빠른 사전 빌드 `api-map.json` 인덱스를 사용하세요. +**인텔 없이 작동.** 기본적으로 가드는 `grep`/`ripgrep`을 사용하여 소스 파일을 검색합니다 — 사전 인덱싱이 필요하지 않습니다. `intel.enabled: true`로 `/gsd-map-codebase`를 실행했다면 `plan_review.source_grounding_authority: intel`로 설정하여 더 빠른 사전 빌드 `api-map.json` 인덱스를 사용하세요. ```bash # Enable/disable (default: on) @@ -511,7 +511,7 @@ claude --dangerously-skip-permissions /gsd-settings plan_review.source_grounding_authority intel # pre-indexed api-map.json ``` -프로젝트 설정 시(`/gsd:new-project`가 워크플로우 선호도 중 질문) 또는 `/gsd:settings`를 통해 언제든지 전환 가능합니다(계획 섹션 → 드리프트 가드). +프로젝트 설정 시(`/gsd-new-project`가 워크플로우 선호도 중 질문) 또는 `/gsd-settings`를 통해 언제든지 전환 가능합니다(계획 섹션 → 드리프트 가드). ### 빠른 버그 수정 diff --git a/docs/ko-KR/how-to/install-on-your-runtime.md b/docs/ko-KR/how-to/install-on-your-runtime.md index 435e48c81..f7503a9c6 100644 --- a/docs/ko-KR/how-to/install-on-your-runtime.md +++ b/docs/ko-KR/how-to/install-on-your-runtime.md @@ -8,7 +8,7 @@ GSD Core(`@opengsd/gsd-core`)를 매일 사용하는 AI 코딩 런타임에 설 ## 인스톨러가 필요한 이유 -GSD Core는 Claude Code의 네이티브 frontmatter 형식으로 에이전트 및 명령 파일을 제공합니다. 각 지원 런타임은 서로 다른 스키마, 디렉터리 구조, 명령 호출 문법을 요구합니다. 인스톨러는 필요한 변환을 수행합니다. 예를 들어 OpenCode용 도구 목록 및 색상 값 변환, Codex용 TOML 에이전트 항목 작성, Gemini CLI용 모든 명령 본문을 하이픈 형식(`/gsd-update`)에서 콜론 형식(`/gsd:update`)으로 재작성합니다. +GSD Core는 Claude Code의 네이티브 frontmatter 형식으로 에이전트 및 명령 파일을 제공합니다. 각 지원 런타임은 서로 다른 스키마, 디렉터리 구조, 명령 호출 문법을 요구합니다. 인스톨러는 필요한 변환을 수행합니다. 예를 들어 OpenCode용 도구 목록 및 색상 값 변환, Codex용 TOML 에이전트 항목 작성, Gemini CLI용 모든 명령 본문을 하이픈 형식(`/gsd-update`)에서 콜론 형식(`/gsd-update`)으로 재작성합니다. **`agents/` 또는 `commands/`에서 파일을 직접 복사하지 마세요.** 그렇게 하면 변환을 우회하게 되어 스키마 유효성 검사 오류나 누락된 명령이 발생합니다. @@ -50,7 +50,7 @@ CLAUDE_CONFIG_DIR=~/.claude-alt npx @opengsd/gsd-core@latest --claude --global npx @opengsd/gsd-core@latest --gemini --global ``` -스킬은 `~/.gemini/`에 저장됩니다. 인스톨러는 모든 명령 본문을 Gemini의 콜론 네임스페이스(`/gsd:update`, `/gsd:config` 등)로 재작성합니다. 설치 후 Gemini CLI를 재시작하세요. +스킬은 `~/.gemini/`에 저장됩니다. 인스톨러는 모든 명령 본문을 Gemini의 콜론 네임스페이스(`/gsd-update`, `/gsd-config` 등)로 재작성합니다. 설치 후 Gemini CLI를 재시작하세요. **설치 디렉터리 재정의:** diff --git a/docs/ko-KR/reference/context-md.md b/docs/ko-KR/reference/context-md.md index 9b6a0eb11..098071ca2 100644 --- a/docs/ko-KR/reference/context-md.md +++ b/docs/ko-KR/reference/context-md.md @@ -1,6 +1,6 @@ # CONTEXT.md 스키마 참조 -페이즈별 `CONTEXT.md`는 `/gsd:discuss-phase` 중 캡처된 구현 결정을 담는 GSD Core의 파일입니다. 이 파일은 리서치 에이전트와 플래닝 에이전트 모두를 위한 주요 업스트림 입력입니다. 이 페이지는 해당 파일의 구조를 설명합니다. [문서 인덱스](../../README.md)를 참조하세요. +페이즈별 `CONTEXT.md`는 `/gsd-discuss-phase` 중 캡처된 구현 결정을 담는 GSD Core의 파일입니다. 이 파일은 리서치 에이전트와 플래닝 에이전트 모두를 위한 주요 업스트림 입력입니다. 이 페이지는 해당 파일의 구조를 설명합니다. [문서 인덱스](../../README.md)를 참조하세요. --- @@ -107,7 +107,7 @@ No external specs — requirements fully captured in decisions above ## SPEC.md 통합 -페이즈를 논의하기 전에 `/gsd:spec-phase`가 실행된 경우, `check_spec` 단계에서 `*-SPEC.md` 파일을 찾아 ``을 활성화합니다: +페이즈를 논의하기 전에 `/gsd-spec-phase`가 실행된 경우, `check_spec` 단계에서 `*-SPEC.md` 파일을 찾아 ``을 활성화합니다: ```markdown diff --git a/docs/ko-KR/reference/plan-md.md b/docs/ko-KR/reference/plan-md.md index 1635caa20..617490a91 100644 --- a/docs/ko-KR/reference/plan-md.md +++ b/docs/ko-KR/reference/plan-md.md @@ -14,7 +14,7 @@ 예: `.planning/phases/03-post-feed/03-02-PLAN.md` (Phase 3, Plan 2). -플랜은 `gsd-planner` 에이전트(`/gsd:plan-phase`에 의해 생성됨)가 만들고 `execute-phase`가 소비합니다. 페이즈는 보통 1~4개의 플랜을 포함하며, 페이즈 내의 플랜은 독립적인 작업이 병렬로 실행되도록 실행 웨이브에 할당됩니다. +플랜은 `gsd-planner` 에이전트(`/gsd-plan-phase`에 의해 생성됨)가 만들고 `execute-phase`가 소비합니다. 페이즈는 보통 1~4개의 플랜을 포함하며, 페이즈 내의 플랜은 독립적인 작업이 병렬로 실행되도록 실행 웨이브에 할당됩니다. --- diff --git a/docs/proposals/mempalace-capability-prd-adr.md b/docs/proposals/mempalace-capability-prd-adr.md index 1ff30b7dd..e23809e77 100644 --- a/docs/proposals/mempalace-capability-prd-adr.md +++ b/docs/proposals/mempalace-capability-prd-adr.md @@ -244,7 +244,7 @@ All steps/contributions are `onError: skip`. No gates. | **5 — Passive hooks + autonomous** | `auto_capture_hooks` installs native hooks; CLI-path capture verified headless (`/gsd-autonomous`, cron) | headless run captures with no MCP | | **6 — Loop wiring (shipped via ADR-857)** | the host-loop workflows call `loop render-hooks` at each canonical point, so registered capability hooks auto-fire | with `mempalace.enabled`, a `/gsd-execute-phase` run **auto-produces `MEMORY-RECALL.md` at `plan:pre`**, files capture at `plan:post`/`verify:post` with **no manual invocation**, and the curator spawns at `ship:post` — **verified** (`gsd-tools loop render-hooks plan:pre` returns the `mempalace-recall` step) | -ADR-857 (the capability system + `loop render-hooks` infrastructure) is **released**, so the Phase-6 loop wiring is shipped: the host-loop workflows call `loop render-hooks` at each canonical point, and MemPalace auto-fires through it when `mempalace.enabled`. The skills (`/gsd:mempalace-recall`, `/gsd:mempalace-capture`) are also invocable directly for manual use. +ADR-857 (the capability system + `loop render-hooks` infrastructure) is **released**, so the Phase-6 loop wiring is shipped: the host-loop workflows call `loop render-hooks` at each canonical point, and MemPalace auto-fires through it when `mempalace.enabled`. The skills (`/gsd-mempalace-recall`, `/gsd-mempalace-capture`) are also invocable directly for manual use. ### 15.1 Decision → Phase ownership (traceability) @@ -261,7 +261,7 @@ Every design decision (§10) and user-facing capability is the explicit responsi ### 15.2 Loop wiring status -ADR-857 (the capability system + the `loop render-hooks` resolver + the workflow call sites) is **released**. The host-loop workflows (`plan-phase.md`, `execute-phase.md`, `verify-work.md`, `ship.md`, `discuss-phase.md`) call `loop render-hooks ` at each canonical point, so any registered capability — including `mempalace` — auto-fires when its `when` gate is true. **Verified:** `gsd-tools loop render-hooks plan:pre --raw` with `mempalace.enabled: true` returns the `mempalace-recall` step (`capId: mempalace`, `produces: MEMORY-RECALL.md`), rendered into the workflow markdown. There is therefore **no outstanding cross-doc gating dependency** for UX-auto / UX-curator — the earlier "blocked on ADR-857 *Migrate*" framing (in the original §15 and a prior audit comment) is retracted: that phase shipped. The manual skills (`/gsd:mempalace-recall`, `/gsd:mempalace-capture`) remain available for direct invocation independent of the loop. +ADR-857 (the capability system + the `loop render-hooks` resolver + the workflow call sites) is **released**. The host-loop workflows (`plan-phase.md`, `execute-phase.md`, `verify-work.md`, `ship.md`, `discuss-phase.md`) call `loop render-hooks ` at each canonical point, so any registered capability — including `mempalace` — auto-fires when its `when` gate is true. **Verified:** `gsd-tools loop render-hooks plan:pre --raw` with `mempalace.enabled: true` returns the `mempalace-recall` step (`capId: mempalace`, `produces: MEMORY-RECALL.md`), rendered into the workflow markdown. There is therefore **no outstanding cross-doc gating dependency** for UX-auto / UX-curator — the earlier "blocked on ADR-857 *Migrate*" framing (in the original §15 and a prior audit comment) is retracted: that phase shipped. The manual skills (`/gsd-mempalace-recall`, `/gsd-mempalace-capture`) remain available for direct invocation independent of the loop. ## 16. Registration tax (per ADR-857 + repo checklists) @@ -285,7 +285,7 @@ Each open question is traced to the phase whose acceptance must **resolve** it ( 2. **`replace` migration** _(resolve in **Phase 4**)_ — do we backfill existing `.planning/graphs/` into the palace KG, or only forward-fill? Recommendation: ship a one-shot `mempalace mine .planning/` + KG import as part of mode switch. Owned by the Phase-4 "Modes" gate. 3. **Curator agent tier** _(resolve in **Phase 2**)_ — the curator is operational (branches, API calls, error recovery) ⇒ `sonnet` model. Confirm at Phase-2 agent delivery. 4. **Headless MCP availability** _(resolve in **Phase 5**)_ — verify MemPalace's stdio MCP server *is* reachable under `/gsd-autonomous`/cron, or commit fully to the CLI path there (FR-T1). Owned by the Phase-5 headless gate. -5. **Loop wiring** _(resolved — shipped)_ — ADR-857 is released and the host-loop workflows call `loop render-hooks`, so Phase-6 auto-fire is wired and verified end-to-end (§15.2). The manual skills (`/gsd:mempalace-recall`, `/gsd:mempalace-capture`) remain available for direct use. +5. **Loop wiring** _(resolved — shipped)_ — ADR-857 is released and the host-loop workflows call `loop render-hooks`, so Phase-6 auto-fire is wired and verified end-to-end (§15.2). The manual skills (`/gsd-mempalace-recall`, `/gsd-mempalace-capture`) remain available for direct use. 6. **Diary `agent_name`** _(resolve in **Phase 6**)_ — namespace per GSD role (`gsd-orchestrator`) or per repo? Recommendation: per repo+role so diaries don't collide across projects. Owned by the Phase-6 curator wiring (UX-curator). --- diff --git a/docs/pt-BR/CONFIGURATION.md b/docs/pt-BR/CONFIGURATION.md index 8b742641b..51626fb4e 100644 --- a/docs/pt-BR/CONFIGURATION.md +++ b/docs/pt-BR/CONFIGURATION.md @@ -471,8 +471,8 @@ O namespace `plan_review.*` controla o guardião de deriva de plano, que verific | Configuração | Tipo | Padrão | Descrição | |---------|------|---------|-------------| -| `plan_review.source_grounding` | boolean | `true` | Habilita o guardião de deriva de plano. Quando `true` (padrão), a revisão de plano resolve cada referência de símbolo citada em um PLAN.md em relação à árvore de fontes ativa. Planos que citam uma função, classe, decorador ou flag CLI inexistente produzem um aviso `needs-acknowledgement` antes do plano ser aprovado. Desabilite com `false` para ignorar completamente a verificação de símbolo. Ative durante a configuração (`/gsd:new-project`) ou a qualquer momento via `/gsd:settings`. | -| `plan_review.source_grounding_authority` | enum | `grep` | Seleciona o adaptador de resolução usado para verificar a existência de símbolos. Valores permitidos: `grep` (padrão — busca ripgrep/grep de arquivos de fonte, funciona em qualquer projeto sem ferramental adicional), `intel` (consulta o índice `.planning/intel/api-map.json` construído por `/gsd:map-codebase`; requer `intel.enabled: true`), `treesitter` (reservado para adaptador tree-sitter futuro), `lsp` (reservado para adaptador LSP futuro), `scip` (reservado para adaptador SCIP/LSIF futuro). Use `intel` quando tiver executado `/gsd:map-codebase` e quiser a busca mais rápida e pré-indexada. Todos os outros valores além de `grep` e `intel` são reservados e não têm efeito na versão atual. | +| `plan_review.source_grounding` | boolean | `true` | Habilita o guardião de deriva de plano. Quando `true` (padrão), a revisão de plano resolve cada referência de símbolo citada em um PLAN.md em relação à árvore de fontes ativa. Planos que citam uma função, classe, decorador ou flag CLI inexistente produzem um aviso `needs-acknowledgement` antes do plano ser aprovado. Desabilite com `false` para ignorar completamente a verificação de símbolo. Ative durante a configuração (`/gsd-new-project`) ou a qualquer momento via `/gsd-settings`. | +| `plan_review.source_grounding_authority` | enum | `grep` | Seleciona o adaptador de resolução usado para verificar a existência de símbolos. Valores permitidos: `grep` (padrão — busca ripgrep/grep de arquivos de fonte, funciona em qualquer projeto sem ferramental adicional), `intel` (consulta o índice `.planning/intel/api-map.json` construído por `/gsd-map-codebase`; requer `intel.enabled: true`), `treesitter` (reservado para adaptador tree-sitter futuro), `lsp` (reservado para adaptador LSP futuro), `scip` (reservado para adaptador SCIP/LSIF futuro). Use `intel` quando tiver executado `/gsd-map-codebase` e quiser a busca mais rápida e pré-indexada. Todos os outros valores além de `grep` e `intel` são reservados e não têm efeito na versão atual. | ### Configurações do Graphify @@ -1210,7 +1210,7 @@ Isso resolve `gsd-planner` → `gpt-5.6-sol` (xhigh), `gsd-executor` → `gpt-5. > **[#49](https://github.com/open-gsd/gsd-core/issues/49)** — superfície de configuração de política de modelo neutra em relação ao provedor. Resolve antes do legado `model_profile_overrides`. -`model_policy` fornece uma maneira mais simples e neutra em relação ao provedor de configurar níveis de modelo entre runtimes. É a superfície preferida para runtimes não-Anthropic onde `model_profile_overrides` exigiria conhecer manualmente os IDs de modelo corretos. Configure via `/gsd:settings` → Seção 8 (Model Policy). +`model_policy` fornece uma maneira mais simples e neutra em relação ao provedor de configurar níveis de modelo entre runtimes. É a superfície preferida para runtimes não-Anthropic onde `model_profile_overrides` exigiria conhecer manualmente os IDs de modelo corretos. Configure via `/gsd-settings` → Seção 8 (Model Policy). ### Predefinição de provedor conhecido diff --git a/docs/pt-BR/INVENTORY.md b/docs/pt-BR/INVENTORY.md index 0b06d29f4..693c11351 100644 --- a/docs/pt-BR/INVENTORY.md +++ b/docs/pt-BR/INVENTORY.md @@ -382,7 +382,7 @@ Listagem completa: `gsd-core/bin/lib/*.cjs`. | `cjs-command-router-adapter.cjs` | Adaptador de compatibilidade compartilhado para roteadores de família de comandos CJS com suporte de manifesto | | `clock.cjs` | Costura de relógio injetável (now/sleep) para teste determinístico de bloqueio | | `clusters.cjs` | Definições de cluster de habilidades para o módulo de superfície de runtime (ADR-0011 Fase 2) | -| `code-review-flags.cjs` | Analisador de flags tipado para `/gsd:code-review`; exporta `parseCodeReviewFlags(argv)` (→ `{ fix, all, auto, depth, files }`) e `resolveCodeReviewWorkflow(flags)` (→ `'code-review.md' \| 'code-review-fix.md'`); costura de despacho canônica para roteamento de `--fix`/`--all`/`--auto` | +| `code-review-flags.cjs` | Analisador de flags tipado para `/gsd-code-review`; exporta `parseCodeReviewFlags(argv)` (→ `{ fix, all, auto, depth, files }`) e `resolveCodeReviewWorkflow(flags)` (→ `'code-review.md' \| 'code-review-fix.md'`); costura de despacho canônica para roteamento de `--fix`/`--all`/`--auto` | | `command-aliases.cjs` | Metadados de alias/subcomando para roteadores de família com suporte de manifesto | | `command-arg-projection.cjs` | Auxiliares de projeção de flag tipada e argumento posicional compartilhados entre roteadores de família de comandos | | `command-routing-hub.cjs` | Hub de despacho de resultado puro que centraliza a decisão de modo (SDK vs CJS), taxonomia de erros e contrato sem lançamento para todos os roteadores de família de comandos (#3788) | @@ -444,7 +444,7 @@ Listagem completa: `gsd-core/bin/lib/*.cjs`. | `template.cjs` | Seleção e preenchimento de template com substituição de variáveis | | `uat.cjs` | Análise de arquivo UAT, rastreamento de dívida de verificação, suporte audit-uat | | `ui-safety-gate.cjs` | Detector de token de UI de limite de palavra sem shell (#3706, #3718); lê texto de seção de fase do stdin, sai com 0 (UI encontrada) ou 1 (sem UI); também implantado em `gsd-core/bin/lib/` para que o instalador GSD o entregue em `$RUNTIME_DIR` (#448) | -| `update-context.cjs` | Resolvedor de contexto de instalação puro para `/gsd:update` — detecção de runtime/escopo/config-dir/versão (LOCAL/GLOBAL/UNKNOWN) portada do bash de update.md; sustenta `gsd-tools update-context` (#498) | +| `update-context.cjs` | Resolvedor de contexto de instalação puro para `/gsd-update` — detecção de runtime/escopo/config-dir/versão (LOCAL/GLOBAL/UNKNOWN) portada do bash de update.md; sustenta `gsd-tools update-context` (#498) | | `validate-command-router.cjs` | Adaptador de roteador de subcomando CJS fino para `gsd-tools validate` | | `validate.cjs` | Auxiliares de normalização de variante de fase puros (`phaseVariants`, `buildRoadmapPhaseVariants`, `buildNotStartedPhaseVariants`) usados por `verify.cjs` para verificações W006/W007; sem I/O, sem async | | `verify-command-router.cjs` | Adaptador de roteador de subcomando CJS fino para `gsd-tools verify` | diff --git a/docs/pt-BR/USER-GUIDE.md b/docs/pt-BR/USER-GUIDE.md index 3a881405a..ef0b5af6a 100644 --- a/docs/pt-BR/USER-GUIDE.md +++ b/docs/pt-BR/USER-GUIDE.md @@ -499,7 +499,7 @@ claude --dangerously-skip-permissions **Comportamento de needs-acknowledgement.** Quando o protetor encontra um símbolo ausente, ele emite um aviso de needs-acknowledgement na saída da revisão do plano em vez de bloquear permanentemente. Você pode reconhecer e prosseguir (o símbolo pode ser intencionalmente novo) ou solicitar uma revisão do plano. O protetor não rejeita planos automaticamente — ele apresenta sinais para decisão humana. -**Funciona sem intel.** Por padrão, o protetor usa `grep`/`ripgrep` para pesquisar arquivos de código-fonte — não requer pré-indexação. Se você executou `/gsd:map-codebase` com `intel.enabled: true`, defina `plan_review.source_grounding_authority: intel` para usar o índice pré-construído `api-map.json` mais rápido. +**Funciona sem intel.** Por padrão, o protetor usa `grep`/`ripgrep` para pesquisar arquivos de código-fonte — não requer pré-indexação. Se você executou `/gsd-map-codebase` com `intel.enabled: true`, defina `plan_review.source_grounding_authority: intel` para usar o índice pré-construído `api-map.json` mais rápido. ```bash # Enable/disable (default: on) @@ -511,7 +511,7 @@ claude --dangerously-skip-permissions /gsd-settings plan_review.source_grounding_authority intel # pre-indexed api-map.json ``` -Alterne na configuração do projeto (`/gsd:new-project` pergunta durante as preferências de workflow) ou a qualquer momento via `/gsd:settings` (seção Planning → Drift Guard). +Alterne na configuração do projeto (`/gsd-new-project` pergunta durante as preferências de workflow) ou a qualquer momento via `/gsd-settings` (seção Planning → Drift Guard). ### Correção rápida de bug diff --git a/docs/pt-BR/how-to/install-on-your-runtime.md b/docs/pt-BR/how-to/install-on-your-runtime.md index 3b70bc4e8..cdb1d3853 100644 --- a/docs/pt-BR/how-to/install-on-your-runtime.md +++ b/docs/pt-BR/how-to/install-on-your-runtime.md @@ -8,7 +8,7 @@ Instale o GSD Core (`@opengsd/gsd-core`) no ambiente de codificação com IA que ## Por que o instalador é necessário -O GSD Core distribui arquivos de agente e comando no formato nativo de frontmatter do Claude Code. Cada ambiente suportado espera um schema, layout de diretório e sintaxe de invocação de comandos diferente. O instalador realiza as transformações necessárias — por exemplo, convertendo listas de ferramentas e valores de cor para o OpenCode, escrevendo entradas TOML de agente para o Codex e reescrevendo o corpo de cada comando do formato com hífen (`/gsd-update`) para o formato com dois-pontos (`/gsd:update`) para o Gemini CLI. +O GSD Core distribui arquivos de agente e comando no formato nativo de frontmatter do Claude Code. Cada ambiente suportado espera um schema, layout de diretório e sintaxe de invocação de comandos diferente. O instalador realiza as transformações necessárias — por exemplo, convertendo listas de ferramentas e valores de cor para o OpenCode, escrevendo entradas TOML de agente para o Codex e reescrevendo o corpo de cada comando do formato com hífen (`/gsd-update`) para o formato com dois-pontos (`/gsd-update`) para o Gemini CLI. **Não copie arquivos de `agents/` ou `commands/` diretamente.** Fazer isso ignora as transformações e produz erros de validação de schema ou comandos ausentes. @@ -50,7 +50,7 @@ CLAUDE_CONFIG_DIR=~/.claude-alt npx @opengsd/gsd-core@latest --claude --global npx @opengsd/gsd-core@latest --gemini --global ``` -As habilidades são instaladas em `~/.gemini/`. O instalador reescreve todos os corpos de comando para o namespace de dois-pontos do Gemini (`/gsd:update`, `/gsd:config`, etc.). Reinicie o Gemini CLI após a instalação. +As habilidades são instaladas em `~/.gemini/`. O instalador reescreve todos os corpos de comando para o namespace de dois-pontos do Gemini (`/gsd-update`, `/gsd-config`, etc.). Reinicie o Gemini CLI após a instalação. **Substituir o diretório de instalação:** diff --git a/docs/pt-BR/reference/context-md.md b/docs/pt-BR/reference/context-md.md index b4a1ce186..fd5b8467e 100644 --- a/docs/pt-BR/reference/context-md.md +++ b/docs/pt-BR/reference/context-md.md @@ -1,6 +1,6 @@ # Referência do esquema CONTEXT.md -Um `CONTEXT.md` por fase é o mecanismo do GSD Core para capturar decisões de implementação durante `/gsd:discuss-phase`. É a principal entrada upstream para os agentes de pesquisa e planejamento. Esta página documenta sua estrutura. Consulte o [índice de documentação](../README.md). +Um `CONTEXT.md` por fase é o mecanismo do GSD Core para capturar decisões de implementação durante `/gsd-discuss-phase`. É a principal entrada upstream para os agentes de pesquisa e planejamento. Esta página documenta sua estrutura. Consulte o [índice de documentação](../README.md). --- @@ -107,7 +107,7 @@ Um CONTEXT.md cujas decisões sobrevivem aos planos é considerado conforme. Um ## Integração com SPEC.md -Quando `/gsd:spec-phase` foi executado antes de discutir uma fase, a etapa `check_spec` encontra o arquivo `*-SPEC.md` e ativa o ``: +Quando `/gsd-spec-phase` foi executado antes de discutir uma fase, a etapa `check_spec` encontra o arquivo `*-SPEC.md` e ativa o ``: ```markdown diff --git a/docs/pt-BR/reference/plan-md.md b/docs/pt-BR/reference/plan-md.md index 014d37a19..6d4c4e472 100644 --- a/docs/pt-BR/reference/plan-md.md +++ b/docs/pt-BR/reference/plan-md.md @@ -14,7 +14,7 @@ Os planos ficam dentro de diretórios de fase em: Por exemplo: `.planning/phases/03-post-feed/03-02-PLAN.md` (Fase 3, Plano 2). -Os planos são produzidos pelo agente `gsd-planner` (disparado por `/gsd:plan-phase`) e consumidos por `execute-phase`. Uma fase normalmente contém entre um e quatro planos; os planos dentro de uma fase são atribuídos a ondas de execução para que trabalhos independentes sejam executados em paralelo. +Os planos são produzidos pelo agente `gsd-planner` (disparado por `/gsd-plan-phase`) e consumidos por `execute-phase`. Uma fase normalmente contém entre um e quatro planos; os planos dentro de uma fase são atribuídos a ondas de execução para que trabalhos independentes sejam executados em paralelo. --- diff --git a/docs/reference/capability-manifest.md b/docs/reference/capability-manifest.md index cbab1e46f..60b186f61 100644 --- a/docs/reference/capability-manifest.md +++ b/docs/reference/capability-manifest.md @@ -182,7 +182,7 @@ For a minimal `role: "runtime"` example, see [ADR-1016 §Decision 8](../adr/1016 ## Reviewer body (`role: "reviewer"`, or on any role) -[ADR-2782](../adr/2782-reviewer-lane-capability-surface.md) introduces the *reviewer lane*: one external CLI or model endpoint that `/gsd:review` hands a plan to for independent review. +[ADR-2782](../adr/2782-reviewer-lane-capability-surface.md) introduces the *reviewer lane*: one external CLI or model endpoint that `/gsd-review` hands a plan to for independent review. To declare one, follow [Ship a reviewer lane in your capability](../how-to/ship-a-reviewer-lane.md). This section is the field reference behind that guide. @@ -227,7 +227,7 @@ An unknown field inside a `reviewer` body is a **non-fatal warning on stderr, ne "role": "reviewer", "version": "1.8.0", "title": "CodeRabbit", - "description": "CodeRabbit CLI — cross-AI /gsd:review reviewer lane only; not a GSD install target (no runtime body, no artifacts).", + "description": "CodeRabbit CLI — cross-AI /gsd-review reviewer lane only; not a GSD install target (no runtime body, no artifacts).", "tier": "full", "requires": [], "engines": { "gsd": ">=1.8.0" }, diff --git a/docs/reference/capability-matrix.md b/docs/reference/capability-matrix.md index 228f87efe..97944ad7b 100644 --- a/docs/reference/capability-matrix.md +++ b/docs/reference/capability-matrix.md @@ -105,7 +105,7 @@ emission), so their extension-point and hook-kind cells are `—`. ### Reviewer capabilities (role: reviewer) — 5 Reviewer capabilities declare a cross-AI **reviewer lane** — one external CLI or -model endpoint `/gsd:review` hands a plan to (ADR-2782 D3). They are not install +model endpoint `/gsd-review` hands a plan to (ADR-2782 D3). They are not install targets: they emit no skills, agents, hooks or surface files, so their extension-point and hook-kind cells are `—`. A host that is *also* a reviewer (Claude, Codex, Cursor, OpenCode, Qwen, Antigravity) keeps one manifest and diff --git a/docs/reference/context-md.md b/docs/reference/context-md.md index 7b5ab2908..cc53a1190 100644 --- a/docs/reference/context-md.md +++ b/docs/reference/context-md.md @@ -1,6 +1,6 @@ # CONTEXT.md schema reference -A per-phase `CONTEXT.md` is GSD Core's carrier for implementation decisions captured during `/gsd:discuss-phase`. It is the primary upstream input for both the research and planning agents. This page documents its structure. See [docs index](../README.md). +A per-phase `CONTEXT.md` is GSD Core's carrier for implementation decisions captured during `/gsd-discuss-phase`. It is the primary upstream input for both the research and planning agents. This page documents its structure. See [docs index](../README.md). --- @@ -107,7 +107,7 @@ A CONTEXT.md where decisions survive into plans is considered compliant. A CONTE ## SPEC.md integration -When `/gsd:spec-phase` has been run before discussing a phase, the `check_spec` step finds the `*-SPEC.md` file and activates ``: +When `/gsd-spec-phase` has been run before discussing a phase, the `check_spec` step finds the `*-SPEC.md` file and activates ``: ```markdown diff --git a/docs/reference/plan-md.md b/docs/reference/plan-md.md index 2989b406e..0324cea63 100644 --- a/docs/reference/plan-md.md +++ b/docs/reference/plan-md.md @@ -14,7 +14,7 @@ Plans live inside phase directories at: For example: `.planning/phases/03-post-feed/03-02-PLAN.md` (Phase 3, Plan 2). -Plans are produced by the `gsd-planner` agent (spawned by `/gsd:plan-phase`) and consumed by `execute-phase`. A phase typically contains between one and four plans; plans within a phase are assigned to execution waves so that independent work runs in parallel. +Plans are produced by the `gsd-planner` agent (spawned by `/gsd-plan-phase`) and consumed by `execute-phase`. A phase typically contains between one and four plans; plans within a phase are assigned to execution waves so that independent work runs in parallel. --- @@ -219,7 +219,7 @@ Full emission rules, anti-patterns ("the system is ready" is not checkable; do n **Autonomy:** inserting a `checkpoint:decision` means the plan contains a checkpoint, so its frontmatter must set `autonomous: false`. -**Override:** `/gsd:plan-phase --no-reversibility-gates` (`REVERSIBILITY_GATES=false`) suppresses checkpoint insertion for intentionally-unattended runs. Ratings are still recorded and `costly` items are still flagged — the override changes what stops the run, not what the plan remembers. +**Override:** `/gsd-plan-phase --no-reversibility-gates` (`REVERSIBILITY_GATES=false`) suppresses checkpoint insertion for intentionally-unattended runs. Ratings are still recorded and `costly` items are still flagged — the override changes what stops the run, not what the plan remembers. Full taxonomy, emission rules, and anti-patterns (chiefly: rating everything `one-way` produces checkpoint fatigue; prefer *removing* irreversibility over gating it): see `gsd-core/references/planner-reversibility.md`. diff --git a/docs/reference/planning-artifacts.md b/docs/reference/planning-artifacts.md index 969db01ff..3034f6c6d 100644 --- a/docs/reference/planning-artifacts.md +++ b/docs/reference/planning-artifacts.md @@ -198,7 +198,7 @@ actuals: commits: 7 ``` -`tokens` uses the **same scale as the estimate**, not a harness-reported token count — an executor subagent cannot read its own consumption, and a ratio between two different measurement methods would measure the methods rather than the miss. `/gsd:extract-learnings` pairs each phase's estimate with its actuals via `gsd_run query estimate-calibrate`, writes `.planning/estimation-calibration.json`, and the planner applies the resulting factor to subsequent estimates. Additive and optional: a summary without `actuals` simply contributes no calibration sample. +`tokens` uses the **same scale as the estimate**, not a harness-reported token count — an executor subagent cannot read its own consumption, and a ratio between two different measurement methods would measure the methods rather than the miss. `/gsd-extract-learnings` pairs each phase's estimate with its actuals via `gsd_run query estimate-calibrate`, writes `.planning/estimation-calibration.json`, and the planner applies the resulting factor to subsequent estimates. Additive and optional: a summary without `actuals` simply contributes no calibration sample. ### `-VERIFICATION.md` @@ -245,7 +245,7 @@ actuals: | `status` | enum | Scheduler-agnostic lifecycle state (see below). | | `expected_artifacts` | string[] | Paths the job is expected to produce; verified before the plan is closed. | | `verification_command` | string | Command that verifies the job's output before close-out. | -| `resume_command` | string | Exact command to resume GSD reconciliation (re-enter the loop to re-check the job), e.g. `/gsd:execute-phase `. This is a GSD reconciliation entry point, not a scheduler resubmit. | +| `resume_command` | string | Exact command to resume GSD reconciliation (re-enter the loop to re-check the job), e.g. `/gsd-execute-phase `. This is a GSD reconciliation entry point, not a scheduler resubmit. | | `submitted_at` | string | ISO 8601 submission timestamp. | | `terminal_details` | object \| null | Failure/terminal-state detail; `null` while non-terminal. | diff --git a/docs/reference/review-verification-capabilities.md b/docs/reference/review-verification-capabilities.md index 341f7ab73..e1d2073f5 100644 --- a/docs/reference/review-verification-capabilities.md +++ b/docs/reference/review-verification-capabilities.md @@ -62,9 +62,9 @@ In that output, `configured` reflects config/default resolution, while `active` Direct command workflows self-gate the same way: -- `/gsd:code-review` resolves the active `execute:post` hook whose `ref.skill == "code-review"`. -- `/gsd:secure-phase` resolves the active `verify:post` hook whose `ref.skill == "secure-phase"`. -- `/gsd:validate-phase` resolves the active `verify:post` hook whose `ref.skill == "validate-phase"`. +- `/gsd-code-review` resolves the active `execute:post` hook whose `ref.skill == "code-review"`. +- `/gsd-secure-phase` resolves the active `verify:post` hook whose `ref.skill == "secure-phase"`. +- `/gsd-validate-phase` resolves the active `verify:post` hook whose `ref.skill == "validate-phase"`. ## Authoring Notes diff --git a/docs/research/2026-05-12-skill-surface-budget.md b/docs/research/2026-05-12-skill-surface-budget.md index 4a4f0c115..c65c6e46c 100644 --- a/docs/research/2026-05-12-skill-surface-budget.md +++ b/docs/research/2026-05-12-skill-surface-budget.md @@ -34,7 +34,7 @@ GSD has done one consolidation pass and shipped one install-time lever: - **Hard 100-char description budget**, enforced in CI by `scripts/lint-descriptions.cjs` and `npm run lint:descriptions`. - **`gsd update` (without `--minimal`)** as the documented upgrade path from minimal → full. -The 100-char cap means **shrinking descriptions further is not a viable lever** — average is already 72.5 chars and the rare 99-char outliers exist because they earn their length (e.g. `gsd:progress`, `gsd:inbox`). Any future budget relief has to come from **emitting fewer skills**, not shorter ones. +The 100-char cap means **shrinking descriptions further is not a viable lever** — average is already 72.5 chars and the rare 99-char outliers exist because they earn their length (e.g. `gsd-progress`, `gsd-inbox`). Any future budget relief has to come from **emitting fewer skills**, not shorter ones. ## 3. Audit findings @@ -54,7 +54,7 @@ Hot nodes (counted by other-skill body references): | 6 | `new-project` | 2 | Bootstrap | | 6 | `plan-phase` | 2 | Main-loop step 2 | -`phase` and `review` are the two skills whose absence would silently break dozens of others. **`phase` is referenced by 38 other skills but is not in the current minimal allowlist** — a latent gap worth raising. Confirm with a `--minimal` install + a `/gsd:audit-fix` invocation whether it still works. +`phase` and `review` are the two skills whose absence would silently break dozens of others. **`phase` is referenced by 38 other skills but is not in the current minimal allowlist** — a latent gap worth raising. Confirm with a `--minimal` install + a `/gsd-audit-fix` invocation whether it still works. ### 3.2 Functional clusters @@ -114,19 +114,19 @@ gsd install --profile=core,audit,ui # composable feature tags ### Option B — Runtime enable/disable command -A `/gsd:surface` (or `gsd surface` CLI) command that toggles which skills are visible to the runtime without touching installed files: +A `/gsd-surface` (or `gsd surface` CLI) command that toggles which skills are visible to the runtime without touching installed files: ``` -/gsd:surface list # show enabled/disabled -/gsd:surface disable ui audit # hide a cluster -/gsd:surface profile standard # apply a named profile +/gsd-surface list # show enabled/disabled +/gsd-surface disable ui audit # hide a cluster +/gsd-surface profile standard # apply a named profile ``` Implementation: write enable/disable state to `~/.claude/skills//SKILL.md.disabled` (rename) or maintain a `gsd-surface.json` manifest the installer reads on every `update`. | Dimension | Assessment | |---|---| -| User UX | Discoverable through `/gsd:help`. Lower commit than reinstall. Mirrors VS Code's enable/disable extension UX. | +| User UX | Discoverable through `/gsd-help`. Lower commit than reinstall. Mirrors VS Code's enable/disable extension UX. | | Implementation cost | **Medium.** Need persistent state separate from install files, plus a re-apply loop on `gsd update`. | | Dependency safety | Same manifest requirement as Option A — disabling `phase` should warn that 38 skills depend on it. | | Token savings | High — user-driven; can match Option A's savings. | @@ -207,7 +207,7 @@ Why this ordering: 1. **A reuses an existing seam.** `install-profiles.cjs` is already the staging point; this is the lowest-risk way to ship meaningful relief in the next release. 2. **A is composable.** Naming clusters as profiles is a forcing function for the dependency manifest, which we want anyway for the lint described in 3.1. -3. **B follows A naturally.** Once profiles exist, the `/gsd:surface` command is "apply a profile to a live install plus persist deltas." Without A, B has no profiles to apply. +3. **B follows A naturally.** Once profiles exist, the `/gsd-surface` command is "apply a profile to a live install plus persist deltas." Without A, B has no profiles to apply. 4. **C is independent and orthogonal.** It can happen in parallel as IA cleanup; it should not block A. 5. **D and E are platform-level.** GSD ships A regardless; D/E are documented as cooperative asks so Anthropic sees them in context. @@ -229,7 +229,7 @@ Drafted for filing at or similar channel; cop ### Ask 4 — Disable/enable without uninstall -> Today the only way to remove a skill from the listing is to delete its `SKILL.md`. Proposal: a `.disabled` suffix (e.g. `SKILL.md.disabled`) or a per-skill `enabled: false` frontmatter is treated as "not surfaced" by the harness. This lets plugins ship surface-toggle UIs (like our proposed `/gsd:surface disable`) without touching install state. +> Today the only way to remove a skill from the listing is to delete its `SKILL.md`. Proposal: a `.disabled` suffix (e.g. `SKILL.md.disabled`) or a per-skill `enabled: false` frontmatter is treated as "not surfaced" by the harness. This lets plugins ship surface-toggle UIs (like our proposed `/gsd-surface disable`) without touching install state. ## 7. Implementation sketch (for the ADR) @@ -243,7 +243,7 @@ Phase 1 — profiles (ships with ADR-0010): Phase 2 — runtime surface command (follow-up ADR or amendment): -1. `/gsd:surface` command writes to the profile marker and re-runs the staging step for the active runtime. +1. `/gsd-surface` command writes to the profile marker and re-runs the staging step for the active runtime. 2. Once Anthropic ships Ask 4, switch from file-deletion to `.disabled`-suffix toggling. ## 8. Follow-ups outside this scope @@ -253,9 +253,9 @@ Phase 2 — runtime surface command (follow-up ADR or amendment): ## 9. Risks and unknowns -- **The `phase` dispatcher gap in the existing minimal allowlist.** Confirm whether a fresh `--minimal` install + the documented main loop actually works end-to-end. If `discuss-phase`/`plan-phase`/`execute-phase` silently fall back to `/gsd:phase`, the minimal allowlist is currently broken. Track as a separate bug if confirmed. +- **The `phase` dispatcher gap in the existing minimal allowlist.** Confirm whether a fresh `--minimal` install + the documented main loop actually works end-to-end. If `discuss-phase`/`plan-phase`/`execute-phase` silently fall back to `/gsd-phase`, the minimal allowlist is currently broken. Track as a separate bug if confirmed. - **Profile naming bikeshed.** `core` / `standard` / `full` vs. `minimal` / `recommended` / `everything` vs. functional names (`planning`, `audit`, `research`). Settle in the ADR's Open Questions. -- **Discoverability of disabled skills.** If `gsd:audit-fix` isn't surfaced, a user asking "audit my project" won't get it suggested. `/gsd:help` should list installed-but-not-surfaced skills with a one-line upgrade hint. +- **Discoverability of disabled skills.** If `gsd-audit-fix` isn't surfaced, a user asking "audit my project" won't get it suggested. `/gsd-help` should list installed-but-not-surfaced skills with a one-line upgrade hint. - **Telemetry blind spot.** GSD doesn't currently know which skills users invoke, so "drop the long tail" is theoretical. Survey or self-reporting may be needed before drawing the `standard` profile line. ## 10. References diff --git a/docs/superpowers/specs/2026-06-27-gsd-smart-entry-design.md b/docs/superpowers/specs/2026-06-27-gsd-smart-entry-design.md index 1911c98f8..f2779fd61 100644 --- a/docs/superpowers/specs/2026-06-27-gsd-smart-entry-design.md +++ b/docs/superpowers/specs/2026-06-27-gsd-smart-entry-design.md @@ -8,11 +8,11 @@ ## Summary -A `/gsd:next` command that acts as gsd-core's **state-aware front door**. It reads project + workflow state, classifies the user's situation, and presents a small menu of the right next actions — then dispatches to an existing command. The "smart" part is deterministic detection living in Node (a new `gsd-tools smart-entry` subcommand); the presentation is an idiomatic markdown command + workflow using `AskUserQuestion` with a `--text` fallback for non-Claude runtimes. +A `/gsd-next` command that acts as gsd-core's **state-aware front door**. It reads project + workflow state, classifies the user's situation, and presents a small menu of the right next actions — then dispatches to an existing command. The "smart" part is deterministic detection living in Node (a new `gsd-tools smart-entry` subcommand); the presentation is an idiomatic markdown command + workflow using `AskUserQuestion` with a `--text` fallback for non-Claude runtimes. This is a **launcher / router**, not an executor. It never does the work itself. -> **Implementation note (command name):** the command-contract (ADR-0002) requires `name:` to be `gsd:*` or `gsd-*` prefixed; a bare `/gsd` is not expressible. The command is therefore `gsd:next` → `/gsd:next` (file `commands/gsd/next.md`, backed by `gsd-core/workflows/smart-entry.md`). The "smart entry" concept and behavior are unchanged; only the surfaced name differs from the original `/gsd` sketch. +> **Implementation note (command name):** the command-contract (ADR-0002) requires `name:` to be `gsd:*` or `gsd-*` prefixed; a bare `/gsd` is not expressible. The frontmatter is therefore `name: gsd:next`, surfacing as `/gsd-next` (file `commands/gsd/next.md`, backed by `gsd-core/workflows/smart-entry.md`). The "smart entry" concept and behavior are unchanged; only the surfaced name differs from the original `/gsd` sketch. --- @@ -34,13 +34,13 @@ These were chosen during brainstorming and are fixed inputs to this spec: 3. **Richness: phase + smart signals.** The classifier branches on gsd-core's phase loop **and** richer gsd-pi-style signals (blocked/recover, idle/stranded, paused, complete). All 10 situations below are in scope. -4. **Relationship to `/gsd-progress`: complementary, not redundant.** `/gsd:next` is the **front door / launcher** — a state-aware *menu* the user picks the next action from. `/gsd-progress` remains the **detailed situational report + auto-advance** (`--next` chaining). `/gsd:next` will frequently recommend `/gsd:progress`; it does not replace or deprecate it. +4. **Relationship to `/gsd-progress`: complementary, not redundant.** `/gsd-next` is the **front door / launcher** — a state-aware *menu* the user picks the next action from. `/gsd-progress` remains the **detailed situational report + auto-advance** (`--next` chaining). `/gsd-next` will frequently recommend `/gsd-progress`; it does not replace or deprecate it. --- ## Non-goals -- **No init/onboarding wizard.** `/gsd-new-project` already owns first-run project setup. `/gsd:next` routes to it. +- **No init/onboarding wizard.** `/gsd-new-project` already owns first-run project setup. `/gsd-next` routes to it. - **No new prompt/TUI library.** `AskUserQuestion` (Claude) + `--text` numbered-list fallback (other runtimes) — matching repo convention. No inquirer/clack/ink. - **No copy of gsd-pi's branch tree.** gsd-pi's milestone/slice/task model does not exist here. The situation table is **redesigned for gsd-core's phase loop** (`.planning/`). - **No execution.** Pure launcher. Picked action dispatches to an existing command and stops. @@ -51,7 +51,7 @@ These were chosen during brainstorming and are fixed inputs to this spec: ## Architecture ```text -/gsd:next (commands/gsd/next.md — thin markdown dispatcher) +/gsd-next (commands/gsd/next.md — thin markdown dispatcher) │ ▼ workflow: gsd-core/workflows/smart-entry.md ◄── presentation + dispatch @@ -154,10 +154,10 @@ unknown → progress*, "progress --next", quick, help "blockers": [] }, "actions": [ - { "id": "execute-phase", "label": "Continue executing phase 2", "command": "/gsd:execute-phase", "recommended": true }, - { "id": "progress-next", "label": "Advance to the next step", "command": "/gsd:progress --next", "recommended": false }, - { "id": "quick", "label": "Quick task", "command": "/gsd:quick", "recommended": false }, - { "id": "code-review", "label": "Review recent work", "command": "/gsd:code-review", "recommended": false } + { "id": "execute-phase", "label": "Continue executing phase 2", "command": "/gsd-execute-phase", "recommended": true }, + { "id": "progress-next", "label": "Advance to the next step", "command": "/gsd-progress --next", "recommended": false }, + { "id": "quick", "label": "Quick task", "command": "/gsd-quick", "recommended": false }, + { "id": "code-review", "label": "Review recent work", "command": "/gsd-code-review", "recommended": false } ] } ``` @@ -165,7 +165,7 @@ unknown → progress*, "progress --next", quick, help - `situation`, `recommended`, `actions[]` are the contract the workflow depends on. - `signals` is informational (shown in the summary banner); the workflow does not branch on it. - `summary` is a one-line human string; the workflow may show it verbatim or reformat. -- `actions[].command` is the full slash command string the workflow dispatches, including flags (e.g. `/gsd:progress --next`). +- `actions[].command` is the full slash command string the workflow dispatches, including flags (e.g. `/gsd-progress --next`). --- @@ -176,7 +176,7 @@ unknown → progress*, "progress --next", quick, help Thin dispatcher, modeled on `commands/gsd/progress.md` and `commands/gsd/help.md`. Backed by `gsd-core/workflows/smart-entry.md` (named for the `smart-entry` classifier + `gsd-tools smart-entry` subcommand; does not collide with the existing `workflows/next.md`, which is the progress `--next` sub-workflow). Frontmatter: -- `name: gsd:next` (surfaces as `/gsd:next`; the command-contract requires a `gsd:*`/`gsd-*` prefix — a bare `/gsd` is not expressible, see ADR-0002) +- `name: gsd:next` (surfaces as `/gsd-next`; the command-contract requires a `gsd:*`/`gsd-*` prefix — a bare `/gsd` is not expressible, see ADR-0002) - `description:` "GSD smart entry — the state-aware front door. Reads your project state and routes you to the right next action." - `argument-hint: ""` (no args for v1; reserved) - `effort: low` @@ -196,7 +196,7 @@ Five steps. **Must stay under 32 KiB (NEW_FILE_CAP)** — lean, because all bran ```bash SNAPSHOT=$(gsd_run smart-entry --json 2>/dev/null) ``` -Parse `SNAPSHOT` as JSON. If missing or unparseable → fall back to `/gsd:progress` (Step 5, with a one-line note "smart-entry unavailable — showing progress"). The agent never gets stuck. +Parse `SNAPSHOT` as JSON. If missing or unparseable → fall back to `/gsd-progress` (Step 5, with a one-line note "smart-entry unavailable — showing progress"). The agent never gets stuck. **Step 3 — `present` (render the menu):** @@ -225,13 +225,13 @@ The `--text` fallback is mandatory and is the reason we keep menus small and log | failure | behavior | |---|---| | `gsd_run` shim not found | the shim block itself errors with the standard install hint (from `do.md:29`); not our concern | -| `smart-entry` command missing (older gsd-core) | workflow sees empty/unparseable output → falls back to `/gsd:progress` with a note | -| `smart-entry` throws | same: caught by the `2>/dev/null` + parse check → fallback to `/gsd:progress` | +| `smart-entry` command missing (older gsd-core) | workflow sees empty/unparseable output → falls back to `/gsd-progress` with a note | +| `smart-entry` throws | same: caught by the `2>/dev/null` + parse check → fallback to `/gsd-progress` | | `.planning/` absent | `smart-entry` returns `situation: "no-project"` → menu offers `new-project` | | git unavailable / not a repo | classifier swallows git errors; works without git signals | | `AskUserQuestion` unavailable (non-Claude) | TEXT_MODE numbered list | -**Invariant:** `/gsd` always produces *some* actionable menu and never strands the user. The ultimate fallback is `/gsd:progress`, which is always safe and always exists. +**Invariant:** `/gsd` always produces *some* actionable menu and never strands the user. The ultimate fallback is `/gsd-progress`, which is always safe and always exists. --- @@ -279,7 +279,7 @@ Invariants over the markdown layer (these are structural/format assertions on sh | `src/smart-entry.cts` | NEW — detection + classifier; `--json` + human output | — | | `gsd-core/bin/lib/smart-entry.cjs` | generated by `build:lib` (gitignored) | — | | `gsd-core/bin/gsd-tools.cjs` | add `case 'smart-entry':` (~2 lines) | — | -| `commands/gsd/next.md` | NEW — thin dispatcher command (`gsd:next` → `/gsd:next`) | small | +| `commands/gsd/next.md` | NEW — thin dispatcher command (`name: gsd:next` → `/gsd-next`) | small | | `gsd-core/workflows/smart-entry.md` | NEW — presentation + dispatch | < 32 KiB | | `tests/smart-entry.unit.test.cjs` | NEW — classifier behavior | — | | `tests/gsd-workflow.structure.test.cjs` | NEW — markdown-layer invariants | — | @@ -305,6 +305,6 @@ None blocking. Two noted for the implementer's judgment (not spec-level): - [ ] `/gsd` in a real project shows a situation-appropriate menu and dispatches the chosen command. - [ ] `/gsd` pre-project offers `new-project`. - [ ] `/gsd` works under TEXT_MODE (no `AskUserQuestion`). -- [ ] Any `smart-entry` failure falls back to `/gsd:progress` without erroring. +- [ ] Any `smart-entry` failure falls back to `/gsd-progress` without erroring. - [ ] New workflow under 32 KiB; `size:baseline` updated; coverage gate passes. - [ ] No new dependencies; no existing command modified. diff --git a/docs/tutorials/build-your-first-capability.md b/docs/tutorials/build-your-first-capability.md index 0194ff4ad..7f273b4cf 100644 --- a/docs/tutorials/build-your-first-capability.md +++ b/docs/tutorials/build-your-first-capability.md @@ -189,7 +189,7 @@ Notice that `fragment.inline` now holds the materialised text from `fragments/pl Planning is driven by a slash command, not a `gsd` subcommand. In your AI assistant, start a planning session for a phase with: ```text -/gsd:plan-phase +/gsd-plan-phase ``` When the planner runs, the `plan:pre` hook set is rendered into its prompt, so it receives the `hello-note` contribution and, following the fragment's instruction, records a one-line note in `HELLO.md`. diff --git a/docs/tutorials/embed-gsd-in-a-new-host.md b/docs/tutorials/embed-gsd-in-a-new-host.md index 1c9f71c6a..b300f6e46 100644 --- a/docs/tutorials/embed-gsd-in-a-new-host.md +++ b/docs/tutorials/embed-gsd-in-a-new-host.md @@ -53,7 +53,7 @@ const { effective, points, warnings } = SDK.handleHandshakeRequest(req); ## Step 4 — Run a GSD command through the embedded engine The imperative adapter exposes the engine surface; your host binds its command -surface (slash commands, palette, chat) to it. A user invoking `/gsd:phase` in +surface (slash commands, palette, chat) to it. A user invoking `/gsd-phase` in your host dispatches through the embedded engine exactly as it would in a first-party host — that is the parity the interface guarantees. diff --git a/docs/whats-new-1.7.0.md b/docs/whats-new-1.7.0.md index c30f9ae2f..827c1b6ec 100644 --- a/docs/whats-new-1.7.0.md +++ b/docs/whats-new-1.7.0.md @@ -14,7 +14,7 @@ **Gemini CLI removed** (#1928): Google discontinued Gemini CLI on 2026-06-18, so `--gemini` now prints a deprecation notice pointing to Antigravity CLI, the official successor and already a first-class GSD runtime. -`/gsd:surface` and `--materialize` now produce byte-identical agent output to a fresh install for descriptor-driven runtimes (#1575). +`/gsd-surface` and `--materialize` now produce byte-identical agent output to a fresh install for descriptor-driven runtimes (#1575). Read more: [Embeddable Orchestration System](explanation/embeddable-orchestration-system.md) · [Host-Integration Interface reference](reference/host-integration-interface.md) · [Interface versioning policy](explanation/interface-versioning-policy.md) · [Install on your runtime](how-to/install-on-your-runtime.md). @@ -62,7 +62,7 @@ See [Configuration — model profiles](CONFIGURATION.md) and [Configure model pr ## Planning, verification & workflow -- The **API-coverage gate** (#1562): a phase that integrates an external API/SDK/service cannot seal `/gsd:verify-work` without a decided coverage matrix. +- The **API-coverage gate** (#1562): a phase that integrates an external API/SDK/service cannot seal `/gsd-verify-work` without a decided coverage matrix. - `plan-phase` now authors edge and prohibition predicates into `PLAN.md` `must_have` (#1154), and the **honest verifier** abstains (`human_needed`) on non-inferable `backstop` truths instead of confidently false-passing them (#1154). - A plural/optional/chosen **assumption-delta checkpoint** during planning re-asks identity-model questions when cardinality changes (#1561). - `/gsd-ui-phase` gains a **UI state-coverage probe** (#1979); `/gsd-review` supports **custom reviewer instances** (#1517). diff --git a/docs/zh-CN/CONFIGURATION.md b/docs/zh-CN/CONFIGURATION.md index 0155fc139..dd20faa72 100644 --- a/docs/zh-CN/CONFIGURATION.md +++ b/docs/zh-CN/CONFIGURATION.md @@ -471,8 +471,8 @@ gsd-tools query config-set agent_skills.gsd-executor '["skills/my-skill"]' | 设置 | 类型 | 默认值 | 描述 | |---------|------|---------|-------------| -| `plan_review.source_grounding` | boolean | `true` | 启用计划漂移防护。为 `true`（默认）时，计划审查将 PLAN.md 中引用的每个符号与实时源代码树对比解析。引用不存在的函数、类、装饰器或 CLI 标志的计划在计划批准前产生 `needs-acknowledgement` 通知。设为 `false` 完全跳过符号验证。可在设置期间（`/gsd:new-project`）或随时通过 `/gsd:settings` 切换。 | -| `plan_review.source_grounding_authority` | enum | `grep` | 选择用于验证符号存在性的解析器适配器。允许值：`grep`（默认——对源文件进行 ripgrep/grep 搜索，任何项目无需额外工具即可使用），`intel`（查询 `/gsd:map-codebase` 构建的 `.planning/intel/api-map.json` 索引；需要 `intel.enabled: true`），`treesitter`（保留用于未来的 tree-sitter 适配器），`lsp`（保留用于未来的 LSP 适配器），`scip`（保留用于未来的 SCIP/LSIF 适配器）。当您已运行 `/gsd:map-codebase` 并希望使用更快的预索引查找时，使用 `intel`。`grep` 和 `intel` 之外的所有值均为保留值，在当前版本中无效。 | +| `plan_review.source_grounding` | boolean | `true` | 启用计划漂移防护。为 `true`（默认）时，计划审查将 PLAN.md 中引用的每个符号与实时源代码树对比解析。引用不存在的函数、类、装饰器或 CLI 标志的计划在计划批准前产生 `needs-acknowledgement` 通知。设为 `false` 完全跳过符号验证。可在设置期间（`/gsd-new-project`）或随时通过 `/gsd-settings` 切换。 | +| `plan_review.source_grounding_authority` | enum | `grep` | 选择用于验证符号存在性的解析器适配器。允许值：`grep`（默认——对源文件进行 ripgrep/grep 搜索，任何项目无需额外工具即可使用），`intel`（查询 `/gsd-map-codebase` 构建的 `.planning/intel/api-map.json` 索引；需要 `intel.enabled: true`），`treesitter`（保留用于未来的 tree-sitter 适配器），`lsp`（保留用于未来的 LSP 适配器），`scip`（保留用于未来的 SCIP/LSIF 适配器）。当您已运行 `/gsd-map-codebase` 并希望使用更快的预索引查找时，使用 `intel`。`grep` 和 `intel` 之外的所有值均为保留值，在当前版本中无效。 | ### Graphify 设置 @@ -1179,7 +1179,7 @@ minimal < low < medium < high < xhigh < max > **[#49](https://github.com/open-gsd/gsd-core/issues/49)** — 提供商中立的模型策略配置界面。在旧版 `model_profile_overrides` 之前解析。 -`model_policy` 提供了一种更简单、提供商中立的方式来跨运行时配置模型层级。对于手动知道正确模型 ID 需要使用 `model_profile_overrides` 的非 Anthropic 运行时，这是首选界面。通过 `/gsd:settings` → 第 8 节（模型策略）配置。 +`model_policy` 提供了一种更简单、提供商中立的方式来跨运行时配置模型层级。对于手动知道正确模型 ID 需要使用 `model_profile_overrides` 的非 Anthropic 运行时，这是首选界面。通过 `/gsd-settings` → 第 8 节（模型策略）配置。 ### 已知提供商预设 diff --git a/docs/zh-CN/FEATURES.md b/docs/zh-CN/FEATURES.md index 673a1a84a..79efe6c0b 100644 --- a/docs/zh-CN/FEATURES.md +++ b/docs/zh-CN/FEATURES.md @@ -2840,7 +2840,7 @@ Source commit: abc1234 (3 commits behind HEAD) | `standard` | 核心加常用阶段管理命令 | | `full` | 完整界面；默认 | -**运行时控制：** `/gsd:surface` 列出配置文件状态，无需重新安装即可启用、禁用或重置技能集群。 +**运行时控制：** `/gsd-surface` 列出配置文件状态，无需重新安装即可启用、禁用或重置技能集群。 **需求：** - REQ-SURFACE-01：安装器必须解析 `--profile=` 并将活跃配置文件持久化在 `.gsd-profile` 中。 diff --git a/docs/zh-CN/INVENTORY.md b/docs/zh-CN/INVENTORY.md index d422c6cb9..76f395511 100644 --- a/docs/zh-CN/INVENTORY.md +++ b/docs/zh-CN/INVENTORY.md @@ -382,7 +382,7 @@ | `cjs-command-router-adapter.cjs` | 清单支持的 CJS 命令族路由器的共享兼容性适配器 | | `clock.cjs` | 用于确定性锁测试的可注入时钟接缝（now/sleep） | | `clusters.cjs` | 运行时 surface 模块的技能集群定义（ADR-0011 阶段 2） | -| `code-review-flags.cjs` | `/gsd:code-review` 的类型化标志解析器；导出 `parseCodeReviewFlags(argv)`（→ `{ fix, all, auto, depth, files }`）和 `resolveCodeReviewWorkflow(flags)`（→ `'code-review.md' \| 'code-review-fix.md'`）；`--fix`/`--all`/`--auto` 路由的规范分发接缝 | +| `code-review-flags.cjs` | `/gsd-code-review` 的类型化标志解析器；导出 `parseCodeReviewFlags(argv)`（→ `{ fix, all, auto, depth, files }`）和 `resolveCodeReviewWorkflow(flags)`（→ `'code-review.md' \| 'code-review-fix.md'`）；`--fix`/`--all`/`--auto` 路由的规范分发接缝 | | `command-aliases.cjs` | 清单支持的族路由器的别名/子命令元数据 | | `command-arg-projection.cjs` | 跨命令族路由器共享的类型化标志和位置参数投影帮助器 | | `command-routing-hub.cjs` | 纯结果分发中心，集中了所有命令族路由器的模式决策（SDK vs CJS）、错误分类和无抛出契约（#3788） | @@ -444,7 +444,7 @@ | `template.cjs` | 带变量替换的模板选择和填充 | | `uat.cjs` | UAT 文件解析、验证债务跟踪、audit-uat 支持 | | `ui-safety-gate.cjs` | 无 shell 的词边界 UI 令牌检测器（#3706，#3718）；从 stdin 读取阶段章节文本，退出 0（找到 UI）或 1（未找到 UI）；也部署到 `gsd-core/bin/lib/`，以便 GSD 安装程序将其传送到 `$RUNTIME_DIR`（#448） | -| `update-context.cjs` | `/gsd:update` 的纯安装上下文解析器 — 从 update.md bash 移植的运行时/范围/配置目录/版本检测（LOCAL/GLOBAL/UNKNOWN）；支持 `gsd-tools update-context`（#498） | +| `update-context.cjs` | `/gsd-update` 的纯安装上下文解析器 — 从 update.md bash 移植的运行时/范围/配置目录/版本检测（LOCAL/GLOBAL/UNKNOWN）；支持 `gsd-tools update-context`（#498） | | `validate-command-router.cjs` | `gsd-tools validate` 的轻量 CJS 子命令路由适配器 | | `validate.cjs` | 纯阶段变体规范化帮助器（`phaseVariants`、`buildRoadmapPhaseVariants`、`buildNotStartedPhaseVariants`），被 `verify.cjs` 用于 W006/W007 检查；无 I/O，无异步 | | `verify-command-router.cjs` | `gsd-tools verify` 的轻量 CJS 子命令路由适配器 | diff --git a/docs/zh-CN/USER-GUIDE.md b/docs/zh-CN/USER-GUIDE.md index 328e0b98f..0bfb4af22 100644 --- a/docs/zh-CN/USER-GUIDE.md +++ b/docs/zh-CN/USER-GUIDE.md @@ -498,7 +498,7 @@ claude --dangerously-skip-permissions **needs-acknowledgement 行为。** 当守卫发现缺失的符号时，它会在计划审查输出中发出 needs-acknowledgement 通知，而不是硬性阻塞。您可以确认并继续（该符号可能是有意新增的），或请求修改计划。守卫不会自动拒绝计划——它为人工决策提供信号。 -**无需 intel 即可工作。** 默认情况下，守卫使用 `grep`/`ripgrep` 搜索源文件——无需预先索引。如果您已使用 `intel.enabled: true` 运行 `/gsd:map-codebase`，请将 `plan_review.source_grounding_authority: intel` 设置为使用更快的预构建 `api-map.json` 索引。 +**无需 intel 即可工作。** 默认情况下，守卫使用 `grep`/`ripgrep` 搜索源文件——无需预先索引。如果您已使用 `intel.enabled: true` 运行 `/gsd-map-codebase`，请将 `plan_review.source_grounding_authority: intel` 设置为使用更快的预构建 `api-map.json` 索引。 ```bash # Enable/disable (default: on) @@ -510,7 +510,7 @@ claude --dangerously-skip-permissions /gsd-settings plan_review.source_grounding_authority intel # pre-indexed api-map.json ``` -在项目设置时切换（`/gsd:new-project` 在工作流偏好设置期间询问）或随时通过 `/gsd:settings`（计划部分 → 漂移守卫）切换。 +在项目设置时切换（`/gsd-new-project` 在工作流偏好设置期间询问）或随时通过 `/gsd-settings`（计划部分 → 漂移守卫）切换。 ### 快速修复 Bug diff --git a/docs/zh-CN/how-to/install-on-your-runtime.md b/docs/zh-CN/how-to/install-on-your-runtime.md index 7bf6f97fb..e8e34d194 100644 --- a/docs/zh-CN/how-to/install-on-your-runtime.md +++ b/docs/zh-CN/how-to/install-on-your-runtime.md @@ -8,7 +8,7 @@ ## 为什么需要安装程序 -GSD Core 以 Claude Code 原生 frontmatter 格式分发代理和命令文件。每个支持的运行时需要不同的 schema、目录结构和命令调用语法。安装程序负责执行必要的转换——例如，为 OpenCode 转换工具列表和颜色值、为 Codex 写入 TOML 代理条目，以及将所有命令体从连字符格式（`/gsd-update`）重写为冒号格式（`/gsd:update`）以适配 Gemini CLI。 +GSD Core 以 Claude Code 原生 frontmatter 格式分发代理和命令文件。每个支持的运行时需要不同的 schema、目录结构和命令调用语法。安装程序负责执行必要的转换——例如，为 OpenCode 转换工具列表和颜色值、为 Codex 写入 TOML 代理条目，以及将所有命令体从连字符格式（`/gsd-update`）重写为冒号格式（`/gsd-update`）以适配 Gemini CLI。 **请勿直接从 `agents/` 或 `commands/` 复制文件。** 这样做会绕过转换过程，导致 schema 验证错误或命令缺失。 @@ -50,7 +50,7 @@ CLAUDE_CONFIG_DIR=~/.claude-alt npx @opengsd/gsd-core@latest --claude --global npx @opengsd/gsd-core@latest --gemini --global ``` -技能文件存放于 `~/.gemini/`。安装程序将所有命令体重写为 Gemini 的冒号命名空间格式（`/gsd:update`、`/gsd:config` 等）。安装后重启 Gemini CLI。 +技能文件存放于 `~/.gemini/`。安装程序将所有命令体重写为 Gemini 的冒号命名空间格式（`/gsd-update`、`/gsd-config` 等）。安装后重启 Gemini CLI。 **覆盖安装目录：** diff --git a/docs/zh-CN/reference/context-md.md b/docs/zh-CN/reference/context-md.md index 67c9ea87c..eea4de9f4 100644 --- a/docs/zh-CN/reference/context-md.md +++ b/docs/zh-CN/reference/context-md.md @@ -1,6 +1,6 @@ # CONTEXT.md 结构参考 -每个阶段的 `CONTEXT.md` 是 GSD Core 用于保存 `/gsd:discuss-phase` 阶段所收集的实现决策的载体。它是研究代理和规划代理的主要上游输入。本页面记录其结构。参见[文档索引](../README.md)。 +每个阶段的 `CONTEXT.md` 是 GSD Core 用于保存 `/gsd-discuss-phase` 阶段所收集的实现决策的载体。它是研究代理和规划代理的主要上游输入。本页面记录其结构。参见[文档索引](../README.md)。 --- @@ -107,7 +107,7 @@ No external specs — requirements fully captured in decisions above ## SPEC.md 集成 -当 `/gsd:spec-phase` 在讨论阶段之前运行时，`check_spec` 步骤会找到 `*-SPEC.md` 文件并激活 ``： +当 `/gsd-spec-phase` 在讨论阶段之前运行时，`check_spec` 步骤会找到 `*-SPEC.md` 文件并激活 ``： ```markdown diff --git a/docs/zh-CN/reference/plan-md.md b/docs/zh-CN/reference/plan-md.md index 2bc8fe3d8..9a87d06cd 100644 --- a/docs/zh-CN/reference/plan-md.md +++ b/docs/zh-CN/reference/plan-md.md @@ -14,7 +14,7 @@ 例如：`.planning/phases/03-post-feed/03-02-PLAN.md`（第 3 阶段，第 2 计划）。 -计划由 `gsd-planner` 代理生成（由 `/gsd:plan-phase` 触发），并由 `execute-phase` 消费。一个阶段通常包含一到四个计划；同一阶段内的计划被分配到执行波次，以便独立工作并行运行。 +计划由 `gsd-planner` 代理生成（由 `/gsd-plan-phase` 触发），并由 `execute-phase` 消费。一个阶段通常包含一到四个计划；同一阶段内的计划被分配到执行波次，以便独立工作并行运行。 --- diff --git a/package.json b/package.json index 6ccd7ba19..29f2c53fd 100644 --- a/package.json +++ b/package.json @@ -108,7 +108,7 @@ "lint": "eslint . --cache --cache-location node_modules/.cache/eslint/", "lint:fix": "eslint . --fix", "lint:table-schema-drift": "node scripts/lint-table-schema-drift.cjs", - "lint:ci": "npm run lint && npm run lint:skill-deps && npm run lint:generated-sync && node scripts/lint-test-file-count.cjs && node scripts/lint-command-contract.cjs && node scripts/lint-pr-check-project-dir.cjs && npm run lint:legacy-name && node scripts/lint-regression-test-names.cjs && node scripts/lint-allow-test-rule-refs.cjs && node scripts/lint-resolution-provenance.cjs && node scripts/lint-emitted-drift-ack.cjs && node scripts/lint-portable-timeout.cjs && node scripts/validate-registry.cjs && node scripts/lint-table-schema-drift.cjs && node scripts/lint-fix-has-regression-test.cjs && node scripts/lint-example-parser-parity.cjs", + "lint:ci": "npm run lint && npm run lint:skill-deps && npm run lint:generated-sync && node scripts/lint-test-file-count.cjs && node scripts/lint-command-contract.cjs && node scripts/lint-pr-check-project-dir.cjs && npm run lint:legacy-name && node scripts/lint-regression-test-names.cjs && node scripts/lint-allow-test-rule-refs.cjs && node scripts/lint-resolution-provenance.cjs && node scripts/lint-emitted-drift-ack.cjs && node scripts/lint-portable-timeout.cjs && node scripts/validate-registry.cjs && node scripts/lint-table-schema-drift.cjs && node scripts/lint-fix-has-regression-test.cjs && node scripts/lint-example-parser-parity.cjs && node scripts/lint-docs-command-form.cjs", "lint:allow-test-rule-refs": "node scripts/lint-allow-test-rule-refs.cjs", "lint:regression-names": "node scripts/lint-regression-test-names.cjs", "lint:descriptions": "node scripts/lint-descriptions.cjs", @@ -120,6 +120,7 @@ "lint:docs": "node scripts/lint-docs-required.cjs", "lint:qa-smells": "node scripts/qa-smell-ratchet.cjs", "lint:legacy-name": "node scripts/lint-legacy-dir-name.cjs", + "lint:docs-command-form": "node scripts/lint-docs-command-form.cjs", "ci:test-scope": "node scripts/ci-test-scope.cjs", "changeset": "node scripts/changeset/new.cjs", "changelog:render": "node scripts/changeset/cli.cjs render", diff --git a/scripts/gen-capability-matrix.cjs b/scripts/gen-capability-matrix.cjs index ab86db3fc..00b0ea7d2 100644 --- a/scripts/gen-capability-matrix.cjs +++ b/scripts/gen-capability-matrix.cjs @@ -190,7 +190,7 @@ ${runtimeTable} ### Reviewer capabilities (role: reviewer) — ${reviewerCount} Reviewer capabilities declare a cross-AI **reviewer lane** — one external CLI or -model endpoint \`/gsd:review\` hands a plan to (ADR-2782 D3). They are not install +model endpoint \`/gsd-review\` hands a plan to (ADR-2782 D3). They are not install targets: they emit no skills, agents, hooks or surface files, so their extension-point and hook-kind cells are \`—\`. A host that is *also* a reviewer (Claude, Codex, Cursor, OpenCode, Qwen, Antigravity) keeps one manifest and diff --git a/scripts/lint-docs-command-form.cjs b/scripts/lint-docs-command-form.cjs new file mode 100644 index 000000000..eaab1a019 --- /dev/null +++ b/scripts/lint-docs-command-form.cjs @@ -0,0 +1,195 @@ +#!/usr/bin/env node +/** + * lint-docs-command-form.cjs + * + * Enforces the human-facing command form in docs/ (#2903). + * + * `/gsd:` (and bare `gsd:`) is a SOURCE-AUTHORING token: install-time + * converters (`transformContentToHyphen`, `convertSlashCommandsToSkillMentions`) + * rewrite it to `/gsd-` per-runtime. It is correct in `commands/gsd/**`, + * `gsd-core/workflows/**`, and `agents/**` — but docs are never passed through a + * converter, so a doc telling a reader to type `/gsd:` names a command no + * runtime registers. The real user-facing form is `/gsd-`. + * + * This guard fails any `docs/**\/*.md` file that still contains `/gsd:` or + * bare `gsd:` where `` is a real command name (drawn from the + * `commands/gsd/*.md` roster). It explicitly permits `/gsd-core:` (the + * Claude Code plugin namespace) and any `gsd:` whose `` is not a + * real command (e.g. the `gsd:section` / `gsd:loop-host` workflow-fragment + * marker syntax documented in docs/reference/workflow-fragments.md, or + * `gsd:command-name` used as a placeholder while explaining the Gemini CLI + * colon-form convention). + * + * Exclusions (never checked): + * - docs/adr/** (historical record) + * - docs/RELEASE-NOTES-LEGACY.md (maintainer question still open) + * - commands/gsd/**, gsd-core/workflows/**, agents/** — never touched by this + * guard at all; the colon form is correct there. + * + * Exemption — `name:` frontmatter key citations: source command files + * (`commands/gsd/*.md`) carry the colon form in their `name:` YAML frontmatter + * key (e.g. `name: gsd:next`). A doc that quotes that key verbatim — e.g. + * `` `name: gsd:next` `` or `name: gsd:next` — is citing the real source file, + * not telling a reader what to type. Rewriting that citation to `gsd-next` + * would make the doc lie about the source it's quoting, so a `gsd:` token + * immediately preceded by `name:` (optionally with a backtick/whitespace in + * between) is permitted. This is narrow: it does not exempt `gsd:` + * anywhere else on the line or file, including the reader-facing `/gsd-` + * form that may appear later in the same sentence. + * + * Detection is case-insensitive (`/GSD:next`, `Gsd:Next`, etc. are all + * flagged) since the install-time converters and runtimes treat command names + * case-insensitively in practice, and a doc typo in casing is still a lie + * about the real command form. + * + * Exit 0 if no violations; exit 1 if any are found (with stderr diagnostics). + */ + +'use strict'; + +const { execFileSync } = require('child_process'); +const fs = require('fs'); +const path = require('path'); +const { ExitError, runMain } = require('./lib/cli-exit.cjs'); + +const SELF_PATH = path.resolve(__filename); +// GSD_LINT_DOCS_COMMAND_FORM_REPO_ROOT is used by tests to redirect the guard to +// a temporary fixture git repo without touching the real working tree. +const REPO_ROOT = process.env.GSD_LINT_DOCS_COMMAND_FORM_REPO_ROOT + ? path.resolve(process.env.GSD_LINT_DOCS_COMMAND_FORM_REPO_ROOT) + : path.resolve(__dirname, '..'); + +const DOCS_PREFIX = 'docs/'; +const ADR_PREFIX = 'docs/adr/'; +const RELEASE_NOTES_LEGACY = 'docs/RELEASE-NOTES-LEGACY.md'; +const COMMANDS_DIR = path.join(REPO_ROOT, 'commands/gsd'); + +// Matches `/gsd:` and bare `gsd:` (not part of `/gsd-core:`, +// which does not contain the substring `gsd:` — the hyphen breaks it). +// Case-insensitive so `/GSD:next` / `Gsd:Next` are also caught. +const COMMAND_FORM_RE = /(^|[^A-Za-z0-9_-])(\/)?gsd:([A-Za-z0-9_-]+)/gi; + +// A `gsd:` token is exempt when it is a citation of a source file's +// YAML `name:` frontmatter key — i.e. the text immediately before the match +// (ending exactly where the match begins) is `name:` followed by optional +// whitespace and/or a backtick. Only applies to the bare (non-`/`) form, +// since the real frontmatter key never carries a leading slash. +const NAME_KEY_CITATION_RE = /name:\s*`?\s*$/i; + +function loadRoster() { + let entries; + try { + entries = fs.readdirSync(COMMANDS_DIR); + } catch (err) { + throw new ExitError(1, 'ERROR lint-docs-command-form: could not read commands/gsd: ' + err.message); + } + return new Set( + entries.filter((f) => f.endsWith('.md')).map((f) => f.replace(/\.md$/, '')), + ); +} + +function isCheckedDocsFile(relPath) { + if (!relPath.startsWith(DOCS_PREFIX)) return false; + if (relPath.startsWith(ADR_PREFIX)) return false; + if (relPath === RELEASE_NOTES_LEGACY) return false; + return relPath.endsWith('.md'); +} + +/** + * Pure scan — no fs, no git. Returns violations for a single file's content. + * + * @param {string} relPath file path (used only in violation records) + * @param {string} content file contents + * @param {Set} roster valid command names + * @returns {Array<{file:string, line:number, col:number, text:string}>} + */ +function scanContent(relPath, content, roster) { + const violations = []; + const lines = content.split('\n'); + for (let i = 0; i < lines.length; i++) { + const line = lines[i]; + COMMAND_FORM_RE.lastIndex = 0; + let match; + while ((match = COMMAND_FORM_RE.exec(line)) !== null) { + const [, pre, slash, cmd] = match; + if (!roster.has(cmd.toLowerCase())) continue; + if (!slash) { + const preContext = line.slice(0, match.index + pre.length); + if (NAME_KEY_CITATION_RE.test(preContext)) continue; + } + const matchedToken = (slash || '') + 'gsd:' + cmd; + violations.push({ + file: relPath, + line: i + 1, + col: match.index + pre.length + 1, + text: matchedToken, + }); + } + } + return violations; +} + +function main() { + const roster = loadRoster(); + + let trackedFiles; + try { + trackedFiles = execFileSync('git', ['ls-files'], { cwd: REPO_ROOT, encoding: 'utf8' }) + .split('\n') + .map((f) => f.trim()) + .filter(Boolean); + } catch (err) { + throw new ExitError(1, 'ERROR lint-docs-command-form: git ls-files failed: ' + err.message); + } + + const docsFiles = trackedFiles.filter(isCheckedDocsFile); + const violations = []; + + for (const relPath of docsFiles) { + const fullPath = path.join(REPO_ROOT, relPath); + if (path.resolve(fullPath) === SELF_PATH) continue; + + let content; + try { + content = fs.readFileSync(fullPath, 'utf8'); + } catch { + // Unreadable/deleted files — skip silently. + continue; + } + + violations.push(...scanContent(relPath, content, roster)); + } + + if (violations.length === 0) { + process.stdout.write( + 'ok lint-docs-command-form: ' + docsFiles.length + ' file(s) checked, 0 violations\n', + ); + return 0; + } + + process.stderr.write('\nERROR lint-docs-command-form: ' + violations.length + ' violation(s) found\n\n'); + for (const v of violations) { + process.stderr.write(' ' + v.file + ':' + v.line + ':' + v.col + ' — ' + JSON.stringify(v.text) + '\n'); + } + process.stderr.write('\n'); + process.stderr.write( + 'Fix: docs are never passed through the install-time slash-form converters, so the\n', + ); + process.stderr.write( + ' colon form names a command no runtime registers. Rewrite to the hyphen form\n', + ); + process.stderr.write( + ' (`/gsd-`), or `/gsd-core:` if this is genuinely the Claude Code\n', + ); + process.stderr.write(' plugin namespace.\n\n'); + return 1; +} + +if (require.main === module) runMain(main); + +module.exports = { + scanContent, + isCheckedDocsFile, + loadRoster, + COMMAND_FORM_RE, +}; diff --git a/tests/lint-docs-command-form.test.cjs b/tests/lint-docs-command-form.test.cjs new file mode 100644 index 000000000..f298cb313 --- /dev/null +++ b/tests/lint-docs-command-form.test.cjs @@ -0,0 +1,213 @@ +'use strict'; + +/** + * TDD tests for scripts/lint-docs-command-form.cjs (#2903). + * + * Uses spawnSync to invoke the guard script against a temporary git repo so + * we can inject fixtures without touching the real repo. Mirrors the fixture + * pattern in tests/lint-legacy-dir-name.test.cjs. + */ + +const { describe, test } = require('node:test'); +const assert = require('node:assert/strict'); +const { spawnSync, execFileSync } = require('node:child_process'); +const fs = require('node:fs'); +const os = require('node:os'); +const path = require('node:path'); + +const GUARD_SCRIPT = path.resolve(__dirname, '..', 'scripts', 'lint-docs-command-form.cjs'); + +function createTempRepo() { + const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-lint-docs-command-form-test-')); + execFileSync('git', ['init', '--initial-branch=main'], { cwd: dir }); + execFileSync('git', ['config', 'user.email', 'test@example.com'], { cwd: dir }); + execFileSync('git', ['config', 'user.name', 'Test'], { cwd: dir }); + // Roster source: the guard reads commands/gsd/*.md filenames as valid + // command names, regardless of tracked/staged status. + writeFile(dir, 'commands/gsd/plan-phase.md', '# plan-phase\n'); + return dir; +} + +function writeFile(dir, relPath, content) { + const fullPath = path.join(dir, relPath); + fs.mkdirSync(path.dirname(fullPath), { recursive: true }); + fs.writeFileSync(fullPath, content, 'utf8'); +} + +function gitAdd(dir, relPath) { + execFileSync('git', ['add', relPath], { cwd: dir }); +} + +function cleanup(dir) { + // eslint-disable-next-line local/no-raw-rmsync-in-tests -- local cleanup in lint test; no helpers import available + fs.rmSync(dir, { recursive: true, force: true }); +} + +function runGuard(cwd) { + return spawnSync(process.execPath, [GUARD_SCRIPT], { + cwd, + encoding: 'utf8', + env: { ...process.env, GSD_LINT_DOCS_COMMAND_FORM_REPO_ROOT: cwd }, + }); +} + +describe('lint-docs-command-form — colon slash form flagged', () => { + test('exits non-zero and names the file when docs contain /gsd:', () => { + const dir = createTempRepo(); + try { + writeFile(dir, 'docs/how-to/example.md', 'Run `/gsd:plan-phase` to start.\n'); + gitAdd(dir, 'commands/gsd/plan-phase.md'); + gitAdd(dir, 'docs/how-to/example.md'); + + const result = runGuard(dir); + assert.notEqual(result.status, 0, `expected non-zero exit, got ${result.status}; stdout: ${result.stdout}`); + assert.ok(result.stderr.includes('docs/how-to/example.md'), `stderr should name the file: ${result.stderr}`); + } finally { + cleanup(dir); + } + }); +}); + +describe('lint-docs-command-form — plugin namespace permitted', () => { + test('exits 0 when docs contain /gsd-core:', () => { + const dir = createTempRepo(); + try { + writeFile(dir, 'docs/how-to/example.md', 'Run `/gsd-core:plan-phase` to start.\n'); + gitAdd(dir, 'commands/gsd/plan-phase.md'); + gitAdd(dir, 'docs/how-to/example.md'); + + const result = runGuard(dir); + assert.equal(result.status, 0, `expected exit 0 for /gsd-core:, got ${result.status}; stderr: ${result.stderr}`); + } finally { + cleanup(dir); + } + }); +}); + +describe('lint-docs-command-form — docs/adr exempt', () => { + test('exits 0 for a fixture under docs/adr/', () => { + const dir = createTempRepo(); + try { + writeFile(dir, 'docs/adr/999-example.md', 'Historically we typed `/gsd:plan-phase`.\n'); + gitAdd(dir, 'commands/gsd/plan-phase.md'); + gitAdd(dir, 'docs/adr/999-example.md'); + + const result = runGuard(dir); + assert.equal(result.status, 0, `expected exit 0 under docs/adr/, got ${result.status}; stderr: ${result.stderr}`); + } finally { + cleanup(dir); + } + }); +}); + +describe('lint-docs-command-form — source trees never checked', () => { + test('exits 0 for a fixture under gsd-core/workflows/ (colon form is correct there)', () => { + const dir = createTempRepo(); + try { + writeFile(dir, 'gsd-core/workflows/example.md', 'Dispatch `/gsd:plan-phase`.\n'); + gitAdd(dir, 'commands/gsd/plan-phase.md'); + gitAdd(dir, 'gsd-core/workflows/example.md'); + + const result = runGuard(dir); + assert.equal(result.status, 0, `expected exit 0 under gsd-core/workflows/, got ${result.status}; stderr: ${result.stderr}`); + } finally { + cleanup(dir); + } + }); +}); + +describe('lint-docs-command-form — bare colon form flagged', () => { + test('exits non-zero when docs contain bare gsd:', () => { + const dir = createTempRepo(); + try { + writeFile(dir, 'docs/how-to/example.md', 'The command is gsd:plan-phase.\n'); + gitAdd(dir, 'commands/gsd/plan-phase.md'); + gitAdd(dir, 'docs/how-to/example.md'); + + const result = runGuard(dir); + assert.notEqual(result.status, 0, `expected non-zero exit, got ${result.status}; stdout: ${result.stdout}`); + assert.ok(result.stderr.includes('docs/how-to/example.md'), `stderr should name the file: ${result.stderr}`); + } finally { + cleanup(dir); + } + }); +}); + +describe('lint-docs-command-form — name: frontmatter key citation exempt', () => { + test('exits 0 when docs quote `name: gsd:next` as a source frontmatter citation', () => { + const dir = createTempRepo(); + try { + writeFile(dir, 'commands/gsd/next.md', '---\nname: gsd:next\n---\n'); + writeFile( + dir, + 'docs/how-to/example.md', + 'Frontmatter:\n- `name: gsd:next` (surfaces as `/gsd-next`)\n', + ); + gitAdd(dir, 'commands/gsd/next.md'); + gitAdd(dir, 'docs/how-to/example.md'); + + const result = runGuard(dir); + assert.equal( + result.status, + 0, + `expected exit 0 for a name: frontmatter citation, got ${result.status}; stderr: ${result.stderr}`, + ); + assert.ok(result.stdout.includes('0 violations'), `stdout: ${result.stdout}`); + } finally { + cleanup(dir); + } + }); +}); + +describe('lint-docs-command-form — name: exemption is narrow, not a blanket hole', () => { + test('exits non-zero when bare gsd:next appears without a preceding name: key', () => { + const dir = createTempRepo(); + try { + writeFile(dir, 'commands/gsd/next.md', '---\nname: gsd:next\n---\n'); + writeFile(dir, 'docs/how-to/example.md', 'Just type gsd:next to run it.\n'); + gitAdd(dir, 'commands/gsd/next.md'); + gitAdd(dir, 'docs/how-to/example.md'); + + const result = runGuard(dir); + assert.notEqual(result.status, 0, `expected non-zero exit, got ${result.status}; stdout: ${result.stdout}`); + assert.ok(result.stderr.includes('docs/how-to/example.md'), `stderr should name the file: ${result.stderr}`); + } finally { + cleanup(dir); + } + }); +}); + +describe('lint-docs-command-form — case-insensitive detection', () => { + test('exits non-zero when docs contain /GSD:next (mixed case)', () => { + const dir = createTempRepo(); + try { + writeFile(dir, 'commands/gsd/next.md', '---\nname: gsd:next\n---\n'); + writeFile(dir, 'docs/how-to/example.md', 'Run `/GSD:next` to start.\n'); + gitAdd(dir, 'commands/gsd/next.md'); + gitAdd(dir, 'docs/how-to/example.md'); + + const result = runGuard(dir); + assert.notEqual(result.status, 0, `expected non-zero exit, got ${result.status}; stdout: ${result.stdout}`); + assert.ok(result.stderr.includes('docs/how-to/example.md'), `stderr should name the file: ${result.stderr}`); + } finally { + cleanup(dir); + } + }); +}); + +describe('lint-docs-command-form — clean docs tree', () => { + test('exits 0 on a clean fixture repo with no colon-form commands', () => { + const dir = createTempRepo(); + try { + writeFile(dir, 'docs/how-to/example.md', 'Run `/gsd-plan-phase` to start.\n'); + gitAdd(dir, 'commands/gsd/plan-phase.md'); + gitAdd(dir, 'docs/how-to/example.md'); + + const result = runGuard(dir); + assert.equal(result.status, 0, `expected exit 0, got ${result.status}; stderr: ${result.stderr}`); + assert.ok(result.stdout.includes('0 violations'), `stdout: ${result.stdout}`); + } finally { + cleanup(dir); + } + }); +}); diff --git a/tests/repo-invariants.test.cjs b/tests/repo-invariants.test.cjs index 2b2e1409f..08ce3b7f8 100644 --- a/tests/repo-invariants.test.cjs +++ b/tests/repo-invariants.test.cjs @@ -124,59 +124,29 @@ describe('ESLint coverage tracks the bin/lib TS migration (ADR-457 / #537)', () // ──────────────────────────────────────────────────────────────────────── -// Folded from tests/bug-3054-stale-gsd-next-references.test.cjs — consolidation epic #1969 (B8 #1977) +// RETIRED: folded:bug-3054-stale-gsd-next-references (consolidation epic #1969 B8 #1977) // ──────────────────────────────────────────────────────────────────────── -{ - const { describe: __foldDescribe } = require('node:test'); - __foldDescribe("folded:bug-3054-stale-gsd-next-references (consolidation epic #1969 B8 #1977)", () => { -'use strict'; - -const { test, describe } = require('node:test'); -const assert = require('node:assert/strict'); -const fs = require('node:fs'); -const path = require('node:path'); - -function walkMd(dir, out = []) { - if (!fs.existsSync(dir)) return out; - for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { - const full = path.join(dir, entry.name); - if (entry.isDirectory()) walkMd(full, out); - else if (entry.name.endsWith('.md')) out.push(full); - } - return out; -} - -function extractSlashCommandTokens(markdown) { - const tokenRe = /\/gsd-[a-z0-9-]+/gi; - const tokens = new Set(); - let m; - while ((m = tokenRe.exec(markdown)) !== null) { - tokens.add(m[0]); - } - return tokens; -} - -describe('bug #3054: user-facing docs should not reference removed /gsd-next command', () => { - test('docs, workflows, and README surfaces use /gsd-progress --next instead', () => { - const root = path.join(__dirname, '..'); - const files = [ - ...walkMd(path.join(root, 'docs')), - ...walkMd(path.join(root, 'gsd-core', 'workflows')), - ...fs.readdirSync(root).filter((f) => /^README.*\.md$/.test(f)).map((f) => path.join(root, f)), - ]; - - const offenders = []; - for (const file of files) { - const content = fs.readFileSync(file, 'utf8'); - const tokens = extractSlashCommandTokens(content); - if (tokens.has('/gsd-next')) offenders.push(path.relative(root, file)); - } - - assert.deepStrictEqual(offenders, [], `stale /gsd-next references remain in: ${offenders.join(', ')}`); - }); -}); - }); -} +// +// This invariant used to fail any docs/workflows/README file that contained +// the literal string `/gsd-next`, on the premise that `/gsd-next` named a +// RETIRED workflow-advance command and any occurrence was a stale reference +// that should have read `/gsd-progress --next` instead. +// +// That premise is now obsolete. #2903 established that human-facing docs +// must use the hyphen command form (`/gsd-`), and the maintainer +// resolved the #3054-vs-#2903 conflict in favor of retiring this invariant +// (option B) rather than exempting `next` from the #2903 sweep (option A): +// `/gsd-next` no longer names the retired workflow-advance command — it is +// the correct, live, user-facing name for the state-aware smart-entry +// launcher (`commands/gsd/next.md`), exactly as documented by +// `docs/FEATURES.md`'s REQ-CONSOLIDATE-03 ("`/gsd-next` is not the retired +// workflow-advance command; it is reserved for the state-aware smart-entry +// launcher. Workflow advancement remains under `/gsd-progress --next`."). +// +// Keeping this scan alive would now contradict the documented command form: +// it would fail the build the moment `/gsd-next` legitimately appears in +// docs, which #2903 requires everywhere `next` is referenced. See #3054, +// #2903, and docs/FEATURES.md REQ-CONSOLIDATE-03. // ────────────────────────────────────────────────────────────────────────