Merge pull request #662 from open-gsd/release/1.3.0

chore: merge release v1.3.0 to main

.changeset/245-summary-rescue-copy-failure.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 616
+---
+**`worktree.cleanup-wave` no longer silently loses a SUMMARY.md when the rescue copy fails** — a failed `*SUMMARY.md` rescue now blocks cleanup with `summary_rescue_failed` instead of merging and removing the worktree, preventing silent data loss.

.changeset/384-agents-dir-runtime-aware.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 617
+---
+**`/gsd:init` no longer reports agents as missing on OpenCode and other non-Claude runtimes** — `getAgentsDir()` now resolves the per-runtime global config directory instead of always checking the Claude path, and init diagnostics surface `agent_runtime` and `agents_dir`.

.changeset/549-total-phases-decimal-overcounting.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 549
+---
+State progress writer no longer over-counts `total_phases` by 1 when the ROADMAP contains a non-phase section heading (e.g. `## Phase Overview:`) that matched the looser regex in `getMilestonePhaseFilter`. Both `buildStateFrontmatter` and `cmdStateSync` now source `total_phases` from the same digit-anchored phase-heading pattern used by `roadmap.analyze` — single source of truth.

.changeset/557-details-summary-milestone-strip.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 557
+---
+**Milestone marked complete while ROADMAP lists unstarted phases** — `extractCurrentMilestone()` had two miss paths that caused it to fall through to `stripShippedMilestones()`: (1) `sectionPattern` only matched `##`/`###` headings, so when a milestone version appeared exclusively inside a `<summary>` tag the section was not found; (2) `activeMarkerPattern` and the Step 2 fallback regex did not include `🔄`, so milestones using that emoji as the in-progress marker were not recognised. Both misses caused `stripShippedMilestones()` to erase the active `<details open>` block, leaving `roadmap.analyze` with `phase_count: 0`. Fixes: (a) `<summary>` tag content is now searched when heading matches are absent; (b) `🔄` is added to `activeMarkerPattern` and the fallback emoji regex; (c) `cmdMilestoneComplete` now guards against completing when STATE confirms the current milestone still has phases with no directory on disk; (d) `validate health` emits W021 when STATE says milestone complete but ROADMAP lists unstarted phases. (#557)

.changeset/566-spawn-liveness-banner.md

@@ -0,0 +1,5 @@
+---
+type: Changed
+pr: 566
+---
+**Spawn announcements now include a liveness note** — every `◆ Spawning …` line and subagent dispatch instruction across all 26+ GSD workflows now carries the canonical phrase `runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze`. Silent subagents are visually identical to frozen sessions; this inline note sets the expectation so users wait instead of interrupting. Documented in `references/ui-brand.md § Spawning Indicators`, enforced by `tests/spawn-liveness-banner.test.cjs`, and explained in `docs/USER-GUIDE.md § Troubleshooting`.

.changeset/604-rename-get-shit-done-to-gsd-core.md

@@ -0,0 +1,7 @@
+---
+type: Changed
+pr: 604
+---
+
+**Installer migration 003 removes stale legacy runtime directory files on upgrade** — the installed runtime config subdirectory was renamed from `~/.claude/get-shit-done/` to `~/.claude/gsd-core/` in #604. <!-- gsd-allow-legacy-name -->
+Installer migration `2026-06-02-rename-get-shit-done-to-gsd-core` now removes managed files from the stale legacy directory once `gsd-core/` is confirmed present, preserving any user-added files under the old path. Emptied subdirectory shells may remain on disk (the migration framework operates per-file, not per-directory). The npm package name and binary entrypoints are unchanged.

.changeset/614-discuss-phase-shim-resolution.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 618
+---
+**`/gsd-discuss-phase` now honors `workflow.discuss_mode: assumptions` on shim-only installs** — mode routing resolves `gsd-tools` via the runtime shim instead of the bare PATH command, so a missing PATH binary no longer silently falls back to standard discuss mode.

.changeset/calm-cranes-roar.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 583
+---
+**Local-install `.sh` hooks no longer fail on Claude Code/Windows** — on a local install, managed `.sh` hooks (`gsd-session-state.sh`, `gsd-validate-commit.sh`, `gsd-graphify-update.sh`, `gsd-phase-boundary.sh`) were emitted wrapped with the absolute Git Bash path. Because Claude Code runs the hook command string inside Git Bash, the explicit `bash.exe` became the binary bash tried to exec → `cannot execute binary file` on every hook event. The local path now drops the `bash.exe` wrapper and emits the `$CLAUDE_PROJECT_DIR`-anchored script path, matching the global install path's #166/#377 guard. (#580)

.changeset/clever-deer-wander.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 640
+---
+**`gsd-tools query summary-extract` no longer drops snake_case `requirements_completed`** — the reader now accepts both the kebab `requirements-completed` and the snake `requirements_completed` key forms (the snake form is what the tool's own JSON output and the milestone audit `--pick` emit), so a round-tripped requirements field is no longer silently read back as empty.

.changeset/code-review-flags-ts-migration.md

@@ -0,0 +1,7 @@
+---
+type: Changed
+pr: 537
+---
+Migrate code-review-flags to a TypeScript source of truth (`src/code-review-flags.cts`), compiled to a gitignored `.cjs` build artifact per ADR-457 (#537). Behaviour is preserved byte-for-behaviour from the prior hand-written `.cjs`; adds compile-time type checking via strict TypeScript with `CodeReviewFlags` interface and `CodeReviewWorkflow` union type.
+
+<!-- docs-exempt: Internal build-at-publish source migration (ADR-457). The hand-written .cjs is collapsed to a TS source compiled to a behaviourally-identical gitignored artifact at the same require() path. No user-facing command, output, behaviour, or configuration change. -->

.changeset/code-review-leaf-batch-1-ts.md

@@ -0,0 +1,7 @@
+---
+type: Changed
+pr: 537
+---
+Migrate 9 pure leaf modules from hand-written CommonJS to TypeScript source of truth per ADR-457 (#537). Modules migrated: `context-utilization`, `artifacts`, `command-arg-projection`, `clock`, `ui-safety-gate`, `review-reviewer-selection`, `clusters`, `installer-migrations/001-legacy-orphan-files`, and `observability/redaction`. Each `src/<m>.cts` compiles to a gitignored `get-shit-done/bin/lib/<m>.cjs` with behaviour preserved byte-for-behaviour; only types are added. A minimal `src/node-globals.d.ts` ambient declaration covers `process`, `require`, and `module` globals for modules that use them (since `"types": []` is set in `tsconfig.build.json`).
+
+<!-- docs-exempt: Internal ADR-457 build-at-publish source migration; hand-written .cjs collapsed to TS sources compiled to behaviourally-identical gitignored artifacts at the same require() paths. No user-facing change. -->

.changeset/curious-lynx-travel.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 635
+---
+**`/gsd-plan-phase` gap-analysis no longer reports the tool as "not found" on non-default installs** — the post-planning-gaps step now resolves `gsd-tools` through the workflow's `gsd_run` launcher instead of a hardcoded `$HOME/.claude/...` path, so it works under relocated/global installs and non-Claude runtimes instead of silently falling back to a frontmatter-only coverage check.

.changeset/daring-yaks-zip.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 538
+---
+**`/gsd-plan-phase` §13e post-planning gap analysis now scopes to the phase's mapped REQ-IDs** — a phase that maps no requirements (`phase_req_ids` null/TBD) no longer reports every unrelated project requirement as "not covered". CONTEXT.md decisions remain in scope. Mapped REQ-IDs that are listed in the roadmap but absent from `REQUIREMENTS.md` are now surfaced as explicit "⚠ Missing from REQUIREMENTS.md" rows instead of being silently dropped, preventing false "all covered" reports when the requirements document has drifted.

.changeset/feat-41-ship-tdd-audit.md

@@ -0,0 +1,7 @@
+---
+type: Added
+pr: 585
+---
+**`/gsd-ship` PR bodies now include a TDD Audit section** — `generate_pr_body` walks the `merge-base..HEAD` commit range (merges excluded), reads each commit's `gate_status:` Git trailer (`skill` | `fallback` | `exempt`), pairs each `test:` commit with its following `feat:`/`fix:` implementation commit in a table, and counts commits without a recognized trailer as `missing`.
+
+A single aggregate `gate_status: skill=N, fallback=N, exempt=N, missing=N` trailer is emitted as the final line of the PR body, so a GitHub squash-merge carries the per-phase TDD audit footprint into the base branch instead of losing it with the deleted PR branch.

.changeset/fierce-finches-munch.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 613
+---
+**Fresh installs now ship `managed-hooks-registry.cjs` next to `gsd-check-update-worker.js`, so the background update checker no longer crashes silently (#606)** — the worker `require()`s that sibling, but it had been missing from the hooks copy allowlist, so on a clean install the worker threw `Cannot find module` in the background and the update cache was never written. The file is now in the allowlist, and a regression guard asserts that every same-directory `require()` target of a shipped hook is itself shipped. Thanks @baksohyeon for the clean-room reproduction.

.changeset/fierce-rams-rest.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 488
+---
+Add gsd-tools effort sync command to re-apply effort config changes to installed agents without a full reinstall

.changeset/graceful-quails-hop.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 598
+---
+**`gsd-phase-researcher` no longer fails to write `RESEARCH.md` on OpenCode** — large research files that previously hit `JSON parsing failed: Expected '}'` and a retry doom-loop now write reliably. The agent keeps its single-write default and falls back to incremental section-by-section writes only when a runtime truncates an oversized tool call.

.changeset/happy-herons-snooze.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 560
+---
+execute-phase no longer accepts 'approved' at the human_needed checkpoint as a substitute for actual verification — the phase stays pending until /gsd:verify-work completes the UAT.

.changeset/lively-newts-romp.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 539
+---
+**UI Design Contract gate no longer silently no-ops in installed projects** — `/gsd-plan-phase` §5.6 and the autonomous workflow now resolve `ui-safety-gate.cjs` against the GSD install dir (`RUNTIME_DIR`) instead of the consuming project's git root, so frontend phases correctly trigger the UI-SPEC prompt. `ui-safety-gate.cjs` is now also deployed to `get-shit-done/bin/lib/` (the path the GSD installer copies to `$RUNTIME_DIR`) and probed there first, ensuring it is found in installed runtimes where root `bin/lib/` is not present.

.changeset/lucid-docs-rebrand.md

@@ -0,0 +1,5 @@
+---
+type: Changed
+pr: 605
+---
+**Public documentation rebranded to GSD Core and restructured around Diataxis** — the root README and `docs/` are reorganised into tutorials, how-to guides, reference, and explanation, with new how-to guides, schema references (STATE.md / CONTEXT.md / PLAN.md / planning artifacts), and full cross-linking; legacy `gsd-build` references are updated to `open-gsd`, and the localised doc trees (ja-JP, ko-KR, pt-BR, zh-CN) are regenerated to match. Internal filesystem paths are unchanged. (#605)

.changeset/migration-batch-10-ts.md

@@ -0,0 +1,7 @@
+---
+type: Changed
+pr: 537
+---
+Migrate 9 modules from hand-written CommonJS to TypeScript source of truth per ADR-457 (#537). Modules migrated: `phases-command-router`, `verify-command-router`, `init-command-router`, `agent-command-router`, `task-command-router`, `validate-command-router`, `workstream-inventory`, `roadmap-command-router`, and `state-command-router`. Each `src/<m>.cts` compiles to a gitignored `get-shit-done/bin/lib/<m>.cjs` with behaviour preserved byte-for-behaviour; only strict types are added.
+
+<!-- docs-exempt: Internal ADR-457 build-at-publish source migration; behaviourally-identical gitignored artifacts at same require() paths; no user-facing change. -->

.changeset/migration-batch-11-ts.md

@@ -0,0 +1,7 @@
+---
+type: Changed
+pr: 537
+---
+Migrate 7 modules from hand-written CommonJS to TypeScript source of truth per ADR-457 (#537). Modules migrated: `gap-checker`, `docs`, `check-command-router`, `frontmatter`, `learnings`, `gsd2-import`, and `profile-pipeline`. Each `src/<m>.cts` compiles to a gitignored `get-shit-done/bin/lib/<m>.cjs` with behaviour preserved byte-for-behaviour; only strict types are added.
+
+<!-- docs-exempt: Internal ADR-457 build-at-publish source migration; behaviourally-identical gitignored artifacts at same require() paths; no user-facing change. -->

.changeset/migration-batch-12-ts.md

@@ -0,0 +1,7 @@
+---
+type: Changed
+pr: 537
+---
+Migrate 2 modules from hand-written CommonJS to TypeScript source of truth per ADR-457 (#537). Modules migrated: `config` and `profile-output`. Each `src/<m>.cts` compiles to a gitignored `get-shit-done/bin/lib/<m>.cjs` with behaviour preserved byte-for-behaviour; only strict types are added. Note: `cmdMigrateConfig` async dropped (migrateOnDisk is synchronous; caller's `await` is safe on a sync return value).
+
+<!-- docs-exempt: Internal ADR-457 build-at-publish source migration; behaviourally-identical gitignored artifacts at same require() paths; no user-facing change. -->

.changeset/migration-batch-13-ts.md

@@ -0,0 +1,7 @@
+---
+type: Changed
+pr: 537
+---
+Migrate 5 modules from hand-written CommonJS to TypeScript source of truth per ADR-457 (#537). Modules migrated: `template`, `uat`, `workstream`, `roadmap`, and `audit`. Each `src/<m>.cts` compiles to a gitignored `get-shit-done/bin/lib/<m>.cjs` with behaviour preserved byte-for-behaviour; only strict types are added.
+
+<!-- docs-exempt: Internal ADR-457 build-at-publish source migration; behaviourally-identical gitignored artifacts at same require() paths; no user-facing change. -->

.changeset/migration-batch-14-ts.md

@@ -0,0 +1,7 @@
+---
+type: Changed
+pr: 537
+---
+Migrate 2 hub modules from hand-written CommonJS to TypeScript source of truth per ADR-457 (#537). Modules migrated: `commands` (~1305 LOC, 17 exported functions including `cmdCommit`, `cmdStats`, `cmdWebsearch`, `cmdEffortSync`, etc.) and `state` (~2074 LOC, 28 exported functions including `readModifyWriteStateMd`, `acquireStateLock`, `cmdStateBeginPhase`, `cmdStateSync`, etc.). Each `src/<m>.cts` compiles to a gitignored `get-shit-done/bin/lib/<m>.cjs` with behaviour preserved byte-for-behaviour; only strict types are added.
+
+<!-- docs-exempt: Internal ADR-457 build-at-publish source migration; behaviourally-identical gitignored artifacts at same require() paths; no user-facing change. -->

.changeset/migration-batch-15-ts.md

@@ -0,0 +1,7 @@
+---
+type: Changed
+pr: 537
+---
+Migrate 3 modules from hand-written CommonJS to TypeScript source of truth per ADR-457 (#537). Modules migrated: `phase` (~1608 LOC, 11 exported functions including `cmdPhasesList`, `cmdPhaseAdd`, `cmdPhaseInsert`, `cmdPhaseRemove`, `cmdPhaseComplete`, `computeDependencyLevels`, etc.), `verify` (~1615 LOC, 12 exported functions including `cmdValidateHealth`, `cmdValidateConsistency`, `cmdVerifyCodebaseDrift`, `cmdVerifySchemaDrift`, `cmdValidateAgents`, etc.), and `init` (~2113 LOC, 20 exported functions including `cmdInitExecutePhase`, `cmdInitPlanPhase`, `cmdInitManager`, `cmdInitProgress`, `cmdAgentSkills`, `buildSkillManifest`, etc.). Also adds `src/package-identity.d.cts` declaration file for the permanently hand-written `package-identity.cjs` module so strict `.cts` sources can import it under nodenext moduleResolution. Each `src/<m>.cts` compiles to a gitignored `get-shit-done/bin/lib/<m>.cjs` with behaviour preserved byte-for-behaviour; only strict types are added.
+
+<!-- docs-exempt: Internal ADR-457 build-at-publish source migration; behaviourally-identical gitignored artifacts at same require() paths; no user-facing change. -->

.changeset/migration-batch-2-ts.md

@@ -0,0 +1,7 @@
+---
+type: Changed
+pr: 537
+---
+Migrate 10 modules from hand-written CommonJS to TypeScript source of truth per ADR-457 (#537). Modules migrated: `installer-migration-report` (Group A), `prompt-budget` (Group A), `secrets` (Group B), `phase-lifecycle` (Group B), `workstream-name-policy` (Group B), `decisions` (Group B), `validate` (Group B), `schema-detect` (Group B), `runtime-name-policy` (Group C), and `runtime-slash` (Group C — first cross-module TS import, depends on `runtime-name-policy`). Each `src/<m>.cts` compiles to a gitignored `get-shit-done/bin/lib/<m>.cjs` with behaviour preserved byte-for-behaviour; only strict types are added. Group B entries removed from `tsconfig.lint.json` excludes now that they are first-class TypeScript.
+
+<!-- docs-exempt: Internal ADR-457 build-at-publish source migration; behaviourally-identical gitignored artifacts at same require() paths; no user-facing change. -->

.changeset/migration-batch-3-ts.md

@@ -0,0 +1,7 @@
+---
+type: Changed
+pr: 537
+---
+Migrate 10 more `get-shit-done/bin/lib` runtime modules to TypeScript sources of truth (ADR-457 build-at-publish, batch 3): event, workstream-inventory-builder, plan-scan, fallow-runner, project-root, installer-migration-authoring, update-context, 000-first-time-baseline, runtime-homes, model-catalog. Each moves to `src/*.cts` (strict TS), compiled by `tsc` to a gitignored `.cjs` at the same `require()` path; behaviour preserved byte-for-behaviour.
+
+<!-- docs-exempt: Internal ADR-457 build-at-publish source migration; behaviourally-identical gitignored artifacts at same require() paths; no user-facing change. -->

.changeset/migration-batch-4-ts.md

@@ -0,0 +1,7 @@
+---
+type: Changed
+pr: 537
+---
+Migrate 5 modules from hand-written CommonJS to TypeScript source of truth per ADR-457 (#537). Modules migrated: `configuration`, `state-document`, `shell-command-projection`, `security`, and `command-aliases`. Each `src/<m>.cts` compiles to a gitignored `get-shit-done/bin/lib/<m>.cjs` with behaviour preserved byte-for-behaviour; only strict types are added. The three modules previously in `tsconfig.lint.json` excludes (`configuration`, `state-document`, `command-aliases`) are now removed from that list.
+
+<!-- docs-exempt: Internal ADR-457 build-at-publish source migration; behaviourally-identical gitignored artifacts at same require() paths; no user-facing change. -->

.changeset/migration-batch-5-ts.md

@@ -0,0 +1,7 @@
+---
+type: Changed
+pr: 537
+---
+Migrate 6 modules from hand-written CommonJS to TypeScript source of truth per ADR-457 (#537). Modules migrated: `config-schema`, `model-profiles`, `installer-migrations/002-codex-legacy-hooks-json`, `observability/logger`, `active-workstream-store`, and `adr-parser`. Each `src/<m>.cts` compiles to a gitignored `get-shit-done/bin/lib/<m>.cjs` with behaviour preserved byte-for-behaviour; only strict types are added.
+
+<!-- docs-exempt: Internal ADR-457 build-at-publish source migration; behaviourally-identical gitignored artifacts at same require() paths; no user-facing change. -->

.changeset/migration-batch-6-ts.md

@@ -0,0 +1,7 @@
+---
+type: Changed
+pr: 537
+---
+Migrate 5 modules from hand-written CommonJS to TypeScript source of truth per ADR-457 (#537). Modules migrated: `graphify`, `install-profiles`, `intel`, `installer-migrations`, and `worktree-safety`. Each `src/<m>.cts` compiles to a gitignored `get-shit-done/bin/lib/<m>.cjs` with behaviour preserved byte-for-behaviour; only strict types are added.
+
+<!-- docs-exempt: Internal ADR-457 build-at-publish source migration; behaviourally-identical gitignored artifacts at same require() paths; no user-facing change. -->

.changeset/migration-batch-7-ts.md

@@ -0,0 +1,7 @@
+---
+type: Changed
+pr: 537
+---
+Migrate 4 modules from hand-written CommonJS to TypeScript source of truth per ADR-457 (#537). Modules migrated: `planning-workspace`, `runtime-artifact-layout`, `command-routing-hub`, and `drift`. Each `src/<m>.cts` compiles to a gitignored `get-shit-done/bin/lib/<m>.cjs` with behaviour preserved byte-for-behaviour; only strict types are added.
+
+<!-- docs-exempt: Internal ADR-457 build-at-publish source migration; behaviourally-identical gitignored artifacts at same require() paths; no user-facing change. -->

.changeset/migration-batch-8-ts.md

@@ -0,0 +1,7 @@
+---
+type: Changed
+pr: 537
+---
+Migrate 4 modules from hand-written CommonJS to TypeScript source of truth per ADR-457 (#537). Modules migrated: `cjs-command-router-adapter`, `phase-command-router`, `surface`, and `roadmap-upgrade`. Each `src/<m>.cts` compiles to a gitignored `get-shit-done/bin/lib/<m>.cjs` with behaviour preserved byte-for-behaviour; only strict types are added.
+
+<!-- docs-exempt: Internal ADR-457 build-at-publish source migration; behaviourally-identical gitignored artifacts at same require() paths; no user-facing change. -->

.changeset/migration-core-ts.md

@@ -0,0 +1,7 @@
+---
+type: Changed
+pr: 537
+---
+Migrate `core` (the most depended-upon module, ~68 internal dependents) from hand-written CommonJS to TypeScript source of truth per ADR-457 (#537). `src/core.cts` compiles to a gitignored `get-shit-done/bin/lib/core.cjs` with behaviour preserved byte-for-behaviour; only strict types are added.
+
+<!-- docs-exempt: Internal ADR-457 build-at-publish source migration; behaviourally-identical gitignored artifact at same require() path; no user-facing change. -->

.changeset/migration-finalize-ts.md

@@ -0,0 +1,7 @@
+---
+type: Changed
+pr: 537
+---
+Finalize the ADR-457 `bin/lib` TypeScript migration (#537): retire the `tsconfig.lint.json` `checkJs` stopgap now that every hand-written `bin/lib/*.cjs` has been collapsed to a `src/*.cts` source of truth, and treat the tsc-generated `config-types.cjs` as a gitignored build artifact like the rest. `package-identity.cjs` remains value-baked (declared via `src/package-identity.d.cts`).
+
+<!-- docs-exempt: Internal ADR-457 build-at-publish migration finalization; removes an unused stopgap tsconfig and gitignores a generated artifact; no user-facing change. -->

.changeset/migration-milestone-ts.md

@@ -0,0 +1,7 @@
+---
+type: Changed
+pr: 537
+---
+Migrate `get-shit-done/bin/lib/milestone.cjs` to a TypeScript source of truth (`src/milestone.cts`) per ADR-457 build-at-publish; compiled by `tsc` to a gitignored `.cjs` at the same `require()` path. Behaviour preserved byte-for-behaviour. Also relaxes `core`'s `output()` 3rd parameter to optional, matching its real (always-optional) call contract.
+
+<!-- docs-exempt: Internal ADR-457 build-at-publish source migration; behaviourally-identical gitignored artifact at same require() path; no user-facing change. -->

.changeset/nimble-eagles-romp.md

@@ -0,0 +1,5 @@
+---
+type: Changed
+pr: 611
+---
+**Update-check cache is now per-package and lineage-validated, and the installer cleans up leftover `get-shit-done-cc` installs** — after migrating from `get-shit-done-cc` to `@opengsd/gsd-core`, a leftover old install in any runtime dir could write a higher `latest` into the shared update cache and cause a permanent false `⬆ /gsd:update`. The cache now uses a per-package filename (`gsd-update-check-<slug>.json`) carrying a `package_name` lineage field that readers validate, so a different package can no longer poison the indicator (multi-runtime visibility preserved). The installer now auto-detects and removes leftover `get-shit-done-cc` artifacts across runtime config dirs on every install; a new `--dry-run` flag previews the cleanup plan without modifying anything. `/gsd:update` clears the cache for all 15 supported runtimes. See the new how-to: docs/cleanup-get-shit-done-cc.md.

.changeset/patient-voles-swim.md

@@ -0,0 +1,5 @@
+---
+type: Added
+pr: 553
+---
+**Antigravity CLI (`agy`) peer reviewer in `/gsd-review`** — `--agy` / `--antigravity` flag invokes `agy -p` and produces an `## Antigravity Review` section in REVIEWS.md. Auto-detected by `--all`. Preserves Google-family adversarial review coverage after Gemini CLI's free-tier retirement on 2026-06-18. Windows support included via transcript fallback (no extra tooling required).

.changeset/plucky-cats-purr.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 579
+---
+Worktree executor agents no longer leak writes to the main checkout: a new PreToolUse hook (gsd-worktree-path-guard.js) hard-blocks Edit/Write/MultiEdit calls whose absolute path resolves outside the active worktree root.

.changeset/plucky-herons-sing.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 643
+---
+**Wave-cleanup no longer refuses merge-back for an orchestrator running from a non-primary worktree** — the two `execute-phase` wave-cleanup guards now pin to the dispatch-time orchestrator root persisted in `WAVE_WORKTREE_MANIFEST`, instead of `git worktree list`'s first entry (always the main checkout). A per-phase-lane orchestrator with `workflow.use_worktrees: true` is no longer cd'd off its own branch into the #3174 branch-drift assertion at cleanup. Byte-identical for a primary-worktree orchestrator. Follow-up to #590.

.changeset/plucky-yaks-forage.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 577
+---
+effort.agent_overrides and effort.default in config-defaults.manifest.json now fall back correctly when no project-level effort config exists

.changeset/quick-pumas-fly.md

@@ -0,0 +1,5 @@
+---
+type: Changed
+pr: 591
+---
+**`gsd-roadmapper` granularity defaults tightened to reduce thin-phase fragmentation.** Coarse 3-5 -> 2-4, Standard 4-6 (was 5-8), Fine 6-10 (was 8-12). New inline guidance below the Granularity Calibration table names the thin-phase failure pattern (single requirement, internal-quality goal, task-shaped success criteria) and instructs the agent to fold into the most-related neighbor rather than create a standalone phase. Affects `/gsd-new-project`, `/gsd-new-milestone`, and `/gsd-plan-milestone-gaps`.

.changeset/quick-quails-wake.md

@@ -0,0 +1,5 @@
+---
+type: Changed
+pr: 590
+---
+**Worktree base checks are now verify-only and fail-closed** — a GSD executor sub-agent no longer runs `git reset --hard` to self-correct a mismatched worktree base (which could fail silently under a `git reset --hard` deny rule and risk a wrong-base merge of unrelated files). On a base or HEAD-namespace mismatch the sub-agent now halts with `exit 42` and hands recovery to the orchestrator (the worktree lifecycle owner). The orchestrator also guards against cwd drift into an agent worktree at `execute_waves` entry.

.changeset/rapid-dogs-run.md

@@ -0,0 +1,5 @@
+---
+type: Added
+pr: 595
+---
+**Per-phase granularity overrides (`granularities.<phaseType>`)** — planning granularity can now be set per phase type (planning/discuss/research/execution/verification/completion) to override the global `granularity`, mirroring `models.<phaseType>`. Resolve with `gsd-tools query resolve-granularity <phaseType>`.

.changeset/rapid-voles-hop.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 634
+---
+**`/gsd-graphify build` no longer fails when the graph is too large for an HTML visualization** — when a graph exceeds graphify's HTML viz node limit (default 5000) the `graph.html` artifact is intentionally skipped; the build pipeline now tolerates its absence instead of aborting, so `graph.json`, `GRAPH_REPORT.md`, the diff snapshot, and the status report all still complete.

.changeset/ship-verification-actionable.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 650
+---
+**ship now tells you how to clear a blocked verification** — the `PHASE_VERIFICATION_INCOMPLETE` block names the exact next action per status (`gaps_found`, `human_needed`, or missing), and the dead `pass` status arm is gone.

.changeset/silly-jaguars-swim.md

@@ -0,0 +1,5 @@
+---
+type: Added
+pr: 49
+---
+Add `model_policy` config surface with known-provider presets (openai/anthropic/google/qwen) and `generic` provider escape hatch. `model_policy.runtime_tiers` resolves before legacy `model_profile_overrides`. `reasoning_effort` is stripped for unsupported runtimes.

.changeset/silly-orcas-dance.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 645
+---
+**Post-execution codebase-drift detection no longer silently disables itself on shim-only installs** — `codebase-drift-gate` now resolves `gsd-tools` through the runtime shim launcher (`gsd_run`) instead of the bare PATH binary, which exited 127 (hidden by `2>/dev/null`) and marked the gate skipped whenever `gsd-tools` wasn't on `PATH`. The gate remains fully non-blocking.

.changeset/silly-seals-parade.md

@@ -0,0 +1,5 @@
+---
+type: Added
+pr: 576
+---
+**Vertical MVP Slice mode shipped** — `/gsd-plan-phase --mvp` organizes tasks as vertical feature slices (UI→API→DB) instead of horizontal layers; `--mvp --tdd` produces slices where every behavior-adding task starts with a failing test; `**Mode:** mvp` in ROADMAP.md auto-applies without the flag; `/gsd-mvp-phase <N>` guides story capture + SPIDR splitting + mode persistence; Walking Skeleton fires on Phase 1 of a new project; `verify-phase` generates user-flow-first UAT for MVP phases; `new-project` offers Vertical MVP vs Horizontal Layers mode choice. Also fixes a silent bug where `--tdd` on the CLI was a no-op (TDD_MODE was config-only; now the flag sets TDD_MODE directly).

.changeset/steady-geese-hum.md

@@ -0,0 +1,5 @@
+---
+type: Changed
+pr: 589
+---
+Consolidated the worktree_branch_check safety guard into a single canonical fragment (get-shit-done/references/worktree-branch-check.md) shared by all worktree-spawning workflows, replacing five divergent copies. No change to guard behavior.

.changeset/steady-jays-sing.md

@@ -0,0 +1,5 @@
+---
+type: Security
+pr: 572
+---
+Hardened resolveModelPolicy against prototype pollution: Object.hasOwn guards now block \_\_proto\_\_ / constructor keys in user-supplied provider/budget/runtime_tiers from reaching inherited prototype slots. Also fixed resolveModelForTier to check model_policy before dynamic_routing so provider presets are not silently bypassed when dynamic routing is enabled.

.changeset/steady-pandas-purr.md

@@ -0,0 +1,5 @@
+---
+type: Added
+pr: 565
+---
+**Milestone-prefixed phase ID convention (`Phase M-NN`) with migration tool and validation** — introduces globally unique phase IDs within a project, resolving cross-session reference ambiguity behind bugs #3537/#3287/#3297/#3298. Adds `getMilestoneFromPhaseId()` / `getPhaseDirFromPhaseId()` helpers to `core.cjs`, fixes `isDirInMilestone` to correctly match `GSD-02-01-setup` style dirs, extends heading regex to tolerate `[bracket-token]` scope prefixes, adds W021 validation rule for milestone-prefix mismatch, adds `gsd-tools roadmap validate` and `roadmap upgrade --convention milestone-prefixed` commands, and introduces the `phase_id_convention` config field (`null` default, fully backwards-compatible). Closes #39.

.changeset/sturdy-pumas-sing.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 571
+---
+gsd-doc-writer fix mode now uses the Edit tool for surgical corrections instead of Write. Previously, the fix_loop in docs-update.md could call gsd-doc-writer in fix mode with Write, truncating an untracked doc to a single line with no git recovery path. Adds a post-fix line-count guard in fix_loop that restores from pre-fix content if >90% shrinkage is detected.

.changeset/sturdy-writers-survive.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 599
+---
+**Large-file GSD writer agents no longer fail to write their output on OpenCode** — `gsd-research-synthesizer`, `gsd-planner`, `gsd-executor`, `gsd-domain-researcher`, `gsd-project-researcher`, and `gsd-ui-researcher` now carry the same truncation-resilient write contract added for `gsd-phase-researcher` in #214. Each keeps its single-write default and falls back to an incremental, sentinel-based Write→Read→Edit sequence only when a runtime truncates an oversized tool call (upstream opencode#18108), instead of doom-looping on `JSON parsing failed: Expected '}'`.

.changeset/sunny-lynx-rally.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 570
+---
+Codex leak scanner now reads gsd-file-manifest.json to scope path checks to GSD-owned files only; bare ~/.claude (no trailing slash) is now replaced in converted Codex markdown; writeManifest now records agents/gsd-*.toml so the manifest-scoped scanner covers them

.changeset/tidy-goats-cheer.md

@@ -0,0 +1,5 @@
+---
+type: Changed
+pr: 541
+---
+Runtime `bin/lib` modules can now be authored as TypeScript and compiled to CommonJS via `tsc` (ADR-457 build-at-publish pilot). The first module, `semver-compare`, moves to `src/semver-compare.cts`; its `.cjs` is now a generated, gitignored build artifact emitted by `npm run build:lib` (wired into build, pretest, prepare, and prepublishOnly). Behavior is unchanged and the package still ships CommonJS.

.changeset/wise-hawks-bark.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 582
+---
+Six writer agents (`gsd-eval-planner`, `gsd-ai-researcher`, `gsd-domain-researcher`, `gsd-phase-researcher`, `gsd-ui-researcher`, `gsd-debug-session-manager`) now carry `Edit` alongside `Write` in their `tools:` frontmatter, so the Edit-only discipline in their spawn prompts is enforceable. Previously, without `Edit`, they fell back to whole-file `Write` and silently clobbered sibling sections of shared files such as `AI-SPEC.md`. Same bug class as #571 (fixed for `gsd-doc-writer` in #575). See #581.

.changeset/wise-pumas-march.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 557
+---
+**Milestone marked complete while ROADMAP lists unstarted phases** — extractCurrentMilestone() had two miss paths that caused it to fall through to stripShippedMilestones(): (1) sectionPattern only matched ##/### headings so when a milestone version appeared only inside a <summary> tag the section was not found; (2) activeMarkerPattern and the Step 2 fallback regex did not include the 🔄 emoji so milestones using it as the in-progress marker were not recognised. Both misses caused stripShippedMilestones() to erase the active <details open> block, leaving roadmap.analyze with phase_count: 0. Fixes: (a) <summary> tag content is now searched when heading matches are absent; (b) 🔄 is added to activeMarkerPattern and the fallback emoji regex; (c) cmdMilestoneComplete now guards against completing when STATE confirms the current milestone still has phases with no directory on disk; (d) validate health emits W021 when STATE says milestone complete but ROADMAP lists unstarted phases. (#557)

.changeset/wise-yaks-run.md

@@ -0,0 +1,5 @@
+---
+type: Changed
+pr: 562
+---
+/gsd-cleanup now prunes local branches whose upstream is gone — symmetric with delete_branch_on_merge; dry-run is non-side-effecting and current-branch exclusion is explicit in the awk filter

.clinerules

@@ -10,8 +10,8 @@ Do not make direct repo edits. All changes must go through a GSD workflow:
 - `/gsd:verify-work` → verify results
 
 ## Architecture
-- `get-shit-done/bin/lib/` — Core Node.js library (CommonJS .cjs, no external deps)
-- `get-shit-done/workflows/` — Workflow definition files (.md)
+- `gsd-core/bin/lib/` — Core Node.js library (CommonJS .cjs, no external deps)
+- `gsd-core/workflows/` — Workflow definition files (.md)
 - `agents/` — Agent definition files (.md)
 - `commands/gsd/` — Slash command definitions (.md)
 - `tests/` — Test files (.test.cjs, node:test + node:assert)
@@ -24,4 +24,4 @@ Do not make direct repo edits. All changes must go through a GSD workflow:
 
 ## Safety
 - Use `execFileSync` (array args) not `execSync` (string interpolation)
-- Validate user-provided paths with `validatePath()` from `get-shit-done/bin/lib/security.cjs`
+- Validate user-provided paths with `validatePath()` from `gsd-core/bin/lib/security.cjs`

.coderabbit.yaml

@@ -4,7 +4,7 @@
 #
 # Project context: GSD ships a CLI tool + an agent runtime, not a documented
 # public library. We carry rich JSDoc on internal helpers that warrant it
-# (see bin/install.js, get-shit-done/bin/lib/*.cjs) but we do not enforce a
+# (see bin/install.js, gsd-core/bin/lib/*.cjs) but we do not enforce a
 # blanket docstring coverage bar — see issue #2932 for rationale.
 
 reviews:

.githooks/pre-commit

@@ -6,42 +6,42 @@ set -euo pipefail
 GIT_CMD="${GIT_OVERRIDE:-git}"
 NPM_CMD="${NPM_OVERRIDE:-npm}"
 
-if "$GIT_CMD" diff --cached --name-only | grep -Eq "^sdk/src/query/command-manifest\.|^sdk/src/query/command-aliases\.generated\.ts$|^get-shit-done/bin/lib/command-aliases\.cjs$|^sdk/scripts/gen-command-aliases\.ts$"; then
+if "$GIT_CMD" diff --cached --name-only | grep -Eq "^sdk/src/query/command-manifest\.|^sdk/src/query/command-aliases\.generated\.ts$|^gsd-core/bin/lib/command-aliases\.cjs$|^sdk/scripts/gen-command-aliases\.ts$"; then
   "$NPM_CMD" run check:alias-drift
 fi
 
-if "$GIT_CMD" diff --cached --name-only | grep -Eq "^sdk/src/query/state-document\.|^get-shit-done/bin/lib/state-document\.generated\.cjs$|^sdk/scripts/gen-state-document\.ts$|^sdk/scripts/check-state-document-fresh\.mjs$"; then
+if "$GIT_CMD" diff --cached --name-only | grep -Eq "^sdk/src/query/state-document\.|^gsd-core/bin/lib/state-document\.generated\.cjs$|^sdk/scripts/gen-state-document\.ts$|^sdk/scripts/check-state-document-fresh\.mjs$"; then
   "$NPM_CMD" run check:state-document-fresh
 fi
 
-if "$GIT_CMD" diff --cached --name-only | grep -Eq "^sdk/src/configuration/|^sdk/shared/config-(defaults|schema)\.manifest\.json$|^get-shit-done/bin/lib/configuration\.generated\.cjs$|^sdk/scripts/gen-configuration\.mjs$"; then
+if "$GIT_CMD" diff --cached --name-only | grep -Eq "^sdk/src/configuration/|^sdk/shared/config-(defaults|schema)\.manifest\.json$|^gsd-core/bin/lib/configuration\.generated\.cjs$|^sdk/scripts/gen-configuration\.mjs$"; then
   "$NPM_CMD" run check:configuration-fresh
 fi
 
-if "$GIT_CMD" diff --cached --name-only | grep -Eq "^sdk/src/workstream-inventory/|^get-shit-done/bin/lib/workstream-inventory-builder\.generated\.cjs$|^sdk/scripts/gen-workstream-inventory-builder\.mjs$|^sdk/scripts/check-workstream-inventory-builder-fresh\.mjs$"; then
+if "$GIT_CMD" diff --cached --name-only | grep -Eq "^sdk/src/workstream-inventory/|^gsd-core/bin/lib/workstream-inventory-builder\.generated\.cjs$|^sdk/scripts/gen-workstream-inventory-builder\.mjs$|^sdk/scripts/check-workstream-inventory-builder-fresh\.mjs$"; then
   "$NPM_CMD" run check:workstream-inventory-builder-fresh
 fi
 
-if "$GIT_CMD" diff --cached --name-only | grep -Eq "^sdk/src/project-root/|^get-shit-done/bin/lib/project-root\.generated\.cjs$|^sdk/scripts/gen-project-root\.mjs$|^sdk/scripts/check-project-root-fresh\.mjs$"; then
+if "$GIT_CMD" diff --cached --name-only | grep -Eq "^sdk/src/project-root/|^gsd-core/bin/lib/project-root\.generated\.cjs$|^sdk/scripts/gen-project-root\.mjs$|^sdk/scripts/check-project-root-fresh\.mjs$"; then
   "$NPM_CMD" run check:project-root-fresh
 fi
 
-if "$GIT_CMD" diff --cached --name-only | grep -Eq "^sdk/src/query/plan-scan\.ts$|^get-shit-done/bin/lib/plan-scan\.generated\.cjs$|^sdk/scripts/gen-plan-scan\.mjs$|^sdk/scripts/check-plan-scan-fresh\.mjs$"; then
+if "$GIT_CMD" diff --cached --name-only | grep -Eq "^sdk/src/query/plan-scan\.ts$|^gsd-core/bin/lib/plan-scan\.generated\.cjs$|^sdk/scripts/gen-plan-scan\.mjs$|^sdk/scripts/check-plan-scan-fresh\.mjs$"; then
   "$NPM_CMD" run check:plan-scan-fresh
 fi
 
-if "$GIT_CMD" diff --cached --name-only | grep -Eq "^sdk/src/query/secrets\.ts$|^get-shit-done/bin/lib/secrets\.generated\.cjs$|^sdk/scripts/gen-secrets\.mjs$|^sdk/scripts/check-secrets-fresh\.mjs$"; then
+if "$GIT_CMD" diff --cached --name-only | grep -Eq "^sdk/src/query/secrets\.ts$|^gsd-core/bin/lib/secrets\.generated\.cjs$|^sdk/scripts/gen-secrets\.mjs$|^sdk/scripts/check-secrets-fresh\.mjs$"; then
   "$NPM_CMD" run check:secrets-fresh
 fi
 
-if "$GIT_CMD" diff --cached --name-only | grep -Eq "^sdk/src/query/schema-detect\.ts$|^get-shit-done/bin/lib/schema-detect\.generated\.cjs$|^sdk/scripts/gen-schema-detect\.mjs$|^sdk/scripts/check-schema-detect-fresh\.mjs$"; then
+if "$GIT_CMD" diff --cached --name-only | grep -Eq "^sdk/src/query/schema-detect\.ts$|^gsd-core/bin/lib/schema-detect\.generated\.cjs$|^sdk/scripts/gen-schema-detect\.mjs$|^sdk/scripts/check-schema-detect-fresh\.mjs$"; then
   "$NPM_CMD" run check:schema-detect-fresh
 fi
 
-if "$GIT_CMD" diff --cached --name-only | grep -Eq "^sdk/src/query/decisions\.ts$|^get-shit-done/bin/lib/decisions\.generated\.cjs$|^sdk/scripts/gen-decisions\.mjs$|^sdk/scripts/check-decisions-fresh\.mjs$"; then
+if "$GIT_CMD" diff --cached --name-only | grep -Eq "^sdk/src/query/decisions\.ts$|^gsd-core/bin/lib/decisions\.generated\.cjs$|^sdk/scripts/gen-decisions\.mjs$|^sdk/scripts/check-decisions-fresh\.mjs$"; then
   "$NPM_CMD" run check:decisions-fresh
 fi
 
-if "$GIT_CMD" diff --cached --name-only | grep -Eq "^sdk/src/workstream-name-policy\.ts$|^get-shit-done/bin/lib/workstream-name-policy\.generated\.cjs$|^sdk/scripts/gen-workstream-name-policy\.mjs$|^sdk/scripts/check-workstream-name-policy-fresh\.mjs$"; then
+if "$GIT_CMD" diff --cached --name-only | grep -Eq "^sdk/src/workstream-name-policy\.ts$|^gsd-core/bin/lib/workstream-name-policy\.generated\.cjs$|^sdk/scripts/gen-workstream-name-policy\.mjs$|^sdk/scripts/check-workstream-name-policy-fresh\.mjs$"; then
   "$NPM_CMD" run check:workstream-name-policy-fresh
 fi

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -216,8 +216,8 @@ body:
 
         **Useful diagnostics to include (if applicable):**
         - `npm list -g @opengsd/gsd-core` — confirms installed version
-        - `ls -la ~/.claude/get-shit-done/` — confirms installation files (Claude Code)
-        - `cat ~/.claude/get-shit-done/gsd-file-manifest.json` — file manifest for debugging install issues
+        - `ls -la ~/.claude/gsd-core/` — confirms installation files (Claude Code)
+        - `cat ~/.claude/gsd-core/gsd-file-manifest.json` — file manifest for debugging install issues
         - `ls -la .planning/` — confirms planning directory state
 
         **⚠️ PII Warning:** File listings and manifests contain your home directory path. Replace your username with `REDACTED`.

.github/ISSUE_TEMPLATE/enhancement.yml

@@ -105,8 +105,8 @@ body:
         An enhancement should have a narrow, well-defined scope. If your list is long, this might be a feature, not an enhancement.
       placeholder: |
         Files modified:
-        - `get-shit-done/commands/gsd/status.md` — update output format description
-        - `get-shit-done/bin/lib/state.cjs` — expose phase name in status() return value
+        - `gsd-core/commands/gsd/status.md` — update output format description
+        - `gsd-core/bin/lib/state.cjs` — expose phase name in status() return value
         - `tests/status.test.cjs` — update snapshot and add test for phase name in output
         - `CHANGELOG.md` — user-facing change entry
 

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -105,11 +105,11 @@ body:
         If you cannot fill this out, you do not understand the codebase well enough to propose this feature yet.
       placeholder: |
         Files that would be created:
-        - `get-shit-done/commands/gsd/rollback.md` — new slash command definition
+        - `gsd-core/commands/gsd/rollback.md` — new slash command definition
 
         Files that would be modified:
-        - `get-shit-done/bin/lib/state.cjs` — add rollback() function
-        - `get-shit-done/bin/lib/phases.cjs` — expose phase snapshot API
+        - `gsd-core/bin/lib/state.cjs` — add rollback() function
+        - `gsd-core/bin/lib/phases.cjs` — expose phase snapshot API
         - `tests/rollback.test.cjs` — new test file
         - `docs/COMMANDS.md` — document new command
         - `CHANGELOG.md` — entry for this feature

.github/workflows/close-draft-prs.yml

@@ -14,7 +14,10 @@ permissions:
 jobs:
   close-if-draft:
     name: Reject draft PRs
-    if: github.event.pull_request.draft == true
+    # Maintainers may use draft PRs for internal coordination.
+    if: >-
+      github.event.pull_request.draft == true &&
+      contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.pull_request.author_association) == false
     runs-on: ubuntu-latest
     steps:
       - name: Comment and close draft PR

.github/workflows/hotfix.yml

@@ -376,6 +376,10 @@ jobs:
               --generate-notes \
               --latest
           fi
+          # Reformat the auto-generated notes into the curated
+          # Install + Feature/Enhancement/Fix format.
+          node scripts/release-notes/format-github-release-notes.cjs \
+            --tag "v${VERSION}" --latest --apply
 
       - name: Create PR to merge hotfix back to main
         if: ${{ !inputs.dry_run }}

.github/workflows/install-smoke.yml

@@ -20,8 +20,10 @@ on:
       - main
     paths:
       - 'bin/install.js'
-      - 'get-shit-done/bin/gsd-tools.cjs'
-      - 'get-shit-done/bin/**'
+      - 'gsd-core/bin/gsd-tools.cjs'
+      - 'gsd-core/bin/**'
+      - 'src/**'
+      - 'tsconfig.build.json'
       - 'package.json'
       - 'package-lock.json'
       - 'scripts/release-tarball-smoke.cjs'

.github/workflows/mutation.yml

@@ -1,10 +1,11 @@
 name: Mutation Testing
 
 # PR-GATING: runs on every pull_request targeting `next` or `main`.
-# Computes changed core lib files via git diff and passes them to --mutate,
-# so only mutants in CHANGED files are tested — keeps the job bounded.
-# If no core lib files changed, the gate passes trivially (skip+exit 0).
-# Full-repo mutation runs are reserved for local exploration (npm run test:mutation).
+# scripts/mutation-matrix.cjs is the single source of truth for which modules
+# are "covered" (have meaningful test coverage for mutation). It computes
+# changed modules from git diff and emits a GitHub Actions matrix so each
+# changed module gets its own Stryker shard running in parallel.
+# If no covered modules changed the gate passes trivially (has_work: false).
 
 on:
   pull_request:
@@ -12,10 +13,15 @@ on:
       - next
       - main
     paths:
-      # Only run when lib source or property tests change
-      - 'get-shit-done/bin/lib/**/*.cjs'
+      # Only run when lib source, property/unit tests, or mutation config change
+      - 'src/**/*.cts'
+      - 'gsd-core/bin/lib/**/*.cjs'
       - 'tests/**/*.property.test.cjs'
+      - 'tests/**/*.unit.test.cjs'
+      - 'tests/adr-parser.test.cjs'
+      - 'tests/active-workstream-store.test.cjs'
       - 'stryker.config.mjs'
+      - 'scripts/mutation-matrix.cjs'
   workflow_dispatch:
 
 concurrency:
@@ -26,10 +32,60 @@ permissions:
   contents: read
 
 jobs:
-  mutation:
-    name: Stryker mutation score (changed files only)
+  # ── Job 1: detect ─────────────────────────────────────────────────────────
+  # Computes which covered modules changed and emits a matrix for the mutate job.
+  # Intentionally does NOT run npm ci — it only needs git + Node builtins.
+  detect:
+    name: Detect changed covered modules
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    outputs:
+      has_work: ${{ steps.matrix.outputs.has_work }}
+      matrix: ${{ steps.matrix.outputs.matrix }}
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          fetch-depth: 0
+          persist-credentials: true
+
+      - name: Fetch base ref for diff
+        # Ensure the base branch tip is available for the git diff below.
+        # fetch-depth: 0 above gets all history, but the remote ref name must exist.
+        # For workflow_dispatch (no base_ref) we fall back to `next`.
+        run: git fetch origin ${{ github.base_ref || 'next' }} --depth=1
+
+      - name: Compute mutation matrix
+        id: matrix
+        run: |
+          BASE_REF="origin/${{ github.base_ref || 'next' }}"
+          # Run the matrix script; capture the JSON output.
+          JSON=$(node scripts/mutation-matrix.cjs --base "${BASE_REF}")
+
+          # Extract has_work and the compact matrix string for GITHUB_OUTPUT.
+          HAS_WORK=$(node -e "process.stdout.write(JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')).has_work)" <<< "${JSON}")
+          MATRIX=$(node -e "process.stdout.write(JSON.stringify(JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')).matrix))" <<< "${JSON}")
+
+          echo "has_work=${HAS_WORK}" >> "${GITHUB_OUTPUT}"
+          echo "matrix=${MATRIX}" >> "${GITHUB_OUTPUT}"
+
+          # Human-readable summary for the step log.
+          echo "has_work=${HAS_WORK}"
+          echo "${JSON}"
+
+  # ── Job 2: mutate ──────────────────────────────────────────────────────────
+  # One shard per changed covered module, each running only that module's tests.
+  # Skipped entirely when detect reports no covered files changed.
+  mutate:
+    name: Stryker (${{ matrix.name }})
+    needs: detect
+    if: needs.detect.outputs.has_work == 'true'
+    # GitHub-hosted runners only. Speed comes from running shards in PARALLEL
+    # (one job per changed module), not from larger/3rd-party runners.
+    runs-on: ubuntu-latest
+    timeout-minutes: 15  # per-shard; lower than the old 30-min serial budget
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.detect.outputs.matrix) }}
 
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
@@ -43,52 +99,69 @@ jobs:
           node-version-file: .nvmrc
           cache: npm
 
-      - name: Install dependencies
+      - name: Install dependencies (builds .cjs via prepare)
         run: npm ci
 
-      - name: Fetch base ref for diff
-        # Ensure the base branch tip is available for the git diff below.
-        # fetch-depth: 0 above gets all history, but the remote ref name must exist.
-        run: git fetch origin ${{ github.base_ref }} --depth=1
-
-      - name: Compute changed core lib files
-        id: changed
-        run: |
-          BASE_REF="origin/${{ github.base_ref }}"
-          # Find changed non-test, non-generated .cjs files in bin/lib
-          CHANGED=$(git diff --name-only "${BASE_REF}...HEAD" -- 'get-shit-done/bin/lib/**/*.cjs' \
-            | grep -v '\.test\.cjs$' \
-            | grep -v -E '/(configuration|command-aliases|commands|core|install-profiles|installer-migrations|phase|profile-output|state|verify|init|audit|gsd2-import)\.cjs$' \
-            || true)
-          if [ -z "$CHANGED" ]; then
-            echo "changed=" >> "$GITHUB_OUTPUT"
-          else
-            # Join with commas for --mutate
-            MUTATE_LIST=$(echo "$CHANGED" | paste -sd, -)
-            echo "changed=${MUTATE_LIST}" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Skip mutation gate (no core lib files changed)
-        if: steps.changed.outputs.changed == ''
-        run: echo "No core lib files changed; skipping mutation gate"
-
-      - name: Run Stryker (incremental, changed files only)
-        if: steps.changed.outputs.changed != ''
-        # --mutate scopes mutation to only the changed production files.
+      - name: Run Stryker — ${{ matrix.name }}
+        # MUTATION_TEST_CMD scopes the command runner to only this module's tests.
+        # --mutate scopes mutation to only the changed module's built artifact.
         # --incremental reuses cached results for unchanged mutants.
-        # The break threshold (50) is read from stryker.config.mjs and causes
-        # Stryker to exit non-zero when mutation score < 50%, failing the PR check.
+        # The break threshold (50) is read from stryker.config.mjs.
         env:
           NODE_OPTIONS: '--max-old-space-size=4096'
+          MUTATION_TEST_CMD: node --test ${{ matrix.tests }}
         run: |
-          MUTATE_LIST="${{ steps.changed.outputs.changed }}"
-          echo "Running Stryker --mutate '${MUTATE_LIST}'"
-          npx stryker run --incremental --mutate "${MUTATE_LIST}"
+          echo "Module:  ${{ matrix.name }}"
+          echo "Mutate:  ${{ matrix.mutate }}"
+          echo "Tests:   ${{ matrix.tests }}"
+          npx stryker run --incremental --mutate "${{ matrix.mutate }}"
 
-      - name: Upload mutation HTML report
+      - name: Upload mutation report — ${{ matrix.name }}
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
         if: always()  # upload even on failure so the score is visible
         with:
-          name: mutation-report-${{ github.run_number }}
+          name: mutation-report-${{ matrix.name }}-${{ github.run_number }}
           path: reports/mutation/mutation.html
           retention-days: 14
+
+  # ── Job 3: mutation-gate ───────────────────────────────────────────────────
+  # Stable required-check name for branch protection. Passes when:
+  #   • has_work is false (nothing to mutate — trivial pass), OR
+  #   • all mutate shards succeeded.
+  # Fails when any shard failed.
+  # Summary job keeps the LEGACY check name so existing branch protection
+  # (which requires "Stryker mutation score (changed files only)") needs no
+  # change. The per-module shards report as "Stryker (<module>)".
+  mutation-gate:
+    name: Stryker mutation score (changed files only)
+    needs: [detect, mutate]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Evaluate gate
+        run: |
+          DETECT="${{ needs.detect.result }}"
+          MUTATE="${{ needs.mutate.result }}"
+          HAS_WORK="${{ needs.detect.outputs.has_work }}"
+
+          echo "detect result : ${DETECT}"
+          echo "mutate result : ${MUTATE}"
+          echo "has_work      : ${HAS_WORK}"
+
+          if [ "${DETECT}" != "success" ]; then
+            echo "FAIL: detect job did not succeed (${DETECT})"
+            exit 1
+          fi
+
+          if [ "${HAS_WORK}" = "false" ]; then
+            echo "PASS: no covered modules changed — gate trivially green"
+            exit 0
+          fi
+
+          if [ "${MUTATE}" = "success" ]; then
+            echo "PASS: all mutation shards passed"
+            exit 0
+          fi
+
+          echo "FAIL: one or more mutation shards failed or were cancelled (${MUTATE})"
+          exit 1

.github/workflows/pr-target-validator.yml

@@ -22,6 +22,9 @@ permissions:
 
 jobs:
   validate-target:
+    # Maintainers may open internal release/backport coordination PRs against main.
+    if: >-
+      contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.pull_request.author_association) == false
     runs-on: ubuntu-latest
     timeout-minutes: 2
     env:

.github/workflows/release.yml

@@ -238,22 +238,16 @@ jobs:
             --title "v${PRE_VERSION}" \
             --generate-notes \
             --prerelease
+          # Reformat the auto-generated notes into the curated
+          # Install + Feature/Enhancement/Fix format.
+          node scripts/release-notes/format-github-release-notes.cjs \
+            --tag "v${PRE_VERSION}" --prerelease --apply
 
       - name: Verify publish
         if: ${{ !inputs.dry_run }}
         env:
           PRE_VERSION: ${{ steps.prerelease.outputs.pre_version }}
-        run: |
-          sleep 10
-          PUBLISHED=$(npm view @opengsd/gsd-core@"$PRE_VERSION" version 2>/dev/null || echo "NOT_FOUND")
-          if [ "$PUBLISHED" != "$PRE_VERSION" ]; then
-            echo "::error::Published version verification failed. Expected $PRE_VERSION, got $PUBLISHED"
-            exit 1
-          fi
-          echo "✓ Verified: @opengsd/gsd-core@$PRE_VERSION is live on npm"
-          # Also verify dist-tag
-          NEXT_TAG=$(npm dist-tag ls @opengsd/gsd-core 2>/dev/null | grep "next:" | awk '{print $2}')
-          echo "✓ next tag points to: $NEXT_TAG"
+        run: node scripts/verify-npm-publish.cjs --package @opengsd/gsd-core --version "$PRE_VERSION" --dist-tag next
 
       - name: Summary
         env:
@@ -392,6 +386,10 @@ jobs:
             --title "v${VERSION}" \
             --generate-notes \
             --latest
+          # Reformat the auto-generated notes into the curated
+          # Install + Feature/Enhancement/Fix format.
+          node scripts/release-notes/format-github-release-notes.cjs \
+            --tag "v${VERSION}" --latest --apply
 
       - name: Clean up next dist-tag
         if: ${{ !inputs.dry_run }}
@@ -407,17 +405,7 @@ jobs:
         if: ${{ !inputs.dry_run }}
         env:
           VERSION: ${{ inputs.version }}
-        run: |
-          sleep 10
-          PUBLISHED=$(npm view @opengsd/gsd-core@"$VERSION" version 2>/dev/null || echo "NOT_FOUND")
-          if [ "$PUBLISHED" != "$VERSION" ]; then
-            echo "::error::Published version verification failed. Expected $VERSION, got $PUBLISHED"
-            exit 1
-          fi
-          echo "✓ Verified: @opengsd/gsd-core@$VERSION is live on npm"
-          # Verify latest tag
-          LATEST_TAG=$(npm dist-tag ls @opengsd/gsd-core 2>/dev/null | grep "latest:" | awk '{print $2}')
-          echo "✓ latest tag points to: $LATEST_TAG"
+        run: node scripts/verify-npm-publish.cjs --package @opengsd/gsd-core --version "$VERSION" --dist-tag latest
 
       - name: Summary
         env:

.github/workflows/security-scan.yml

@@ -8,7 +8,7 @@ on:
       - 'release/**'
       - 'hotfix/**'
     paths:
-      - 'get-shit-done/**'
+      - 'gsd-core/**'
       - 'agents/**'
       - 'commands/**'
       - 'hooks/**'
@@ -25,7 +25,10 @@ concurrency:
 jobs:
   security:
     runs-on: ubuntu-latest
-    timeout-minutes: 10
+    # 30m (was 10m): the base64 scan is O(changed-files); a very large diff
+    # (e.g. the #604 repo-wide rename, ~800 changed files) can exceed 10m. The
+    # scan itself is unchanged; this only raises the ceiling for big diffs.
+    timeout-minutes: 30
 
     steps:
       - name: Checkout

.github/workflows/test.yml

@@ -96,6 +96,11 @@ jobs:
           node-version: 24
       - name: Install dev dependencies
         run: npm ci --ignore-scripts
+      # ADR-457 build-at-publish: bin/lib/*.cjs are gitignored, built by tsc.
+      # --ignore-scripts skips the prepare build, but lint:skill-deps (and other
+      # lint scripts) require() the built modules — so build them explicitly.
+      - name: Build runtime lib (required by lint scripts)
+        run: npm run build:lib
       - name: Lint — ESLint (source-grep + timing + no-only-tests + quality)
         run: npx eslint . --cache --cache-location node_modules/.cache/eslint/
       - name: Lint — skill dependency graph
@@ -106,6 +111,8 @@ jobs:
         run: node scripts/lint-command-contract.cjs
       - name: Lint — PR checks use projectDir
         run: node scripts/lint-pr-check-project-dir.cjs
+      - name: Lint — legacy directory name guard (#604)
+        run: npm run lint:legacy-name
 
   test:
     name: test (${{ matrix.os }}, ${{ matrix.node-version }})

.gitignore

@@ -42,8 +42,8 @@ philosophy.md
 # Installed skills
 .github/agents/gsd-*
 .github/skills/gsd-*
-.github/get-shit-done/*
-.github/skills/get-shit-done
+.github/gsd-core/*
+.github/skills/gsd-core
 .github/copilot-instructions.md
 .bg-shell/
 
@@ -62,6 +62,97 @@ Thumbs.db
 .next/
 dist/
 build/
+
+# ADR-457 build-at-publish: TS-generated runtime artifacts (compiled from src/*.cts
+# by `npm run build:lib`). Source of truth is src/; these are emitted, never edited.
+# Published via prepublishOnly; built before test via pretest. Grows as modules migrate.
+/gsd-core/bin/lib/semver-compare.cjs
+/gsd-core/bin/lib/config-types.cjs
+/gsd-core/bin/lib/code-review-flags.cjs
+/gsd-core/bin/lib/context-utilization.cjs
+/gsd-core/bin/lib/artifacts.cjs
+/gsd-core/bin/lib/command-arg-projection.cjs
+/gsd-core/bin/lib/clock.cjs
+/gsd-core/bin/lib/ui-safety-gate.cjs
+/gsd-core/bin/lib/review-reviewer-selection.cjs
+/gsd-core/bin/lib/clusters.cjs
+/gsd-core/bin/lib/installer-migrations/001-legacy-orphan-files.cjs
+/gsd-core/bin/lib/observability/redaction.cjs
+/gsd-core/bin/lib/installer-migration-report.cjs
+/gsd-core/bin/lib/prompt-budget.cjs
+/gsd-core/bin/lib/secrets.cjs
+/gsd-core/bin/lib/phase-lifecycle.cjs
+/gsd-core/bin/lib/workstream-name-policy.cjs
+/gsd-core/bin/lib/decisions.cjs
+/gsd-core/bin/lib/validate.cjs
+/gsd-core/bin/lib/schema-detect.cjs
+/gsd-core/bin/lib/runtime-name-policy.cjs
+/gsd-core/bin/lib/runtime-slash.cjs
+/gsd-core/bin/lib/observability/event.cjs
+/gsd-core/bin/lib/workstream-inventory-builder.cjs
+/gsd-core/bin/lib/plan-scan.cjs
+/gsd-core/bin/lib/fallow-runner.cjs
+/gsd-core/bin/lib/project-root.cjs
+/gsd-core/bin/lib/installer-migration-authoring.cjs
+/gsd-core/bin/lib/update-context.cjs
+/gsd-core/bin/lib/installer-migrations/000-first-time-baseline.cjs
+/gsd-core/bin/lib/runtime-homes.cjs
+/gsd-core/bin/lib/model-catalog.cjs
+/gsd-core/bin/lib/configuration.cjs
+/gsd-core/bin/lib/state-document.cjs
+/gsd-core/bin/lib/shell-command-projection.cjs
+/gsd-core/bin/lib/security.cjs
+/gsd-core/bin/lib/command-aliases.cjs
+/gsd-core/bin/lib/config-schema.cjs
+/gsd-core/bin/lib/model-profiles.cjs
+/gsd-core/bin/lib/installer-migrations/002-codex-legacy-hooks-json.cjs
+/gsd-core/bin/lib/installer-migrations/003-rename-get-shit-done-to-gsd-core.cjs
+/gsd-core/bin/lib/observability/logger.cjs
+/gsd-core/bin/lib/active-workstream-store.cjs
+/gsd-core/bin/lib/adr-parser.cjs
+/gsd-core/bin/lib/graphify.cjs
+/gsd-core/bin/lib/install-profiles.cjs
+/gsd-core/bin/lib/intel.cjs
+/gsd-core/bin/lib/installer-migrations.cjs
+/gsd-core/bin/lib/worktree-safety.cjs
+/gsd-core/bin/lib/planning-workspace.cjs
+/gsd-core/bin/lib/runtime-artifact-layout.cjs
+/gsd-core/bin/lib/command-routing-hub.cjs
+/gsd-core/bin/lib/core.cjs
+/gsd-core/bin/lib/drift.cjs
+/gsd-core/bin/lib/cjs-command-router-adapter.cjs
+/gsd-core/bin/lib/phase-command-router.cjs
+/gsd-core/bin/lib/surface.cjs
+/gsd-core/bin/lib/gap-checker.cjs
+/gsd-core/bin/lib/docs.cjs
+/gsd-core/bin/lib/check-command-router.cjs
+/gsd-core/bin/lib/frontmatter.cjs
+/gsd-core/bin/lib/learnings.cjs
+/gsd-core/bin/lib/gsd2-import.cjs
+/gsd-core/bin/lib/profile-pipeline.cjs
+/gsd-core/bin/lib/roadmap-upgrade.cjs
+/gsd-core/bin/lib/phases-command-router.cjs
+/gsd-core/bin/lib/verify-command-router.cjs
+/gsd-core/bin/lib/init-command-router.cjs
+/gsd-core/bin/lib/agent-command-router.cjs
+/gsd-core/bin/lib/task-command-router.cjs
+/gsd-core/bin/lib/validate-command-router.cjs
+/gsd-core/bin/lib/workstream-inventory.cjs
+/gsd-core/bin/lib/roadmap-command-router.cjs
+/gsd-core/bin/lib/state-command-router.cjs
+/gsd-core/bin/lib/config.cjs
+/gsd-core/bin/lib/profile-output.cjs
+/gsd-core/bin/lib/template.cjs
+/gsd-core/bin/lib/commands.cjs
+/gsd-core/bin/lib/state.cjs
+/gsd-core/bin/lib/milestone.cjs
+/gsd-core/bin/lib/phase.cjs
+/gsd-core/bin/lib/verify.cjs
+/gsd-core/bin/lib/init.cjs
+/gsd-core/bin/lib/uat.cjs
+/gsd-core/bin/lib/workstream.cjs
+/gsd-core/bin/lib/roadmap.cjs
+/gsd-core/bin/lib/audit.cjs
 __pycache__/
 *.pyc
 .venv/

.out-of-scope/agent-template-rendering.md

@@ -100,5 +100,5 @@ This may be revisited if a contributor:
   precedent for deterministic compile-time embedding into agent files)
 - v1.37.0 release notes — shared-boilerplate extraction (reference files for
   mandatory-initial-read, project-skills-discovery)
-- `get-shit-done/workflows/` — workflow-level config embedding before subagent
+- `gsd-core/workflows/` — workflow-level config embedding before subagent
   spawn (the path of least friction for incremental deterministic gating)

.out-of-scope/temporal-context.md

@@ -53,4 +53,4 @@ through to a triage decision rather than dropping an issue and moving on.
 ## Related
 
 - `.planning/state/` — existing session-continuity artifacts
-- `get-shit-done/references/` — where any future plugin-interface doc would live
+- `gsd-core/references/` — where any future plugin-interface doc would live

.plans/1755-install-audit-fix.md

@@ -10,7 +10,7 @@ All changes in `bin/install.js` unless noted.
 **Line 5391-5392** — After `fs.copyFileSync`, add `fs.chmodSync(destFile, 0o755)` for `.sh` files.
 
 ### Fix 2: Fix Codex hook path and filename (CRITICAL)
-**Line 5485** — Change `gsd-update-check.js` to `gsd-check-update.js` and fix path from `get-shit-done/hooks/` to `hooks/`.
+**Line 5485** — Change `gsd-update-check.js` to `gsd-check-update.js` and fix path from `gsd-core/hooks/` to `hooks/`.
 **Line 5492** — Update dedup check to use `gsd-check-update`.
 
 ### Fix 3: Fix stale cache invalidation path (CRITICAL)

.secretscanignore

@@ -23,5 +23,8 @@
 # Lint: scripts/secret-scan-lint.sh --file .secretscanignore
 # Strict scan: scripts/secret-scan.sh --diff origin/main --strict
 
-# allow: get-shit-done/workflows/plan-phase.md  reason="contains illustrative DATABASE_URL/REDIS_URL example strings used as documentation placeholders — not real credentials"  owner="@open-gsd/maintainers"  expires="2027-06-30"
-get-shit-done/workflows/plan-phase.md
+# allow: gsd-core/workflows/plan-phase.md  reason="contains illustrative DATABASE_URL/REDIS_URL example strings used as documentation placeholders — not real credentials"  owner="@open-gsd/maintainers"  expires="2027-06-30"
+gsd-core/workflows/plan-phase.md
+
+# allow: gsd-core/references/verification-patterns.md  reason="documents stub/placeholder RED-FLAG examples for env vars (illustrative Stripe test-key, database-URL and API-key placeholders shown as what NOT to ship) — not real credentials"  owner="@open-gsd/maintainers"  expires="2027-06-30"
+gsd-core/references/verification-patterns.md

AGENTS.md

@@ -8,7 +8,7 @@ For current work on **Grok Build compatibility** and multi-runtime synchronizati
 
 ## Project Structure & Module Organization
 
-This repository ships GSD as a Node.js CLI and SDK. Root package entry points live in `bin/`, scripts in `scripts/`, runtime hooks in `hooks/`, command definitions in `commands/gsd/`, and workflow/template content in `get-shit-done/`. Agent role files are in `agents/`; docs are in `docs/`; logos and terminal images are in `assets/`. Root tests are in `tests/*.test.cjs`. The TypeScript SDK is isolated under `sdk/`, with source and Vitest tests in `sdk/src/`.
+This repository ships GSD as a Node.js CLI and SDK. Root package entry points live in `bin/`, scripts in `scripts/`, runtime hooks in `hooks/`, command definitions in `commands/gsd/`, and workflow/template content in `gsd-core/`. Agent role files are in `agents/`; docs are in `docs/`; logos and terminal images are in `assets/`. Root tests are in `tests/*.test.cjs`. The TypeScript SDK is isolated under `sdk/`, with source and Vitest tests in `sdk/src/`.
 
 ## Build, Test, and Development Commands
 
@@ -39,3 +39,17 @@ Every PR must link an approved or confirmed issue with `Closes #123`, `Fixes #12
 ## Security & Configuration Tips
 
 Do not commit secrets, local config, or generated worktree artifacts. Before release-facing changes, run the relevant scan scripts in `scripts/`, especially `secret-scan.sh`, `base64-scan.sh`, and `prompt-injection-scan.sh`.
+
+## Agent skills
+
+### Issue tracker
+
+Issues live in GitHub Issues at `open-gsd/gsd-core` (via the `gh` CLI, always with `--repo open-gsd/gsd-core`). See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Five canonical triage roles mapped to this repo's labels — `needs-info`→`needs-reproduction`, `ready-for-agent`→`confirmed`, `ready-for-human`→`approved-enhancement`/`approved-feature`, others default. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context — `CONTEXT.md` (domain glossary + recurring PR rules) and `docs/adr/` at the repo root. See `docs/agents/domain.md`.

CONTEXT.md

@@ -9,13 +9,13 @@
 ## Glossary — Domain modules and seams
 
 ### Milestone Module
-Module owning `milestone complete` (archive roadmap/requirements/phases, build MILESTONES.md entry, update STATE.md), `requirements mark-complete` (checkbox + table update with regex-global-state fix), and `phases clear`. Key behaviors: milestone-phase scoping (extract phases from ROADMAP.md milestone slice, support project-code-prefix dirs e.g. CK-01-name, exclude prior-milestone phases), milestone-archive layout (resolve phase dirs from `.planning/milestones/v*-phases/` when `.planning/phases/` absent), fenced-code-block boundary tracking in `extractCurrentMilestone`. Source of truth: `get-shit-done/bin/lib/milestone.cjs` (query handlers for `milestone.complete`, `phases.archive`). Test consolidation: PR #3753 (10 files → 4). (The SDK milestone surface and `GSD.run()` milestone runner were retired with the SDK package per ADR-0174.)
+Module owning `milestone complete` (archive roadmap/requirements/phases, build MILESTONES.md entry, update STATE.md), `requirements mark-complete` (checkbox + table update with regex-global-state fix), and `phases clear`. Key behaviors: milestone-phase scoping (extract phases from ROADMAP.md milestone slice, support project-code-prefix dirs e.g. CK-01-name, exclude prior-milestone phases), milestone-archive layout (resolve phase dirs from `.planning/milestones/v*-phases/` when `.planning/phases/` absent), fenced-code-block boundary tracking in `extractCurrentMilestone`. Source of truth: `gsd-core/bin/lib/milestone.cjs` (query handlers for `milestone.complete`, `phases.archive`). Test consolidation: PR #3753 (10 files → 4). (The SDK milestone surface and `GSD.run()` milestone runner were retired with the SDK package per ADR-0174.)
 
 ### Dispatch Pipeline Module
-Module that composes Dispatch Policy Module, Query Execution Policy Module, and per-stage handlers (input-validation, plan, execution, result-builder, formatting, error-mapping, observability) into the end-to-end pipeline that produces a `QueryDispatchResult`. The SDK-era pipeline collapsed onto the Command Routing Hub per ADR-0174; current dispatch seam: `get-shit-done/bin/lib/command-routing-hub.cjs` (see Command Routing Hub below).
+Module that composes Dispatch Policy Module, Query Execution Policy Module, and per-stage handlers (input-validation, plan, execution, result-builder, formatting, error-mapping, observability) into the end-to-end pipeline that produces a `QueryDispatchResult`. The SDK-era pipeline collapsed onto the Command Routing Hub per ADR-0174; current dispatch seam: `gsd-core/bin/lib/command-routing-hub.cjs` (see Command Routing Hub below).
 
 ### Phase Lifecycle Module
-Module owning phase create, rename, complete, remove, list, and plan-index operations, plus phase-dir prefix validation, STATE.md staleness detection, and auto-prune behaviour. Entry point: `get-shit-done/bin/lib/phase.cjs` (CJS surface). Typed phase events: `GSDPhaseStartEvent`, `GSDPhaseStepStartEvent`, `GSDPhaseStepCompleteEvent`, `GSDPhaseCompleteEvent`. (The SDK native-query surface, the `types.ts` event definitions, `phase-runner.ts`, and `phase-prompt.ts` were retired with the SDK package per ADR-0174.)
+Module owning phase create, rename, complete, remove, list, and plan-index operations, plus phase-dir prefix validation, STATE.md staleness detection, and auto-prune behaviour. Entry point: `gsd-core/bin/lib/phase.cjs` (CJS surface). Typed phase events: `GSDPhaseStartEvent`, `GSDPhaseStepStartEvent`, `GSDPhaseStepCompleteEvent`, `GSDPhaseCompleteEvent`. (The SDK native-query surface, the `types.ts` event definitions, `phase-runner.ts`, and `phase-prompt.ts` were retired with the SDK package per ADR-0174.)
 
 ### Dispatch Policy Module
 Module owning dispatch error mapping, fallback policy, timeout classification, and CLI exit mapping contract.
@@ -41,7 +41,7 @@ Adapter Module that satisfies native query dispatch at the Dispatch Policy seam,
 Module owning projection from dispatch results/errors to CLI `{ exitCode, stdoutChunks, stderrLines }` output contract.
 
 ### STATE.md Document Module
-Module owning STATE.md parse, field extraction, field replacement, status normalization, and frontmatter reconstruction. It does not scan `.planning/phases` and does not own persistence or locking; phase/plan/summary counts arrive from inventory/progress Modules as inputs, and read-modify-write paths remain Adapters. Source of truth: `get-shit-done/bin/lib/state-document.cjs`.
+Module owning STATE.md parse, field extraction, field replacement, status normalization, and frontmatter reconstruction. It does not scan `.planning/phases` and does not own persistence or locking; phase/plan/summary counts arrive from inventory/progress Modules as inputs, and read-modify-write paths remain Adapters. Source of truth: `gsd-core/bin/lib/state-document.cjs`.
 
 ### Query Execution Policy Module
 Module owning query transport routing policy projection (`preferNative`, fallback policy, workstream subprocess forcing) at execution seam.
@@ -56,70 +56,70 @@ Canonical command normalization and resolution Interface (`query-command-resolut
 Module owning command resolution, policy projection (`mutation`, `output_mode`), unknown-command diagnosis, and handler Adapter binding at one seam for query dispatch.
 
 ### Init Command Module
-Module owning the `init.*` family of query handlers that compose atomic queries into the flat JSON bundles consumed by init workflows (`/gsd-execute-phase`, `/gsd-plan-phase`, `/gsd-verify-work`, `/gsd-new-project`, `/gsd-manager`, `/gsd-progress`, `/gsd-resume`, etc.). Source of truth: `get-shit-done/bin/lib/init.cjs` — the basic handlers (plus `withProjectRoot` project-identity injection) and the 3 heavyweight handlers (`initNewProject`, `initProgress`, `initManager`). All handlers return `{ data: <flat JSON> }`. Test seams: `tests/init.test.cjs` and `tests/init-manager.test.cjs` (cover withProjectRoot precedence, progress/manager precedence regression #2674, workstream scoping regression #3196, and cross-milestone dependency regression #2267). (The SDK `handlers/init/*.ts` sources and the `init*.test.ts` seams were retired with the SDK package per ADR-0174.)
+Module owning the `init.*` family of query handlers that compose atomic queries into the flat JSON bundles consumed by init workflows (`/gsd-execute-phase`, `/gsd-plan-phase`, `/gsd-verify-work`, `/gsd-new-project`, `/gsd-manager`, `/gsd-progress`, `/gsd-resume`, etc.). Source of truth: `gsd-core/bin/lib/init.cjs` — the basic handlers (plus `withProjectRoot` project-identity injection) and the 3 heavyweight handlers (`initNewProject`, `initProgress`, `initManager`). All handlers return `{ data: <flat JSON> }`. Test seams: `tests/init.test.cjs` and `tests/init-manager.test.cjs` (cover withProjectRoot precedence, progress/manager precedence regression #2674, workstream scoping regression #3196, and cross-milestone dependency regression #2267). (The SDK `handlers/init/*.ts` sources and the `init*.test.ts` seams were retired with the SDK package per ADR-0174.)
 
 ### Command Routing Hub
-Single dispatch seam (`get-shit-done/bin/lib/command-routing-hub.cjs`) that centralizes CJS routing, the no-throw pure-result contract, typed error variants, and dispatch-event emission for all command family adapters. Interface: `createHub({ cjsRegistry, manifest, logger }) → hub`; `hub.dispatch({ family, subcommand, args, cwd, raw, parentTraceId? }) → Result` where `Result = { ok: true, data } | { ok: false, kind, ...typedPayload }` and `kind ∈ { UnknownCommand, InvalidArgs, HandlerRefusal, HandlerFailure }`. The Hub is single-runtime (no mode selection, no sdkLoader), never prints, never exits, never throws. Adapters call `createHub`, dispatch, then translate the pure Result to `output()`/`error()` calls. Source: `get-shit-done/bin/lib/command-routing-hub.cjs`; ADR: `docs/adr/0174-retire-gsd-sdk-package-boundary.md`.
+Single dispatch seam (`gsd-core/bin/lib/command-routing-hub.cjs`) that centralizes CJS routing, the no-throw pure-result contract, typed error variants, and dispatch-event emission for all command family adapters. Interface: `createHub({ cjsRegistry, manifest, logger }) → hub`; `hub.dispatch({ family, subcommand, args, cwd, raw, parentTraceId? }) → Result` where `Result = { ok: true, data } | { ok: false, kind, ...typedPayload }` and `kind ∈ { UnknownCommand, InvalidArgs, HandlerRefusal, HandlerFailure }`. The Hub is single-runtime (no mode selection, no sdkLoader), never prints, never exits, never throws. Adapters call `createHub`, dispatch, then translate the pure Result to `output()`/`error()` calls. Source: `gsd-core/bin/lib/command-routing-hub.cjs`; ADR: `docs/adr/0174-retire-gsd-sdk-package-boundary.md`.
 
 ### Runtime Source Layout Module
-Single-runtime seam layout for this repository after SDK retirement. Runtime execution paths live under `get-shit-done/bin/lib/` and are grouped by seam concern (dispatch, manifest, handlers, runtime, observability, installer). ADR-0174 preserves the seam vocabulary and defines the canonical long-term shape as a seam-aligned TypeScript `src/` tree (`src/dispatch/`, `src/handlers/`, `src/errors/`, `src/manifest/`, `src/config/`, `src/state/`, `src/workstream/`, `src/runtime/`, `src/cli/`, `src/observability/`) compiled to CJS.
+Single-runtime seam layout for this repository after SDK retirement. Runtime execution paths live under `gsd-core/bin/lib/` and are grouped by seam concern (dispatch, manifest, handlers, runtime, observability, installer). ADR-0174 preserves the seam vocabulary and defines the canonical long-term shape as a seam-aligned TypeScript `src/` tree (`src/dispatch/`, `src/handlers/`, `src/errors/`, `src/manifest/`, `src/config/`, `src/state/`, `src/workstream/`, `src/runtime/`, `src/cli/`, `src/observability/`) compiled to CJS.
 
 ### Runtime Launcher Module
-Canonical space-safe shell preamble (`gsd_run`) used by every workflow bash block to invoke the GSD runtime CLI. Resolves `get-shit-done/bin/gsd-tools.cjs` via `node` when present, falls back to a `gsd-tools` binary on PATH, else errors. Single source of truth: `get-shit-done/workflows/_runtime-launcher.snippet.sh`; propagated by `scripts/sync-runtime-launcher.cjs`; enforced by `tests/runtime-launcher-parity.test.cjs`. Replaced the retired unquoted `$GSD_SDK` variable (#373).
+Canonical space-safe shell preamble (`gsd_run`) used by every workflow bash block to invoke the GSD runtime CLI. Resolves `gsd-core/bin/gsd-tools.cjs` via `node` when present, falls back to a `gsd-tools` binary on PATH, else errors. Single source of truth: `gsd-core/workflows/_runtime-launcher.snippet.sh`; propagated by `scripts/sync-runtime-launcher.cjs`; enforced by `tests/runtime-launcher-parity.test.cjs`. Replaced the retired unquoted `$GSD_SDK` variable (#373).
 
 ### Dispatch Observability Module
-Module owning dispatch-event creation, redaction, and logger behavior for the Command Routing Hub. Core files: `get-shit-done/bin/lib/observability/event.cjs`, `get-shit-done/bin/lib/observability/logger.cjs`, `get-shit-done/bin/lib/observability/redaction.cjs`. Contract: silent on success by default, structured JSON to stderr on error, and opt-in audit trail at `.planning/.gsd-trace.jsonl` via `GSD_AUDIT=1` or config (`audit.enabled`). Each dispatch carries a `traceId`; composed dispatches set `parentTraceId` for correlation.
+Module owning dispatch-event creation, redaction, and logger behavior for the Command Routing Hub. Core files: `gsd-core/bin/lib/observability/event.cjs`, `gsd-core/bin/lib/observability/logger.cjs`, `gsd-core/bin/lib/observability/redaction.cjs`. Contract: silent on success by default, structured JSON to stderr on error, and opt-in audit trail at `.planning/.gsd-trace.jsonl` via `GSD_AUDIT=1` or config (`audit.enabled`). Each dispatch carries a `traceId`; composed dispatches set `parentTraceId` for correlation.
 
 ### Query Pre-Project Config Policy Module
 Module policy that defines query-time behavior when `.planning/config.json` is absent: use built-in defaults for parity-sensitive query Interfaces, and emit parity-aligned empty model ids for pre-project model resolution surfaces.
 
 ### Configuration Module
-Module owning config load, legacy-key normalization, defaults merge, and explicit on-disk migration for `.planning/config.json`. Interface: `loadConfig(cwd) → MergedConfig` (pure read, never writes disk), `normalizeLegacyKeys(parsed) → { parsed, normalizations[] }` (idempotent, pure, returns the list of normalizations applied), `mergeDefaults(parsed) → MergedConfig` (deep-merge of parsed config over canonical defaults), `migrateOnDisk(cwd) → MigrationReport` (explicit, opt-in, called by the installer and by `gsd-tools migrate-config`). Invariants: never mutates disk inside `loadConfig`; legacy top-level keys (`branching_strategy`, `sub_repos`, `multiRepo`, `depth`) are normalized into their canonical nested locations in the returned value; defaults come from the shared `get-shit-done/bin/shared/config-defaults.manifest.json`; schema (`VALID_CONFIG_KEYS`, `RUNTIME_STATE_KEYS`, `DYNAMIC_KEY_PATTERNS`) comes from `get-shit-done/bin/shared/config-schema.manifest.json`. Source of truth: `get-shit-done/bin/lib/configuration.cjs`, consumed via the thin Adapters at `bin/lib/core.cjs:loadConfig` and `bin/lib/config-schema.cjs`. Eliminates the recurring #3523-class drift bug structurally.
+Module owning config load, legacy-key normalization, defaults merge, and explicit on-disk migration for `.planning/config.json`. Interface: `loadConfig(cwd) → MergedConfig` (pure read, never writes disk), `normalizeLegacyKeys(parsed) → { parsed, normalizations[] }` (idempotent, pure, returns the list of normalizations applied), `mergeDefaults(parsed) → MergedConfig` (deep-merge of parsed config over canonical defaults), `migrateOnDisk(cwd) → MigrationReport` (explicit, opt-in, called by the installer and by `gsd-tools migrate-config`). Invariants: never mutates disk inside `loadConfig`; legacy top-level keys (`branching_strategy`, `sub_repos`, `multiRepo`, `depth`) are normalized into their canonical nested locations in the returned value; defaults come from the shared `gsd-core/bin/shared/config-defaults.manifest.json`; schema (`VALID_CONFIG_KEYS`, `RUNTIME_STATE_KEYS`, `DYNAMIC_KEY_PATTERNS`) comes from `gsd-core/bin/shared/config-schema.manifest.json`. Source of truth: `gsd-core/bin/lib/configuration.cjs`, consumed via the thin Adapters at `bin/lib/core.cjs:loadConfig` and `bin/lib/config-schema.cjs`. Eliminates the recurring #3523-class drift bug structurally.
 
 ### Planning Workspace Module
 Module owning `.planning` path resolution, active workstream pointer policy (`session-scoped > shared`), pointer self-heal behavior, and planning lock semantics for workstream-aware execution.
 
 ### Workstream Inventory Module
-Module owning workstream directory discovery, per-workstream state projection, phase/plan/summary counting, roadmap-declared phase count, active marker projection, and active-workstream collision inputs. Command handlers render list/status/progress outputs from this inventory instead of rescanning `.planning/workstreams/*` directly. Source of truth for the pure projection is `get-shit-done/bin/lib/workstream-inventory-builder.cjs` (a Builder Module); the Reader Adapter `get-shit-done/bin/lib/workstream-inventory.cjs` collects filesystem inputs and delegates projection to the Builder.
+Module owning workstream directory discovery, per-workstream state projection, phase/plan/summary counting, roadmap-declared phase count, active marker projection, and active-workstream collision inputs. Command handlers render list/status/progress outputs from this inventory instead of rescanning `.planning/workstreams/*` directly. Source of truth for the pure projection is `gsd-core/bin/lib/workstream-inventory-builder.cjs` (a Builder Module); the Reader Adapter `gsd-core/bin/lib/workstream-inventory.cjs` collects filesystem inputs and delegates projection to the Builder.
 
 ### Project-Root Resolution Module
-Module owning project-root resolution from any starting directory. Walks the ancestor chain (bounded by `FIND_PROJECT_ROOT_MAX_DEPTH = 10`) applying four heuristics in order: (0) own `.planning/` guard (#1362), (1) parent `.planning/config.json` `sub_repos` traversal, (2) legacy `multiRepo: true` boolean + ancestor `.git`, (3) `.git` heuristic with parent `.planning/`. Returns `startDir` when no ancestor qualifies. Sync `node:fs` I/O. Source of truth: `get-shit-done/bin/lib/project-root.cjs`; consumed via a thin re-export at `get-shit-done/bin/lib/core.cjs`.
+Module owning project-root resolution from any starting directory. Walks the ancestor chain (bounded by `FIND_PROJECT_ROOT_MAX_DEPTH = 10`) applying four heuristics in order: (0) own `.planning/` guard (#1362), (1) parent `.planning/config.json` `sub_repos` traversal, (2) legacy `multiRepo: true` boolean + ancestor `.git`, (3) `.git` heuristic with parent `.planning/`. Returns `startDir` when no ancestor qualifies. Sync `node:fs` I/O. Source of truth: `gsd-core/bin/lib/project-root.cjs`; consumed via a thin re-export at `gsd-core/bin/lib/core.cjs`.
 
 ### Planning Path Projection Module
 SDK query Module owning projection from project/workstream context to concrete `.planning` paths. Policy precedence is `explicit workstream > env workstream > env project > root`. Invalid workspace context is a validation error at this seam rather than a silent fallback.
 
 ### Worktree Safety Policy Module
-CJS Module owning worktree lifecycle safety policy for the GSD orchestration layer. Interface: `resolveWorktreeContext(cwd, deps) → WorktreeContext` (linked-worktree root mapping), `parseWorktreePorcelain(output) → WorktreeEntry[]` (porcelain parser, skips detached HEAD), `planWorktreePrune(repoRoot, opts, deps) → PrunePlan` (metadata-prune plan, never destructive by default), `executeWorktreePrunePlan(plan, deps) → PruneResult` (executes prune; degrades gracefully on git timeout), `listLinkedWorktreePaths(repoRoot, deps) → LinkedPathsResult`, `inspectWorktreeHealth(repoRoot, opts, deps) → HealthResult` (orphan + stale detection), `snapshotWorktreeInventory(repoRoot, opts, deps) → InventoryResult`, `planWorktreeWaveCleanup(repoRoot, manifest) → CleanupPlan` (manifest-scoped, fail-closed), `executeWorktreeWaveCleanupPlan(plan, deps) → CleanupResult`. Source of truth: `get-shit-done/bin/lib/worktree-safety.cjs`. Timeout path: all git subprocess calls are bounded; callers receive `ok:false, reason:'git_timed_out'` rather than a thrown exception. Test anchor: `tests/worktree-safety.test.cjs`.
+CJS Module owning worktree lifecycle safety policy for the GSD orchestration layer. Interface: `resolveWorktreeContext(cwd, deps) → WorktreeContext` (linked-worktree root mapping), `parseWorktreePorcelain(output) → WorktreeEntry[]` (porcelain parser, skips detached HEAD), `planWorktreePrune(repoRoot, opts, deps) → PrunePlan` (metadata-prune plan, never destructive by default), `executeWorktreePrunePlan(plan, deps) → PruneResult` (executes prune; degrades gracefully on git timeout), `listLinkedWorktreePaths(repoRoot, deps) → LinkedPathsResult`, `inspectWorktreeHealth(repoRoot, opts, deps) → HealthResult` (orphan + stale detection), `snapshotWorktreeInventory(repoRoot, opts, deps) → InventoryResult`, `planWorktreeWaveCleanup(repoRoot, manifest) → CleanupPlan` (manifest-scoped, fail-closed), `executeWorktreeWaveCleanupPlan(plan, deps) → CleanupResult`. Source of truth: `gsd-core/bin/lib/worktree-safety.cjs`. Timeout path: all git subprocess calls are bounded; callers receive `ok:false, reason:'git_timed_out'` rather than a thrown exception. Test anchor: `tests/worktree-safety.test.cjs`.
 
 ### Worktree Lifecycle Module
-Workflow contract seam covering agent worktree lifecycle orchestration rules embedded in `get-shit-done/workflows/execute-phase.md`, `quick.md`, `execute-plan.md`, and `agents/gsd-executor.md`. Key invariants: `worktree_branch_check` uses `git reset --hard` (not `--soft`); HEAD attachment verified via `git symbolic-ref` before any reset; positive allow-list `^worktree-agent-*` enforced; `git update-ref` on protected refs is prohibited; cleanup is manifest-scoped (`WAVE_WORKTREE_MANIFEST`) not global-discovery-based; worktree spawning is sequential (one `run_in_background` at a time to avoid `config.lock` contention). Test anchor: `tests/worktree.test.cjs`.
+Workflow contract seam covering agent worktree lifecycle orchestration rules. The `worktree_branch_check` block lives in one canonical fragment (`gsd-core/references/worktree-branch-check.md`) that `execute-phase.md`, `quick.md`, `diagnose-issues.md`, and `execute-plan.md` embed at dispatch. Key invariants: `worktree_branch_check` is **verify-only and fail-closed** — the orchestrator owns worktree lifecycle and base recovery, so the sub-agent holds no state-correction primitives; HEAD attachment verified via `git symbolic-ref`; positive allow-list `^worktree-agent-*` enforced; `git update-ref` on protected refs is prohibited; on base mismatch the sub-agent halts with `exit 42` and surfaces to the orchestrator (#48); the orchestrator runs a cwd-drift guard at `execute_waves` entry that resolves the worktree root and refuses drift into an agent worktree (#48); cleanup is manifest-scoped (`WAVE_WORKTREE_MANIFEST`) not global-discovery-based; worktree spawning is sequential (one `run_in_background` at a time to avoid `config.lock` contention). Test anchor: `tests/worktree.test.cjs`.
 
 ### Worktree Root Resolution Adapter Module
 Adapter Module owning linked-worktree root mapping and metadata-prune policy (`git worktree prune` non-destructive default) for planning/workstream callers.
 
 ### Runtime Name Policy Module
-Module owning runtime identity normalization at runtime-selection seams. Canonicalizes alias signals from env/config (`GSD_RUNTIME`, `.planning/config.json:runtime`) to supported runtime IDs so output emitters and query runtime gates stay consistent across naming variants (for example `codex-app`/`codex-cli` -> `codex`). Sources: `get-shit-done/bin/lib/runtime-name-policy.cjs`, alias manifest `get-shit-done/bin/shared/runtime-aliases.manifest.json`.
+Module owning runtime identity normalization at runtime-selection seams. Canonicalizes alias signals from env/config (`GSD_RUNTIME`, `.planning/config.json:runtime`) to supported runtime IDs so output emitters and query runtime gates stay consistent across naming variants (for example `codex-app`/`codex-cli` -> `codex`). Sources: `gsd-core/bin/lib/runtime-name-policy.cjs`, alias manifest `gsd-core/bin/shared/runtime-aliases.manifest.json`.
 
 ### Installer Migration Authoring Guard Module
 Module owning validation for Installer Migration Module records and planned actions. It enforces migration metadata, explicit install scopes, ownership evidence for destructive/config actions, and runtime contract citations for runtime config rewrites before a migration can enter planning or apply.
 
 ### Installer Module
-Primary installer for all runtimes. Single production file: `bin/install.js` (generated). Exports: `install(isGlobal, runtime[, configDir])` → typed result `{ runtime, configDir, settingsPath, settings, statuslineCommand, updateBannerCommand }`; `uninstall(isGlobal, runtime[, configDir])`; `installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile)`; `uninstallRuntimeArtifacts(runtime, configDir, scope)`; `writeManifest(configDir, runtime)`. Runtime enum: `allRuntimes` (15 values: claude, antigravity, augment, cline, codebuddy, codex, copilot, cursor, gemini, hermes, kilo, opencode, qwen, trae, windsurf). Directory helpers: `getDirName(runtime)` → local dir name; `getGlobalDir(runtime[, explicitDir])` → global path (env-var–aware per runtime); `getConfigDirFromHome(runtime, isGlobal)` → shell-quoted path fragment. Runtime-specific helpers: `resolveKiloConfigPath(configDir)`, `configureKiloPermissions(isGlobal[, explicitDir])`. Layout-driven artifact copy/removal delegates to `get-shit-done/bin/lib/runtime-artifact-layout.cjs:resolveRuntimeArtifactLayout` (throws `TypeError` for unknown runtimes). Hermes uses nested `skills/gsd/<stem>/` layout (prefix: ''); other skill-runtimes use flat `skills/gsd-<stem>/` layout. See Skill Surface Budget Module and Runtime Artifact Layout Module.
+Primary installer for all runtimes. Single production file: `bin/install.js` (generated). Exports: `install(isGlobal, runtime[, configDir])` → typed result `{ runtime, configDir, settingsPath, settings, statuslineCommand, updateBannerCommand }`; `uninstall(isGlobal, runtime[, configDir])`; `installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile)`; `uninstallRuntimeArtifacts(runtime, configDir, scope)`; `writeManifest(configDir, runtime)`. Runtime enum: `allRuntimes` (15 values: claude, antigravity, augment, cline, codebuddy, codex, copilot, cursor, gemini, hermes, kilo, opencode, qwen, trae, windsurf). Directory helpers: `getDirName(runtime)` → local dir name; `getGlobalDir(runtime[, explicitDir])` → global path (env-var–aware per runtime); `getConfigDirFromHome(runtime, isGlobal)` → shell-quoted path fragment. Runtime-specific helpers: `resolveKiloConfigPath(configDir)`, `configureKiloPermissions(isGlobal[, explicitDir])`. Layout-driven artifact copy/removal delegates to `gsd-core/bin/lib/runtime-artifact-layout.cjs:resolveRuntimeArtifactLayout` (throws `TypeError` for unknown runtimes). Hermes uses nested `skills/gsd/<stem>/` layout (prefix: ''); other skill-runtimes use flat `skills/gsd-<stem>/` layout. See Skill Surface Budget Module and Runtime Artifact Layout Module.
 
 ### Package Identity Module [Planned]
-Single seam owning GSD's published-package coordinates so a repoint/rename is a one-line change instead of a tree-wide sweep. Source of truth is `package.json`; values are *derived*, not re-typed: `packageName` (`.name` → `@opengsd/get-shit-done-redux`), `binName` (`Object.keys(.bin)[0]` → `get-shit-done-redux`), `repoSlug` (parsed from `.repository.url` → `open-gsd/get-shit-done-redux`), plus derived `changelogRawUrl` and `manualInstallCommand({ scope, runtime })`. Generated `.cjs` per ADR-457 (generated-single-source); shipped under `get-shit-done/bin/lib/`. Three consumer worlds: **Node** consumers `require()` it at runtime (worker, `check-latest-version.cjs`, `bin/install.js`); the **bash launcher** snippet receives the literal injected by `scripts/sync-runtime-launcher.cjs` at sync time; **prose/help** literals (`update.md`, installer help) carry a committed copy. A drift-guard lint (`scripts/lint-package-identity-drift.cjs`, sibling to `check:alias-drift`) fails CI on any raw package/repo literal outside `package.json`, the generated module, and the value-checked materialization sites — this is what keeps the seam real (`two adapters`, not one). Replaces the contradictory pair it consolidates: the runtime-broken `require('../package.json').name` in `hooks/gsd-check-update-worker.js` (#378, resolves to `undefined` post-install) and the hardcoded constant in `check-latest-version.cjs` (#2992). _Avoid_: "package name string", "the npm name" (when you mean the seam). See ADR-457 and Installer Module.
+Single seam owning GSD's published-package coordinates so a repoint/rename is a one-line change instead of a tree-wide sweep. Source of truth is `package.json`; values are *derived*, not re-typed: `packageName` (`.name` → `@opengsd/get-shit-done-redux`), `binName` (`Object.keys(.bin)[0]` → `get-shit-done-redux`), `repoSlug` (parsed from `.repository.url` → `open-gsd/get-shit-done-redux`), plus derived `changelogRawUrl` and `manualInstallCommand({ scope, runtime })`. Generated `.cjs` per ADR-457 (generated-single-source); shipped under `gsd-core/bin/lib/`. Three consumer worlds: **Node** consumers `require()` it at runtime (worker, `check-latest-version.cjs`, `bin/install.js`); the **bash launcher** snippet receives the literal injected by `scripts/sync-runtime-launcher.cjs` at sync time; **prose/help** literals (`update.md`, installer help) carry a committed copy. A drift-guard lint (`scripts/lint-package-identity-drift.cjs`, sibling to `check:alias-drift`) fails CI on any raw package/repo literal outside `package.json`, the generated module, and the value-checked materialization sites — this is what keeps the seam real (`two adapters`, not one). Replaces the contradictory pair it consolidates: the runtime-broken `require('../package.json').name` in `hooks/gsd-check-update-worker.js` (#378, resolves to `undefined` post-install) and the hardcoded constant in `check-latest-version.cjs` (#2992). _Avoid_: "package name string", "the npm name" (when you mean the seam). See ADR-457 and Installer Module.
 
 ### Update Context Module [Planned]
-Module owning install detection for `/gsd:update`. `resolveUpdateContext({ home, cwd, env, fs, preferredConfigDir, preferredRuntime })` is a pure, injected-fs port of update.md's former ~280-line `get_installed_version` bash; it reproduces the full precedence cascade — preferred-config-dir fast path, local-over-global probe with same-path dedup, env-var overrides (`CLAUDE_CONFIG_DIR`, `OPENCODE_CONFIG`, `KILO_CONFIG`, `XDG_CONFIG_HOME`, `CODEX_HOME`, …), and semver validation — and returns the 4-field contract `{ installedVersion, scope, runtime, gsdDir }` (scope ∈ `LOCAL`/`GLOBAL`/`UNKNOWN`). Antigravity is modelled first-class (its `.gemini/antigravity{,-ide,-cli}` dirs probe before bare `.gemini`; #3608). Exposed to the workflow as `gsd-tools update-context [--config-dir <d>] [--runtime <r>] --json`; `loadUpdateContext` wires the real fs. The workflow keeps only the execution_context path → `PREFERRED_*` derivation (the one input it alone knows). Source: `get-shit-done/bin/lib/update-context.cjs`; tests: `tests/issue-498-update-context.test.cjs`. See Installer Module and Package Identity Module.
+Module owning install detection for `/gsd:update`. `resolveUpdateContext({ home, cwd, env, fs, preferredConfigDir, preferredRuntime })` is a pure, injected-fs port of update.md's former ~280-line `get_installed_version` bash; it reproduces the full precedence cascade — preferred-config-dir fast path, local-over-global probe with same-path dedup, env-var overrides (`CLAUDE_CONFIG_DIR`, `OPENCODE_CONFIG`, `KILO_CONFIG`, `XDG_CONFIG_HOME`, `CODEX_HOME`, …), and semver validation — and returns the 4-field contract `{ installedVersion, scope, runtime, gsdDir }` (scope ∈ `LOCAL`/`GLOBAL`/`UNKNOWN`). Antigravity is modelled first-class (its `.gemini/antigravity{,-ide,-cli}` dirs probe before bare `.gemini`; #3608). Exposed to the workflow as `gsd-tools update-context [--config-dir <d>] [--runtime <r>] --json`; `loadUpdateContext` wires the real fs. The workflow keeps only the execution_context path → `PREFERRED_*` derivation (the one input it alone knows). Source: `gsd-core/bin/lib/update-context.cjs`; tests: `tests/issue-498-update-context.test.cjs`. See Installer Module and Package Identity Module.
 
 ### Skill Surface Budget Module
-Module owning which skills and agents are written to runtime config directories at install time (Phase 1) and at runtime via cluster-level toggles (Phase 2). Phase 1: `get-shit-done/bin/lib/install-profiles.cjs` defines named profiles (`core`, `standard`, `full`), computes transitive closure over `requires:` frontmatter, stages skills/agents to runtime config dirs, and persists the chosen profile in a `.gsd-profile` marker. Profile resolution precedence: explicit `--profile=` flag > `.gsd-profile` marker > `full`. `--minimal`/`--core-only` are back-compat aliases for `--profile=core`. Phase 2: `get-shit-done/bin/lib/surface.cjs` implements the `/gsd:surface` slash command for cluster-level enable/disable without reinstall; cluster definitions live in `get-shit-done/bin/lib/clusters.cjs`; per-runtime state persists in `<runtimeConfigDir>/.gsd-surface.json` independent from the `.gsd-profile` marker. See ADR-0011.
+Module owning which skills and agents are written to runtime config directories at install time (Phase 1) and at runtime via cluster-level toggles (Phase 2). Phase 1: `gsd-core/bin/lib/install-profiles.cjs` defines named profiles (`core`, `standard`, `full`), computes transitive closure over `requires:` frontmatter, stages skills/agents to runtime config dirs, and persists the chosen profile in a `.gsd-profile` marker. Profile resolution precedence: explicit `--profile=` flag > `.gsd-profile` marker > `full`. `--minimal`/`--core-only` are back-compat aliases for `--profile=core`. Phase 2: `gsd-core/bin/lib/surface.cjs` implements the `/gsd:surface` slash command for cluster-level enable/disable without reinstall; cluster definitions live in `gsd-core/bin/lib/clusters.cjs`; per-runtime state persists in `<runtimeConfigDir>/.gsd-surface.json` independent from the `.gsd-profile` marker. See ADR-0011.
 
 ### Runtime Artifact Layout Module
 Module owning the per-runtime mapping from artifact kind to filesystem placement. ADR-3660 defines the typed `kinds` per runtime (`commands`, `agents`, `skills`) with destination subpath, prefix, and stage adapter (with per-runtime converters in `bin/install.js`: `convertClaudeCommandToClaudeSkill`, `…CodexSkill`, `…CopilotSkill`, `…AntigravitySkill`). Phase 1 applies this seam to the Runtime Surface Module (`surface.cjs:applySurface`). Phase 2 is planned to migrate install/uninstall in `bin/install.js` so all lifecycle sites iterate one shared layout table instead of re-encoding runtime layout logic. This design is intended to remove the #3659 class of omissions. Migrations remain under the Installer Migration Module (ADR-0008). See ADR-3660.
 
 ### Knowledge Graph Module
-Module owning the graphify integration: config gate (`isGraphifyEnabled`), disabled response (`disabledResponse`), subprocess helper (`execGraphify`, typed `GRAPHIFY_REASON` enum), presence detection (`checkGraphifyInstalled`), version checking (`checkGraphifyVersion`), query surface (`graphifyQuery` — BFS seed-expand + budget trim), status surface (`graphifyStatus` — node/edge counts, mtime staleness, commit-staleness tri-state via `built_at_commit`/`commits_behind`/`commit_stale`), diff surface (`graphifyDiff` — added/removed/changed nodes+edges), build pre-flight (`graphifyBuild`), snapshot management (`writeSnapshot`). Reads `.planning/config.json:graphify.enabled` as config gate; writes to `.planning/graphs/`. Auto-update hook (`hooks/gsd-graphify-update.sh`) triggers a detached background rebuild after HEAD-advancing git operations on the default branch when `graphify.auto_update=true`. Status file `.planning/graphs/.last-build-status.json` carries `{ ts, status, exit_code, duration_ms, head_at_build, graphify_version }`. Graph IR uses `nodes[]`, `edges[]` (or `links[]` for graphify ≥0.7 compat), `hyperedges[]`, `built_at_commit`. `commit_stale` is tri-state: `false` (known fresh), `true` (stale), `null` (unknown — no git or pre-v0.7 graph). Source: `get-shit-done/bin/lib/graphify.cjs`. Skill: `commands/gsd/graphify.md`.
+Module owning the graphify integration: config gate (`isGraphifyEnabled`), disabled response (`disabledResponse`), subprocess helper (`execGraphify`, typed `GRAPHIFY_REASON` enum), presence detection (`checkGraphifyInstalled`), version checking (`checkGraphifyVersion`), query surface (`graphifyQuery` — BFS seed-expand + budget trim), status surface (`graphifyStatus` — node/edge counts, mtime staleness, commit-staleness tri-state via `built_at_commit`/`commits_behind`/`commit_stale`), diff surface (`graphifyDiff` — added/removed/changed nodes+edges), build pre-flight (`graphifyBuild`), snapshot management (`writeSnapshot`). Reads `.planning/config.json:graphify.enabled` as config gate; writes to `.planning/graphs/`. Auto-update hook (`hooks/gsd-graphify-update.sh`) triggers a detached background rebuild after HEAD-advancing git operations on the default branch when `graphify.auto_update=true`. Status file `.planning/graphs/.last-build-status.json` carries `{ ts, status, exit_code, duration_ms, head_at_build, graphify_version }`. Graph IR uses `nodes[]`, `edges[]` (or `links[]` for graphify ≥0.7 compat), `hyperedges[]`, `built_at_commit`. `commit_stale` is tri-state: `false` (known fresh), `true` (stale), `null` (unknown — no git or pre-v0.7 graph). Source: `gsd-core/bin/lib/graphify.cjs`. Skill: `commands/gsd/graphify.md`.
 
 ### MVP Mode
 Phase-level planning mode that frames work as a vertical slice (UI → API → DB) of one user-visible capability instead of horizontal layers. Resolved at workflow init via the precedence chain: `--mvp` CLI flag → ROADMAP.md `**Mode:** mvp` field → `workflow.mvp_mode` config → false. All-or-nothing per phase (PRD #2826 Q1). Surfaced as `MVP_MODE=true|false` to the planner, executor, verifier, and discovery surfaces (progress, stats, graphify). Canonical parser: `roadmap.cjs` `**Mode:**` field; canonical resolution chain documented in `workflows/plan-phase.md`. Concept index: `references/mvp-concepts.md`.
@@ -140,7 +140,7 @@ Predicate over a PLAN.md task: `tdd="true"` frontmatter AND `<behavior>` block n
 Per-task runtime gate in `/gsd-execute-phase` that, when both `MVP_MODE` and `TDD_MODE` are true, refuses to advance a Behavior-Adding Task until a failing-test commit (`test({phase}-{plan})`) exists for it. The `tdd_review_checkpoint` end-of-phase review escalates from advisory to blocking under the same condition. Documented contract: `references/execute-mvp-tdd.md`. Reserved escape hatch `--force-mvp-gate` is documented but not implemented.
 
 ### SPIDR Splitting
-Five-axis story decomposition discipline (**S**pike, **P**aths, **I**nterfaces, **D**ata, **R**ules) used by `/gsd-mvp-phase` when a User Story is too large for one phase. Full interactive flow per PRD #2826 Q3 (not a lightweight filter). Reference: `get-shit-done/references/spidr-splitting.md`.
+Five-axis story decomposition discipline (**S**pike, **P**aths, **I**nterfaces, **D**ata, **R**ules) used by `/gsd-mvp-phase` when a User Story is too large for one phase. Full interactive flow per PRD #2826 Q3 (not a lightweight filter). Reference: `gsd-core/references/spidr-splitting.md`.
 
 ### Clock seam
 An injectable time abstraction accepted as an optional parameter by production code (`{ clock = Date } = {}`). Test code substitutes `node:test` `mock.timers` to control time deterministically without waiting for real OS scheduler events. Canonical pattern established by ADR 456 (`docs/adr/456-test-rigor-architecture.md`).
@@ -239,7 +239,7 @@ The canonical lint infrastructure adopted in ADR 452 (`docs/adr/452-eslint-lint-
 `PR.3267.POSTMORTEM.recovery=[issue#3270 created, label approved-enhancement applied, PR reopened, body includes "Closes #3270", label no-changelog applied]`
 
 `WORKTREE.SEAM.current=Worktree Safety Policy Module`
-`WORKTREE.SEAM.files=[get-shit-done/bin/lib/worktree-safety.cjs, get-shit-done/bin/lib/core.cjs]`
+`WORKTREE.SEAM.files=[gsd-core/bin/lib/worktree-safety.cjs, gsd-core/bin/lib/core.cjs]`
 `WORKTREE.SEAM.interface=[resolveWorktreeContext, parseWorktreePorcelain, planWorktreePrune, executeWorktreePrunePlan]`
 `WORKTREE.SEAM.default-prune-policy=metadata_prune_only (non-destructive)`
 `WORKTREE.SEAM.decision-1=retain non-destructive default; destructive path only as explicit future opt-in scaffold`
@@ -261,8 +261,8 @@ The canonical lint infrastructure adopted in ADR 452 (`docs/adr/452-eslint-lint-
 `PLANNING.PATH.PARITY.sdk-project-scope=.planning/<project> (never .planning/projects/<project>); mirror planning-workspace.cjs planningDir()`
 `PLANNING.PATH.SEAM.sdk=helpers.planningPaths delegates to workspacePlanningPaths + resolveWorkspaceContext; precedence explicit-ws > env-ws > env-project > root`
 `PLANNING.PATH.SEAM.init-handlers=[initExecutePhase, initPlanPhase, initPhaseOp, initMilestoneOp] consume helpers.planningPaths().planning (no direct relPlanningPath join)`
-`WORKSTREAM.NAME.POLICY.cjs-module=get-shit-done/bin/lib/workstream-name-policy.cjs owns toWorkstreamSlug + active-name/path-segment validation`
-`WORKSTREAM.POINTER.SEAM.cjs-module=get-shit-done/bin/lib/active-workstream-store.cjs owns read/write self-heal for .planning/active-workstream`
+`WORKSTREAM.NAME.POLICY.cjs-module=gsd-core/bin/lib/workstream-name-policy.cjs owns toWorkstreamSlug + active-name/path-segment validation`
+`WORKSTREAM.POINTER.SEAM.cjs-module=gsd-core/bin/lib/active-workstream-store.cjs owns read/write self-heal for .planning/active-workstream`
 `CONFIG.SEAM.loadConfig-context=loadConfig(cwd,{workstream}) replaces env-mutation fallback; no temporary process.env GSD_WORKSTREAM rewrites`
 
 ---
@@ -325,7 +325,7 @@ The canonical lint infrastructure adopted in ADR 452 (`docs/adr/452-eslint-lint-
 `PRED.k320.types=Added|Changed|Deprecated|Removed|Fixed|Security`
 `PRED.k320.opt-out-label=no-changelog`
 `PRED.k320.ci-enforcement=scripts/changeset/lint.cjs`
-`PRED.k320.ci-paths-monitored=bin/ get-shit-done/ agents/ commands/ docs/ hooks/ tests/ scripts/`
+`PRED.k320.ci-paths-monitored=bin/ gsd-core/ agents/ commands/ docs/ hooks/ tests/ scripts/`
 `PRED.k320.recovery=open Removed-typed cleanup PR deleting only the redundant row`
 `PRED.k320.evidence=PR #3302 merge-conflict against #3308 CHANGELOG.md row 2026-05-09`
 
@@ -424,7 +424,7 @@ The canonical lint infrastructure adopted in ADR 452 (`docs/adr/452-eslint-lint-
 
 `DEFECT.REMOVED-BUT-NEEDED.symptom=file/key removed because "no longer used" without verifying every consumer (workflows, docs, manifests, npm scripts)`
 `DEFECT.REMOVED-BUT-NEEDED.examples=#3316 root package-lock.json (root package.json declares deps; workflows use cache:'npm' + npm ci), e3b52c70 docs referenced removed /gsd-new-workspace`
-`DEFECT.REMOVED-BUT-NEEDED.detect=before deletion, grep filename across .github/workflows, get-shit-done/, docs/, package.json scripts; if any reference exists removal is incomplete`
+`DEFECT.REMOVED-BUT-NEEDED.detect=before deletion, grep filename across .github/workflows, gsd-core/, docs/, package.json scripts; if any reference exists removal is incomplete`
 `DEFECT.REMOVED-BUT-NEEDED.fix-forward=restore the file or update every consumer in the same commit; do not paper over with --no-package-lock or workflow workarounds that lose reproducibility`
 
 `DEFECT.STATE-TRAMPLE.symptom=state-mutation paths overwrite curated values when body-derived computation is narrower than what's stored in frontmatter`
@@ -458,7 +458,7 @@ The canonical lint infrastructure adopted in ADR 452 (`docs/adr/452-eslint-lint-
 `DEFECT.PROMPT-INJECTION-SCAN-COLLISION.detect=any new bare <system|assistant|human|user> tag in agents/*.md`
 `DEFECT.PROMPT-INJECTION-SCAN-COLLISION.fix-forward=hyphenate the tag (<human-check>, <assistant-prompt>) — scanner regex matches bare names only`
 
-`DEFECT.INVENTORY-DRIFT.symptom=new file added under get-shit-done/references/ or get-shit-done/workflows/ without updating docs/INVENTORY.md count + row AND docs/INVENTORY-MANIFEST.json`
+`DEFECT.INVENTORY-DRIFT.symptom=new file added under gsd-core/references/ or gsd-core/workflows/ without updating docs/INVENTORY.md count + row AND docs/INVENTORY-MANIFEST.json`
 `DEFECT.INVENTORY-DRIFT.examples=#3309 planner-human-verify-mode.md (caught by tests/inventory-counts.test.cjs + tests/inventory-manifest-sync.test.cjs)`
 `DEFECT.INVENTORY-DRIFT.detect=tests/inventory-* fails with "References (N shipped) disagrees with filesystem" or "New surfaces not in manifest"`
 `DEFECT.INVENTORY-DRIFT.fix-forward=update INVENTORY.md headline count + row entry + footnote count; run node scripts/gen-inventory-manifest.cjs --write to regen INVENTORY-MANIFEST.json; only families.workflows is canonical (top-level workflows key is stale)`
@@ -466,7 +466,7 @@ The canonical lint infrastructure adopted in ADR 452 (`docs/adr/452-eslint-lint-
 `DEFECT.AGENT-FILE-SIZE-CAP-BREACH.symptom=adding to agents/gsd-planner.md (or other large agent files) exceeds the 45K char extraction-evidence threshold`
 `DEFECT.AGENT-FILE-SIZE-CAP-BREACH.state=gsd-planner.md is already 49,121 chars on main (over 45K); test fails on main; net-new content makes it strictly worse`
 `DEFECT.AGENT-FILE-SIZE-CAP-BREACH.detect=tests/planner-decomposition.test.cjs ("planner is under 45K chars (proves mode sections were extracted)") and tests/reachability-check.test.cjs ("file stays under 50000 char limit")`
-`DEFECT.AGENT-FILE-SIZE-CAP-BREACH.fix-forward=mirror MVP mode pattern — extract full rules to get-shit-done/references/planner-<mode>.md, leave a slim Detection section in the agent file with @-reference to the new file`
+`DEFECT.AGENT-FILE-SIZE-CAP-BREACH.fix-forward=mirror MVP mode pattern — extract full rules to gsd-core/references/planner-<mode>.md, leave a slim Detection section in the agent file with @-reference to the new file`
 
 `DEFECT.CHANGESET-PR-FIELD-DRIFT.symptom=.changeset/*.md frontmatter pr: value is the issue number, a guess made before PR opened, or a stale stacked-PR number`
 `DEFECT.CHANGESET-PR-FIELD-DRIFT.examples=#3316 (pr:3312 was the issue), #3325 (pr:3319 was a guess); already covered in CONTEXT.md L94 + L186 but recurs every cycle`
@@ -521,7 +521,7 @@ The canonical lint infrastructure adopted in ADR 452 (`docs/adr/452-eslint-lint-
 
 ## Shell Command Projection Module (expanded glossary entry, 2026-05-13)
 
-Module owning all OS-facing I/O for the tool: runtime-aware command-text rendering (hook commands, PATH action lines, shim scripts), subprocess dispatch (run-git, run-npm, run-tool, probeTty), and platform file I/O (platformWriteSync, platformReadSync, platformEnsureDir). Single seam for platform-conditional logic — one place to fix any shell or file write regression across Windows, macOS, and Linux. Lives in `get-shit-done/bin/lib/shell-command-projection.cjs`. See ADR-0009 (superseded "does not execute" constraint) and ADR-0010 (superseded File Operation Engine).
+Module owning all OS-facing I/O for the tool: runtime-aware command-text rendering (hook commands, PATH action lines, shim scripts), subprocess dispatch (run-git, run-npm, run-tool, probeTty), and platform file I/O (platformWriteSync, platformReadSync, platformEnsureDir). Single seam for platform-conditional logic — one place to fix any shell or file write regression across Windows, macOS, and Linux. Lives in `gsd-core/bin/lib/shell-command-projection.cjs`. See ADR-0009 (superseded "does not execute" constraint) and ADR-0010 (superseded File Operation Engine).
 
 Invariants:
 - Result shape: all run-* return `{ exitCode, stdout, stderr }`; never throw on non-zero exit code.
@@ -590,8 +590,8 @@ Migration plan: Phase 1 (#3465) seam additions complete; Phase 2 (#3466) targets
 
 ## Executor failure classification (#3095 / PR #3490)
 
-`EXEC.CLASSIFY.handler=get-shit-done/bin/lib/agent-command-router.cjs:classifyAgentFailure (registered via command-aliases.cjs; mutation:false outputMode:json)`
-`EXEC.CLASSIFY.workflow=get-shit-done/workflows/execute-phase.md step 7; class-distinct prompts (quota-to-wait-for-reset; classify-handoff-bug-to-spot-check; unknown-to-continue/stop)`
+`EXEC.CLASSIFY.handler=gsd-core/bin/lib/agent-command-router.cjs:classifyAgentFailure (registered via command-aliases.cjs; mutation:false outputMode:json)`
+`EXEC.CLASSIFY.workflow=gsd-core/workflows/execute-phase.md step 7; class-distinct prompts (quota-to-wait-for-reset; classify-handoff-bug-to-spot-check; unknown-to-continue/stop)`
 `EXEC.CLASSIFY.classes={class:'quota-exceeded'|'classify-handoff-bug'|'unknown-failure', sentinel?, retryAfterSeconds?}`
 `EXEC.CLASSIFY.sentinel-order=most specific first: 429 beats too-many-requests; quota beats resource_exhausted; case-insensitive; canonical sentinel value is lower-cased form`
 `EXEC.CLASSIFY.cross-runtime=Anthropic/CC: usage limit|rate limit|quota|429|retry-after; Copilot CLI: rate_limit (stem); Codex CLI: 429|usage_limit_reached|too many requests; Gemini CLI: RESOURCE_EXHAUSTED|exceeded your`
@@ -602,7 +602,7 @@ Migration plan: Phase 1 (#3465) seam additions complete; Phase 2 (#3466) targets
 `DEFECT.GSD-TEST-MIRROR-POISONED.symptom=gsd-test-summary --both exits docker=23 (rsync partial transfer) with mkstemp Permission denied on remote mirror files; mirror has root-owned artifacts from prior cold runs`
 `DEFECT.GSD-TEST-MIRROR-POISONED.detect=docker stderr shows rsync: [generator] delete_file: unlink(...) failed: Permission denied (13) OR [receiver] mkstemp ".gsd-*.<suffix>" failed`
 `DEFECT.GSD-TEST-MIRROR-POISONED.root-cause=container ran without --user; build:hooks wrote into bind-mount as root; chown-back-before-exec patch closes forward path but not legacy hosts`
-`DEFECT.GSD-TEST-MIRROR-POISONED.recovery=ssh <host> 'docker run --rm -v ~/gsd-mirror-get-shit-done:/work gsd-test:node22 chown -R <remote-uid>:<remote-gid> /work'; remote-uid is the SSH user's uid on the remote (1000 on holodeck, NOT local Mac 501)`
+`DEFECT.GSD-TEST-MIRROR-POISONED.recovery=ssh <host> 'docker run --rm -v ~/gsd-mirror-gsd-core:/work gsd-test:node22 chown -R <remote-uid>:<remote-gid> /work'; remote-uid is the SSH user's uid on the remote (1000 on holodeck, NOT local Mac 501)`
 `DEFECT.GSD-TEST-MIRROR-POISONED.upstream=trek-e/gsd-test-runner#1 — proposes self-healing init-time chown probe`
 
 `DEFECT.HOOK-OVER-ENFORCEMENT.read-tool-tracking=gh-templates-first PreToolUse hook tracks Read tool invocations specifically; Bash cat/head of the same file does NOT satisfy the hook; future-self must use Read tool from the first contact with template files`

CONTRIBUTING.md

@@ -179,8 +179,6 @@ Contributor requirements (summary):
 - Do not rewrite maintainer intent in `CONTEXT.md`/ADRs as part of drive-by cleanup; propose focused updates tied to approved scope.
 - If using an AI assistant, prompt it to read `CONTEXT.md` and the relevant ADRs before writing any code or docs, and verify it used the correct vocabulary before opening the PR.
 
-**CJS↔SDK seam.** When working on `bin/lib/*.cjs` or `sdk/src/**`, read [`docs/agents/cjs-sdk-seam.md`](docs/agents/cjs-sdk-seam.md). It documents the canonical pattern for Shared Modules (data manifest + source-of-truth file + generator + freshness check + Adapters) and the hand-sync pair lint that blocks new drift. New `<name>.cjs` ↔ `<name>.ts` pairs require either migration to a Shared Module or an explicit allowlist entry with justification in `scripts/shared-module-handsync-allowlist.json`. Adding an allowlist entry requires maintainer review via CODEOWNERS.
-
 **Every PR must link to an approved issue.** PRs without a linked issue are closed without review, no exceptions.
 
 - **No draft PRs** — draft PRs are automatically closed. Only open a PR when it is complete, tested, and ready for review. If your work is not finished, keep it on your local branch until it is.
@@ -205,10 +203,31 @@ This writes `.changeset/<adjective>-<noun>-<noun>.md`. Three random words → co
 
 Fragments are consolidated into `CHANGELOG.md` at release time by the release workflow. See [`.changeset/README.md`](.changeset/README.md) for the format spec and [#2975](https://github.com/open-gsd/gsd-core/issues/2975) for the rationale.
 
-**CI enforcement:** the `Changeset Required` workflow (`scripts/changeset/lint.cjs`) fails any PR that touches `bin/`, `get-shit-done/`, `agents/`, `commands/`, `hooks/`, or `sdk/src/` without a `.changeset/*.md` fragment.
+**CI enforcement:** the `Changeset Required` workflow (`scripts/changeset/lint.cjs`) fails any PR that touches `bin/`, `gsd-core/`, `agents/`, `commands/`, `hooks/`, or `sdk/src/` without a `.changeset/*.md` fragment.
 
 **Opt-out:** PRs with no user-facing impact (test refactors, lint config changes, CI tweaks, formatting-only changes) can add the `no-changelog` label. The lint honors it. When unsure whether a change is user-facing, **add the fragment**.
 
+### Release notes formatting
+
+GitHub release notes are generated automatically. The release and hotfix
+workflows first create the release with `gh release create --generate-notes`,
+then run `scripts/release-notes/format-github-release-notes.cjs --apply` to
+rewrite the body into the project's curated format: an **Install** block,
+followed by **What's Changed** grouped into **Feature** / **Enhancement** /
+**Fix** sections (classified by each PR's conventional-commit title prefix —
+`feat` → Feature, `fix` → Fix, everything else → Enhancement), then
+**New Contributors** and the **Full Changelog** link.
+
+To re-format an existing release by hand (e.g. backfilling an older release):
+
+```bash
+node scripts/release-notes/format-github-release-notes.cjs \
+  --tag vX.Y.Z --repo open-gsd/gsd-core --apply
+```
+
+Omit `--apply` to print the reformatted body to stdout for review without
+publishing.
+
 ## Documentation Updates — Update the Relevant Docs
 
 If your PR adds, changes, deprecates, or removes user-visible behavior, you **must** update the relevant documentation in `docs/`. CI will fail any PR whose changeset fragment is typed `Added`, `Changed`, `Deprecated`, or `Removed` without also modifying at least one file under `docs/` ([#3213](https://github.com/open-gsd/gsd-core/issues/3213)).
@@ -515,7 +534,7 @@ Generator tests should run in temp fixtures and assert atomic output behavior. D
 ```javascript
 // BAD — source-grep theater
 const configSrc = fs.readFileSync(
-  path.join(GSD_ROOT, 'bin', 'lib', 'config-schema.cjs'), 'utf-8'
+  path.join(GSD_ROOT, 'gsd-core', 'bin', 'lib', 'config-schema.cjs'), 'utf-8'
 );
 assert.ok(
   configSrc.includes("'workflow.plan_bounce'"),
@@ -546,7 +565,7 @@ This single test covers key registration in `VALID_CONFIG_KEYS`, the key's names
 
 **Why this pattern broke at scale:** Commit `990c3e64` in this repo updated 5 source-grep tests in one pass when `VALID_CONFIG_KEYS` moved between files. Zero of those tests were testing behavior. If they had been behavioral tests, the migration would have been invisible.
 
-**CI enforcement:** A linter (`scripts/lint-no-source-grep.cjs`, run as `npm run lint:tests`) detects violations. Any test file that calls `readFileSync` on a `.cjs` path in a source directory without the exemption annotation below will fail the `lint-tests` CI job.
+**CI enforcement:** The `local/no-source-grep` ESLint rule (`eslint-rules/no-source-grep.cjs`, wired in `eslint.config.mjs`) detects violations. Any test file that calls `readFileSync` on a `.cjs` path in a source directory without the exemption annotation below is flagged by `npx eslint .` (the `Lint — ESLint` CI step).
 
 ### Exception: `allow-test-rule: <reason>`
 
@@ -617,11 +636,9 @@ Concretely: for any system-under-test that produces text output (a file renderer
 | Error / status / reason | A frozen enum (`Object.freeze({ FAIL_X: 'fail_x', ... })`) | `assert.equal(result.reason, REASON.FAIL_X)` |
 | File presence after a write | `fs.statSync().isFile()`, `.size > 0`, `.mtimeMs` advances | Filesystem facts; never read the file content back |
 
-#### Concrete examples from this repo
+#### Concrete example from this repo
 
-`buildWindowsShimTriple(shimSrc)` in `bin/install.js` is the canonical IR pattern: pure function, no I/O, returns `{ invocation, eol, fileNames, render }`. `trySelfLinkGsdSdkWindows` calls it and writes `triple.render[kind]()` to disk. Tests assert on `triple.invocation.target`, `triple.eol.cmd`, `Object.keys(triple).sort()` — never on the rendered text. Filesystem-level tests assert `fs.statSync(target).size === Buffer.byteLength(triple.render.cmd())` to prove the writer writes what the renderer produces, **without comparing content**.
-
-`scripts/verify-reapply-patches.cjs` exposes a frozen `REASON` enum and emits it through `--json`. Tests assert `report.results[0].reason === REASON.FAIL_USER_LINES_MISSING`. The human formatter exists for operator console output only — tests must not depend on its prose. Adding a new reason code requires updating the `REASON` enum, the `--json` output, AND the test that locks `Object.keys(REASON).sort()` — three coordinated changes that prevent the code surface from drifting from the test surface.
+`gsd-core/bin/verify-reapply-patches.cjs` exposes a frozen `REASON` enum and emits it through `--json`. Tests assert `report.results[0].reason === REASON.FAIL_USER_LINES_MISSING` rather than regex-matching the human-readable prose. The human formatter exists for operator console output only — tests must not depend on it. Adding a new reason code requires updating the `REASON` enum, the `--json` output, AND the test that locks `Object.keys(REASON).sort()` — three coordinated changes that keep the code surface from drifting from the test surface. A pure builder that returns the IR (no I/O) and a writer that consumes it — `fs.statSync(target).size === Buffer.byteLength(render())` to prove the writer writes what the renderer produces, **without comparing content** — is the same pattern applied to rendered files.
 
 #### Hiding grep behind a function is still grep
 
@@ -636,7 +653,7 @@ There are exactly two cases where text content is the legitimate object of a tes
 
 For everything else, if a test reaches for `.includes()` / `.startsWith()` / `assert.match(text, /…/)`, the production code is missing a typed surface. **Add the typed surface; do not work around it.**
 
-**CI enforcement:** `scripts/lint-no-source-grep.cjs` is being extended (see issue tracker for the latest scope) to flag `String#includes`/`String#startsWith`/`String#endsWith`/`assert.match` on `readFileSync` results and on `cp.spawnSync` stdout/stderr in test files, with the same `// allow-test-rule:` exemption mechanism.
+**CI enforcement:** the `local/no-source-grep` ESLint rule (`eslint-rules/no-source-grep.cjs`) is being extended (see issue tracker for the latest scope) to flag `String#includes`/`String#startsWith`/`String#endsWith`/`assert.match` on `readFileSync` results and on `cp.spawnSync` stdout/stderr in test files, with the same `// allow-test-rule:` exemption mechanism.
 
 ### Node.js Version Compatibility
 
@@ -718,7 +735,7 @@ cat > .githooks/pre-commit <<'EOF'
 #!/usr/bin/env bash
 set -euo pipefail
 
-if git diff --cached --name-only | grep -Eq "^sdk/src/query/command-manifest\.|^sdk/src/query/command-aliases\.generated\.ts$|^get-shit-done/bin/lib/command-aliases\.generated\.cjs$|^sdk/scripts/gen-command-aliases\.ts$"; then
+if git diff --cached --name-only | grep -Eq "^sdk/src/query/command-manifest\.|^sdk/src/query/command-aliases\.generated\.ts$|^gsd-core/bin/lib/command-aliases\.generated\.cjs$|^sdk/scripts/gen-command-aliases\.ts$"; then
   npm run check:alias-drift
 fi
 EOF
@@ -772,11 +789,9 @@ The following checks run on every PR in addition to the test suite:
 
 | Job | What it checks | How to pass |
 |-----|----------------|-------------|
-| `lint-tests` | No source-grep tests (see above) | Replace with `runGsdTools()` behavioral tests, or add `// allow-test-rule: <reason>` |
+| `Lint — ESLint` | No source-grep tests (see above), via the `local/no-source-grep` rule | Replace with `runGsdTools()` behavioral tests, or add `// allow-test-rule: <reason>` |
 
-Run locally before pushing: `npm run lint:tests`
-
-### Test Requirements by Contribution Type
+Run locally before pushing: `npm run lint` (or `npx eslint .`)
 
 ### Architecture-Aware Testing Requirements
 
@@ -786,6 +801,8 @@ When work touches architecture, routing, policy, registry assembly, or command s
 - Ensure tests validate canonical behavior through the defined seam (for example: structured result contracts, canonical command metadata, and adapter parity), not source-text coupling.
 - If ADRs define expected behavior, tests should assert those expectations directly.
 
+### Test Requirements by Contribution Type
+
 The required tests differ depending on what you are contributing:
 
 **Bug Fix:** A regression test is required. Write the test first — it must demonstrate the original failure before your fix is applied, then pass after the fix. A PR that fixes a bug without a regression test will be asked to add one. If the bug involves CLI input, parsers, filesystem writes, security/prompt surfaces, generated files, or SDK/runtime parity, the regression test must use the relevant QA matrix above and include negative proof that the bad behavior no longer happens. "Tests pass" does not prove correctness; it proves the bug isn't present in the tests that exist.
@@ -823,7 +840,7 @@ Defensive normalization at trust boundaries must validate both the value's type
 
 ```
 bin/install.js          — Installer (multi-runtime)
-get-shit-done/
+gsd-core/
   bin/lib/              — Core library modules (.cjs)
   workflows/            — Workflow definitions (.md)
                           Large workflows split per progressive-disclosure

README.ja-JP.md

@@ -1,16 +1,12 @@
-> ⚠️ This is an active fork. See the [English README](README.md) for the full notice about the original repo.
-
 <div align="center">
 
 # GSD Core
 
 **Git. Ship. Done.**
 
-[English](README.md) · [Português](README.pt-BR.md) · [简体中文](README.zh-CN.md) · **日本語**
+[English](README.md) · [Português](README.pt-BR.md) · [简体中文](README.zh-CN.md) · **日本語** · [한국어](README.ko-KR.md)
 
-**Claude Code、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf、Antigravity、Augment、Trae、Cline向けの軽量かつ強力なメタプロンプティング、コンテキストエンジニアリング、仕様駆動開発システム。**
-
-**コンテキストロット（Claudeがコンテキストウィンドウを消費するにつれ品質が劣化する現象）を解決します。**
+**Claude Code、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf などに対応した、軽量なメタプロンプティング・コンテキストエンジニアリング・仕様駆動開発システムです。**
 
 [![npm version](https://img.shields.io/npm/v/%40opengsd%2Fgsd-core?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@opengsd/gsd-core)
 [![npm downloads](https://img.shields.io/npm/dm/%40opengsd%2Fgsd-core?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@opengsd/gsd-core)
@@ -19,830 +15,88 @@
 [![GitHub stars](https://img.shields.io/github/stars/open-gsd/gsd-core?style=for-the-badge&logo=github&color=181717)](https://github.com/open-gsd/gsd-core)
 [![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
 
-<br>
-
-```bash
-npx @opengsd/gsd-core@latest
-```
-
-**Mac、Windows、Linuxで動作します。**
-
-<br>
-
-![GSD Install](assets/terminal.svg)
-
-<br>
-
-*「自分が何を作りたいか明確に分かっていれば、これが確実に作ってくれる。嘘じゃない。」*
-
-*「SpecKit、OpenSpec、Taskmasterを試してきたが、これが一番良い結果を出してくれた。」*
-
-*「Claude Codeへの最強の追加ツール。過剰な設計は一切なし。文字通り、やるべきことをやってくれる。」*
-
-<br>
-
-**Amazon、Google、Shopify、Webflowのエンジニアに信頼されています。**
-
-[なぜ作ったのか](#なぜ作ったのか) · [仕組み](#仕組み) · [コマンド](#コマンド) · [なぜ効果的なのか](#なぜ効果的なのか) · [ユーザーガイド](docs/ja-JP/USER-GUIDE.md)
-
 </div>
 
 ---
 
-## なぜ作ったのか
+## GSD Core とは
 
-私はソロ開発者です。コードは自分で書きません — Claude Codeが書きます。
-
-仕様駆動開発ツールは他にもあります。BMAD、Spekkitなど。しかしどれも必要以上に複雑にしているように見えます（スプリントセレモニー、ストーリーポイント、ステークホルダーとの同期、振り返り、Jiraワークフローなど）。あるいは、何を作ろうとしているのかの全体像を本当には理解していません。私は50人規模のソフトウェア会社ではありません。エンタープライズごっこをしたいわけではありません。ただ、うまく動く素晴らしいものを作りたいクリエイティブな人間です。
-
-だからGSDを作りました。複雑さはシステムの中にあり、ワークフローの中にはありません。裏側では、コンテキストエンジニアリング、XMLプロンプトフォーマッティング、サブエージェントのオーケストレーション、状態管理が動いています。あなたが目にするのは、ただ動くいくつかのコマンドだけです。
-
-このシステムは、Claudeが仕事をし、*かつ*検証するために必要なすべてを提供します。私はこのワークフローを信頼しています。ちゃんといい仕事をしてくれます。
-
-これがGSDです。エンタープライズごっこは一切なし。Claude Codeを使って一貫してクールなものを作るための、非常に効果的なシステムです。
-
-— **TÂCHES**
+GSD Core は、コンテキストエンジニアリングと仕様駆動開発のフレームワークです。AI コーディングエージェント（Claude Code、Codex、Gemini CLI、Copilot、Cursor など）を規律あるフェーズループで動かします。[コンテキストの腐敗](docs/ja-JP/explanation/context-engineering.md)—AI がコンテキストウィンドウを埋めるにつれて出力品質が低下する問題—を解決するために、重いリサーチ・計画・実行作業をすべて新鮮なコンテキストのサブエージェントで実行し、メインセッションをスリムに保ちます。
 
 ---
 
-バイブコーディングは評判が悪い。やりたいことを説明し、AIがコードを生成し、スケールすると崩壊する一貫性のないゴミが出来上がる。
+## 動作原理
 
-GSDはそれを解決します。Claude Codeを信頼性の高いものにするコンテキストエンジニアリングレイヤーです。アイデアを説明し、システムに必要なすべてを抽出させ、Claude Codeに仕事をさせましょう。
+各マイルストーンは同じ 5 ステップのループを、1 フェーズずつ繰り返します。
+
+1. **Discuss（議論）** — 計画を立てる前に実装上の決定事項を記録する
+2. **Plan（計画）** — リサーチし、タスクを分解し、計画が新鮮なコンテキストウィンドウに収まることを確認する
+3. **Execute（実行）** — 並列ウェーブで計画を実行する。各エグゼキューターはクリーンな 200k トークンのコンテキストから開始する
+4. **Verify（検証）** — 構築されたものを確認し、完了を宣言する前に診断・修正する
+5. **Ship（出荷）** — PR を作成し、フェーズをアーカイブし、次のフェーズに進む
 
 ---
 
-## こんな人のために
-
-やりたいことを説明するだけで正しく構築してほしい人 — 50人のエンジニア組織を運営しているふりをせずに。
-
-ビルトインの品質ゲートが本当の問題を検出します：スキーマドリフト検出はマイグレーション漏れのORM変更をフラグし、セキュリティ強制は検証を脅威モデルに紐付け、スコープ削減検出はプランナーが要件を暗黙的に落とすのを防止します。
-
-### 機能ハイライト
-
-正規のバージョンは npm に公開された `@opengsd/gsd-core` のバージョンと `package.json` です。`docs/` の古いリリースノートは継続性の履歴として残しているだけで、現在の GSD Core パッケージバージョンではありません。
-
-- **`--minimal` インストールプロファイル** — エイリアス `--core-only`。メインループの6スキル（`new-project`、`discuss-phase`、`plan-phase`、`execute-phase`、`help`、`update`）のみをインストールし、`gsd-*` サブエージェントはゼロ。コールドスタート時のシステムプロンプトのオーバーヘッドを ~12kトークンから ~700トークンへ削減（≥94%減）。32K〜128Kコンテキストのローカル LLM やトークン課金 API に有効。
-- **`/gsd-phase --edit`** — `ROADMAP.md` 上の既存フェーズの任意フィールドをその場で編集（番号や位置は変更されない）。`--force` で確認 diff をスキップ、`depends_on` の参照を検証し、書き込み時に `STATE.md` も更新。
-- **マージ後ビルド & テストゲート** — `execute-phase` のステップ 5.6 が `workflow.build_command` の設定を自動検出し、無ければ Xcode（`.xcodeproj`）、Makefile、Justfile、Cargo、Go、Python、npm の順にフォールバック。Xcode/iOS プロジェクトでは `xcodebuild build` と `xcodebuild test` を自動実行。並列・直列両モードで動作。
-- **ランタイム別レビューモデル選択** — `review.models.<cli>` で各外部レビュー CLI（codex、gemini など）が使うモデルをプランナー/実行プロファイルとは独立に指定可能。
-- **ワークストリーム設定の継承** — `GSD_WORKSTREAM` が設定されている場合、ルートの `.planning/config.json` を先に読み込み、ワークストリーム設定をディープマージ（衝突時はワークストリーム側が優先）。ワークストリーム設定で明示的に `null` を指定するとルート値を上書き可能。
-- **スキルの統合：86 → 59** — 4つの新しいグループ化スキル（`capture`、`phase`、`config`、`workspace`）が31のマイクロスキルを吸収。既存の親スキル6つはラップアップやサブ操作をフラグ化：`update --sync/--reapply`、`sketch --wrap-up`、`spike --wrap-up`、`map-codebase --fast/--query`、`code-review --fix`、`progress --do/--next`。機能の欠損なし。
-
----
-
-## はじめに
+## クイックスタート
 
 ```bash
 npx @opengsd/gsd-core@latest
 ```
 
-インストーラーが以下の選択を求めます：
-1. **ランタイム** — Claude Code、OpenCode、Gemini、Kilo、Codex、Copilot、Cursor、Windsurf、Antigravity、Augment、Trae、Cline、またはすべて（インタラクティブ複数選択 — 1回のインストールセッションで複数のランタイムを選択可能）
-2. **インストール先** — グローバル（全プロジェクト）またはローカル（現在のプロジェクトのみ）
+インストーラーはランタイム（Claude Code、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf など）とグローバルインストールかローカルインストールかを尋ねます。クロスランタイム互換性のためにインストーラーが必要です。`agents/` や `commands/` からファイルを直接コピーしないでください。
 
-確認方法：
-- Claude Code / Gemini / Copilot / Antigravity: `/gsd-help`
-- OpenCode / Kilo / Augment / Trae: `/gsd-help`
-- Codex: `$gsd-help`
-- Cline: GSDは`.clinerules`経由でインストール — `.clinerules`の存在を確認
+別のランタイムをお使いの場合や Node.js がない場合は [ランタイムへのインストール](docs/ja-JP/how-to/install-on-your-runtime.md) を参照してください。
 
-> [!NOTE]
-> Claude Code 2.1.88+とCodexはスキル（`skills/gsd-*/SKILL.md`）としてインストールされます。Clineは`.clinerules`を使用します。インストーラーがすべての形式を自動的に処理します。
-
-> [!TIP]
-> ソースベースのインストールやnpmが利用できない環境については、**[docs/manual-update.md](docs/manual-update.md)**を参照してください。
-
-### 最新の状態を保つ
-
-GSDは急速に進化しています。定期的にアップデートしてください：
+インストール後、最初のプロジェクトを開始します。
 
 ```bash
-npx @opengsd/gsd-core@latest
-```
-
-<details>
-<summary><strong>非インタラクティブインストール（Docker、CI、スクリプト）</strong></summary>
-
-```bash
-# Claude Code
-npx @opengsd/gsd-core --claude --global   # ~/.claude/ にインストール
-npx @opengsd/gsd-core --claude --local    # ./.claude/ にインストール
-
-# OpenCode
-npx @opengsd/gsd-core --opencode --global # ~/.config/opencode/ にインストール
-
-# Gemini CLI
-npx @opengsd/gsd-core --gemini --global   # ~/.gemini/ にインストール
-
-# Kilo
-npx @opengsd/gsd-core --kilo --global     # ~/.config/kilo/ にインストール
-npx @opengsd/gsd-core --kilo --local      # ./.kilo/ にインストール
-
-# Codex
-npx @opengsd/gsd-core --codex --global    # ~/.codex/ にインストール
-npx @opengsd/gsd-core --codex --local     # ./.codex/ にインストール
-
-# Copilot
-npx @opengsd/gsd-core --copilot --global  # ~/.github/ にインストール
-npx @opengsd/gsd-core --copilot --local   # ./.github/ にインストール
-
-# Cursor CLI
-npx @opengsd/gsd-core --cursor --global      # ~/.cursor/ にインストール
-npx @opengsd/gsd-core --cursor --local       # ./.cursor/ にインストール
-
-# Antigravity
-npx @opengsd/gsd-core --antigravity --global # ~/.gemini/antigravity/ にインストール
-npx @opengsd/gsd-core --antigravity --local  # ./.agent/ にインストール
-
-# Augment
-npx @opengsd/gsd-core --augment --global     # ~/.augment/ にインストール
-npx @opengsd/gsd-core --augment --local      # ./.augment/ にインストール
-
-# Trae
-npx @opengsd/gsd-core --trae --global        # ~/.trae/ にインストール
-npx @opengsd/gsd-core --trae --local         # ./.trae/ にインストール
-
-# Cline
-npx @opengsd/gsd-core --cline --global       # ~/.cline/ にインストール
-npx @opengsd/gsd-core --cline --local        # ./.clinerules にインストール
-
-# 全ランタイム
-npx @opengsd/gsd-core --all --global      # すべてのディレクトリにインストール
-```
-
-`--global`（`-g`）または `--local`（`-l`）でインストール先の質問をスキップできます。
-`--claude`、`--opencode`、`--gemini`、`--kilo`、`--codex`、`--copilot`、`--cursor`、`--windsurf`、`--antigravity`、`--augment`、`--trae`、`--cline`、または `--all` でランタイムの質問をスキップできます。
-
-</details>
-
-<details>
-<summary><strong>開発用インストール</strong></summary>
-
-リポジトリをクローンしてインストーラーをローカルで実行します：
-
-```bash
-git clone https://github.com/open-gsd/gsd-core.git
-cd gsd-core
-node bin/install.js --claude --local
-```
-
-コントリビュートする前に変更をテストするため、`./.claude/` にインストールされます。
-
-</details>
-
-### 推奨：パーミッションスキップモード
-
-GSDは摩擦のない自動化のために設計されています。Claude Codeを以下のように実行してください：
-
-```bash
-claude --dangerously-skip-permissions
-```
-
-> [!TIP]
-> これがGSDの意図された使い方です — `date` や `git commit` を50回も承認するために止まっていては目的が台無しです。
-
-<details>
-<summary><strong>代替案：詳細なパーミッション設定</strong></summary>
-
-このフラグを使いたくない場合は、プロジェクトの `.claude/settings.json` に以下を追加してください：
-
-```json
-{
-  "permissions": {
-    "allow": [
-      "Bash(date:*)",
-      "Bash(echo:*)",
-      "Bash(cat:*)",
-      "Bash(ls:*)",
-      "Bash(mkdir:*)",
-      "Bash(wc:*)",
-      "Bash(head:*)",
-      "Bash(tail:*)",
-      "Bash(sort:*)",
-      "Bash(grep:*)",
-      "Bash(tr:*)",
-      "Bash(git add:*)",
-      "Bash(git commit:*)",
-      "Bash(git status:*)",
-      "Bash(git log:*)",
-      "Bash(git diff:*)",
-      "Bash(git tag:*)"
-    ]
-  }
-}
-```
-
-</details>
-
----
-
-## 仕組み
-
-> **既存のコードがある場合は？** まず `/gsd-map-codebase` を実行してください。並列エージェントが起動し、スタック、アーキテクチャ、規約、懸念点を分析します。その後 `/gsd-new-project` がコードベースを把握した状態で動作し、質問は追加する内容に焦点を当て、計画時にはパターンが自動的に読み込まれます。
-
-### 1. プロジェクトの初期化
-
-```
 /gsd-new-project
 ```
 
-1つのコマンド、1つのフロー。システムが以下を行います：
-
-1. **質問** — アイデアを完全に理解するまで質問します（目標、制約、技術的な好み、エッジケース）
-2. **リサーチ** — 並列エージェントが起動しドメインを調査します（オプションですが推奨）
-3. **要件定義** — v1、v2、スコープ外を抽出します
-4. **ロードマップ** — 要件に紐づくフェーズを作成します
-
-ロードマップを承認します。これでビルドの準備が整いました。
-
-**作成されるファイル：** `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md`、`STATE.md`、`.planning/research/`
+初めての方は [はじめてのプロジェクト](docs/ja-JP/tutorials/your-first-project.md) で、インストールから最初のフェーズ出荷までのガイド付きチュートリアルをご覧ください。
 
 ---
 
-### 2. フェーズの議論
+## ドキュメント
 
-```
-/gsd-discuss-phase 1
-```
+**チュートリアル** — 実践で学ぶ:
+- [はじめてのプロジェクト](docs/ja-JP/tutorials/your-first-project.md)
+- [既存コードベースのオンボーディング](docs/ja-JP/tutorials/onboarding-an-existing-codebase.md)
 
-**ここで実装の方向性を決めます。**
+**ハウツーガイド** — タスク別レシピ:
+- [ランタイムへのインストール](docs/ja-JP/how-to/install-on-your-runtime.md)
+- [フェーズを計画する](docs/ja-JP/how-to/plan-a-phase.md)
+- [検証と出荷](docs/ja-JP/how-to/verify-and-ship.md)
+- … [すべてのハウツーガイドを見る](docs/ja-JP/README.md#how-to-guides)
 
-ロードマップには各フェーズにつき1〜2文しかありません。あなたが*想像する*通りに構築するには十分なコンテキストではありません。このステップでは、リサーチや計画の前にあなたの好みを記録します。
+**リファレンス** — 信頼できる情報:
+- [コマンド](docs/ja-JP/COMMANDS.md)
+- [設定](docs/ja-JP/CONFIGURATION.md)
+- [CLI ツール](docs/ja-JP/CLI-TOOLS.md)
 
-システムがフェーズを分析し、構築内容に基づいてグレーゾーンを特定します：
+**解説** — コンセプトと設計上の決定:
+- [コンテキストエンジニアリング](docs/ja-JP/explanation/context-engineering.md)
+- [フェーズループ](docs/ja-JP/explanation/the-phase-loop.md)
+- [アーキテクチャ](docs/ja-JP/ARCHITECTURE.md)
 
-- **ビジュアル機能** → レイアウト、密度、インタラクション、空状態
-- **API/CLI** → レスポンス形式、フラグ、エラーハンドリング、詳細度
-- **コンテンツシステム** → 構造、トーン、深さ、フロー
-- **整理タスク** → グルーピング基準、命名、重複、例外
-
-選択した各領域について、あなたが満足するまで質問します。出力される `CONTEXT.md` は、次の2つのステップに直接反映されます：
-
-1. **リサーチャーが読む** — どんなパターンを調査すべきかを把握（「ユーザーはカードレイアウトを希望」→ カードコンポーネントライブラリを調査）
-2. **プランナーが読む** — どの決定が確定済みかを把握（「無限スクロールに決定」→ スクロール処理を計画に含める）
-
-ここで深く掘り下げるほど、システムはあなたが本当に望むものを構築します。スキップすれば妥当なデフォルトが使われます。活用すれば*あなたのビジョン*が反映されます。
-
-**作成されるファイル：** `{phase_num}-CONTEXT.md`
-
-> **前提モード：** 質問よりもコードベース分析を優先したい場合は、`/gsd-settings` で `workflow.discuss_mode` を `assumptions` に設定してください。システムがコードを読み、何をなぜそうするかを提示し、間違っている部分だけ修正を求めます。詳しくは[ディスカスモード](docs/ja-JP/workflow-discuss-mode.md)をご覧ください。
+全インデックス: [docs/ja-JP/README.md](docs/ja-JP/README.md)。他の言語: [日本語](README.ja-JP.md) · [한국어](README.ko-KR.md) · [Português](README.pt-BR.md) · [简体中文](README.zh-CN.md)。
 
 ---
 
-### 3. フェーズの計画
+## なぜ機能するのか
 
-```
-/gsd-plan-phase 1
-```
+多くの AI コーディング環境は、コンテキストの膨張が出力品質を静かに低下させ、セッション間に共有メモリがなく、コードが実際に動作するかを検証するものがないため、大規模では失敗します。GSD Core はこの 3 つすべてを解決します。重い作業は新鮮なサブエージェントで実行され、`STATE.md` や `CONTEXT.md` などの構造化アーティファクトがセッション境界を越えて保存され、検証ステップが構築されたものを確認してフェーズを完了と宣言する前に修正計画を生成します。詳細な理由については [docs/ja-JP/explanation/context-engineering.md](docs/ja-JP/explanation/context-engineering.md) を参照してください。
 
-システムが以下を行います：
-
-1. **リサーチ** — CONTEXT.mdの決定事項をもとに、このフェーズの実装方法を調査します
-2. **計画** — XML構造で2〜3個のアトミックなタスクプランを作成します
-3. **検証** — プランを要件と照合し、合格するまでループします
-
-各プランは新しいコンテキストウィンドウで実行できるほど小さくなっています。品質の劣化も「もっと簡潔にしますね」もありません。
-
-**作成されるファイル：** `{phase_num}-RESEARCH.md`、`{phase_num}-{N}-PLAN.md`
+トラブルシューティングは [docs/ja-JP/how-to/recover-and-troubleshoot.md](docs/ja-JP/how-to/recover-and-troubleshoot.md) を参照してください。
 
 ---
 
-### 4. フェーズの実行
+## コミュニティ
 
-```
-/gsd-execute-phase 1
-```
-
-システムが以下を行います：
-
-1. **ウェーブでプランを実行** — 可能な限り並列、依存関係がある場合は逐次
-2. **プランごとにフレッシュなコンテキスト** — 実装に200kトークンをフル活用、蓄積されたゴミはゼロ
-3. **タスクごとにコミット** — 各タスクが独自のアトミックコミットを取得
-4. **目標に対して検証** — コードベースがフェーズの約束を果たしているか確認
-
-席を離れて、戻ってきたらクリーンなgit履歴とともに完了した作業が待っています。
-
-**ウェーブ実行の仕組み：**
-
-プランは依存関係に基づいて「ウェーブ」にグループ化されます。各ウェーブ内のプランは並列実行されます。ウェーブは逐次実行されます。
-
-```
-┌────────────────────────────────────────────────────────────────────┐
-│  PHASE EXECUTION                                                   │
-├────────────────────────────────────────────────────────────────────┤
-│                                                                    │
-│  WAVE 1 (parallel)          WAVE 2 (parallel)          WAVE 3      │
-│  ┌─────────┐ ┌─────────┐    ┌─────────┐ ┌─────────┐    ┌─────────┐ │
-│  │ Plan 01 │ │ Plan 02 │ →  │ Plan 03 │ │ Plan 04 │ →  │ Plan 05 │ │
-│  │         │ │         │    │         │ │         │    │         │ │
-│  │ User    │ │ Product │    │ Orders  │ │ Cart    │    │ Checkout│ │
-│  │ Model   │ │ Model   │    │ API     │ │ API     │    │ UI      │ │
-│  └─────────┘ └─────────┘    └─────────┘ └─────────┘    └─────────┘ │
-│       │           │              ↑           ↑              ↑      │
-│       └───────────┴──────────────┴───────────┘              │      │
-│              Dependencies: Plan 03 needs Plan 01            │      │
-│                          Plan 04 needs Plan 02              │      │
-│                          Plan 05 needs Plans 03 + 04        │      │
-│                                                                    │
-└────────────────────────────────────────────────────────────────────┘
-```
-
-**ウェーブが重要な理由：**
-- 独立したプラン → 同じウェーブ → 並列実行
-- 依存するプラン → 後のウェーブ → 依存関係を待つ
-- ファイル競合 → 逐次プランまたは同一プラン内
-
-これが「バーティカルスライス」（Plan 01: ユーザー機能をエンドツーエンド）が「ホリゾンタルレイヤー」（Plan 01: 全モデル、Plan 02: 全API）より並列化に適している理由です。
-
-**作成されるファイル：** `{phase_num}-{N}-SUMMARY.md`、`{phase_num}-VERIFICATION.md`
-
----
-
-### 5. 作業の検証
-
-```
-/gsd-verify-work 1
-```
-
-**ここで実際に動作するか確認します。**
-
-自動検証はコードの存在とテストの合格を確認します。しかし、その機能は*期待通りに*動作していますか？ここはあなたが実際に使ってみる場です。
-
-システムが以下を行います：
-
-1. **テスト可能な成果物を抽出** — 今できるようになっているはずのこと
-2. **1つずつ案内** — 「メールでログインできますか？」はい/いいえ、または何が問題かを説明
-3. **障害を自動診断** — デバッグエージェントが起動し根本原因を特定
-4. **検証済みの修正プランを作成** — 即座に再実行可能
-
-すべてパスすれば次に進みます。何か壊れていれば、手動でデバッグする必要はありません — 作成された修正プランで `/gsd-execute-phase` を再度実行するだけです。
-
-**作成されるファイル：** `{phase_num}-UAT.md`、問題が見つかった場合は修正プラン
-
----
-
-### 6. 繰り返し → シップ → 完了 → 次のマイルストーン
-
-```
-/gsd-discuss-phase 2
-/gsd-plan-phase 2
-/gsd-execute-phase 2
-/gsd-verify-work 2
-/gsd-ship 2                  # 検証済みの作業からPRを作成
-...
-/gsd-complete-milestone
-/gsd-new-milestone
-```
-
-またはGSDに次のステップを自動判定させます：
-
-```
-/gsd-progress --next                    # 次のステップを自動検出して実行
-```
-
-**discuss → plan → execute → verify → ship** のループをマイルストーン完了まで繰り返します。
-
-ディスカッション中のインプットを速くしたい場合は、`/gsd-discuss-phase <n> --batch` で1つずつではなく小さなグループにまとめた質問に一括で回答できます。`--chain` を使うと、ディスカッションからプラン+実行まで途中で止まらずに自動チェインできます。
-
-各フェーズであなたのインプット（discuss）、適切なリサーチ（plan）、クリーンな実行（execute）、人間による検証（verify）が行われます。コンテキストは常にフレッシュ。品質は常に高い。
-
-すべてのフェーズが完了したら、`/gsd-complete-milestone` でマイルストーンをアーカイブしリリースをタグ付けします。
-
-次に `/gsd-new-milestone` で次のバージョンを開始します — `new-project` と同じフローですが既存のコードベース向けです。次に構築したいものを説明し、システムがドメインを調査し、要件をスコーピングし、新しいロードマップを作成します。各マイルストーンはクリーンなサイクルです：定義 → 構築 → シップ。
-
----
-
-### クイックモード
-
-```
-/gsd-quick
-```
-
-**フル計画が不要なアドホックタスク向け。**
-
-クイックモードはGSDの保証（アトミックコミット、状態トラッキング）をより速いパスで提供します：
-
-- **同じエージェント** — プランナー + エグゼキューター、同じ品質
-- **オプションステップをスキップ** — デフォルトではリサーチ、プランチェッカー、ベリファイアなし
-- **別トラッキング** — `.planning/quick/` に保存、フェーズとは別管理
-
-**`--discuss` フラグ：** 計画前にグレーゾーンを洗い出す軽量ディスカッション。
-
-**`--research` フラグ：** 計画前にフォーカスされたリサーチャーを起動。実装アプローチ、ライブラリの選択肢、落とし穴を調査します。タスクへのアプローチが不明な場合に使用してください。
-
-**`--full` フラグ：** 全フェーズを有効化 — ディスカッション + リサーチ + プランチェック + 検証。クイックタスク形式のフルGSDパイプライン。
-
-**`--validate` フラグ：** プランチェック + 実行後の検証のみを有効化（以前の `--full` の動作）。
-
-フラグは組み合わせ可能：`--discuss --research --validate` でディスカッション + リサーチ + プランチェック + 検証が行われます。
-
-```
-/gsd-quick
-> What do you want to do? "Add dark mode toggle to settings"
-```
-
-**作成されるファイル：** `.planning/quick/001-add-dark-mode-toggle/PLAN.md`、`SUMMARY.md`
-
----
-
-## なぜ効果的なのか
-
-### コンテキストエンジニアリング
-
-Claude Codeは必要なコンテキストを与えれば非常に強力です。ほとんどの人はそれをしていません。
-
-GSDがそれを代わりに処理します：
-
-| ファイル | 役割 |
-|------|--------------|
-| `PROJECT.md` | プロジェクトビジョン、常に読み込まれる |
-| `research/` | エコシステムの知識（スタック、機能、アーキテクチャ、落とし穴） |
-| `REQUIREMENTS.md` | フェーズとのトレーサビリティを持つスコープ済みv1/v2要件 |
-| `ROADMAP.md` | 進む方向、完了済みの作業 |
-| `STATE.md` | 決定事項、ブロッカー、現在地 — セッション間のメモリ |
-| `PLAN.md` | XML構造のアトミックタスク、検証ステップ付き |
-| `SUMMARY.md` | 何が起きたか、何が変わったか、履歴にコミット |
-| `todos/` | 後で取り組むアイデアやタスクのキャプチャ |
-| `threads/` | セッションをまたぐ作業のための永続コンテキストスレッド |
-| `seeds/` | 適切なマイルストーンで浮上する将来志向のアイデア |
-
-サイズ制限はClaudeの品質が劣化するポイントに基づいています。制限内に収まれば、一貫した高品質が得られます。
-
-### XMLプロンプトフォーマッティング
-
-すべてのプランはClaude向けに最適化された構造化XMLです：
-
-```xml
-<task type="auto">
-  <name>Create login endpoint</name>
-  <files>src/app/api/auth/login/route.ts</files>
-  <action>
-    <!-- CommonJSの問題があるため、jsonwebtokenではなくjoseをJWTに使用。 -->
-    <!-- usersテーブルに対して認証情報を検証。 -->
-    <!-- 成功時にhttpOnly cookieを返す。 -->
-    Use jose for JWT (not jsonwebtoken - CommonJS issues).
-    Validate credentials against users table.
-    Return httpOnly cookie on success.
-  </action>
-  <verify>curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie</verify>
-  <done>Valid credentials return cookie, invalid return 401</done>
-</task>
-```
-
-正確な指示。推測なし。検証が組み込み済み。
-
-### マルチエージェントオーケストレーション
-
-すべてのステージで同じパターンを使用します：薄いオーケストレーターが専門エージェントを起動し、結果を収集し、次のステップにルーティングします。
-
-| ステージ | オーケストレーターの役割 | エージェントの役割 |
-|-------|------------------|-----------|
-| リサーチ | 調整し、発見事項を提示 | 4つの並列リサーチャーがスタック、機能、アーキテクチャ、落とし穴を調査 |
-| プランニング | 検証し、イテレーションを管理 | プランナーがプランを作成、チェッカーが検証、合格するまでループ |
-| 実行 | ウェーブにグループ化し、進捗を追跡 | エグゼキューターがフレッシュな200kコンテキストで並列実装 |
-| 検証 | 結果を提示し、次にルーティング | ベリファイアがコードベースを目標と照合、デバッガーが障害を診断 |
-
-オーケストレーターは重い処理を行いません。エージェントを起動し、待機し、結果を統合します。
-
-**結果：** フェーズ全体を実行できます — 深いリサーチ、複数のプランの作成と検証、並列エグゼキューターによる数千行のコード記述、目標に対する自動検証 — そしてメインのコンテキストウィンドウは30〜40%に留まります。処理はフレッシュなサブエージェントコンテキストで行われます。セッションは高速でレスポンシブなままです。
-
-### アトミックGitコミット
-
-各タスクは完了直後に独自のコミットを取得します：
-
-```bash
-abc123f docs(08-02): complete user registration plan
-def456g feat(08-02): add email confirmation flow
-hij789k feat(08-02): implement password hashing
-lmn012o feat(08-02): create registration endpoint
-```
-
-> [!NOTE]
-> **メリット：** git bisectで問題のある正確なタスクを特定可能。各タスクを個別にリバート可能。将来のセッションでClaudeに明確な履歴を提供。AI自動化ワークフローにおけるオブザーバビリティの向上。
-
-すべてのコミットは的確で、追跡可能で、意味があります。
-
-### モジュラー設計
-
-- 現在のマイルストーンにフェーズを追加
-- フェーズ間に緊急作業を挿入
-- マイルストーンを完了して新しく開始
-- すべてを再構築せずにプランを調整
-
-ロックインされることはありません。システムが適応します。
-
----
-
-## コマンド
-
-### コアワークフロー
-
-| コマンド | 説明 |
-|---------|--------------|
-| `/gsd-new-project [--auto]` | フル初期化：質問 → リサーチ → 要件定義 → ロードマップ |
-| `/gsd-discuss-phase [N] [--auto] [--analyze] [--chain]` | 計画前に実装の決定事項をキャプチャ（`--analyze` でトレードオフ分析を追加、`--chain` でプラン+実行へ自動チェイン） |
-| `/gsd-plan-phase [N] [--auto] [--reviews]` | フェーズのリサーチ + プラン + 検証（`--reviews` でコードベースレビューの発見事項を読み込み） |
-| `/gsd-execute-phase <N>` | 全プランを並列ウェーブで実行し、完了時に検証 |
-| `/gsd-verify-work [N]` | 手動ユーザー受入テスト ¹ |
-| `/gsd-ship [N] [--draft]` | 検証済みのフェーズ作業から自動生成された本文付きのPRを作成 |
-| `/gsd-progress --next` | 次の論理的なワークフローステップに自動的に進む |
-| `/gsd-fast <text>` | インラインの軽微タスク — 計画を完全にスキップし即座に実行 |
-| `/gsd-audit-milestone` | マイルストーンが完了の定義を達成したか検証 |
-| `/gsd-complete-milestone` | マイルストーンをアーカイブし、リリースをタグ付け |
-| `/gsd-new-milestone [name]` | 次のバージョンを開始：質問 → リサーチ → 要件定義 → ロードマップ |
-| `/gsd-forensics [desc]` | 失敗したワークフロー実行の事後分析（停止ループ、欠落成果物、git異常の診断） |
-| `/gsd-milestone-summary [version]` | チームオンボーディングとレビュー向けの包括的なプロジェクトサマリーを生成 |
-
-### ワークストリーム
-
-| コマンド | 説明 |
-|---------|--------------|
-| `/gsd-workstreams list` | 全ワークストリームとそのステータスを表示 |
-| `/gsd-workstreams create <name>` | 並列マイルストーン作業用の名前空間付きワークストリームを作成 |
-| `/gsd-workstreams switch <name>` | アクティブなワークストリームを切り替え |
-| `/gsd-workstreams complete <name>` | ワークストリームを完了しマージ |
-
-### マルチプロジェクトワークスペース
-
-| コマンド | 説明 |
-|---------|--------------|
-| `/gsd-workspace --new` | リポジトリのコピー（worktreeまたはクローン）で隔離されたワークスペースを作成 |
-| `/gsd-workspace --list` | すべてのGSDワークスペースとそのステータスを表示 |
-| `/gsd-workspace --remove` | ワークスペースを削除しworktreeをクリーンアップ |
-
-### UIデザイン
-
-| コマンド | 説明 |
-|---------|--------------|
-| `/gsd-ui-phase [N]` | フロントエンドフェーズ用のUIデザイン契約（UI-SPEC.md）を生成 |
-| `/gsd-ui-review [N]` | 実装済みフロントエンドコードの6つの柱によるビジュアル監査（遡及的） |
-
-### ナビゲーション
-
-| コマンド | 説明 |
-|---------|--------------|
-| `/gsd-progress` | 今どこにいる？次は何？ |
-| `/gsd-progress --next` | 状態を自動検出し次のステップを実行 |
-| `/gsd-help` | 全コマンドと使い方ガイドを表示 |
-| `/gsd-update` | チェンジログプレビュー付きでGSDをアップデート |
-| `/gsd-manager` | 複数フェーズ管理用のインタラクティブコマンドセンター |
-
-### ブラウンフィールド
-
-| コマンド | 説明 |
-|---------|--------------|
-| `/gsd-map-codebase [area]` | new-project前に既存のコードベースを分析 |
-
-### フェーズ管理
-
-| コマンド | 説明 |
-|---------|--------------|
-| `/gsd-phase` | ロードマップにフェーズを追加 |
-| `/gsd-phase --insert [N]` | フェーズ間に緊急作業を挿入 |
-| `/gsd-phase --edit [N] [--force]` | 既存フェーズの任意フィールドをその場で編集 — 番号と位置は変更されない |
-| `/gsd-phase --remove [N]` | 将来のフェーズを削除し番号を振り直し |
-| `/gsd-discuss-phase --assumptions [N]` | 計画前にClaudeの意図するアプローチを確認 |
-| `/gsd-audit-milestone --fix` | 監査で見つかったギャップを埋めるフェーズを作成 |
-
-### セッション
-
-| コマンド | 説明 |
-|---------|--------------|
-| `/gsd-pause-work` | フェーズ途中で停止する際の引き継ぎを作成（HANDOFF.jsonを書き込み） |
-| `/gsd-resume-work` | 前回のセッションから復元 |
-| `/gsd-pause-work --report` | 実行した作業と結果のセッションサマリーを生成 |
-
-### ワークストリーム
-
-| コマンド | 説明 |
-|---------|--------------|
-| `/gsd-workstreams` | 並列ワークストリームを管理（list、create、switch、status、progress、complete） |
-
-### コード品質
-
-| コマンド | 説明 |
-|---------|--------------|
-| `/gsd-review` | 現在のフェーズまたはブランチのクロスAIピアレビュー |
-| `/gsd-pr-branch` | `.planning/` コミットをフィルタリングしたクリーンなPRブランチを作成 |
-| `/gsd-audit-uat` | 検証負債を監査 — UATが未実施のフェーズを検出 |
-
-### バックログ & スレッド
-
-| コマンド | 説明 |
-|---------|--------------|
-| `/gsd-capture --seed <idea>` | トリガー条件付きの将来志向のアイデアをキャプチャ — 適切なマイルストーンで浮上 |
-| `/gsd-capture --backlog <desc>` | バックログのパーキングロットにアイデアを追加（999.xナンバリング、アクティブシーケンス外） |
-| `/gsd-review-backlog` | バックログ項目をレビューし、アクティブマイルストーンに昇格またはstaleエントリを削除 |
-| `/gsd-thread [name]` | 永続コンテキストスレッド — 複数セッションにまたがる作業用の軽量クロスセッション知識 |
-
-### ユーティリティ
-
-| コマンド | 説明 |
-|---------|--------------|
-| `/gsd-settings` | モデルプロファイルとワークフローエージェントを設定 |
-| `/gsd-config --profile <profile>` | モデルプロファイルを切り替え（quality/balanced/budget/inherit） |
-| `/gsd-capture [desc]` | 後で取り組むアイデアをキャプチャ |
-| `/gsd-capture --list` | 保留中のtodoを一覧表示 |
-| `/gsd-debug [desc]` | 永続状態を持つ体系的デバッグ |
-| `/gsd-do <text>` | フリーフォームテキストを適切なGSDコマンドに自動ルーティング |
-| `/gsd-note <text>` | ゼロフリクションのアイデアキャプチャ — ノートの追加、一覧、todoへの昇格 |
-| `/gsd-quick [--full] [--discuss] [--research]` | GSDの保証付きでアドホックタスクを実行（`--full` で全フェーズを有効化、`--discuss` で事前にコンテキストを収集、`--research` で計画前にアプローチを調査） |
-| `/gsd-health [--repair]` | `.planning/` ディレクトリの整合性を検証、`--repair` で自動修復 |
-| `/gsd-stats` | プロジェクト統計を表示 — フェーズ、プラン、要件、gitメトリクス |
-| `/gsd-profile-user [--questionnaire] [--refresh]` | セッション分析から開発者行動プロファイルを生成し、パーソナライズされた応答を提供 |
-
-<sup>¹ Redditユーザー OracleGreyBeard による貢献</sup>
-
----
-
-## 設定
-
-GSDはプロジェクト設定を `.planning/config.json` に保存します。`/gsd-new-project` 実行時に設定するか、後から `/gsd-settings` で更新できます。完全な設定スキーマ、ワークフロートグル、gitブランチオプション、エージェントごとのモデル内訳については、[ユーザーガイド](docs/ja-JP/USER-GUIDE.md#configuration-reference)をご覧ください。
-
-### コア設定
-
-| 設定 | オプション | デフォルト | 制御内容 |
-|---------|---------|---------|------------------|
-| `mode` | `yolo`, `interactive` | `interactive` | 自動承認 vs 各ステップで確認 |
-| `granularity` | `coarse`, `standard`, `fine` | `standard` | フェーズの粒度 — スコープをどれだけ細かく分割するか（フェーズ × プラン） |
-
-### モデルプロファイル
-
-各エージェントが使用するClaudeモデルを制御します。品質とトークン消費のバランスを取ります。
-
-| プロファイル | プランニング | 実行 | 検証 |
-|---------|----------|-----------|--------------|
-| `quality` | Opus | Opus | Sonnet |
-| `balanced`（デフォルト） | Opus | Sonnet | Sonnet |
-| `budget` | Sonnet | Sonnet | Haiku |
-| `inherit` | Inherit | Inherit | Inherit |
-
-プロファイルの切り替え：
-```
-/gsd-config --profile budget
-```
-
-非Anthropicプロバイダー（OpenRouter、ローカルモデル）を使用する場合や、現在のランタイムのモデル選択に従う場合（例：OpenCode `/model`）は `inherit` を使用してください。
-
-または `/gsd-settings` で設定できます。
-
-### ワークフローエージェント
-
-プランニング/実行時に追加のエージェントを起動します。品質は向上しますが、トークンと時間が追加されます。
-
-| 設定 | デフォルト | 説明 |
-|---------|---------|--------------|
-| `workflow.research` | `true` | 各フェーズの計画前にドメインを調査 |
-| `workflow.plan_check` | `true` | 実行前にプランがフェーズ目標を達成しているか検証 |
-| `workflow.verifier` | `true` | 実行後に必須項目が提供されたか確認 |
-| `workflow.auto_advance` | `false` | discuss → plan → execute を停止せずに自動チェーン |
-| `workflow.research_before_questions` | `false` | ディスカッション質問の後ではなく前にリサーチを実行 |
-| `workflow.discuss_mode` | `'discuss'` | ディスカッションモード：`discuss`（インタビュー）、`assumptions`（コードベースファースト） |
-| `workflow.skip_discuss` | `false` | 自律モードでdiscuss-phaseをスキップ |
-| `workflow.text_mode` | `false` | リモートセッション用のテキスト専用モード（TUIメニューなし） |
-
-これらのトグルには `/gsd-settings` を使用するか、呼び出し時にオーバーライドできます：
-- `/gsd-plan-phase --skip-research`
-- `/gsd-plan-phase --skip-verify`
-
-### 実行
-
-| 設定 | デフォルト | 制御内容 |
-|---------|---------|------------------|
-| `parallelization.enabled` | `true` | 独立したプランを同時に実行 |
-| `planning.commit_docs` | `true` | `.planning/` をgitで追跡 |
-| `hooks.context_warnings` | `true` | コンテキストウィンドウの使用量警告を表示 |
-
-### Gitブランチ
-
-GSDが実行中にブランチをどう扱うかを制御します。
-
-| 設定 | オプション | デフォルト | 説明 |
-|---------|---------|---------|--------------|
-| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | ブランチ作成戦略 |
-| `git.phase_branch_template` | string | `gsd/phase-{phase}-{slug}` | フェーズブランチのテンプレート |
-| `git.milestone_branch_template` | string | `gsd/{milestone}-{slug}` | マイルストーンブランチのテンプレート |
-
-**戦略：**
-- **`none`** — 現在のブランチにコミット（デフォルトのGSD動作）
-- **`phase`** — フェーズごとにブランチを作成し、フェーズ完了時にマージ
-- **`milestone`** — マイルストーン全体で1つのブランチを作成し、完了時にマージ
-
-マイルストーン完了時、GSDはスカッシュマージ（推奨）または履歴付きマージを提案します。
-
----
-
-## セキュリティ
-
-### 組み込みセキュリティハードニング
-
-GSDはv1.27以降、多層防御セキュリティを備えています：
-
-- **パストラバーサル防止** — ユーザー提供のすべてのファイルパス（`--text-file`、`--prd`）がプロジェクトディレクトリ内に解決されるか検証
-- **プロンプトインジェクション検出** — 集中型 `security.cjs` モジュールが計画成果物に入る前にユーザー提供テキストのインジェクションパターンをスキャン
-- **PreToolUseプロンプトガードフック** — `gsd-prompt-guard` が `.planning/` への書き込みに埋め込まれたインジェクションベクトルをスキャン（アドバイザリー、ブロッキングではない）
-- **安全なJSON解析** — 不正な `--fields` 引数が状態を破損する前にキャッチ
-- **シェル引数バリデーション** — シェル補間前にユーザーテキストをサニタイズ
-- **CI対応インジェクションスキャナー** — `prompt-injection-scan.test.cjs` が全エージェント/ワークフロー/コマンドファイルの埋め込みインジェクションベクトルをスキャン
-
-> [!NOTE]
-> GSDはLLMシステムプロンプトとなるマークダウンファイルを生成するため、計画成果物に流入するユーザー制御テキストは潜在的な間接プロンプトインジェクションベクトルとなります。これらの保護は、そのようなベクトルを複数のレイヤーで捕捉するように設計されています。
-
-### 機密ファイルの保護
-
-GSDのコードベースマッピングおよび分析コマンドは、プロジェクトを理解するためにファイルを読み取ります。**シークレットを含むファイルを保護する**には、Claude Codeの拒否リストに追加してください：
-
-1. Claude Code設定（`.claude/settings.json` またはグローバル）を開きます
-2. 機密ファイルパターンを拒否リストに追加します：
-
-```json
-{
-  "permissions": {
-    "deny": [
-      "Read(.env)",
-      "Read(.env.*)",
-      "Read(**/secrets/*)",
-      "Read(**/*credential*)",
-      "Read(**/*.pem)",
-      "Read(**/*.key)"
-    ]
-  }
-}
-```
-
-これにより、どのコマンドを実行しても、Claudeがこれらのファイルを完全に読み取ることを防ぎます。
-
-> [!IMPORTANT]
-> GSDにはシークレットのコミットに対する組み込み保護がありますが、多層防御がベストプラクティスです。防御の第一線として、機密ファイルへの読み取りアクセスを拒否してください。
-
----
-
-## トラブルシューティング
-
-**インストール後にコマンドが見つからない？**
-- ランタイムを再起動してコマンド/スキルを再読み込みしてください
-- `~/.claude/commands/gsd/`（グローバル）または `./.claude/commands/gsd/`（ローカル）にファイルが存在するか確認してください
-- Codexの場合、`~/.codex/skills/gsd-*/SKILL.md`（グローバル）または `./.codex/skills/gsd-*/SKILL.md`（ローカル）にスキルが存在するか確認してください
-
-**コマンドが期待通りに動作しない？**
-- `/gsd-help` を実行してインストールを確認してください
-- `npx @opengsd/gsd-core` を再実行して再インストールしてください
-
-**最新バージョンへのアップデート？**
-```bash
-npx @opengsd/gsd-core@latest
-```
-
-**Dockerまたはコンテナ化環境を使用している？**
-
-チルダパス（`~/.claude/...`）でファイル読み取りが失敗する場合、インストール前に `CLAUDE_CONFIG_DIR` を設定してください：
-```bash
-CLAUDE_CONFIG_DIR=/home/youruser/.claude npx @opengsd/gsd-core --global
-```
-これにより、コンテナ内で正しく展開されない可能性がある `~` の代わりに絶対パスが使用されます。
-
-### アンインストール
-
-GSDを完全に削除するには：
-
-```bash
-# グローバルインストール
-npx @opengsd/gsd-core --claude --global --uninstall
-npx @opengsd/gsd-core --opencode --global --uninstall
-npx @opengsd/gsd-core --gemini --global --uninstall
-npx @opengsd/gsd-core --kilo --global --uninstall
-npx @opengsd/gsd-core --codex --global --uninstall
-npx @opengsd/gsd-core --copilot --global --uninstall
-npx @opengsd/gsd-core --cursor --global --uninstall
-npx @opengsd/gsd-core --antigravity --global --uninstall
-npx @opengsd/gsd-core --trae --global --uninstall
-
-# ローカルインストール（現在のプロジェクト）
-npx @opengsd/gsd-core --claude --local --uninstall
-npx @opengsd/gsd-core --opencode --local --uninstall
-npx @opengsd/gsd-core --gemini --local --uninstall
-npx @opengsd/gsd-core --kilo --local --uninstall
-npx @opengsd/gsd-core --codex --local --uninstall
-npx @opengsd/gsd-core --copilot --local --uninstall
-npx @opengsd/gsd-core --cursor --local --uninstall
-npx @opengsd/gsd-core --antigravity --local --uninstall
-npx @opengsd/gsd-core --trae --local --uninstall
-```
-
-これにより、他の設定を保持しながら、すべてのGSDコマンド、エージェント、フック、設定が削除されます。
-
----
-
-## コミュニティポート
-
-OpenCode、Gemini CLI、Kilo、Codexは `npx @opengsd/gsd-core` でネイティブサポートされています。
-
-以下のコミュニティポートがマルチランタイムサポートの先駆けとなりました：
-
-| プロジェクト | プラットフォーム | 説明 |
-|---------|----------|-------------|
-| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | OpenCode | オリジナルのOpenCode対応版 |
-| gsd-gemini（アーカイブ済み） | Gemini CLI | uberfuzzyによるオリジナルのGemini対応版 |
+| プロジェクト | プラットフォーム |
+|---------|----------|
+| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | オリジナル OpenCode ポート |
+| [Discord](https://discord.gg/mYgfVNfA2r) | コミュニティサポート |
 
 ---
 
@@ -860,12 +114,12 @@ OpenCode、Gemini CLI、Kilo、Codexは `npx @opengsd/gsd-core` でネイティ
 
 ## ライセンス
 
-MITライセンス。詳細は [LICENSE](LICENSE) をご覧ください。
+MIT ライセンス。詳細は [LICENSE](LICENSE) を参照してください。
 
 ---
 
 <div align="center">
 
-**Claude Codeは強力です。GSDはそれを信頼性の高いものにします。**
+**Claude Code は強力です。GSD Core はそれを信頼できるものにします。**
 
 </div>

README.ko-KR.md

@@ -1,5 +1,3 @@
-> ⚠️ This is an active fork. See the [English README](README.md) for the full notice about the original repo.
-
 <div align="center">
 
 # GSD Core
@@ -8,9 +6,7 @@
 
 [English](README.md) · [Português](README.pt-BR.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja-JP.md) · **한국어**
 
-**Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf, Antigravity, Augment, Trae, Cline을 위한 가볍고 강력한 메타 프롬프팅, 컨텍스트 엔지니어링, 스펙 기반 개발 시스템.**
-
-**컨텍스트 rot를 해결합니다 — Claude의 컨텍스트 창이 채워질수록 품질이 저하되는 문제.**
+**Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf 등을 위한 경량 메타 프롬프팅, 컨텍스트 엔지니어링, 스펙 기반 개발 시스템.**
 
 [![npm version](https://img.shields.io/npm/v/%40opengsd%2Fgsd-core?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@opengsd/gsd-core)
 [![npm downloads](https://img.shields.io/npm/dm/%40opengsd%2Fgsd-core?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@opengsd/gsd-core)
@@ -19,821 +15,88 @@
 [![GitHub stars](https://img.shields.io/github/stars/open-gsd/gsd-core?style=for-the-badge&logo=github&color=181717)](https://github.com/open-gsd/gsd-core)
 [![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
 
-<br>
-
-```bash
-npx @opengsd/gsd-core@latest
-```
-
-**Mac, Windows, Linux 모두 지원.**
-
-<br>
-
-![GSD Install](assets/terminal.svg)
-
-<br>
-
-*"원하는 게 뭔지 명확하게 알고 있다면, 이게 진짜로 만들어줍니다. 과장 없이."*
-
-*"SpecKit, OpenSpec, Taskmaster 다 써봤는데 — 지금까지 이게 제일 결과가 좋았어요."*
-
-*"Claude Code에 추가한 것 중 단연 가장 강력합니다. 과하게 엔지니어링하지 않고, 말 그대로 그냥 해냅니다."*
-
-<br>
-
-**Amazon, Google, Shopify, Webflow 엔지니어들이 신뢰합니다.**
-
-[왜 만들었나](#왜-만들었나) · [작동 방식](#작동-방식) · [명령어](#명령어) · [왜 효과적인가](#왜-효과적인가) · [사용자 가이드](docs/ko-KR/USER-GUIDE.md)
-
 </div>
 
 ---
 
-## 왜 만들었나
+## GSD Core란
 
-저는 솔로 개발자입니다. 코드는 제가 아니라 Claude Code가 씁니다.
-
-스펙 기반 개발 도구가 없는 건 아닙니다. BMAD, Speckit 같은 것들이 있죠. 근데 다들 필요 이상으로 복잡합니다 — 스프린트 세리머니, 스토리 포인트, 이해관계자 싱크, 회고, 지라 워크플로우. 저는 50인 규모 소프트웨어 회사가 아니에요. 기업 연극을 하고 싶지 않습니다. 그냥 좋은 걸 만들고 싶은 사람입니다.
-
-그래서 GSD를 만들었습니다. 복잡함은 시스템 안에 있습니다. 워크플로우에 있는 게 아니라. 뒤에서 컨텍스트 엔지니어링, XML 프롬프트 포맷팅, 서브에이전트 오케스트레이션, 상태 관리가 돌아갑니다. 겉에서 보이는 건 그냥 몇 가지 명령어뿐입니다.
-
-시스템이 Claude한테 작업하는 데 필요한 것과 검증하는 데 필요한 것을 모두 줍니다. 저는 이 워크플로우를 믿습니다. 그냥 잘 됩니다.
-
-이게 전부입니다. 기업 역할극 같은 건 없습니다. Claude Code를 일관성 있게 쓰기 위한, 진짜로 잘 되는 시스템입니다.
-
-— **TÂCHES**
-
----
-
-바이브코딩은 평판이 안 좋습니다. 원하는 걸 설명하면 AI가 코드를 생성하는데, 규모가 커지면 엉망이 되는 일관성 없는 쓰레기가 나옵니다.
-
-GSD가 그걸 고칩니다. Claude Code를 신뢰할 수 있게 만드는 컨텍스트 엔지니어링 레이어입니다. 아이디어를 설명하면 시스템이 필요한 걸 다 뽑아내고, Claude Code가 일을 시작합니다.
-
----
-
-## 이게 누구를 위한 건가
-
-원하는 걸 설명하면 제대로 만들어지길 바라는 사람들 — 50인 규모 엔지니어링 조직인 척하지 않아도 되는.
-
-내장 품질 게이트가 실제 문제를 잡아냅니다: 스키마 드리프트 감지는 마이그레이션 누락된 ORM 변경을 플래그하고, 보안 강제는 검증을 위협 모델에 고정시키고, 스코프 축소 감지는 플래너가 요구사항을 몰래 빠뜨리는 걸 방지합니다.
-
-### 기능 하이라이트
-
-정식 버전은 npm에 게시된 `@opengsd/gsd-core` 버전과 `package.json`을 기준으로 합니다. `docs/`의 예전 릴리스 노트는 연속성 기록으로만 보관되며, 현재 GSD Core 패키지 버전으로 사용하지 않습니다.
-
-- **`--minimal` 설치 프로파일** — 별칭 `--core-only`. 메인 루프 6개 스킬(`new-project`, `discuss-phase`, `plan-phase`, `execute-phase`, `help`, `update`)만 설치하고 `gsd-*` 서브에이전트는 설치하지 않음. 콜드 스타트 시스템 프롬프트 오버헤드를 ~12k 토큰에서 ~700 토큰으로 축소(≥94% 감소). 32K–128K 컨텍스트의 로컬 LLM이나 토큰 과금 API에 유용.
-- **`/gsd-phase --edit`** — `ROADMAP.md`에 있는 기존 단계의 임의 필드를 그 자리에서 수정(번호와 위치는 변경되지 않음). `--force`는 확인 diff를 건너뛰고, `depends_on` 참조를 검증하며 쓰기 시 `STATE.md`도 갱신.
-- **머지 후 빌드 & 테스트 게이트** — `execute-phase` 5.6 단계가 `workflow.build_command` 설정을 우선 자동 감지하고, 없으면 Xcode(`.xcodeproj`), Makefile, Justfile, Cargo, Go, Python, npm 순으로 폴백. Xcode/iOS 프로젝트는 `xcodebuild build` 및 `xcodebuild test`를 자동 실행. 병렬·직렬 모드 모두에서 동작.
-- **런타임별 리뷰 모델 선택** — `review.models.<cli>`로 각 외부 리뷰 CLI(codex, gemini 등)가 플래너/실행 프로파일과 독립적으로 자체 모델을 선택할 수 있음.
-- **워크스트림 설정 상속** — `GSD_WORKSTREAM`이 설정되면 루트 `.planning/config.json`을 먼저 로드한 뒤 워크스트림 설정을 딥 머지(충돌 시 워크스트림 우선). 워크스트림 설정에서 명시적 `null`은 루트 값을 덮어씀.
-- **스킬 통합: 86 → 59** — 4개의 새로운 그룹 스킬(`capture`, `phase`, `config`, `workspace`)이 31개의 마이크로 스킬을 흡수. 기존 6개의 부모 스킬은 래퍼업/하위 동작을 플래그로 흡수: `update --sync/--reapply`, `sketch --wrap-up`, `spike --wrap-up`, `map-codebase --fast/--query`, `code-review --fix`, `progress --do/--next`. 기능 손실 없음.
-
----
-
-## 시작하기
-
-```bash
-npx @opengsd/gsd-core@latest
-```
-
-설치 중에 다음을 선택합니다:
-1. **런타임** — Claude Code, OpenCode, Gemini, Kilo, Codex, Copilot, Cursor, Windsurf, Antigravity, Augment, Trae, Cline, 또는 전체 (대화형 다중 선택 — 한 번에 여러 런타임 선택 가능)
-2. **위치** — 전역 (모든 프로젝트) 또는 로컬 (현재 프로젝트만)
-
-설치가 됐는지 확인하려면:
-- Claude Code / Gemini / Copilot / Antigravity: `/gsd-help`
-- OpenCode / Kilo / Augment / Trae: `/gsd-help`
-- Codex: `$gsd-help`
-- Cline: GSD는 `.clinerules`를 통해 설치 — `.clinerules` 존재 여부 확인
-
-> [!NOTE]
-> Claude Code 2.1.88+와 Codex는 스킬(`skills/gsd-*/SKILL.md`)로 설치됩니다. Cline은 `.clinerules`를 사용합니다. 설치 프로그램이 모든 형식을 자동으로 처리합니다.
-
-> [!TIP]
-> 소스 기반 설치 또는 npm을 사용할 수 없는 환경은 **[docs/manual-update.md](docs/manual-update.md)**를 참조하세요.
-
-### 업데이트 유지
-
-GSD는 빠르게 발전합니다. 주기적으로 업데이트하세요:
-
-```bash
-npx @opengsd/gsd-core@latest
-```
-
-<details>
-<summary><strong>비대화형 설치 (Docker, CI, 스크립트)</strong></summary>
-
-```bash
-# Claude Code
-npx @opengsd/gsd-core --claude --global   # ~/.claude/에 설치
-npx @opengsd/gsd-core --claude --local    # ./.claude/에 설치
-
-# OpenCode
-npx @opengsd/gsd-core --opencode --global # ~/.config/opencode/에 설치
-
-# Gemini CLI
-npx @opengsd/gsd-core --gemini --global   # ~/.gemini/에 설치
-
-# Kilo
-npx @opengsd/gsd-core --kilo --global     # ~/.config/kilo/에 설치
-npx @opengsd/gsd-core --kilo --local      # ./.kilo/에 설치
-
-# Codex
-npx @opengsd/gsd-core --codex --global    # ~/.codex/에 설치
-npx @opengsd/gsd-core --codex --local     # ./.codex/에 설치
-
-# Copilot
-npx @opengsd/gsd-core --copilot --global  # ~/.github/에 설치
-npx @opengsd/gsd-core --copilot --local   # ./.github/에 설치
-
-# Cursor CLI
-npx @opengsd/gsd-core --cursor --global      # ~/.cursor/에 설치
-npx @opengsd/gsd-core --cursor --local       # ./.cursor/에 설치
-
-# Antigravity
-npx @opengsd/gsd-core --antigravity --global # ~/.gemini/antigravity/에 설치
-npx @opengsd/gsd-core --antigravity --local  # ./.agent/에 설치
-
-# Augment
-npx @opengsd/gsd-core --augment --global     # ~/.augment/에 설치
-npx @opengsd/gsd-core --augment --local      # ./.augment/에 설치
-
-# Trae
-npx @opengsd/gsd-core --trae --global        # ~/.trae/에 설치
-npx @opengsd/gsd-core --trae --local         # ./.trae/에 설치
-
-# Cline
-npx @opengsd/gsd-core --cline --global       # ~/.cline/에 설치
-npx @opengsd/gsd-core --cline --local        # ./.clinerules에 설치
-
-# 전체 런타임
-npx @opengsd/gsd-core --all --global      # 모든 디렉터리에 설치
-```
-
-위치 프롬프트 건너뛰기: `--global` (`-g`) 또는 `--local` (`-l`).
-런타임 프롬프트 건너뛰기: `--claude`, `--opencode`, `--gemini`, `--kilo`, `--codex`, `--copilot`, `--cursor`, `--windsurf`, `--antigravity`, `--augment`, `--trae`, `--cline`, 또는 `--all`.
-
-</details>
-
-<details>
-<summary><strong>개발 설치</strong></summary>
-
-저장소를 클론하고 설치 프로그램을 로컬에서 실행합니다:
-
-```bash
-git clone https://github.com/open-gsd/gsd-core.git
-cd gsd-core
-node bin/install.js --claude --local
-```
-
-기여 전 수정사항 테스트를 위해 `./.claude/`에 설치됩니다.
-
-</details>
-
-### 권장: 권한 확인 건너뛰기 모드
-
-GSD는 마찰 없는 자동화를 위해 설계되었습니다. Claude Code를 다음과 같이 실행하세요:
-
-```bash
-claude --dangerously-skip-permissions
-```
-
-> [!TIP]
-> 이게 GSD를 사용하는 방법입니다 — `date`와 `git commit` 50번을 승인하러 멈추면 의미가 없습니다.
-
-<details>
-<summary><strong>대안: 세분화된 권한</strong></summary>
-
-해당 플래그를 쓰지 않으려면 프로젝트의 `.claude/settings.json`에 다음을 추가하세요:
-
-```json
-{
-  "permissions": {
-    "allow": [
-      "Bash(date:*)",
-      "Bash(echo:*)",
-      "Bash(cat:*)",
-      "Bash(ls:*)",
-      "Bash(mkdir:*)",
-      "Bash(wc:*)",
-      "Bash(head:*)",
-      "Bash(tail:*)",
-      "Bash(sort:*)",
-      "Bash(grep:*)",
-      "Bash(tr:*)",
-      "Bash(git add:*)",
-      "Bash(git commit:*)",
-      "Bash(git status:*)",
-      "Bash(git log:*)",
-      "Bash(git diff:*)",
-      "Bash(git tag:*)"
-    ]
-  }
-}
-```
-
-</details>
+GSD Core는 컨텍스트 엔지니어링 및 스펙 기반 개발 프레임워크로, AI 코딩 에이전트(Claude Code, Codex, Gemini CLI, Copilot, Cursor 등)를 엄격한 단계 루프로 운용합니다. AI가 컨텍스트 창을 채워 나가면서 발생하는 품질 저하인 [컨텍스트 rot](docs/ko-KR/explanation/context-engineering.md) 문제를 해결합니다. 무거운 리서치, 기획, 실행 작업은 새로운 컨텍스트의 서브에이전트에서 처리하고, 메인 세션은 가볍게 유지됩니다.
 
 ---
 
 ## 작동 방식
 
-> **이미 코드가 있나요?** 먼저 `/gsd-map-codebase`를 실행하세요. 병렬 에이전트를 생성해 스택, 아키텍처, 컨벤션, 고려사항을 분석합니다. 그러면 `/gsd-new-project`가 코드베이스를 파악한 상태에서 시작되고 — 질문은 추가하는 것에 집중되고, 기획 시 자동으로 기존 패턴을 불러옵니다.
+각 마일스톤은 동일한 다섯 단계 루프를 반복합니다:
 
-### 1. 프로젝트 초기화
+1. **논의(Discuss)** — 기획 전에 구현 결정 사항을 미리 정리
+2. **기획(Plan)** — 리서치, 분해, 그리고 플랜이 새 컨텍스트 창에 맞는지 검증
+3. **실행(Execute)** — 병렬 웨이브로 플랜 실행; 각 실행기는 20만 토큰의 깨끗한 컨텍스트로 시작
+4. **검증(Verify)** — 구현 결과를 검토하고, 완료 선언 전 문제 진단 및 수정
+5. **출시(Ship)** — PR 생성, 단계 아카이브, 다음 단계 반복
 
+---
+
+## 빠른 시작
+
+```bash
+npx @opengsd/gsd-core@latest
 ```
+
+설치 프로그램이 런타임(Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf 등)과 전역/로컬 설치 여부를 묻습니다. 크로스 런타임 호환성을 위해 설치 프로그램을 사용해야 합니다 — `agents/` 또는 `commands/`에서 파일을 직접 복사하지 마세요.
+
+다른 런타임이나 Node.js가 없는 환경은 [런타임에 설치하기](docs/ko-KR/how-to/install-on-your-runtime.md)를 참조하세요.
+
+설치 후 첫 번째 프로젝트를 시작합니다:
+
+```bash
 /gsd-new-project
 ```
 
-명령어 하나, 플로우 하나. 시스템이:
-
-1. **질문** — 아이디어를 완전히 이해할 때까지 물어봅니다 (목표, 제약사항, 기술 선호도, 엣지 케이스)
-2. **리서치** — 도메인 조사를 위해 병렬 에이전트를 생성합니다 (선택사항이지만 권장)
-3. **요구사항** — v1, v2, 스코프 밖을 추출합니다
-4. **로드맵** — 요구사항에 매핑된 단계를 생성합니다
-
-로드맵을 승인하면 이제 만들 준비가 됩니다.
-
-**생성 파일:** `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, `.planning/research/`
+처음 사용하시나요? [첫 번째 프로젝트](docs/ko-KR/tutorials/your-first-project.md)를 따라 설치부터 첫 단계 출시까지 안내받으세요.
 
 ---
 
-### 2. 단계 논의
+## 문서
 
-```
-/gsd-discuss-phase 1
-```
+**튜토리얼** — 직접 해보며 배우기:
+- [첫 번째 프로젝트](docs/ko-KR/tutorials/your-first-project.md)
+- [기존 코드베이스 온보딩](docs/ko-KR/tutorials/onboarding-an-existing-codebase.md)
 
-**여기서 구현을 직접 설계합니다.**
+**How-to 가이드** — 작업별 레시피:
+- [런타임에 설치하기](docs/ko-KR/how-to/install-on-your-runtime.md)
+- [단계 기획하기](docs/ko-KR/how-to/plan-a-phase.md)
+- [검증 및 출시](docs/ko-KR/how-to/verify-and-ship.md)
+- … [모든 how-to 가이드 보기](docs/ko-KR/README.md#how-to-guides)
 
-로드맵에는 단계당 한두 문장이 있습니다. 그건 *당신이 상상하는 방식*으로 뭔가를 만들기에 충분한 컨텍스트가 아닙니다. 리서치나 기획이 시작되기 전에 원하는 방향을 미리 잡아두는 단계입니다.
+**레퍼런스** — 권위 있는 사실:
+- [명령어](docs/ko-KR/COMMANDS.md)
+- [설정](docs/ko-KR/CONFIGURATION.md)
+- [CLI 도구](docs/ko-KR/CLI-TOOLS.md)
 
-시스템이 단계를 분석하고 만들어지는 것에 기반한 회색 지대를 식별합니다:
+**설명** — 개념 및 설계 결정:
+- [컨텍스트 엔지니어링](docs/ko-KR/explanation/context-engineering.md)
+- [단계 루프](docs/ko-KR/explanation/the-phase-loop.md)
+- [아키텍처](docs/ko-KR/ARCHITECTURE.md)
 
-- **시각적 기능** → 레이아웃, 밀도, 인터랙션, 빈 상태
-- **API/CLI** → 응답 형식, 플래그, 오류 처리, 상세도
-- **콘텐츠 시스템** → 구조, 톤, 깊이, 흐름
-- **조직 작업** → 그룹화 기준, 이름 지정, 중복, 예외
-
-선택한 각 영역에 대해 만족할 때까지 물어봅니다. 결과물인 `CONTEXT.md`는 다음 두 단계에 바로 쓰입니다.
-
-1. **리서처가 읽습니다** — 어떤 패턴을 조사할지 파악합니다 ("카드 레이아웃 원함" → 카드 컴포넌트 라이브러리 리서치)
-2. **플래너가 읽습니다** — 어떤 결정이 확정됐는지 파악합니다 ("무한 스크롤 결정됨" → 플랜에 스크롤 처리 포함)
-
-여기서 깊이 들어갈수록 시스템이 실제로 원하는 것에 더 가깝게 만듭니다. 건너뛰면 합리적인 기본값을 얻습니다. 사용하면 *당신의* 비전을 얻습니다.
-
-**생성 파일:** `{phase_num}-CONTEXT.md`
-
-> **가정 모드:** 질문보다 코드베이스 분석을 선호하나요? `/gsd-settings`에서 `workflow.discuss_mode`를 `assumptions`로 설정하세요. 시스템이 코드를 읽고 하려는 것과 이유를 제시한 다음 틀린 부분만 수정을 요청합니다. [논의 모드](docs/ko-KR/workflow-discuss-mode.md) 참조.
-
----
-
-### 3. 단계 기획
-
-```
-/gsd-plan-phase 1
-```
-
-시스템이:
-
-1. **리서치** — CONTEXT.md 결정사항을 기반으로 구현 방법을 조사합니다
-2. **기획** — XML 구조로 2~3개의 원자적 작업 계획을 생성합니다
-3. **검증** — 요구사항 대비 계획을 확인하고, 통과할 때까지 반복합니다
-
-각 계획은 새로운 컨텍스트 창에서 실행할 수 있을 만큼 작습니다. 저하 없이, "이제 더 간결하게 하겠습니다" 같은 말도 없습니다.
-
-**생성 파일:** `{phase_num}-RESEARCH.md`, `{phase_num}-{N}-PLAN.md`
-
----
-
-### 4. 단계 실행
-
-```
-/gsd-execute-phase 1
-```
-
-시스템이:
-
-1. **웨이브로 계획 실행** — 가능한 경우 병렬, 의존성 있으면 순차
-2. **계획당 새로운 컨텍스트** — 20만 토큰이 순수하게 구현을 위해, 쌓인 쓰레기 없음
-3. **작업당 커밋** — 모든 작업이 고유한 원자적 커밋을 가짐
-4. **목표 대비 검증** — 코드베이스가 단계에서 약속한 것을 전달했는지 확인
-
-자리를 비우고 돌아오면 깔끔한 git 이력과 함께 완성된 작업이 기다립니다.
-
-**웨이브 실행 방식:**
-
-계획은 의존성에 따라 "웨이브"로 그룹화됩니다. 각 웨이브 안에서 계획이 병렬로 실행됩니다. 웨이브는 순차적으로 실행됩니다.
-
-```
-┌────────────────────────────────────────────────────────────────────┐
-│  단계 실행                                                         │
-├────────────────────────────────────────────────────────────────────┤
-│                                                                    │
-│  웨이브 1 (병렬)           웨이브 2 (병렬)           웨이브 3       │
-│  ┌─────────┐ ┌─────────┐    ┌─────────┐ ┌─────────┐    ┌─────────┐ │
-│  │ 플랜 01 │ │ 플랜 02 │ →  │ 플랜 03 │ │ 플랜 04 │ →  │ 플랜 05 │ │
-│  │         │ │         │    │         │ │         │    │         │ │
-│  │  유저   │ │  제품   │    │  주문   │ │  장바구니│   │  결제   │ │
-│  │  모델   │ │  모델   │    │  API   │ │  API   │    │  UI    │ │
-│  └─────────┘ └─────────┘    └─────────┘ └─────────┘    └─────────┘ │
-│       │           │              ↑           ↑              ↑      │
-│       └───────────┴──────────────┴───────────┘              │      │
-│              의존성: 플랜 03은 플랜 01 필요                  │      │
-│                     플랜 04는 플랜 02 필요                          │
-│                     플랜 05는 플랜 03 + 04 필요                     │
-│                                                                    │
-└────────────────────────────────────────────────────────────────────┘
-```
-
-**웨이브가 중요한 이유:**
-- 독립 계획 → 같은 웨이브 → 병렬 실행
-- 의존 계획 → 이후 웨이브 → 의존성 대기
-- 파일 충돌 → 순차 계획 또는 같은 계획
-
-그래서 "수직 슬라이스" (플랜 01: 유저 기능 엔드투엔드)가 "수평 레이어" (플랜 01: 모든 모델, 플랜 02: 모든 API)보다 더 잘 병렬화됩니다.
-
-**생성 파일:** `{phase_num}-{N}-SUMMARY.md`, `{phase_num}-VERIFICATION.md`
-
----
-
-### 5. 작업 검증
-
-```
-/gsd-verify-work 1
-```
-
-**여기서 실제로 작동하는지 확인합니다.**
-
-자동화된 검증은 코드가 존재하고 테스트가 통과하는지 확인합니다. 하지만 기능이 *당신이 기대하는 방식*으로 작동하나요? 직접 사용해볼 기회입니다.
-
-시스템이:
-
-1. **테스트 가능한 결과물 추출** — 지금 뭘 할 수 있어야 하는지
-2. **하나씩 안내** — "이메일로 로그인할 수 있나요?" 예/아니오, 또는 뭐가 잘못됐는지 설명
-3. **실패 자동 진단** — 근본 원인을 찾기 위해 디버그 에이전트 생성
-4. **검증된 수정 계획 생성** — 즉시 재실행 준비 완료
-
-모든 게 통과하면 다음으로 넘어갑니다. 뭔가 깨졌으면 직접 디버그하지 않아도 됩니다 — 생성된 수정 계획으로 `/gsd-execute-phase`만 다시 실행하면 됩니다.
-
-**생성 파일:** `{phase_num}-UAT.md`, 문제 발견 시 수정 계획
-
----
-
-### 6. 반복 → 출시 → 완료 → 다음 마일스톤
-
-```
-/gsd-discuss-phase 2
-/gsd-plan-phase 2
-/gsd-execute-phase 2
-/gsd-verify-work 2
-/gsd-ship 2                  # 검증된 작업으로 PR 생성
-...
-/gsd-complete-milestone
-/gsd-new-milestone
-```
-
-또는 GSD가 다음 단계를 자동으로 파악하게 합니다:
-
-```
-/gsd-progress --next                    # 다음 단계 자동 감지 및 실행
-```
-
-마일스톤이 완료될 때까지 **논의 → 기획 → 실행 → 검증 → 출시** 반복.
-
-논의 중에 더 빠르게 진행하고 싶다면 `/gsd-discuss-phase <n> --batch`를 사용해 하나씩이 아닌 소그룹으로 한 번에 답할 수 있습니다. `--chain`을 사용하면 논의에서 기획+실행까지 중간에 멈추지 않고 자동 체이닝됩니다.
-
-각 단계는 사용자 입력(논의), 적절한 리서치(기획), 깔끔한 실행(실행), 사람의 검증(검증)을 거칩니다. 컨텍스트는 새롭게 유지됩니다. 품질도 높게 유지됩니다.
-
-모든 단계가 끝나면 `/gsd-complete-milestone`이 마일스톤을 아카이브하고 릴리스에 태그를 답니다.
-
-그다음 `/gsd-new-milestone`으로 다음 버전을 시작합니다 — `new-project`와 같은 흐름이지만 기존 코드베이스를 위한 것입니다. 다음에 만들 것을 설명하면 시스템이 도메인을 리서치하고, 요구사항을 스코핑하고, 새 로드맵을 만듭니다. 각 마일스톤은 깔끔한 사이클입니다: 정의 → 구축 → 출시.
-
----
-
-### 빠른 모드
-
-```
-/gsd-quick
-```
-
-**전체 기획이 필요 없는 임시 작업용.**
-
-빠른 모드는 GSD 보장 (원자적 커밋, 상태 추적)을 더 빠른 경로로 제공합니다:
-
-- **같은 에이전트** — 플래너 + 실행기, 같은 품질
-- **선택적 단계 건너뛰기** — 기본적으로 리서치, 계획 확인기, 검증기 없음
-- **별도 추적** — `.planning/quick/`에 위치, 단계와 별개
-
-**`--discuss` 플래그:** 기획 전 회색 지대를 파악하기 위한 가벼운 논의.
-
-**`--research` 플래그:** 기획 전 집중 리서처를 생성합니다. 구현 접근법, 라이브러리 옵션, 주의사항을 조사합니다. 접근 방식이 불확실할 때 사용하세요.
-
-**`--full` 플래그:** 모든 단계를 활성화 — 논의 + 리서치 + 계획 확인 + 검증. 빠른 작업 형태의 전체 GSD 파이프라인.
-
-**`--validate` 플래그:** 계획 확인 + 실행 후 검증만 활성화 (이전 `--full`의 동작).
-
-플래그는 조합 가능합니다: `--discuss --research --validate`은 논의 + 리서치 + 계획 확인 + 검증을 제공합니다.
-
-```
-/gsd-quick
-> 뭘 하고 싶으신가요? "설정에 다크 모드 토글 추가"
-```
-
-**생성 파일:** `.planning/quick/001-add-dark-mode-toggle/PLAN.md`, `SUMMARY.md`
+전체 색인: [docs/ko-KR/README.md](docs/ko-KR/README.md). 다른 언어: [日本語](README.ja-JP.md) · [한국어](README.ko-KR.md) · [Português](README.pt-BR.md) · [简体中文](README.zh-CN.md).
 
 ---
 
 ## 왜 효과적인가
 
-### 컨텍스트 엔지니어링
+대부분의 AI 코딩 환경은 규모가 커지면 실패합니다. 컨텍스트 비대화로 출력 품질이 조용히 저하되고, 세션 간 공유 메모리가 없으며, 코드가 실제로 동작하는지 검증하는 것이 없기 때문입니다. GSD Core는 이 세 가지를 모두 해결합니다. 무거운 작업은 새 서브에이전트에서 실행되고, `STATE.md`와 `CONTEXT.md` 같은 구조화된 아티팩트가 세션 경계를 넘어 유지되며, 검증 단계가 구현 결과를 검토하고 단계 완료 선언 전 수정 계획을 생성합니다. 자세한 내용은 [docs/ko-KR/explanation/context-engineering.md](docs/ko-KR/explanation/context-engineering.md)를 참조하세요.
 
-Claude Code는 컨텍스트만 제대로 주면 정말 강력합니다. 근데 대부분은 그걸 안 하죠.
-
-GSD가 대신 해줍니다.
-
-| 파일 | 역할 |
-|------|--------------|
-| `PROJECT.md` | 프로젝트 비전, 항상 로드 |
-| `research/` | 생태계 지식 (스택, 기능, 아키텍처, 주의사항) |
-| `REQUIREMENTS.md` | 단계 추적성이 있는 스코핑된 v1/v2 요구사항 |
-| `ROADMAP.md` | 방향과 완료된 것 |
-| `STATE.md` | 결정사항, 블로커, 위치 — 세션 간 메모리 |
-| `PLAN.md` | XML 구조와 검증 단계가 있는 원자적 작업 |
-| `SUMMARY.md` | 무슨 일이 있었는지, 무엇이 바뀌었는지, 이력에 커밋됨 |
-| `todos/` | 나중 작업을 위해 캡처된 아이디어와 작업 |
-| `threads/` | 여러 세션에 걸친 작업을 위한 지속적 컨텍스트 스레드 |
-| `seeds/` | 때가 되면 자연스럽게 떠오르는 미래 아이디어 저장소 |
-
-파일 크기는 Claude 품질이 떨어지기 시작하는 지점에 맞춰 설정했습니다. 그 안에 머물면 일관된 결과가 나옵니다.
-
-### XML 프롬프트 포맷팅
-
-모든 계획은 Claude에 최적화된 구조화된 XML입니다:
-
-```xml
-<task type="auto">
-  <name>로그인 엔드포인트 생성</name>
-  <files>src/app/api/auth/login/route.ts</files>
-  <action>
-    JWT에는 jose 사용 (jsonwebtoken 아님 - CommonJS 이슈).
-    users 테이블 대비 자격증명 검증.
-    성공 시 httpOnly 쿠키 반환.
-  </action>
-  <verify>curl -X POST localhost:3000/api/auth/login이 200 + Set-Cookie 반환</verify>
-  <done>유효한 자격증명은 쿠키 반환, 무효는 401 반환</done>
-</task>
-```
-
-정확한 지시사항. 추측 없음. 검증 내장.
-
-### 멀티 에이전트 오케스트레이션
-
-모든 단계는 같은 패턴입니다. 얇은 오케스트레이터가 전문화된 에이전트를 띄우고 결과를 모아 다음 단계로 넘깁니다.
-
-| 단계 | 오케스트레이터가 하는 일 | 에이전트가 하는 일 |
-|-------|------------------|-----------|
-| 리서치 | 조율, 결과 제시 | 병렬로 4개의 리서처가 스택, 기능, 아키텍처, 주의사항 조사 |
-| 기획 | 검증, 반복 관리 | 플래너가 계획 생성, 확인기가 검증, 통과할 때까지 반복 |
-| 실행 | 웨이브 그룹화, 진행 추적 | 실행기가 병렬로 구현, 각각 새로운 20만 컨텍스트 |
-| 검증 | 결과 제시, 다음 라우팅 | 검증기가 코드베이스를 목표 대비 확인, 디버거가 실패 진단 |
-
-오케스트레이터는 무거운 작업을 직접 하지 않습니다. 에이전트를 띄우고 기다렸다가 결과를 합칩니다.
-
-**결과:** 전체 단계를 다 돌릴 수 있습니다 — 깊은 리서치, 계획 생성과 검증, 병렬 실행기가 수천 줄 코드 작성, 자동화된 검증 — 근데 메인 컨텍스트 창은 30~40%에 머뭅니다. 실제 작업은 새 서브에이전트 컨텍스트에서 이루어지거든요. 세션이 끝까지 빠르고 반응적으로 유지되는 이유입니다.
-
-### 원자적 Git 커밋
-
-각 작업은 완료 직후 자체 커밋을 받습니다:
-
-```bash
-abc123f docs(08-02): complete user registration plan
-def456g feat(08-02): add email confirmation flow
-hij789k feat(08-02): implement password hashing
-lmn012o feat(08-02): create registration endpoint
-```
-
-> [!NOTE]
-> **장점:** Git bisect로 어느 작업에서 깨졌는지 정확히 찍어낼 수 있습니다. 작업 단위로 독립 revert가 됩니다. 다음 세션 Claude가 읽을 명확한 이력이 남습니다. AI 자동화 워크플로우를 한눈에 파악하기 좋습니다.
-
-커밋 하나하나가 외과적이고 추적 가능하며 의미를 담고 있습니다.
-
-### 모듈식 설계
-
-- 현재 마일스톤에 단계 추가
-- 단계 사이에 긴급 작업 삽입
-- 마일스톤 완료 후 새로 시작
-- 전부 다시 만들지 않고 계획 조정
-
-절대 갇히지 않습니다. 시스템이 적응합니다.
+문제가 발생했나요? [docs/ko-KR/how-to/recover-and-troubleshoot.md](docs/ko-KR/how-to/recover-and-troubleshoot.md)를 확인하세요.
 
 ---
 
-## 명령어
+## 커뮤니티
 
-### 핵심 워크플로우
-
-| 명령어 | 역할 |
-|---------|------------|
-| `/gsd-new-project [--auto]` | 전체 초기화: 질문 → 리서치 → 요구사항 → 로드맵 |
-| `/gsd-discuss-phase [N] [--auto] [--analyze] [--chain]` | 기획 전 구현 결정 캡처 (`--analyze`는 트레이드오프 분석 추가, `--chain`은 기획+실행으로 자동 체이닝) |
-| `/gsd-plan-phase [N] [--auto] [--reviews]` | 단계에 대한 리서치 + 기획 + 검증 (`--reviews`는 코드베이스 리뷰 결과 로드) |
-| `/gsd-execute-phase <N>` | 병렬 웨이브로 모든 계획 실행, 완료 시 검증 |
-| `/gsd-verify-work [N]` | 수동 사용자 인수 테스트 ¹ |
-| `/gsd-ship [N] [--draft]` | 자동 생성된 본문으로 검증된 단계 작업에서 PR 생성 |
-| `/gsd-progress --next` | 다음 논리적 워크플로우 단계로 자동 진행 |
-| `/gsd-fast <text>` | 인라인 사소한 작업 — 기획 완전 건너뛰고 즉시 실행 |
-| `/gsd-audit-milestone` | 마일스톤이 완료 정의를 달성했는지 검증 |
-| `/gsd-complete-milestone` | 마일스톤 아카이브, 릴리스 태그 |
-| `/gsd-new-milestone [name]` | 다음 버전 시작: 질문 → 리서치 → 요구사항 → 로드맵 |
-| `/gsd-forensics [desc]` | 실패한 워크플로우 실행의 사후 조사 (막힌 루프, 누락된 아티팩트, git 이상 진단) |
-| `/gsd-milestone-summary [version]` | 팀 온보딩 및 리뷰를 위한 종합 프로젝트 요약 생성 |
-
-### 워크스트림
-
-| 명령어 | 역할 |
-|---------|------------|
-| `/gsd-workstreams list` | 모든 워크스트림과 상태 표시 |
-| `/gsd-workstreams create <name>` | 병렬 마일스톤 작업을 위한 네임스페이스 워크스트림 생성 |
-| `/gsd-workstreams switch <name>` | 활성 워크스트림 전환 |
-| `/gsd-workstreams complete <name>` | 워크스트림 완료 및 병합 |
-
-### 멀티 프로젝트 워크스페이스
-
-| 명령어 | 역할 |
-|---------|------------|
-| `/gsd-workspace --new` | 저장소 복사본으로 격리된 워크스페이스 생성 (worktrees 또는 clones) |
-| `/gsd-workspace --list` | 모든 GSD 워크스페이스와 상태 표시 |
-| `/gsd-workspace --remove` | 워크스페이스 제거 및 worktree 정리 |
-
-### UI 디자인
-
-| 명령어 | 역할 |
-|---------|------------|
-| `/gsd-ui-phase [N]` | 프론트엔드 단계를 위한 UI 디자인 계약 (UI-SPEC.md) 생성 |
-| `/gsd-ui-review [N]` | 구현된 프론트엔드 코드의 소급적 6가지 기준 시각 감사 |
-
-### 탐색
-
-| 명령어 | 역할 |
-|---------|------------|
-| `/gsd-progress` | 지금 어디에 있나? 다음은? |
-| `/gsd-progress --next` | 상태 자동 감지 및 다음 단계 실행 |
-| `/gsd-help` | 모든 명령어와 사용 가이드 표시 |
-| `/gsd-update` | 변경 로그 미리보기와 함께 GSD 업데이트 |
-| `/gsd-manager` | 여러 단계 관리를 위한 대화형 커맨드 센터 |
-
-### 브라운필드
-
-| 명령어 | 역할 |
-|---------|------------|
-| `/gsd-map-codebase [area]` | new-project 전 기존 코드베이스 분석 |
-
-### 단계 관리
-
-| 명령어 | 역할 |
-|---------|------------|
-| `/gsd-phase` | 로드맵에 단계 추가 |
-| `/gsd-phase --insert [N]` | 단계 사이에 긴급 작업 삽입 |
-| `/gsd-phase --edit [N] [--force]` | 기존 단계의 임의 필드를 그 자리에서 수정 — 번호와 위치는 그대로 |
-| `/gsd-phase --remove [N]` | 미래 단계 제거, 번호 재정렬 |
-| `/gsd-discuss-phase --assumptions [N]` | 기획 전 Claude의 의도된 접근 방식 확인 |
-| `/gsd-audit-milestone --fix` | 감사에서 발견된 갭을 해소하기 위한 단계 생성 |
-
-### 세션
-
-| 명령어 | 역할 |
-|---------|------------|
-| `/gsd-pause-work` | 단계 중간에 멈출 때 핸드오프 생성 (HANDOFF.json 작성) |
-| `/gsd-resume-work` | 마지막 세션에서 복원 |
-| `/gsd-pause-work --report` | 수행한 작업과 결과가 담긴 세션 요약 생성 |
-
-### 코드 품질
-
-| 명령어 | 역할 |
-|---------|------------|
-| `/gsd-review` | 현재 단계 또는 브랜치의 Cross-AI 피어 리뷰 |
-| `/gsd-pr-branch` | `.planning/` 커밋을 필터링한 깔끔한 PR 브랜치 생성 |
-| `/gsd-audit-uat` | 검증 부채 감사 — UAT가 누락된 단계 찾기 |
-
-### 백로그 및 스레드
-
-| 명령어 | 역할 |
-|---------|------------|
-| `/gsd-capture --seed <idea>` | 트리거 조건이 있는 아이디어 저장 — 때가 되면 알아서 올라옴 |
-| `/gsd-capture --backlog <desc>` | 백로그 파킹 롯에 아이디어 추가 (999.x 번호 지정, 활성 시퀀스 외부) |
-| `/gsd-review-backlog` | 백로그 항목 리뷰 및 활성 마일스톤으로 승격하거나 오래된 항목 제거 |
-| `/gsd-thread [name]` | 지속적 컨텍스트 스레드 — 여러 세션에 걸친 작업을 위한 가벼운 크로스 세션 지식 |
-
-### 유틸리티
-
-| 명령어 | 역할 |
-|---------|------------|
-| `/gsd-settings` | 모델 프로필 및 워크플로우 에이전트 설정 |
-| `/gsd-config --profile <profile>` | 모델 프로필 전환 (quality/balanced/budget/inherit) |
-| `/gsd-capture [desc]` | 나중을 위한 아이디어 캡처 |
-| `/gsd-capture --list` | 대기 중인 할 일 목록 |
-| `/gsd-debug [desc]` | 지속적 상태를 이용한 체계적 디버깅 |
-| `/gsd-do <text>` | 자유 형식 텍스트를 적절한 GSD 명령어로 자동 라우팅 |
-| `/gsd-note <text>` | 마찰 없는 아이디어 캡처 — 추가, 목록, 또는 할 일로 승격 |
-| `/gsd-quick [--full] [--discuss] [--research]` | GSD 보장과 함께 임시 작업 실행 (`--full`은 전체 단계 활성화, `--discuss`는 먼저 컨텍스트 수집, `--research`는 기획 전 접근법 조사) |
-| `/gsd-health [--repair]` | `.planning/` 디렉터리 무결성 검증, `--repair`로 자동 복구 |
-| `/gsd-stats` | 프로젝트 통계 표시 — 단계, 계획, 요구사항, git 지표 |
-| `/gsd-profile-user [--questionnaire] [--refresh]` | 개인화된 응답을 위해 세션 분석에서 개발자 행동 프로필 생성 |
-
-<sup>¹ reddit 유저 OracleGreyBeard 기여</sup>
-
----
-
-## 설정
-
-GSD는 프로젝트 설정을 `.planning/config.json`에 저장합니다. `/gsd-new-project` 중에 설정하거나 나중에 `/gsd-settings`로 업데이트할 수 있습니다. 전체 config 스키마, 워크플로우 토글, git 브랜칭 옵션, 에이전트별 모델 분석은 [사용자 가이드](docs/ko-KR/USER-GUIDE.md#configuration-reference)를 참조하세요.
-
-### 핵심 설정
-
-| 설정 | 옵션 | 기본값 | 역할 |
-|---------|---------|---------|------------------|
-| `mode` | `yolo`, `interactive` | `interactive` | 각 단계 자동 승인 vs 확인 |
-| `granularity` | `coarse`, `standard`, `fine` | `standard` | 단계 세분성 — 스코프를 얼마나 세밀하게 나눌지 (단계 × 계획) |
-
-### 모델 프로필
-
-각 에이전트가 사용하는 Claude 모델을 제어합니다. 품질 대비 토큰 사용을 균형 잡습니다.
-
-| 프로필 | 기획 | 실행 | 검증 |
-|---------|----------|-----------|--------------|
-| `quality` | Opus | Opus | Sonnet |
-| `balanced` (기본값) | Opus | Sonnet | Sonnet |
-| `budget` | Sonnet | Sonnet | Haiku |
-| `inherit` | 상속 | 상속 | 상속 |
-
-프로필 전환:
-```
-/gsd-config --profile budget
-```
-
-비-Anthropic 제공업체 (OpenRouter, 로컬 모델) 사용 시 또는 현재 런타임 모델 선택을 따를 때 (예: OpenCode `/model`) `inherit`를 사용하세요.
-
-또는 `/gsd-settings`를 통해 설정하세요.
-
-### 워크플로우 에이전트
-
-기획/실행 중에 추가 에이전트를 생성합니다. 품질을 향상시키지만 토큰과 시간이 더 필요합니다.
-
-| 설정 | 기본값 | 역할 |
-|---------|---------|--------------|
-| `workflow.research` | `true` | 각 단계 기획 전 도메인 리서치 |
-| `workflow.plan_check` | `true` | 실행 전 계획이 단계 목표를 달성하는지 확인 |
-| `workflow.verifier` | `true` | 실행 후 필수 사항이 전달됐는지 확인 |
-| `workflow.auto_advance` | `false` | 멈추지 않고 논의 → 기획 → 실행 자동 연결 |
-| `workflow.research_before_questions` | `false` | 논의 질문 대신 리서치 먼저 실행 |
-| `workflow.discuss_mode` | `'discuss'` | 논의 모드: `discuss` (인터뷰), `assumptions` (코드베이스 우선) |
-| `workflow.skip_discuss` | `false` | 자율 모드에서 discuss-phase 건너뛰기 |
-| `workflow.text_mode` | `false` | 원격 세션을 위한 텍스트 전용 모드 (TUI 메뉴 없음) |
-
-`/gsd-settings`로 토글하거나 호출별로 재정의하세요:
-- `/gsd-plan-phase --skip-research`
-- `/gsd-plan-phase --skip-verify`
-
-### 실행
-
-| 설정 | 기본값 | 역할 |
-|---------|---------|------------------|
-| `parallelization.enabled` | `true` | 독립 계획 동시 실행 |
-| `planning.commit_docs` | `true` | git에서 `.planning/` 추적 |
-| `hooks.context_warnings` | `true` | 컨텍스트 창 사용 경고 표시 |
-
-### Git 브랜칭
-
-실행 중 GSD의 브랜치 처리 방식을 제어합니다.
-
-| 설정 | 옵션 | 기본값 | 역할 |
-|---------|---------|---------|--------------|
-| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | 브랜치 생성 전략 |
-| `git.phase_branch_template` | string | `gsd/phase-{phase}-{slug}` | 단계 브랜치 템플릿 |
-| `git.milestone_branch_template` | string | `gsd/{milestone}-{slug}` | 마일스톤 브랜치 템플릿 |
-
-**전략:**
-- **`none`** — 현재 브랜치에 커밋 (기본 GSD 동작)
-- **`phase`** — 단계당 브랜치 생성, 단계 완료 시 병합
-- **`milestone`** — 전체 마일스톤을 위한 하나의 브랜치 생성, 완료 시 병합
-
-마일스톤 완료 시 GSD가 스쿼시 병합 (권장) 또는 이력과 함께 병합을 제안합니다.
-
----
-
-## 보안
-
-### 내장 보안 강화
-
-GSD는 v1.27부터 심층 방어 보안을 포함합니다:
-
-- **경로 순회 방지** — 모든 사용자 제공 파일 경로(`--text-file`, `--prd`)가 프로젝트 디렉터리 내에서 해석되도록 검증
-- **프롬프트 인젝션 감지** — 중앙화된 `security.cjs` 모듈이 사용자 제공 텍스트가 기획 아티팩트에 들어가기 전 인젝션 패턴 스캔
-- **PreToolUse 프롬프트 가드 훅** — `gsd-prompt-guard`가 `.planning/`에 대한 쓰기에서 내장된 인젝션 벡터 스캔 (권고적, 차단하지 않음)
-- **안전한 JSON 파싱** — 잘못된 형식의 `--fields` 인수가 상태를 손상시키기 전에 캐치
-- **셸 인수 검증** — 사용자 텍스트가 셸 보간 전에 살균됨
-- **CI 준비 인젝션 스캐너** — `prompt-injection-scan.test.cjs`가 모든 에이전트/워크플로우/명령어 파일에서 내장된 인젝션 벡터 스캔
-
-> [!NOTE]
-> GSD는 LLM 시스템 프롬프트가 되는 마크다운 파일을 생성하기 때문에, 기획 아티팩트에 들어가는 사용자 제어 텍스트는 잠재적인 간접 프롬프트 인젝션 벡터가 됩니다. 이 보호 장치들은 여러 레이어에서 그런 벡터를 잡도록 설계되었습니다.
-
-### 민감한 파일 보호
-
-GSD의 코드베이스 매핑 및 분석 명령어는 프로젝트를 이해하기 위해 파일을 읽습니다. **비밀이 담긴 파일**을 Claude Code의 거부 목록에 추가해 보호하세요:
-
-1. Claude Code 설정 열기 (`.claude/settings.json` 또는 전역)
-2. 민감한 파일 패턴을 거부 목록에 추가:
-
-```json
-{
-  "permissions": {
-    "deny": [
-      "Read(.env)",
-      "Read(.env.*)",
-      "Read(**/secrets/*)",
-      "Read(**/*credential*)",
-      "Read(**/*.pem)",
-      "Read(**/*.key)"
-    ]
-  }
-}
-```
-
-이렇게 하면 실행하는 명령어와 관계없이 Claude가 이 파일들을 완전히 읽지 못합니다.
-
-> [!IMPORTANT]
-> GSD에는 비밀 커밋에 대한 내장 보호 장치가 있지만, 심층 방어가 모범 사례입니다. 민감한 파일에 대한 읽기 접근을 거부하는 것을 첫 번째 방어선으로 삼으세요.
-
----
-
-## 문제 해결
-
-**설치 후 명령어를 찾을 수 없나요?**
-- 런타임을 재시작해 명령어/스킬을 다시 로드하세요
-- `~/.claude/commands/gsd/` (전역) 또는 `./.claude/commands/gsd/` (로컬)에 파일이 있는지 확인하세요
-- Codex의 경우 `~/.codex/skills/gsd-*/SKILL.md` (전역) 또는 `./.codex/skills/gsd-*/SKILL.md` (로컬)에 스킬이 있는지 확인하세요
-
-**명령어가 예상대로 작동하지 않나요?**
-- `/gsd-help`를 실행해 설치 확인
-- `npx @opengsd/gsd-core`를 다시 실행해 재설치
-
-**최신 버전으로 업데이트하나요?**
-```bash
-npx @opengsd/gsd-core@latest
-```
-
-**Docker 또는 컨테이너 환경을 사용하나요?**
-
-파일 읽기가 틸드 경로(`~/.claude/...`)로 실패하면 설치 전에 `CLAUDE_CONFIG_DIR`를 설정하세요:
-```bash
-CLAUDE_CONFIG_DIR=/home/youruser/.claude npx @opengsd/gsd-core --global
-```
-컨테이너에서 올바르게 확장되지 않을 수 있는 `~` 대신 절대 경로가 사용됩니다.
-
-### 제거
-
-GSD를 완전히 제거하려면:
-
-```bash
-# 전역 설치
-npx @opengsd/gsd-core --claude --global --uninstall
-npx @opengsd/gsd-core --opencode --global --uninstall
-npx @opengsd/gsd-core --gemini --global --uninstall
-npx @opengsd/gsd-core --kilo --global --uninstall
-npx @opengsd/gsd-core --codex --global --uninstall
-npx @opengsd/gsd-core --copilot --global --uninstall
-npx @opengsd/gsd-core --cursor --global --uninstall
-npx @opengsd/gsd-core --antigravity --global --uninstall
-npx @opengsd/gsd-core --trae --global --uninstall
-
-# 로컬 설치 (현재 프로젝트)
-npx @opengsd/gsd-core --claude --local --uninstall
-npx @opengsd/gsd-core --opencode --local --uninstall
-npx @opengsd/gsd-core --gemini --local --uninstall
-npx @opengsd/gsd-core --kilo --local --uninstall
-npx @opengsd/gsd-core --codex --local --uninstall
-npx @opengsd/gsd-core --copilot --local --uninstall
-npx @opengsd/gsd-core --cursor --local --uninstall
-npx @opengsd/gsd-core --antigravity --local --uninstall
-npx @opengsd/gsd-core --trae --local --uninstall
-```
-
-다른 설정은 그대로 유지하면서 GSD의 모든 명령어, 에이전트, 훅, 설정을 제거합니다.
-
----
-
-## 커뮤니티 포트
-
-OpenCode, Gemini CLI, Kilo, Codex는 이제 `npx @opengsd/gsd-core`를 통해 기본 지원됩니다.
-
-이 커뮤니티 포트들이 멀티 런타임 지원의 선구자였습니다:
-
-| 프로젝트 | 플랫폼 | 설명 |
-|---------|----------|-------------|
-| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | OpenCode | 최초 OpenCode 적응 |
-| gsd-gemini (아카이브됨) | Gemini CLI | uberfuzzy의 최초 Gemini 적응 |
+| 프로젝트 | 플랫폼 |
+|---------|----------|
+| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | 최초 OpenCode 포트 |
+| [Discord](https://discord.gg/mYgfVNfA2r) | 커뮤니티 지원 |
 
 ---
 
@@ -857,6 +120,6 @@ MIT 라이선스. 자세한 내용은 [LICENSE](LICENSE)를 참조하세요.
 
 <div align="center">
 
-**Claude Code는 강력합니다. GSD가 그걸 신뢰할 수 있게 만듭니다.**
+**Claude Code는 강력합니다. GSD Core가 그걸 신뢰할 수 있게 만듭니다.**
 
 </div>

README.md

@@ -8,8 +8,6 @@
 
 **A light-weight meta-prompting, context engineering, and spec-driven development system for Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf, and more.**
 
-**Solves context rot — the quality degradation that happens as your AI fills its context window.**
-
 [![npm version](https://img.shields.io/npm/v/%40opengsd%2Fgsd-core?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@opengsd/gsd-core)
 [![npm downloads](https://img.shields.io/npm/dm/%40opengsd%2Fgsd-core?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@opengsd/gsd-core)
 [![Tests](https://img.shields.io/github/actions/workflow/status/open-gsd/gsd-core/test.yml?branch=main&style=for-the-badge&logo=github&label=Tests)](https://github.com/open-gsd/gsd-core/actions/workflows/test.yml)
@@ -17,218 +15,79 @@
 [![GitHub stars](https://img.shields.io/github/stars/open-gsd/gsd-core?style=for-the-badge&logo=github&color=181717)](https://github.com/open-gsd/gsd-core)
 [![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
 
-<br>
+</div>
+
+---
+
+## What is GSD Core
+
+GSD Core is a context-engineering and spec-driven development framework that drives AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, and more) through a disciplined phase loop. It solves [context rot](docs/explanation/context-engineering.md) — the quality degradation that accumulates as an AI fills its context window — by running all heavy research, planning, and execution work in fresh-context subagents while keeping your main session lean.
+
+---
+
+## How it works
+
+Each milestone repeats the same five-step loop, one phase at a time:
+
+1. **Discuss** — capture implementation decisions before anything is planned
+2. **Plan** — research, decompose, and verify the plan fits a fresh context window
+3. **Execute** — run plans in parallel waves; each executor starts with a clean 200k-token context
+4. **Verify** — walk through what was built; diagnose and fix before declaring done
+5. **Ship** — create the PR, archive the phase, repeat for the next one
+
+---
+
+## Quickstart
 
 ```bash
 npx @opengsd/gsd-core@latest
 ```
 
-**Works on Mac, Windows, and Linux.**
+The installer prompts for your runtime (Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf, and more) and whether to install globally or locally. The installer is required for cross-runtime compatibility — do not copy files from `agents/` or `commands/` directly.
 
-<br>
+On another runtime or without Node.js? See [Install on your runtime](docs/how-to/install-on-your-runtime.md).
 
-![GSD Install](assets/terminal.svg)
-
-<br>
-
-*"If you know clearly what you want, this WILL build it for you. No bs."*
-
-*"I've done SpecKit, OpenSpec and Taskmaster — this has produced the best results for me."*
-
-*"By far the most powerful addition to my Claude Code. Nothing over-engineered. It just helps me ship."*
-
-<br>
-
-**Trusted by engineers at Amazon, Google, Shopify, and Webflow.**
-
-</div>
-
----
-
-> [!IMPORTANT]
-> **Returning to GSD Core?**
->
-> Run `/gsd-map-codebase` to re-index your codebase, then `/gsd-new-project` to rebuild GSD's planning context. Your code is fine — GSD just needs its context rebuilt. Use `@opengsd/gsd-core@latest` for the current package line.
-
----
-
-## How It Works
-
-The loop is six commands. Each one does exactly one thing.
-
-### 1. Initialize
+Once installed, start your first project:
 
 ```bash
 /gsd-new-project
 ```
 
-Questions → research → requirements → roadmap. You approve it, then you're ready to build.
-
-> **Already have code?** Run `/gsd-map-codebase` first. It analyzes your stack, architecture, and conventions so `/gsd-new-project` asks the right questions.
-
-### 2. Discuss
-
-```bash
-/gsd-discuss-phase 1
-```
-
-Your roadmap has a sentence per phase. That's not enough to build it the way *you* imagine it. Discuss captures your decisions before anything gets planned: layouts, API shapes, error handling, data structures — whatever gray areas exist for this specific phase.
-
-The output feeds directly into research and planning. Skip it, get reasonable defaults. Use it, get your vision.
-
-### 3. Plan
-
-```bash
-/gsd-plan-phase 1
-```
-
-Research → plan → verify, in a loop until the plans pass. Each plan is small enough to execute in a fresh context window.
-
-### 4. Execute
-
-```bash
-/gsd-execute-phase 1
-```
-
-Plans run in parallel waves. Each executor gets a fresh 200k-token context. Each task gets its own atomic commit. Walk away, come back to completed work with a clean git history.
-
-Your main context window stays at 30–40%. The work happens in the subagents.
-
-### 5. Verify
-
-```bash
-/gsd-verify-work 1
-```
-
-Walk through what was built. Anything broken gets a diagnosed fix plan — ready for immediate re-execution. You don't debug manually; you just run execute again.
-
-### 6. Repeat → Ship
-
-```bash
-/gsd-ship 1
-/gsd-complete-milestone
-/gsd-new-milestone
-```
-
-Loop discuss → plan → execute → verify → ship until the milestone is done. Then archive, tag, and start the next one fresh.
-
----
-
-## Getting Started
-
-```bash
-npx @opengsd/gsd-core@latest
-```
-
-The installer prompts for your runtime (Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf, and more) and whether to install globally or locally.
-
-```bash
-claude --dangerously-skip-permissions
-```
-
-GSD Core is built for frictionless automation. Skip-permissions is how it's intended to run.
-
-Install only the skills you need with `--profile=core` (six core-loop skills), `--profile=standard` (core + phase management), or the default full install. Profiles compose: `--profile=core,audit`. `--minimal` is an alias for `--profile=core`. See **[docs/USER-GUIDE.md](docs/USER-GUIDE.md)** for the full walkthrough, non-interactive install flags for all 15 runtimes, and permissions configuration. See [ADR-0011](docs/adr/0011-skill-surface-budget-module.md) for the profile model and runtime surface control.
-
-The canonical release version is the `@opengsd/gsd-core` version published on npm and mirrored in `package.json`. Older release-note files under `docs/` are retained as legacy continuity notes; do not use archived release-note numbers as the current GSD Core package version.
-
-### Cross-runtime compatibility: installer required
-
-The `agents/` and `commands/` directories in this repository are Claude Code-format source files. The installer (`npx @opengsd/gsd-core@latest`) transforms them per target runtime — stripping or converting frontmatter fields that Claude Code uses but other runtimes reject. For example, OpenCode requires `color` as a hex or semantic value from a fixed set, and does not accept a `tools:` frontmatter field; the installer function `convertClaudeToOpencodeFrontmatter` (`bin/install.js`) handles this automatically.
-
-**Manually copying files** from `agents/` or `commands/` directly into a non-Claude-Code runtime config directory (e.g., `~/.config/opencode/agents`) skips the conversion step and will produce schema validation errors in that runtime.
-
-If you are on a system without Node.js or npm (Windows + OpenCode is the most common case), see **[docs/USER-GUIDE.md — Manual install / no-Node.js setup](docs/USER-GUIDE.md#manual-install--no-nodejs-setup)** for the per-runtime conversion summary and alternative install paths.
-
----
-
-## Commands
-
-The main loop:
-
-| Command | What it does |
-|---------|--------------|
-| `/gsd-new-project` | Questions → research → requirements → roadmap |
-| `/gsd-discuss-phase [N]` | Capture implementation decisions before planning |
-| `/gsd-plan-phase [N]` | Research + plan + verify |
-| `/gsd-execute-phase <N>` | Execute plans in parallel waves |
-| `/gsd-verify-work [N]` | Manual acceptance testing |
-| `/gsd-ship [N]` | Create PR from verified phase work |
-| `/gsd-progress --next` | Auto-detect and run the next step |
-| `/gsd-complete-milestone` | Archive milestone and tag release |
-| `/gsd-new-milestone` | Start next version |
-| `/gsd:surface` | Enable/disable skill clusters at runtime without reinstall |
-
-For ad-hoc tasks, autonomous mode, codebase analysis, forensics, and the full command surface — see **[docs/COMMANDS.md](docs/COMMANDS.md)**.
-
----
-
-## Why It Works
-
-Three things most AI-coding setups get wrong:
-
-**1. Context bloat.** As a session grows, quality degrades. GSD keeps your main context clean by doing the heavy work in fresh subagent contexts. Researchers, planners, and executors each start fresh with exactly what they need.
-
-**2. No shared memory.** GSD maintains structured artifacts that survive session boundaries: `PROJECT.md` (vision), `REQUIREMENTS.md` (scope), `ROADMAP.md` (where you're going), `STATE.md` (current position and decisions), `CONTEXT.md` (per-phase implementation decisions). Every new session loads these and knows exactly where things stand.
-
-**3. No verification.** Code that "runs" isn't code that "works." GSD's verify step walks you through what was built, diagnoses failures with dedicated debug agents, and generates fix plans before you declare a phase done.
-
-See **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** for how the multi-agent orchestration and context engineering work in detail.
-
----
-
-## Configuration
-
-Settings live in `.planning/config.json`. Configure during `/gsd-new-project` or update with `/gsd-settings`.
-
-Key dials:
-
-| Setting | What it controls |
-|---------|-----------------|
-| `mode` | `interactive` (confirm each step) or `yolo` (auto-approve) |
-| Model profiles | `quality` / `balanced` / `budget` — controls which model each agent uses |
-| `workflow.research` / `plan_check` / `verifier` | Toggle the quality agents that add tokens and time |
-| `parallelization.enabled` | Run independent plans simultaneously |
-
-Optional structural review: set `code_quality.fallow.enabled` to `true` to add a fallow pre-pass to `/gsd-code-review`. GSD writes `.planning/phases/<phase>/FALLOW.json` and surfaces a `Structural Findings (fallow)` section in `REVIEW.md`. Install with `npm install -D fallow@^2.70.0` (or system-wide via `cargo install fallow`; note that the Rust binary's JSON schema must match the documented v2.70+ contract — older versions may produce silent zero-finding output).
-
-Package legitimacy checks are built into the research, planning, and execution path: recommended dependencies get audited, unverified packages require a human checkpoint, and failed installs stop instead of trying similarly named alternatives.
-
-For the full configuration reference — all settings, git branching strategies, per-runtime model overrides, workstream config inheritance, agent skills injection — see **[docs/CONFIGURATION.md](docs/CONFIGURATION.md)**.
+New here? Follow [Your first project](docs/tutorials/your-first-project.md) for a guided walkthrough from install to first shipped phase.
 
 ---
 
 ## Documentation
 
-| Doc | What's in it |
-|-----|-------------|
-| [User Guide](docs/USER-GUIDE.md) | End-to-end walkthrough, install options, all runtime flags, configuration reference |
-| [Commands](docs/COMMANDS.md) | Every command with flags and examples |
-| [Configuration](docs/CONFIGURATION.md) | Full config schema, model profiles, git branching |
-| [Architecture](docs/ARCHITECTURE.md) | How the multi-agent orchestration works |
-| [CLI Tools](docs/CLI-TOOLS.md) | `gsd-sdk query` and programmatic SDK dispatch seams |
-| [Features](docs/FEATURES.md) | Complete feature index |
-| [Changelog](CHANGELOG.md) | Release history, including archived legacy continuity notes |
+**Tutorials** — learning by doing:
+- [Your first project](docs/tutorials/your-first-project.md)
+- [Onboarding an existing codebase](docs/tutorials/onboarding-an-existing-codebase.md)
+
+**How-to guides** — task-focused recipes:
+- [Install on your runtime](docs/how-to/install-on-your-runtime.md)
+- [Plan a phase](docs/how-to/plan-a-phase.md)
+- [Verify and ship](docs/how-to/verify-and-ship.md)
+- … [see all how-to guides](docs/README.md#how-to-guides)
+
+**Reference** — authoritative facts:
+- [Commands](docs/COMMANDS.md)
+- [Configuration](docs/CONFIGURATION.md)
+- [CLI tools](docs/CLI-TOOLS.md)
+
+**Explanation** — concepts and design decisions:
+- [Context engineering](docs/explanation/context-engineering.md)
+- [The phase loop](docs/explanation/the-phase-loop.md)
+- [Architecture](docs/ARCHITECTURE.md)
+
+Full index: [docs/README.md](docs/README.md). Other languages: [日本語](README.ja-JP.md) · [한국어](README.ko-KR.md) · [Português](README.pt-BR.md) · [简体中文](README.zh-CN.md).
 
 ---
 
-## Troubleshooting
+## Why it works
 
-**Commands not showing up?** Restart your runtime after install. GSD installs to `~/.claude/skills/gsd-*/` (Claude Code), `~/.codex/skills/gsd-*/` (Codex), or the equivalent for your runtime.
+Most AI-coding setups fail at scale because context bloat silently degrades output quality, there is no shared memory between sessions, and nothing verifies that code actually works. GSD Core solves all three: heavy work runs in fresh subagents, structured artifacts like `STATE.md` and `CONTEXT.md` survive session boundaries, and the verify step walks through what was built and generates fix plans before a phase is declared done. See [docs/explanation/context-engineering.md](docs/explanation/context-engineering.md) for the full reasoning.
 
-**Codex users — minimum supported CLI version is `0.130.0`.** Codex CLI 0.130.0 ([release notes](https://github.com/openai/codex/releases/tag/rust-v0.130.0)) removed extra-skill-roots discovery via [openai/codex#21485](https://github.com/openai/codex/pull/21485); from that version onward Codex discovers skills from standard roots (including `~/.codex/skills/<name>/SKILL.md`). GSD installs there directly. Earlier Codex CLI versions may still discover additional roots, which can surface duplicate `gsd-*` entries (one from extra-roots discovery, one from `~/.codex/skills/`); restart Codex after install and either upgrade or accept the duplicate listing.
-
-**Something broken?** Re-run the installer — it's idempotent:
-```bash
-npx @opengsd/gsd-core@latest
-```
-
-**Containers or Docker?** Set `CLAUDE_CONFIG_DIR` before installing to avoid tilde-expansion issues:
-```bash
-CLAUDE_CONFIG_DIR=/home/youruser/.claude npx @opengsd/gsd-core --global
-```
-
-Full troubleshooting and uninstall instructions in **[docs/USER-GUIDE.md](docs/USER-GUIDE.md#troubleshooting)**.
+Troubleshooting? See [docs/how-to/recover-and-troubleshoot.md](docs/how-to/recover-and-troubleshoot.md).
 
 ---
 

README.pt-BR.md

@@ -1,16 +1,12 @@
-> ⚠️ This is an active fork. See the [English README](README.md) for the full notice about the original repo.
-
 <div align="center">
 
 # GSD Core
 
 **Git. Ship. Done.**
 
-[English](README.md) · **Português** · [简体中文](README.zh-CN.md) · [日本語](README.ja-JP.md)
+[English](README.md) · **Português** · [简体中文](README.zh-CN.md) · [日本語](README.ja-JP.md) · [한국어](README.ko-KR.md)
 
-**Um sistema leve e poderoso de meta-prompting, engenharia de contexto e desenvolvimento orientado a especificação para Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf, Antigravity, Augment, Trae e Cline.**
-
-**Resolve context rot — a degradação de qualidade que acontece conforme o Claude enche a janela de contexto.**
+**Um sistema leve de meta-prompting, engenharia de contexto e desenvolvimento orientado a especificações para Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf e muito mais.**
 
 [![npm version](https://img.shields.io/npm/v/%40opengsd%2Fgsd-core?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@opengsd/gsd-core)
 [![npm downloads](https://img.shields.io/npm/dm/%40opengsd%2Fgsd-core?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@opengsd/gsd-core)
@@ -19,456 +15,92 @@
 [![GitHub stars](https://img.shields.io/github/stars/open-gsd/gsd-core?style=for-the-badge&logo=github&color=181717)](https://github.com/open-gsd/gsd-core)
 [![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
 
-<br>
-
-```bash
-npx @opengsd/gsd-core@latest
-```
-
-**Funciona em Mac, Windows e Linux.**
-
-<br>
-
-![GSD Install](assets/terminal.svg)
-
-<br>
-
-*"Se você sabe claramente o que quer, isso VAI construir para você. Sem enrolação."*
-
-*"Eu já usei SpecKit, OpenSpec e Taskmaster — este me deu os melhores resultados."*
-
-*"De longe a adição mais poderosa ao meu Claude Code. Nada superengenheirado. Simplesmente faz o trabalho."*
-
-<br>
-
-**Confiado por engenheiros da Amazon, Google, Shopify e Webflow.**
-
-[Por que eu criei isso](#por-que-eu-criei-isso) · [Como funciona](#como-funciona) · [Comandos](#comandos) · [Por que funciona](#por-que-funciona) · [Guia do usuário](docs/pt-BR/USER-GUIDE.md)
-
 </div>
 
 ---
 
-## Por que eu criei isso
+## O que é o GSD Core
 
-Sou desenvolvedor solo. Eu não escrevo código — o Claude Code escreve.
-
-Existem outras ferramentas de desenvolvimento orientado por especificação. BMAD, Speckit... Mas quase todas parecem mais complexas do que o necessário (cerimônias de sprint, story points, sync com stakeholders, retrospectivas, fluxos Jira) ou não entendem de verdade o panorama do que você está construindo. Eu não sou uma empresa de software com 50 pessoas. Não quero teatro corporativo. Só quero construir coisas boas que funcionem.
-
-Então eu criei o GSD. A complexidade fica no sistema, não no seu fluxo. Por trás: engenharia de contexto, formatação XML de prompts, orquestração de subagentes, gerenciamento de estado. O que você vê: alguns comandos que simplesmente funcionam.
-
-O sistema dá ao Claude tudo que ele precisa para fazer o trabalho *e* validar o resultado. Eu confio no fluxo. Ele entrega.
-
-— **TÂCHES**
-
----
-
-Vibe coding ganhou má fama. Você descreve algo, a IA gera código, e sai um resultado inconsistente que quebra em escala.
-
-O GSD corrige isso. É a camada de engenharia de contexto que torna o Claude Code confiável.
-
----
-
-## Para quem é
-
-Para quem quer descrever o que precisa e receber isso construído do jeito certo — sem fingir que está rodando uma engenharia de 50 pessoas.
-
-Quality gates embutidos capturam problemas reais: detecção de schema drift sinaliza mudanças ORM sem migrations, segurança ancora verificação a modelos de ameaça, e detecção de redução de escopo impede o planner de descartar requisitos silenciosamente.
-
-### Destaques de recursos
-
-A versão canônica é a versão de `@opengsd/gsd-core` publicada no npm e espelhada em `package.json`. Arquivos antigos de release notes em `docs/` ficam apenas como histórico de continuidade; não use números arquivados como a versão atual do GSD Core.
-
-- **Perfil de instalação `--minimal`** — alias `--core-only`. Instala apenas os 6 skills do loop principal (`new-project`, `discuss-phase`, `plan-phase`, `execute-phase`, `help`, `update`) e nenhum subagente `gsd-*`. Reduz o overhead do system prompt no cold-start de ~12k para ~700 tokens (≥94% de redução). Útil para LLMs locais com contexto de 32K–128K e APIs cobradas por token.
-- **`/gsd-phase --edit`** — edita qualquer campo de uma fase existente em `ROADMAP.md` no lugar, sem alterar o número ou a posição. `--force` pula o diff de confirmação; referências em `depends_on` são validadas e o `STATE.md` é atualizado na escrita.
-- **Build & test gate pós-merge** — o passo 5.6 de `execute-phase` agora detecta automaticamente o comando de build em `workflow.build_command`, com fallback para Xcode (`.xcodeproj`), Makefile, Justfile, Cargo, Go, Python ou npm. Projetos Xcode/iOS rodam `xcodebuild build` e `xcodebuild test` automaticamente. Funciona em modo paralelo e serial.
-- **Modelo de review por runtime** — `review.models.<cli>` permite que cada CLI externa de review (codex, gemini, etc.) escolha seu próprio modelo, independente do perfil de planner/executor.
-- **Herança de configuração de workstream** — quando `GSD_WORKSTREAM` está definido, o `.planning/config.json` raiz é carregado primeiro e merge-deep com o config da workstream (workstream vence em conflito). Um `null` explícito no config da workstream sobrescreve corretamente o valor raiz.
-- **Consolidação de skills: 86 → 59** — 4 novos skills agrupados (`capture`, `phase`, `config`, `workspace`) absorvem 31 micro-skills. 6 skills pais existentes absorvem wrap-up e sub-operações como flags: `update --sync/--reapply`, `sketch --wrap-up`, `spike --wrap-up`, `map-codebase --fast/--query`, `code-review --fix`, `progress --do/--next`. Sem perda funcional.
-
----
-
-## Primeiros passos
-
-```bash
-npx @opengsd/gsd-core@latest
-```
-
-O instalador pede:
-1. **Runtime** — Claude Code, OpenCode, Gemini, Kilo, Codex, Copilot, Cursor, Windsurf, Antigravity, Augment, Trae, Cline, ou todos
-2. **Local** — Global (todos os projetos) ou local (apenas projeto atual)
-
-Verifique com:
-- Claude Code / Gemini / Copilot / Antigravity: `/gsd-help`
-- OpenCode / Kilo / Augment / Trae: `/gsd-help`
-- Codex: `$gsd-help`
-- Cline: GSD instala via `.clinerules` — verifique se `.clinerules` existe
-
-> [!NOTE]
-> Claude Code 2.1.88+ e Codex instalam como skills (`skills/gsd-*/SKILL.md`). Cline usa `.clinerules`. O instalador lida com todos os formatos automaticamente.
-
-> [!TIP]
-> Para instalação a partir do código-fonte ou ambientes sem npm, consulte **[docs/manual-update.md](docs/manual-update.md)**.
-
-### Mantendo atualizado
-
-```bash
-npx @opengsd/gsd-core@latest
-```
-
-<details>
-<summary><strong>Instalação não interativa (Docker, CI, Scripts)</strong></summary>
-
-```bash
-# Claude Code
-npx @opengsd/gsd-core --claude --global
-npx @opengsd/gsd-core --claude --local
-
-# OpenCode
-npx @opengsd/gsd-core --opencode --global
-
-# Gemini CLI
-npx @opengsd/gsd-core --gemini --global
-
-# Kilo
-npx @opengsd/gsd-core --kilo --global
-npx @opengsd/gsd-core --kilo --local
-
-# Codex
-npx @opengsd/gsd-core --codex --global
-npx @opengsd/gsd-core --codex --local
-
-# Copilot
-npx @opengsd/gsd-core --copilot --global
-npx @opengsd/gsd-core --copilot --local
-
-# Cursor
-npx @opengsd/gsd-core --cursor --global
-npx @opengsd/gsd-core --cursor --local
-
-# Antigravity
-npx @opengsd/gsd-core --antigravity --global
-npx @opengsd/gsd-core --antigravity --local
-
-# Augment
-npx @opengsd/gsd-core --augment --global     # Install to ~/.augment/
-npx @opengsd/gsd-core --augment --local      # Install to ./.augment/
-
-# Trae
-npx @opengsd/gsd-core --trae --global        # Install to ~/.trae/
-npx @opengsd/gsd-core --trae --local         # Install to ./.trae/
-
-# Cline
-npx @opengsd/gsd-core --cline --global       # Install to ~/.cline/
-npx @opengsd/gsd-core --cline --local        # Install to ./.clinerules
-
-# Todos
-npx @opengsd/gsd-core --all --global
-```
-
-Use `--global` (`-g`) ou `--local` (`-l`) para pular a pergunta de local.
-Use `--claude`, `--opencode`, `--gemini`, `--kilo`, `--codex`, `--copilot`, `--cursor`, `--windsurf`, `--antigravity`, `--augment`, `--trae`, `--cline` ou `--all` para pular a pergunta de runtime.
-
-</details>
-
-### Recomendado: modo sem permissões
-
-```bash
-claude --dangerously-skip-permissions
-```
-
-> [!TIP]
-> Esse é o modo pensado para o GSD: aprovar `date` e `git commit` 50 vezes mata a produtividade.
+GSD Core é um framework de engenharia de contexto e desenvolvimento orientado a especificações que conduz agentes de codificação com IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor e mais) por meio de um ciclo de fases disciplinado. Ele resolve o [context rot](docs/pt-BR/explanation/context-engineering.md) — a degradação de qualidade que se acumula à medida que uma IA preenche sua janela de contexto — executando todo o trabalho pesado de pesquisa, planejamento e execução em subagentes com contexto limpo, mantendo sua sessão principal enxuta.
 
 ---
 
 ## Como funciona
 
-> **Já tem código?** Rode `/gsd-map-codebase` primeiro para analisar stack, arquitetura, convenções e riscos.
+Cada marco repete o mesmo ciclo de cinco etapas, uma fase por vez:
 
-### 1. Inicializar projeto
+1. **Discuss** — capturar decisões de implementação antes de qualquer planejamento
+2. **Plan** — pesquisar, decompor e verificar se o plano cabe em uma janela de contexto limpa
+3. **Execute** — executar planos em ondas paralelas; cada executor começa com um contexto limpo de 200k tokens
+4. **Verify** — percorrer o que foi construído; diagnosticar e corrigir antes de declarar conclusão
+5. **Ship** — criar o PR, arquivar a fase e repetir para a próxima
 
+---
+
+## Início rápido
+
+```bash
+npx @opengsd/gsd-core@latest
 ```
+
+O instalador solicita seu ambiente de execução (Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf e mais) e se deseja instalar globalmente ou localmente. O instalador é necessário para compatibilidade entre runtimes — não copie arquivos diretamente de `agents/` ou `commands/`.
+
+Em outro runtime ou sem Node.js? Consulte [Instalar no seu runtime](docs/pt-BR/how-to/install-on-your-runtime.md).
+
+Após a instalação, inicie seu primeiro projeto:
+
+```bash
 /gsd-new-project
 ```
 
-O sistema:
-1. **Pergunta** até entender seu objetivo
-2. **Pesquisa** o domínio com agentes em paralelo
-3. **Extrai requisitos** (v1, v2 e fora de escopo)
-4. **Monta roadmap** por fases
+É a primeira vez? Siga [Seu primeiro projeto](docs/pt-BR/tutorials/your-first-project.md) para um passo a passo guiado, desde a instalação até a primeira fase entregue.
 
-**Cria:** `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, `.planning/research/`
+---
 
-### 2. Discutir fase
+## Documentação
 
-```
-/gsd-discuss-phase 1
-```
+**Tutoriais** — aprendendo na prática:
+- [Seu primeiro projeto](docs/pt-BR/tutorials/your-first-project.md)
+- [Integrar uma base de código existente](docs/pt-BR/tutorials/onboarding-an-existing-codebase.md)
 
-Captura suas preferências de implementação antes do planejamento.
+**Guias práticos** — receitas orientadas a tarefas:
+- [Instalar no seu runtime](docs/pt-BR/how-to/install-on-your-runtime.md)
+- [Planejar uma fase](docs/pt-BR/how-to/plan-a-phase.md)
+- [Verificar e entregar](docs/pt-BR/how-to/verify-and-ship.md)
+- … [ver todos os guias práticos](docs/pt-BR/README.md#how-to-guides)
 
-**Cria:** `{phase_num}-CONTEXT.md`
+**Referência** — informações autoritativas:
+- [Comandos](docs/pt-BR/COMMANDS.md)
+- [Configuração](docs/pt-BR/CONFIGURATION.md)
+- [Ferramentas CLI](docs/pt-BR/CLI-TOOLS.md)
 
-### 3. Planejar fase
+**Explicação** — conceitos e decisões de design:
+- [Engenharia de contexto](docs/pt-BR/explanation/context-engineering.md)
+- [O ciclo de fases](docs/pt-BR/explanation/the-phase-loop.md)
+- [Arquitetura](docs/pt-BR/ARCHITECTURE.md)
 
-```
-/gsd-plan-phase 1
-```
-
-1. Pesquisa abordagens
-2. Cria 2-3 planos atômicos em XML
-3. Verifica contra os requisitos
-
-**Cria:** `{phase_num}-RESEARCH.md`, `{phase_num}-{N}-PLAN.md`
-
-### 4. Executar fase
-
-```
-/gsd-execute-phase 1
-```
-
-1. Executa planos em ondas
-2. Contexto novo por plano
-3. Commit atômico por tarefa
-4. Verifica contra objetivos
-
-**Cria:** `{phase_num}-{N}-SUMMARY.md`, `{phase_num}-VERIFICATION.md`
-
-### 5. Verificar trabalho
-
-```
-/gsd-verify-work 1
-```
-
-Validação manual orientada para confirmar que a feature realmente funciona como esperado.
-
-**Cria:** `{phase_num}-UAT.md` e planos de correção se necessário
-
-### 6. Repetir -> Entregar -> Completar
-
-```
-/gsd-discuss-phase 2
-/gsd-plan-phase 2
-/gsd-execute-phase 2
-/gsd-verify-work 2
-/gsd-ship 2
-/gsd-complete-milestone
-/gsd-new-milestone
-```
-
-Ou deixe o GSD decidir:
-
-```
-/gsd-progress --next
-```
-
-### Modo rápido
-
-```
-/gsd-quick
-```
-
-Para tarefas ad-hoc sem ciclo completo de planejamento.
+Índice completo: [docs/pt-BR/README.md](docs/pt-BR/README.md). Outros idiomas: [日本語](README.ja-JP.md) · [한국어](README.ko-KR.md) · [Português](README.pt-BR.md) · [简体中文](README.zh-CN.md).
 
 ---
 
 ## Por que funciona
 
-### Engenharia de contexto
+A maioria das configurações de codificação com IA falha em escala porque o inchaço de contexto degrada silenciosamente a qualidade da saída, não há memória compartilhada entre sessões e nada verifica se o código realmente funciona. O GSD Core resolve os três problemas: o trabalho pesado é executado em subagentes com contexto limpo, artefatos estruturados como `STATE.md` e `CONTEXT.md` sobrevivem às fronteiras de sessão, e a etapa de verificação percorre o que foi construído e gera planos de correção antes de uma fase ser declarada concluída. Consulte [docs/pt-BR/explanation/context-engineering.md](docs/pt-BR/explanation/context-engineering.md) para o raciocínio completo.
 
-| Arquivo | Papel |
-|---------|-------|
-| `PROJECT.md` | Visão do projeto |
-| `research/` | Conhecimento do ecossistema |
-| `REQUIREMENTS.md` | Escopo v1/v2 |
-| `ROADMAP.md` | Direção e progresso |
-| `STATE.md` | Memória entre sessões |
-| `PLAN.md` | Tarefa atômica com XML |
-| `SUMMARY.md` | O que mudou |
-| `todos/` | Ideias para depois |
-| `threads/` | Contexto persistente |
-| `seeds/` | Ideias para próximos marcos |
-
-### Formato XML de prompt
-
-```xml
-<task type="auto">
-  <name>Create login endpoint</name>
-  <files>src/app/api/auth/login/route.ts</files>
-  <action>
-    Use jose for JWT (not jsonwebtoken - CommonJS issues).
-    Validate credentials against users table.
-    Return httpOnly cookie on success.
-  </action>
-  <verify>curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie</verify>
-  <done>Valid credentials return cookie, invalid return 401</done>
-</task>
-```
-
-### Orquestração multiagente
-
-Um orquestrador leve chama agentes especializados para pesquisa, planejamento, execução e verificação.
-
-### Commits atômicos
-
-Cada tarefa gera commit próprio, facilitando `git bisect`, rollback e rastreabilidade.
+Problemas? Consulte [docs/pt-BR/how-to/recover-and-troubleshoot.md](docs/pt-BR/how-to/recover-and-troubleshoot.md).
 
 ---
 
-## Comandos
+## Comunidade
 
-### Fluxo principal
-
-| Comando | O que faz |
-|---------|-----------|
-| `/gsd-new-project [--auto]` | Inicializa projeto completo |
-| `/gsd-discuss-phase [N] [--auto] [--analyze] [--chain]` | Captura decisões antes do plano (`--chain` encadeia automaticamente em plan+execute) |
-| `/gsd-plan-phase [N] [--auto] [--reviews]` | Pesquisa + plano + validação |
-| `/gsd-execute-phase <N>` | Executa planos em ondas paralelas |
-| `/gsd-verify-work [N]` | UAT manual |
-| `/gsd-ship [N] [--draft]` | Cria PR da fase validada |
-| `/gsd-progress --next` | Avança automaticamente para o próximo passo |
-| `/gsd-fast <text>` | Tarefas triviais sem planejamento |
-| `/gsd-complete-milestone` | Fecha o marco e marca release |
-| `/gsd-new-milestone [name]` | Inicia próximo marco |
-
-### Qualidade e utilidades
-
-| Comando | O que faz |
-|---------|-----------|
-| `/gsd-review` | Peer review com múltiplas IAs |
-| `/gsd-pr-branch` | Cria branch limpa para PR |
-| `/gsd-settings` | Configura perfis e agentes |
-| `/gsd-config --profile <profile>` | Troca perfil (quality/balanced/budget/inherit) |
-| `/gsd-quick [--full] [--discuss] [--research]` | Execução rápida com garantias do GSD (`--full` ativa todas as etapas, `--validate` ativa apenas verificação) |
-| `/gsd-health [--repair]` | Verifica e repara `.planning/` |
-
-> Para a lista completa de comandos e opções, use `/gsd-help`.
+| Projeto | Plataforma |
+|---------|----------|
+| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | Port original para OpenCode |
+| [Discord](https://discord.gg/mYgfVNfA2r) | Suporte da comunidade |
 
 ---
 
-## Configuração
-
-As configurações do projeto ficam em `.planning/config.json`.
-Você pode configurar no `/gsd-new-project` ou ajustar depois com `/gsd-settings`.
-
-### Ajustes principais
-
-| Configuração | Opções | Padrão | Controle |
-|--------------|--------|--------|----------|
-| `mode` | `yolo`, `interactive` | `interactive` | Autoaprovar vs confirmar etapas |
-| `granularity` | `coarse`, `standard`, `fine` | `standard` | Granularidade de fases/planos |
-
-### Perfis de modelo
-
-| Perfil | Planejamento | Execução | Verificação |
-|--------|--------------|----------|-------------|
-| `quality` | Opus | Opus | Sonnet |
-| `balanced` | Opus | Sonnet | Sonnet |
-| `budget` | Sonnet | Sonnet | Haiku |
-| `inherit` | Inherit | Inherit | Inherit |
-
-Troca rápida:
-```
-/gsd-config --profile budget
-```
-
----
-
-## Segurança
-
-### Endurecimento embutido
-
-O GSD inclui proteções como:
-- prevenção de path traversal
-- detecção de prompt injection
-- validação de argumentos de shell
-- parsing seguro de JSON
-- scanner de injeção para CI
-
-### Protegendo arquivos sensíveis
-
-Adicione padrões sensíveis ao deny list do Claude Code:
-
-```json
-{
-  "permissions": {
-    "deny": [
-      "Read(.env)",
-      "Read(.env.*)",
-      "Read(**/secrets/*)",
-      "Read(**/*credential*)",
-      "Read(**/*.pem)",
-      "Read(**/*.key)"
-    ]
-  }
-}
-```
-
----
-
-## Solução de problemas
-
-**Comandos não apareceram após instalar?**
-- Reinicie o runtime
-- Verifique se os arquivos foram instalados no diretório correto
-
-**Comandos não funcionam como esperado?**
-- Rode `/gsd-help`
-- Reinstale com `npx @opengsd/gsd-core@latest`
-
-**Em Docker/container?**
-- Defina `CLAUDE_CONFIG_DIR` antes da instalação:
-
-```bash
-CLAUDE_CONFIG_DIR=/home/youruser/.claude npx @opengsd/gsd-core --global
-```
-
-### Desinstalar
-
-```bash
-# Instalações globais
-npx @opengsd/gsd-core --claude --global --uninstall
-npx @opengsd/gsd-core --opencode --global --uninstall
-npx @opengsd/gsd-core --gemini --global --uninstall
-npx @opengsd/gsd-core --kilo --global --uninstall
-npx @opengsd/gsd-core --codex --global --uninstall
-npx @opengsd/gsd-core --copilot --global --uninstall
-npx @opengsd/gsd-core --cursor --global --uninstall
-npx @opengsd/gsd-core --antigravity --global --uninstall
-npx @opengsd/gsd-core --augment --global --uninstall
-npx @opengsd/gsd-core --trae --global --uninstall
-npx @opengsd/gsd-core --cline --global --uninstall
-
-# Instalações locais (projeto atual)
-npx @opengsd/gsd-core --claude --local --uninstall
-npx @opengsd/gsd-core --opencode --local --uninstall
-npx @opengsd/gsd-core --gemini --local --uninstall
-npx @opengsd/gsd-core --kilo --local --uninstall
-npx @opengsd/gsd-core --codex --local --uninstall
-npx @opengsd/gsd-core --copilot --local --uninstall
-npx @opengsd/gsd-core --cursor --local --uninstall
-npx @opengsd/gsd-core --antigravity --local --uninstall
-npx @opengsd/gsd-core --augment --local --uninstall
-npx @opengsd/gsd-core --trae --local --uninstall
-npx @opengsd/gsd-core --cline --local --uninstall
-```
-
----
-
-## Community Ports
-
-OpenCode, Gemini CLI, Kilo e Codex agora são suportados nativamente via `npx @opengsd/gsd-core`.
-
-| Projeto | Plataforma | Descrição |
-|---------|------------|-----------|
-| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | OpenCode | Adaptação original para OpenCode |
-| gsd-gemini (archived) | Gemini CLI | Adaptação original para Gemini por uberfuzzy |
-
----
-
-## Star History
+## Histórico de estrelas
 
 <a href="https://star-history.com/#open-gsd/gsd-core&Date">
  <picture>
@@ -482,12 +114,12 @@ OpenCode, Gemini CLI, Kilo e Codex agora são suportados nativamente via `npx @o
 
 ## Licença
 
-Licença MIT. Veja [LICENSE](LICENSE).
+Licença MIT. Consulte [LICENSE](LICENSE) para detalhes.
 
 ---
 
 <div align="center">
 
-**Claude Code é poderoso. O GSD o torna confiável.**
+**Claude Code é poderoso. GSD Core o torna confiável.**
 
 </div>

README.zh-CN.md

@@ -1,5 +1,3 @@
-> ⚠️ This is an active fork. See the [English README](README.md) for the full notice about the original repo.
-
 <div align="center">
 
 # GSD Core
@@ -8,9 +6,7 @@
 
 [English](README.md) · [Português](README.pt-BR.md) · **简体中文** · [日本語](README.ja-JP.md) · [한국어](README.ko-KR.md)
 
-**一个轻量但强大的元提示、上下文工程与规格驱动开发系统，适用于 Claude Code、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf、Antigravity、Augment、Trae、CodeBuddy 和 Cline。**
-
-**它解决的是 context rot：随着 Claude 的上下文窗口被填满，输出质量逐步劣化的问题。**
+**一套轻量级的元提示、上下文工程与规范驱动开发系统，适用于 Claude Code、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf 等 AI 编程工具。**
 
 [![npm version](https://img.shields.io/npm/v/%40opengsd%2Fgsd-core?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@opengsd/gsd-core)
 [![npm downloads](https://img.shields.io/npm/dm/%40opengsd%2Fgsd-core?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@opengsd/gsd-core)
@@ -19,72 +15,25 @@
 [![GitHub stars](https://img.shields.io/github/stars/open-gsd/gsd-core?style=for-the-badge&logo=github&color=181717)](https://github.com/open-gsd/gsd-core)
 [![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
 
-<br>
-
-```bash
-npx @opengsd/gsd-core@latest
-```
-
-**支持 Mac、Windows 和 Linux。**
-
-<br>
-
-![GSD Install](assets/terminal.svg)
-
-<br>
-
-*"只要你清楚自己想要什么，它就真的能给你做出来。不扯淡。"*
-
-*"我试过 SpecKit、OpenSpec 和 Taskmaster，这套东西目前给我的结果最好。"*
-
-*"这是我给 Claude Code 加过最强的增强。没有过度设计，是真的把事做完。"*
-
-<br>
-
-**已被 Amazon、Google、Shopify 和 Webflow 的工程师采用。**
-
-[我为什么做这个](#我为什么做这个) · [它是怎么工作的](#它是怎么工作的) · [命令](#命令) · [为什么它有效](#为什么它有效) · [用户指南](docs/USER-GUIDE.md)
-
 </div>
 
 ---
 
-## 我为什么做这个
+## 什么是 GSD Core
 
-我是独立开发者。我不写代码，Claude Code 写。
-
-市面上已经有其他规格驱动开发工具，比如 BMAD、Speckit……但它们要么把事情搞得比必要的复杂得多了些（冲刺仪式、故事点、利益相关方同步、复盘、Jira 流程），要么根本缺少对你到底在构建什么的整体理解。我不是一家 50 人的软件公司。我不想演企业流程。我只是个想把好东西真正做出来的创作者。
-
-所以我做了 GSD。复杂性在系统内部，不在你的工作流里。幕后是上下文工程、XML 提示格式、子代理编排、状态管理；你看到的是几个真能工作的命令。
-
-这套系统会把 Claude 完成工作 *以及* 验证结果所需的一切上下文都准备好。我信任这个工作流，因为它确实能把事情做好。
-
-这就是它。没有企业角色扮演式的废话，只有一套非常有效、能让你持续用 Claude Code 构建酷东西的系统。
-
-— **TÂCHES**
+GSD Core 是一套上下文工程与规范驱动开发框架，能够引导 AI 编程智能体（Claude Code、Codex、Gemini CLI、Copilot、Cursor 等）按照严格的阶段循环推进工作。它解决了[上下文腐化](docs/zh-CN/explanation/context-engineering.md)问题——即随着 AI 填满上下文窗口而逐渐累积的质量下降——通过在全新上下文的子智能体中运行所有繁重的研究、规划和执行工作，同时保持主会话的精简。
 
 ---
 
-Vibecoding 的名声不算好。你描述需求，AI 生成代码，结果往往是质量不稳定、规模一上来就散架的垃圾。
+## 工作原理
 
-GSD 解决的就是这个问题。它是让 Claude Code 变得可靠的上下文工程层。你只要描述想法，系统会自动提取它需要知道的一切，然后让 Claude Code 去干活。
+每个里程碑重复相同的五步循环，每次推进一个阶段：
 
----
-
-## 适合谁用
-
-适合那些想把自己的需求说明白，然后让系统正确构建出来的人，而不是假装自己在运营一个 50 人工程组织的人。
-
-### 功能亮点
-
-规范版本以 npm 上发布的 `@opengsd/gsd-core` 版本以及 `package.json` 为准。`docs/` 中旧的发行说明文件仅作为连续性历史保留；不要把归档编号当作当前 GSD Core 包版本。
-
-- **`--minimal` 安装档** — 别名 `--core-only`。仅安装主循环的 6 个核心技能（`new-project`、`discuss-phase`、`plan-phase`、`execute-phase`、`help`、`update`），不安装任何 `gsd-*` 子代理。将冷启动系统提示开销从 ~12k token 降至 ~700 token（≥94% 减少）。适合 32K–128K 上下文的本地 LLM 和按 token 计费的 API。
-- **`/gsd-phase --edit`** — 就地修改 `ROADMAP.md` 中已有阶段的任意字段，不改变其编号或位置。`--force` 跳过确认 diff，验证 `depends_on` 引用，并在写入时更新 `STATE.md`。
-- **合并后构建与测试门** — `execute-phase` 步骤 5.6 优先自动检测 `workflow.build_command` 配置，否则按 Xcode（`.xcodeproj`）、Makefile、Justfile、Cargo、Go、Python、npm 顺序回退。Xcode/iOS 项目自动运行 `xcodebuild build` 和 `xcodebuild test`。在并行与串行模式下均生效。
-- **每运行时评审模型选择** — `review.models.<cli>` 让每个外部评审 CLI（codex、gemini 等）独立于规划/执行档选择自己的模型。
-- **工作流设置继承** — 设置 `GSD_WORKSTREAM` 后，先加载根 `.planning/config.json`，再与该工作流的配置进行深合并（冲突时工作流优先）。工作流配置中显式 `null` 会覆盖根值。
-- **技能整合：86 → 59** — 4 个新分组技能（`capture`、`phase`、`config`、`workspace`）吸收了 31 个微技能。6 个已有父技能将收尾与子操作合并为标志：`update --sync/--reapply`、`sketch --wrap-up`、`spike --wrap-up`、`map-codebase --fast/--query`、`code-review --fix`、`progress --do/--next`。功能无损失。
+1. **讨论（Discuss）** — 在规划任何内容之前，先捕获实现决策
+2. **规划（Plan）** — 研究、分解，并验证计划能够适配全新的上下文窗口
+3. **执行（Execute）** — 以并行波次运行计划；每个执行器以干净的 20 万 token 上下文启动
+4. **验证（Verify）** — 检查已构建的内容；在宣告完成前诊断并修复问题
+5. **交付（Ship）** — 创建 PR，归档阶段，对下一个阶段重复上述流程
 
 ---
 
@@ -94,727 +43,60 @@ GSD 解决的就是这个问题。它是让 Claude Code 变得可靠的上下文
 npx @opengsd/gsd-core@latest
 ```
 
-安装器会提示你选择：
-1. **运行时**：Claude Code、OpenCode、Gemini、Kilo、Codex、Copilot、Cursor、Windsurf、Antigravity、Augment、Trae、CodeBuddy、Cline，或全部
-2. **安装位置**：全局（所有项目）或本地（仅当前项目）
+安装程序会提示选择运行时（Claude Code、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf 等）以及是全局安装还是本地安装。跨运行时兼容性需要使用安装程序——请勿直接从 `agents/` 或 `commands/` 目录复制文件。
 
-安装后可这样验证：
-- Claude Code / Gemini / Copilot / Antigravity：`/gsd-help`
-- OpenCode / Kilo / Augment / Trae / CodeBuddy：`/gsd-help`
-- Codex：`$gsd-help`
-- Cline：GSD 通过 `.clinerules` 安装 — 检查 `.clinerules` 是否存在
+使用其他运行时或没有 Node.js？请参阅[在你的运行时上安装](docs/zh-CN/how-to/install-on-your-runtime.md)。
 
-> [!NOTE]
-> Claude Code 2.1.88+ 和 Codex 以 skill 形式安装（`skills/gsd-*/SKILL.md`）。Cline 使用 `.clinerules`。安装器会自动处理所有格式。
-
-> [!TIP]
-> 基于源码安装或无法使用 npm 的环境，请参阅 **[docs/manual-update.md](docs/manual-update.md)**。
-
-### 保持更新
-
-GSD 迭代很快，建议定期更新：
+安装完成后，启动你的第一个项目：
 
 ```bash
-npx @opengsd/gsd-core@latest
-```
-
-<details>
-<summary><strong>非交互式安装（Docker、CI、脚本）</strong></summary>
-
-```bash
-# Claude Code
-npx @opengsd/gsd-core --claude --global   # 安装到 ~/.claude/
-npx @opengsd/gsd-core --claude --local    # 安装到 ./.claude/
-
-# OpenCode
-npx @opengsd/gsd-core --opencode --global # 安装到 ~/.config/opencode/
-
-# Gemini CLI
-npx @opengsd/gsd-core --gemini --global   # 安装到 ~/.gemini/
-
-# Kilo
-npx @opengsd/gsd-core --kilo --global     # 安装到 ~/.config/kilo/
-npx @opengsd/gsd-core --kilo --local      # 安装到 ./.kilo/
-
-# Codex
-npx @opengsd/gsd-core --codex --global    # 安装到 ~/.codex/
-npx @opengsd/gsd-core --codex --local     # 安装到 ./.codex/
-
-# Copilot
-npx @opengsd/gsd-core --copilot --global  # 安装到 ~/.github/
-npx @opengsd/gsd-core --copilot --local   # 安装到 ./.github/
-
-# Cursor CLI
-npx @opengsd/gsd-core --cursor --global   # 安装到 ~/.cursor/
-npx @opengsd/gsd-core --cursor --local    # 安装到 ./.cursor/
-
-# Antigravity
-npx @opengsd/gsd-core --antigravity --global # 安装到 ~/.gemini/antigravity/
-npx @opengsd/gsd-core --antigravity --local  # 安装到 ./.agent/
-
-# Augment
-npx @opengsd/gsd-core --augment --global     # 安装到 ~/.augment/
-npx @opengsd/gsd-core --augment --local      # 安装到 ./.augment/
-
-# Trae
-npx @opengsd/gsd-core --trae --global     # 安装到 ~/.trae/
-npx @opengsd/gsd-core --trae --local      # 安装到 ./.trae/
-
-# CodeBuddy
-npx @opengsd/gsd-core --codebuddy --global # 安装到 ~/.codebuddy/
-npx @opengsd/gsd-core --codebuddy --local  # 安装到 ./.codebuddy/
-
-# Cline
-npx @opengsd/gsd-core --cline --global       # 安装到 ~/.cline/
-npx @opengsd/gsd-core --cline --local        # 安装到 ./.clinerules
-
-# 所有运行时
-npx @opengsd/gsd-core --all --global      # 安装到所有目录
-```
-
-使用 `--global`（`-g`）或 `--local`（`-l`）可以跳过安装位置提示。
-使用 `--claude`、`--opencode`、`--gemini`、`--kilo`、`--codex`、`--copilot`、`--cursor`、`--windsurf`、`--antigravity`、`--augment`、`--trae`、`--codebuddy`、`--cline` 或 `--all` 可以跳过运行时提示。
-
-</details>
-
-<details>
-<summary><strong>开发安装</strong></summary>
-
-克隆仓库并在本地运行安装器：
-
-```bash
-git clone https://github.com/open-gsd/gsd-core.git
-cd gsd-core
-node bin/install.js --claude --local
-```
-
-这样会安装到 `./.claude/`，方便你在贡献代码前测试自己的改动。
-
-</details>
-
-### 推荐：跳过权限确认模式
-
-GSD 的设计目标是无摩擦自动化。运行 Claude Code 时建议使用：
-
-```bash
-claude --dangerously-skip-permissions
-```
-
-> [!TIP]
-> 这才是 GSD 的预期用法。连 `date` 和 `git commit` 都要来回确认 50 次，整个体验就废了。
-
-<details>
-<summary><strong>替代方案：细粒度权限</strong></summary>
-
-如果你不想使用这个 flag，可以在项目的 `.claude/settings.json` 中加入：
-
-```json
-{
-  "permissions": {
-    "allow": [
-      "Bash(date:*)",
-      "Bash(echo:*)",
-      "Bash(cat:*)",
-      "Bash(ls:*)",
-      "Bash(mkdir:*)",
-      "Bash(wc:*)",
-      "Bash(head:*)",
-      "Bash(tail:*)",
-      "Bash(sort:*)",
-      "Bash(grep:*)",
-      "Bash(tr:*)",
-      "Bash(git add:*)",
-      "Bash(git commit:*)",
-      "Bash(git status:*)",
-      "Bash(git log:*)",
-      "Bash(git diff:*)",
-      "Bash(git tag:*)"
-    ]
-  }
-}
-```
-
-</details>
-
----
-
-## 它是怎么工作的
-
-> **已经有现成代码库？** 先运行 `/gsd-map-codebase`。它会并行拉起多个代理分析你的技术栈、架构、约定和风险点。之后 `/gsd-new-project` 就会真正“理解”你的代码库，提问会聚焦在你打算新增的部分，规划时也会自动加载你的现有模式。
-
-### 1. 初始化项目
-
-```
 /gsd-new-project
 ```
 
-一个命令，一条完整流程。系统会：
-
-1. **提问**：一直问到它彻底理解你的想法（目标、约束、技术偏好、边界情况）
-2. **研究**：并行拉起代理调研领域知识（可选，但强烈建议）
-3. **需求梳理**：提取哪些属于 v1、v2，哪些不在范围内
-4. **路线图**：创建与需求映射的阶段规划
-
-你审核并批准路线图后，就可以开始构建。
-
-**生成：** `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md`、`STATE.md`、`.planning/research/`
+初次使用？请按照[你的第一个项目](docs/zh-CN/tutorials/your-first-project.md)进行引导式操作，从安装到完成第一个交付阶段。
 
 ---
 
-### 2. 讨论阶段
+## 文档
 
-```
-/gsd-discuss-phase 1
-```
+**教程** — 边做边学：
+- [你的第一个项目](docs/zh-CN/tutorials/your-first-project.md)
+- [接入现有代码库](docs/zh-CN/tutorials/onboarding-an-existing-codebase.md)
 
-**这是你塑造实现方式的地方。**
+**操作指南** — 面向任务的实用方法：
+- [在你的运行时上安装](docs/zh-CN/how-to/install-on-your-runtime.md)
+- [规划一个阶段](docs/zh-CN/how-to/plan-a-phase.md)
+- [验证与交付](docs/zh-CN/how-to/verify-and-ship.md)
+- … [查看所有操作指南](docs/zh-CN/README.md#how-to-guides)
 
-你的路线图里，每个阶段通常只有一两句话。这点信息不足以让系统按 *你脑中的样子* 把东西做出来。这一步的作用，就是在研究和规划之前，把你的偏好先收进去。
+**参考文档** — 权威信息：
+- [命令](docs/zh-CN/COMMANDS.md)
+- [配置](docs/zh-CN/CONFIGURATION.md)
+- [CLI 工具](docs/zh-CN/CLI-TOOLS.md)
 
-系统会分析该阶段，并根据要构建的内容识别灰区：
+**概念说明** — 设计理念与决策：
+- [上下文工程](docs/zh-CN/explanation/context-engineering.md)
+- [阶段循环](docs/zh-CN/explanation/the-phase-loop.md)
+- [架构](docs/zh-CN/ARCHITECTURE.md)
 
-- **视觉功能**：布局、信息密度、交互、空状态
-- **API / CLI**：返回格式、flags、错误处理、详细程度
-- **内容系统**：结构、语气、深度、流转方式
-- **组织型任务**：分组标准、命名、去重、例外情况
-
-对每个你选择的区域，系统都会持续追问，直到你满意为止。最终产物 `CONTEXT.md` 会直接喂给后续两个步骤：
-
-1. **研究代理会读取它**：知道该研究哪些模式（例如“用户想要卡片布局” → 去研究卡片组件库）
-2. **规划代理会读取它**：知道哪些决策已经锁定（例如“已决定使用无限滚动” → 计划里就会包含滚动处理）
-
-你在这里给出的信息越具体，系统越能构建出你真正想要的东西。跳过它，你拿到的是合理默认值；用好它，你拿到的是 *你的* 方案。
-
-**生成：** `{phase_num}-CONTEXT.md`
+完整索引：[docs/zh-CN/README.md](docs/zh-CN/README.md)。其他语言：[日本語](README.ja-JP.md) · [한국어](README.ko-KR.md) · [Português](README.pt-BR.md) · [English](README.md)。
 
 ---
 
-### 3. 规划阶段
+## 为什么有效
 
-```
-/gsd-plan-phase 1
-```
+大多数 AI 编程方案在规模化时都会失败，原因在于上下文膨胀会悄无声息地降低输出质量，各会话之间没有共享记忆，也没有任何机制来验证代码是否真正可用。GSD Core 解决了这三个问题：繁重的工作在全新的子智能体中运行，`STATE.md` 和 `CONTEXT.md` 等结构化工件能够跨越会话边界保持存续，验证步骤会检查已构建的内容并在宣告阶段完成前生成修复计划。完整的设计思路请参阅 [docs/zh-CN/explanation/context-engineering.md](docs/zh-CN/explanation/context-engineering.md)。
 
-系统会：
-
-1. **研究**：结合你的 `CONTEXT.md` 决策，调研这一阶段该怎么实现
-2. **制定计划**：创建 2-3 份原子化任务计划，使用 XML 结构
-3. **验证**：将计划与需求对照检查，直到通过为止
-
-每份计划都足够小，可以在一个全新的上下文窗口里执行。没有质量衰减，也不会出现“我接下来会更简洁一些”的退化状态。
-
-**生成：** `{phase_num}-RESEARCH.md`、`{phase_num}-{N}-PLAN.md`
+遇到问题？请参阅 [docs/zh-CN/how-to/recover-and-troubleshoot.md](docs/zh-CN/how-to/recover-and-troubleshoot.md)。
 
 ---
 
-### 4. 执行阶段
+## 社区
 
-```
-/gsd-execute-phase 1
-```
-
-系统会：
-
-1. **按 wave 执行计划**：能并行的并行，有依赖的顺序执行
-2. **每个计划使用新上下文**：20 万 token 纯用于实现，零历史垃圾
-3. **每个任务单独提交**：每项任务都有自己的原子提交
-4. **对照目标验证**：检查代码库是否真的交付了该阶段承诺的内容
-
-你可以离开，回来时看到的是已经完成的工作和干净的 git 历史。
-
-**Wave 执行方式：**
-
-计划会根据依赖关系被分组为不同的 “wave”。同一 wave 内并行执行，不同 wave 之间顺序推进。
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│  PHASE EXECUTION                                                     │
-├─────────────────────────────────────────────────────────────────────┤
-│                                                                      │
-│  WAVE 1 (parallel)          WAVE 2 (parallel)          WAVE 3       │
-│  ┌─────────┐ ┌─────────┐    ┌─────────┐ ┌─────────┐    ┌─────────┐ │
-│  │ Plan 01 │ │ Plan 02 │ →  │ Plan 03 │ │ Plan 04 │ →  │ Plan 05 │ │
-│  │         │ │         │    │         │ │         │    │         │ │
-│  │ User    │ │ Product │    │ Orders  │ │ Cart    │    │ Checkout│ │
-│  │ Model   │ │ Model   │    │ API     │ │ API     │    │ UI      │ │
-│  └─────────┘ └─────────┘    └─────────┘ └─────────┘    └─────────┘ │
-│       │           │              ↑           ↑              ↑       │
-│       └───────────┴──────────────┴───────────┘              │       │
-│              Dependencies: Plan 03 needs Plan 01            │       │
-│                          Plan 04 needs Plan 02              │       │
-│                          Plan 05 needs Plans 03 + 04        │       │
-│                                                                      │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-**为什么 wave 很重要：**
-- 独立计划 → 同一 wave → 并行执行
-- 依赖计划 → 更晚的 wave → 等依赖完成
-- 文件冲突 → 顺序执行，或合并到同一个计划里
-
-这也是为什么“垂直切片”（Plan 01：端到端完成用户功能）比“水平分层”（Plan 01：所有 model，Plan 02：所有 API）更容易并行化。
-
-**生成：** `{phase_num}-{N}-SUMMARY.md`、`{phase_num}-VERIFICATION.md`
-
----
-
-### 5. 验证工作
-
-```
-/gsd-verify-work 1
-```
-
-**这是你确认它是否真的可用的地方。**
-
-自动化验证能检查代码存在、测试通过。但这个功能是否真的按你的预期工作？这一步就是让你亲自用。
-
-系统会：
-
-1. **提取可测试的交付项**：你现在应该能做到什么
-2. **逐项带你验证**：“能否用邮箱登录？” 可以 / 不可以，或者描述哪里不对
-3. **自动诊断失败**：拉起 debug 代理定位根因
-4. **创建验证过的修复计划**：可立刻重新执行
-
-如果一切通过，就进入下一步；如果哪里坏了，你不需要手动 debug，只要重新运行 `/gsd-execute-phase`，执行它自动生成的修复计划即可。
-
-**生成：** `{phase_num}-UAT.md`，以及发现问题时的修复计划
-
----
-
-### 6. 重复 → 发布 → 完成 → 下一个里程碑
-
-```
-/gsd-discuss-phase 2
-/gsd-plan-phase 2
-/gsd-execute-phase 2
-/gsd-verify-work 2
-/gsd-ship 2                  # 从已验证的工作创建 PR
-...
-/gsd-complete-milestone
-/gsd-new-milestone
-```
-
-或者让 GSD 自动判断下一步：
-
-```
-/gsd-progress --next                    # 自动检测并执行下一步
-```
-
-循环执行 **讨论 → 规划 → 执行 → 验证 → 发布**，直到整个里程碑完成。
-
-如果你希望在讨论阶段更快收集信息，可以用 `/gsd-discuss-phase <n> --batch`，一次回答一小组问题，而不是逐个问答。
-
-每个阶段都会得到你的输入（discuss）、充分研究（plan）、干净执行（execute）和人工验证（verify）。上下文始终保持新鲜，质量也能持续稳定。
-
-当所有阶段完成后，`/gsd-complete-milestone` 会归档当前里程碑并打 release tag。
-
-接着用 `/gsd-new-milestone` 开启下一个版本。它和 `new-project` 流程相同，只是面向你现有的代码库。你描述下一步想构建什么，系统研究领域、梳理需求，再产出新的路线图。每个里程碑都是一个干净周期：定义 → 构建 → 发布。
-
----
-
-### 快速模式
-
-```
-/gsd-quick
-```
-
-**适用于不需要完整规划的临时任务。**
-
-快速模式保留 GSD 的核心保障（原子提交、状态跟踪），但路径更短：
-
-- **相同的代理体系**：同样是 planner + executor，质量不降
-- **跳过可选步骤**：默认不启用 research、plan checker、verifier
-- **独立跟踪**：数据存放在 `.planning/quick/`，不和 phase 混在一起
-
-**`--discuss` 参数：** 在规划前先进行轻量讨论，理清灰区。
-
-**`--research` 参数：** 在规划前拉起研究代理。调查实现方式、库选型和潜在坑点。适合你不确定怎么下手的场景。
-
-**`--full` 参数：** 启用计划检查（最多 2 轮迭代）和执行后验证。
-
-参数可组合使用：`--discuss --research --full` 可同时获得讨论 + 研究 + 计划检查 + 验证。
-
-```
-/gsd-quick
-> What do you want to do? "Add dark mode toggle to settings"
-```
-
-**生成：** `.planning/quick/001-add-dark-mode-toggle/PLAN.md`、`SUMMARY.md`
-
----
-
-## 为什么它有效
-
-### 上下文工程
-
-Claude Code 非常强大，前提是你把它需要的上下文给对。大多数人做不到。
-
-GSD 会替你处理：
-
-| 文件 | 作用 |
-|------|------|
-| `PROJECT.md` | 项目愿景，始终加载 |
-| `research/` | 生态知识（技术栈、功能、架构、坑点） |
-| `REQUIREMENTS.md` | 带 phase 可追踪性的 v1/v2 范围定义 |
-| `ROADMAP.md` | 你要去哪里、哪些已经完成 |
-| `STATE.md` | 决策、阻塞、当前位置，跨会话记忆 |
-| `PLAN.md` | 带 XML 结构和验证步骤的原子任务 |
-| `SUMMARY.md` | 做了什么、改了什么、已写入历史 |
-| `todos/` | 留待后续处理的想法和任务 |
-
-这些尺寸限制都是基于 Claude 在何处开始质量退化得出的。控制在阈值内，输出才能持续稳定。
-
-### XML 提示格式
-
-每个计划都会使用为 Claude 优化过的结构化 XML：
-
-```xml
-<task type="auto">
-  <name>Create login endpoint</name>
-  <files>src/app/api/auth/login/route.ts</files>
-  <action>
-    Use jose for JWT (not jsonwebtoken - CommonJS issues).
-    Validate credentials against users table.
-    Return httpOnly cookie on success.
-  </action>
-  <verify>curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie</verify>
-  <done>Valid credentials return cookie, invalid return 401</done>
-</task>
-```
-
-指令足够精确，不需要猜。验证也内建在计划里。
-
-### 多代理编排
-
-每个阶段都遵循同一种模式：一个轻量 orchestrator 拉起专用代理、汇总结果，再路由到下一步。
-
-| 阶段 | Orchestrator 做什么 | Agents 做什么 |
-|------|---------------------|---------------|
-| 研究 | 协调与展示研究结果 | 4 个并行研究代理分别调查技术栈、功能、架构、坑点 |
-| 规划 | 校验并管理迭代 | Planner 生成计划，checker 验证，循环直到通过 |
-| 执行 | 按 wave 分组并跟踪进度 | Executors 并行实现，每个都有全新的 20 万上下文 |
-| 验证 | 呈现结果并决定下一步 | Verifier 对照目标检查代码库，debuggers 诊断失败 |
-
-Orchestrator 本身不做重活，只负责拉代理、等待、整合结果。
-
-**最终效果：** 你可以在一个阶段里完成深度研究、生成并验证多个计划、让多个执行代理并行写下成千上万行代码，再自动对照目标验证，而主上下文窗口依然能维持在 30-40% 左右。真正的工作都发生在新鲜的子代理上下文里，所以你的主会话始终保持快速、响应稳定。
-
-### 原子 Git 提交
-
-每个任务完成后都会立刻生成独立提交：
-
-```bash
-abc123f docs(08-02): complete user registration plan
-def456g feat(08-02): add email confirmation flow
-hij789k feat(08-02): implement password hashing
-lmn012o feat(08-02): create registration endpoint
-```
-
-> [!NOTE]
-> **好处：** `git bisect` 能精准定位是哪项任务引入故障；每个任务都可单独回滚；未来 Claude 读取历史时也更清晰；整个 AI 自动化工作流的可观测性更好。
-
-每个 commit 都是外科手术式的：精确、可追踪、有意义。
-
-### 模块化设计
-
-- 给当前里程碑追加 phase
-- 在 phase 之间插入紧急工作
-- 完成当前里程碑后开启新的周期
-- 在不推倒重来的前提下调整计划
-
-你不会被这套系统绑死，它会随着项目变化而调整。
-
----
-
-## 命令
-
-### 核心工作流
-
-| 命令 | 作用 |
-|------|------|
-| `/gsd-new-project [--auto]` | 完整初始化：提问 → 研究 → 需求 → 路线图 |
-| `/gsd-discuss-phase [N] [--auto] [--analyze]` | 在规划前收集实现决策（`--analyze` 增加权衡分析） |
-| `/gsd-plan-phase [N] [--auto] [--reviews]` | 为某个阶段执行研究 + 规划 + 验证（`--reviews` 加载代码库审查结果） |
-| `/gsd-execute-phase <N>` | 以并行 wave 执行全部计划，完成后验证 |
-| `/gsd-verify-work [N]` | 人工用户验收测试 ¹ |
-| `/gsd-ship [N] [--draft]` | 从已验证的阶段工作创建 PR，自动生成 PR 描述 |
-| `/gsd-fast <text>` | 内联处理琐碎任务——完全跳过规划，立即执行 |
-| `/gsd-progress --next` | 自动推进到下一个逻辑工作流步骤 |
-| `/gsd-audit-milestone` | 验证里程碑是否达到完成定义 |
-| `/gsd-complete-milestone` | 归档里程碑并打 release tag |
-| `/gsd-new-milestone [name]` | 开始下一个版本：提问 → 研究 → 需求 → 路线图 |
-| `/gsd-milestone-summary` | 从已完成的里程碑产物生成项目概览，用于团队上手 |
-| `/gsd-forensics` | 对失败或卡住的工作流进行事后调查 |
-
-### 工作流（Workstreams）
-
-| 命令 | 作用 |
-|------|------|
-| `/gsd-workstreams list` | 显示所有工作流及其状态 |
-| `/gsd-workstreams create <name>` | 创建命名空间工作流，用于并行里程碑工作 |
-| `/gsd-workstreams switch <name>` | 切换当前活跃工作流 |
-| `/gsd-workstreams complete <name>` | 完成并合并工作流 |
-
-### 多项目工作区
-
-| 命令 | 作用 |
-|------|------|
-| `/gsd-workspace --new` | 创建隔离工作区，包含仓库副本（worktree 或 clone） |
-| `/gsd-workspace --list` | 显示所有 GSD 工作区及其状态 |
-| `/gsd-workspace --remove` | 移除工作区并清理 worktree |
-
-### UI 设计
-
-| 命令 | 作用 |
-|------|------|
-| `/gsd-ui-phase [N]` | 为前端阶段生成 UI 设计合约（UI-SPEC.md） |
-| `/gsd-ui-review [N]` | 对已实现前端代码进行 6 维视觉审计 |
-
-### 导航
-
-| 命令 | 作用 |
-|------|------|
-| `/gsd-progress` | 我现在在哪？下一步是什么？ |
-| `/gsd-progress --next` | 自动检测状态并执行下一步 |
-| `/gsd-help` | 显示全部命令和使用指南 |
-| `/gsd-update` | 更新 GSD，并预览变更日志 |
-
-### Brownfield
-
-| 命令 | 作用 |
-|------|------|
-| `/gsd-map-codebase` | 在 `new-project` 前分析现有代码库 |
-
-### 阶段管理
-
-| 命令 | 作用 |
-|------|------|
-| `/gsd-phase` | 在路线图末尾追加 phase |
-| `/gsd-phase --insert [N]` | 在 phase 之间插入紧急工作 |
-| `/gsd-phase --edit [N] [--force]` | 就地修改已有 phase 的任意字段 — 编号与位置保持不变 |
-| `/gsd-phase --remove [N]` | 删除未来 phase，并重编号 |
-| `/gsd-discuss-phase --assumptions [N]` | 在规划前查看 Claude 打算采用的方案 |
-| `/gsd-audit-milestone --fix` | 为 audit 发现的缺口创建 phase |
-
-### 代码质量
-
-| 命令 | 作用 |
-|------|------|
-| `/gsd-review` | 对当前阶段或分支进行跨 AI 同行评审 |
-| `/gsd-pr-branch` | 创建过滤 `.planning/` 提交的干净 PR 分支 |
-| `/gsd-audit-uat` | 审计验证债务——找出缺少 UAT 的阶段 |
-
-### 积压
-
-| 命令 | 作用 |
-|------|------|
-| `/gsd-capture --seed <idea>` | 将想法存入积压停车场，留待未来里程碑 |
-
-### 会话
-
-| 命令 | 作用 |
-|------|------|
-| `/gsd-pause-work` | 在中途暂停时创建交接上下文（写入 HANDOFF.json） |
-| `/gsd-resume-work` | 从上一次会话恢复 |
-| `/gsd-pause-work --report` | 生成会话摘要，包含已完成工作和结果 |
-
-### 工具
-
-| 命令 | 作用 |
-|------|------|
-| `/gsd-settings` | 配置模型 profile 和工作流代理 |
-| `/gsd-config --profile <profile>` | 切换模型 profile（quality / balanced / budget / inherit） |
-| `/gsd-capture [desc]` | 记录一个待办想法 |
-| `/gsd-capture --list` | 查看待办列表 |
-| `/gsd-debug [desc]` | 使用持久状态进行系统化调试 |
-| `/gsd-do <text>` | 将自由文本自动路由到正确的 GSD 命令 |
-| `/gsd-note <text>` | 零摩擦想法捕捉——追加、列出或提升为待办 |
-| `/gsd-quick [--full] [--discuss] [--research]` | 以 GSD 保障执行临时任务（`--full` 增加计划检查和验证，`--discuss` 先补上下文，`--research` 在规划前先调研） |
-| `/gsd-health [--repair]` | 校验 `.planning/` 目录完整性，带 `--repair` 时自动修复 |
-| `/gsd-stats` | 显示项目统计——阶段、计划、需求、git 指标 |
-| `/gsd-profile-user [--questionnaire] [--refresh]` | 从会话分析生成开发者行为档案，用于个性化响应 |
-
-<sup>¹ 由 reddit 用户 OracleGreyBeard 贡献</sup>
-
----
-
-## 配置
-
-GSD 将项目设置保存在 `.planning/config.json`。你可以在 `/gsd-new-project` 时配置，也可以稍后通过 `/gsd-settings` 修改。完整的配置 schema、工作流开关、git branching 选项以及各代理的模型分配，请查看[用户指南](docs/USER-GUIDE.md#configuration-reference)。
-
-### 核心设置
-
-| Setting | Options | Default | 作用 |
-|---------|---------|---------|------|
-| `mode` | `yolo`, `interactive` | `interactive` | 自动批准，还是每一步确认 |
-| `granularity` | `coarse`, `standard`, `fine` | `standard` | phase 粒度，也就是范围切分得多细 |
-
-### 模型 Profile
-
-控制各代理使用哪种 Claude 模型，在质量和 token 成本之间平衡。
-
-| Profile | Planning | Execution | Verification |
-|---------|----------|-----------|--------------|
-| `quality` | Opus | Opus | Sonnet |
-| `balanced`（默认） | Opus | Sonnet | Sonnet |
-| `budget` | Sonnet | Sonnet | Haiku |
-| `inherit` | Inherit | Inherit | Inherit |
-
-切换方式：
-```
-/gsd-config --profile budget
-```
-
-使用非 Anthropic 提供商（OpenRouter、本地模型）时，或想跟随当前运行时的模型选择时（如 OpenCode 的 `/model`），可用 `inherit`。
-
-也可以通过 `/gsd-settings` 配置。
-
-### 工作流代理
-
-这些设置会在规划或执行时拉起额外代理。它们能提升质量，但也会增加 token 消耗和耗时。
-
-| Setting | Default | 作用 |
-|---------|---------|------|
-| `workflow.research` | `true` | 每个 phase 规划前先调研领域知识 |
-| `workflow.plan_check` | `true` | 执行前验证计划是否真能达成阶段目标 |
-| `workflow.verifier` | `true` | 执行后确认“必须交付项”是否已经落地 |
-| `workflow.auto_advance` | `false` | 自动串联 discuss → plan → execute，不中途停下 |
-| `workflow.research_before_questions` | `false` | 在讨论提问前先运行研究，而非之后 |
-| `workflow.skip_discuss` | `false` | 在自主模式下完全跳过讨论阶段 |
-| `workflow.discuss_mode` | `null` | 控制讨论阶段行为（`assumptions` 使用推断默认值） |
-
-可以用 `/gsd-settings` 开关这些项，也可以在单次命令里覆盖：
-- `/gsd-plan-phase --skip-research`
-- `/gsd-plan-phase --skip-verify`
-
-### 执行
-
-| Setting | Default | 作用 |
-|---------|---------|------|
-| `parallelization.enabled` | `true` | 是否并行执行独立计划 |
-| `planning.commit_docs` | `true` | 是否将 `.planning/` 纳入 git 跟踪 |
-| `hooks.context_warnings` | `true` | 显示上下文窗口使用量警告 |
-
-### Git 分支策略
-
-控制 GSD 在执行过程中如何处理分支。
-
-| Setting | Options | Default | 作用 |
-|---------|---------|---------|------|
-| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | 分支创建策略 |
-| `git.phase_branch_template` | string | `gsd/phase-{phase}-{slug}` | phase 分支模板 |
-| `git.milestone_branch_template` | string | `gsd/{milestone}-{slug}` | milestone 分支模板 |
-
-**策略说明：**
-- **`none`**：直接提交到当前分支（GSD 默认行为）
-- **`phase`**：每个 phase 创建一个分支，在 phase 完成时合并
-- **`milestone`**：整个里程碑只用一个分支，在里程碑完成时合并
-
-在里程碑完成时，GSD 会提供 squash merge（推荐）或保留历史的 merge 选项。
-
----
-
-## 安全
-
-### 保护敏感文件
-
-GSD 的代码库映射和分析命令会读取文件来理解你的项目。**包含机密信息的文件应当加入 Claude Code 的 deny list**：
-
-1. 打开 Claude Code 设置（项目级 `.claude/settings.json` 或全局设置）
-2. 把敏感文件模式加入 deny list：
-
-```json
-{
-  "permissions": {
-    "deny": [
-      "Read(.env)",
-      "Read(.env.*)",
-      "Read(**/secrets/*)",
-      "Read(**/*credential*)",
-      "Read(**/*.pem)",
-      "Read(**/*.key)"
-    ]
-  }
-}
-```
-
-这样无论你运行什么命令，Claude 都无法读取这些文件。
-
-> [!IMPORTANT]
-> GSD 内建了防止提交 secrets 的保护，但纵深防御依然是最佳实践。第一道防线应该是直接禁止读取敏感文件。
-
----
-
-## 故障排查
-
-**安装后找不到命令？**
-- 重启你的运行时，让命令或 skills 重新加载
-- 检查文件是否存在于 `~/.claude/commands/gsd/`（全局）或 `./.claude/commands/gsd/`（本地）
-- 对 Codex，检查 skills 是否存在于 `~/.codex/skills/gsd-*/SKILL.md`（全局）或 `./.codex/skills/gsd-*/SKILL.md`（本地）
-
-**命令行为不符合预期？**
-- 运行 `/gsd-help` 确认安装成功
-- 重新执行 `npx @opengsd/gsd-core` 进行重装
-
-**想更新到最新版本？**
-```bash
-npx @opengsd/gsd-core@latest
-```
-
-**在 Docker 或容器环境中使用？**
-
-如果使用波浪线路径（`~/.claude/...`）时读取失败，请在安装前设置 `CLAUDE_CONFIG_DIR`：
-```bash
-CLAUDE_CONFIG_DIR=/home/youruser/.claude npx @opengsd/gsd-core --global
-```
-这样可以确保使用绝对路径，而不是在容器里可能无法正确展开的 `~`。
-
-### 卸载
-
-如果你想彻底移除 GSD：
-
-```bash
-# 全局安装
-npx @opengsd/gsd-core --claude --global --uninstall
-npx @opengsd/gsd-core --opencode --global --uninstall
-npx @opengsd/gsd-core --gemini --global --uninstall
-npx @opengsd/gsd-core --kilo --global --uninstall
-npx @opengsd/gsd-core --codex --global --uninstall
-npx @opengsd/gsd-core --copilot --global --uninstall
-npx @opengsd/gsd-core --cursor --global --uninstall
-npx @opengsd/gsd-core --antigravity --global --uninstall
-npx @opengsd/gsd-core --augment --global --uninstall
-npx @opengsd/gsd-core --trae --global --uninstall
-npx @opengsd/gsd-core --cline --global --uninstall
-
-# 本地安装（当前项目）
-npx @opengsd/gsd-core --claude --local --uninstall
-npx @opengsd/gsd-core --opencode --local --uninstall
-npx @opengsd/gsd-core --gemini --local --uninstall
-npx @opengsd/gsd-core --kilo --local --uninstall
-npx @opengsd/gsd-core --codex --local --uninstall
-npx @opengsd/gsd-core --copilot --local --uninstall
-npx @opengsd/gsd-core --cursor --local --uninstall
-npx @opengsd/gsd-core --antigravity --local --uninstall
-npx @opengsd/gsd-core --augment --local --uninstall
-npx @opengsd/gsd-core --trae --local --uninstall
-npx @opengsd/gsd-core --cline --local --uninstall
-```
-
-这会移除所有 GSD 命令、代理、hooks 和设置，但会保留你其他配置。
-
----
-
-## 社区移植版本
-
-OpenCode、Gemini CLI、Kilo 和 Codex 现在都已经通过 `npx @opengsd/gsd-core` 获得原生支持。
-
-这些社区移植版本曾率先探索多运行时支持：
-
-| Project | Platform | Description |
-|---------|----------|-------------|
-| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | OpenCode | 最初的 OpenCode 适配版本 |
-| gsd-gemini (archived) | Gemini CLI | uberfuzzy 制作的最初 Gemini 适配版本 |
+| 项目 | 平台 |
+|---------|----------|
+| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | 原始 OpenCode 移植版 |
+| [Discord](https://discord.gg/mYgfVNfA2r) | 社区支持 |
 
 ---
 
@@ -830,14 +112,14 @@ OpenCode、Gemini CLI、Kilo 和 Codex 现在都已经通过 `npx @opengsd/gsd-c
 
 ---
 
-## License
+## 许可证
 
-MIT License。详情见 [LICENSE](LICENSE)。
+MIT 许可证。详情请参阅 [LICENSE](LICENSE)。
 
 ---
 
 <div align="center">
 
-**Claude Code 很强，GSD 让它变得可靠。**
+**Claude Code 功能强大。GSD Core 让它更可靠。**
 
 </div>

TEST-EXAMPLES.md

@@ -57,7 +57,7 @@ for (const scenario of cases) {
 
     const result = spawnSync(
       process.execPath,
-      [path.join(__dirname, '..', 'get-shit-done', 'bin', 'gsd-tools.cjs'), ...scenario.args, '--json'],
+      [path.join(__dirname, '..', 'gsd-core', 'bin', 'gsd-tools.cjs'), ...scenario.args, '--json'],
       { cwd: projectDir, encoding: 'utf8' },
     );
 

agents/gsd-ai-researcher.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-ai-researcher
 description: Researches a chosen AI framework's official docs to produce implementation-ready guidance — best practices, syntax, core patterns, and pitfalls distilled for the specific use case. Writes the Framework Quick Reference and Implementation Guidance sections of AI-SPEC.md. Spawned by /gsd:ai-integration-phase orchestrator.
-tools: Read, Write, Bash, Grep, Glob, WebFetch, WebSearch, mcp__context7__*
+tools: Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch, mcp__context7__*
 color: "#34D399"
 # hooks:
 #   PostToolUse:
@@ -40,7 +40,7 @@ works via Bash and produces equivalent output.
 </documentation_lookup>
 
 <required_reading>
-Read `~/.claude/get-shit-done/references/ai-frameworks.md` for framework profiles and known pitfalls before fetching docs.
+Read `~/.claude/gsd-core/references/ai-frameworks.md` for framework profiles and known pitfalls before fetching docs.
 </required_reading>
 
 <input>

agents/gsd-debug-session-manager.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-debug-session-manager
 description: Manages multi-cycle /gsd:debug checkpoint and continuation loop in isolated context. Spawns gsd-debugger agents, handles checkpoints via AskUserQuestion, dispatches specialist skills, applies fixes. Returns compact summary to main context. Spawned by /gsd:debug command.
-tools: Read, Write, Bash, Grep, Glob, Agent, AskUserQuestion
+tools: Read, Write, Edit, Bash, Grep, Glob, Agent, AskUserQuestion
 color: orange
 # hooks:
 #   PostToolUse:

agents/gsd-debugger.md

@@ -21,7 +21,7 @@ You are spawned by:
 
 Your job: Find the root cause through hypothesis testing, maintain debug file state, optionally fix and verify (depending on mode).
 
-@~/.claude/get-shit-done/references/mandatory-initial-read.md
+@~/.claude/gsd-core/references/mandatory-initial-read.md
 
 **Core responsibilities:**
 - Investigate autonomously (user reports symptoms, you find cause)
@@ -33,16 +33,16 @@ Your job: Find the root cause through hypothesis testing, maintain debug file st
 </role>
 
 <required_reading>
-@~/.claude/get-shit-done/references/common-bug-patterns.md
+@~/.claude/gsd-core/references/common-bug-patterns.md
 </required_reading>
 
-**Project skills:** @~/.claude/get-shit-done/references/project-skills-discovery.md
+**Project skills:** @~/.claude/gsd-core/references/project-skills-discovery.md
 - Load `rules/*.md` as needed during **investigation and fix**.
 - Follow skill rules relevant to the bug being investigated and the fix being applied.
 
 <philosophy>
 
-@~/.claude/get-shit-done/references/debugger-philosophy.md
+@~/.claude/gsd-core/references/debugger-philosophy.md
 
 </philosophy>
 
@@ -433,8 +433,8 @@ Check code says:  hooksDir = path.join(configDir, 'hooks')
                   → checks ~/.claude/hooks/
 
 Installer says:   hooksDest = path.join(targetDir, 'hooks')
-                  targetDir = ~/.claude/get-shit-done
-                  → writes to ~/.claude/get-shit-done/hooks/
+                  targetDir = ~/.claude/gsd-core
+                  → writes to ~/.claude/gsd-core/hooks/
 
 MISMATCH: Checker looks in wrong directory → hooks "not found" → reported as stale
 ```
@@ -959,7 +959,7 @@ Gather symptoms through questioning. Update file after EACH answer.
 
 <step name="investigation_loop">
 At investigation decision points, apply structured reasoning:
-@~/.claude/get-shit-done/references/thinking-models-debug.md
+@~/.claude/gsd-core/references/thinking-models-debug.md
 
 **Autonomous investigation. Update file continuously.**
 
@@ -982,7 +982,7 @@ At investigation decision points, apply structured reasoning:
 - APPEND to Evidence after each finding
 
 **Phase 1.5: Check common bug patterns**
-- Read @~/.claude/get-shit-done/references/common-bug-patterns.md
+- Read @~/.claude/gsd-core/references/common-bug-patterns.md
 - Match symptoms to pattern categories using the Symptom-to-Category Quick Map
 - Any matching patterns become hypothesis candidates for Phase 2
 - If no patterns match, proceed to open-ended hypothesis formation

agents/gsd-doc-writer.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-doc-writer
 description: Writes and updates project documentation. Spawned with a doc_assignment block specifying doc type, mode (create/update/supplement), and project context.
-tools: Read, Bash, Grep, Glob, Write
+tools: Read, Bash, Grep, Glob, Write, Edit
 color: purple
 # hooks:
 #   PostToolUse:
@@ -93,12 +93,12 @@ Correct specific failing claims identified by the gsd-doc-verifier. ONLY modify
 1. Parse the `<doc_assignment>` block -- mode will be `fix`, and the block includes `doc_path`, `existing_content`, and `failures` array.
 2. Each failure has: `line` (line number in the doc), `claim` (the incorrect claim text), `expected` (what verification expected), `actual` (what verification found).
 3. For each failure:
-   a. Locate the line in existing_content.
+   a. Locate the exact text of the incorrect claim in `existing_content`.
    b. Explore the codebase using Read, Grep, Glob to find the correct value.
-   c. Replace ONLY the incorrect claim with the verified-correct value.
-   d. If the correct value cannot be determined, replace the claim with a `<!-- VERIFY: {claim} -->` marker.
-4. Write the corrected file using the Write tool.
-5. Ensure the GSD marker `<!-- generated-by: gsd-doc-writer -->` remains on the first line.
+   c. Use the **Edit** tool to replace ONLY the incorrect claim text with the verified-correct value. Pass the smallest possible `old_string` that uniquely identifies the incorrect text.
+   d. If the correct value cannot be determined, use Edit to replace the claim with a `<!-- VERIFY: {claim} -->` marker.
+4. **NEVER use the Write tool on an existing file in fix mode.** Write replaces the entire file with whatever you provide — any content not in your context window is permanently destroyed. There is no recovery if the file is untracked. Edit makes targeted replacements and is the only safe tool for fix mode.
+5. After all Edit calls, verify the GSD marker `<!-- generated-by: gsd-doc-writer -->` is still present on the first line. If it was removed by an Edit, use Edit to restore it.
 
 Fix mode must correct ONLY the lines listed in the failures array. Do not modify, reorder, rephrase, or "improve" any other content in the file. The goal is surgical precision -- change the minimum number of characters to fix each failing claim.
 </fix_mode>
@@ -597,6 +597,7 @@ change — only location and metadata change.
 3. Include the GSD marker `<!-- generated-by: gsd-doc-writer -->` as the first line of every generated doc file (except supplement mode — see rule 7).
 4. Explore the actual codebase before writing — never fabricate file paths, function names, endpoints, or configuration values.
 8. Use the Write tool to create files — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
+9. In fix mode, ALWAYS use the Edit tool for corrections — NEVER call Write on an existing file in fix mode. Write replaces the entire file; any lines not present in your context window are permanently destroyed and unrecoverable if the file is untracked.
 5. Use `<!-- VERIFY: {claim} -->` markers for any infrastructure claim (URLs, server configs, external service details) that cannot be verified from the repository contents alone.
 6. In update mode, PRESERVE user-authored content in sections that are still accurate. Only rewrite inaccurate or missing sections.
 7. In supplement mode, NEVER modify existing content. Only append missing sections. Do NOT add the GSD marker to hand-written files.

agents/gsd-domain-researcher.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-domain-researcher
 description: Researches the business domain and real-world application context of the AI system being built. Surfaces domain expert evaluation criteria, industry-specific failure modes, regulatory context, and what "good" looks like for practitioners in this field — before the eval-planner turns it into measurable rubrics. Spawned by /gsd:ai-integration-phase orchestrator.
-tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
+tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
 color: "#A78BFA"
 # hooks:
 #   PostToolUse:
@@ -40,7 +40,7 @@ works via Bash and produces equivalent output.
 </documentation_lookup>
 
 <required_reading>
-Read `~/.claude/get-shit-done/references/ai-evals.md` — specifically the rubric design and domain expert sections.
+Read `~/.claude/gsd-core/references/ai-evals.md` — specifically the rubric design and domain expert sections.
 </required_reading>
 
 <input>
@@ -98,6 +98,19 @@ If internal tooling with no regulated domain, "domain expert" = product owner or
 <step name="write_section_1b">
 **ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
 
+**Write contract (hard rules — must follow):**
+
+Section 1b of AI-SPEC.md is the output of this step. The orchestrator reads `AI-SPEC.md` from disk after you return; it does NOT read your return message for the file content.
+
+1. **Default: write the section in a single `Write` call.** On most runtimes this is correct and reliable — do this unless rule 4 applies.
+2. **Do NOT return the AI-SPEC.md content in your response.** Your return message is a brief confirmation; the content lives on disk.
+3. **Do NOT use `Bash(cat << 'EOF')` or heredoc** for file creation. Use the `Write` tool.
+4. **Large-file / truncation fallback.** Some runtimes (e.g. OpenCode) cap tool-call output, and a single oversized `Write` is truncated mid-payload — surfacing a tool error such as `JSON Parse error: Expected '}'`. If a `Write` fails with a truncation / invalid-tool error, **do NOT retry the same oversized call** (that loops forever). Instead build the file incrementally so no single tool call carries the whole payload:
+   - `Write` the file with only the first section, ending with the sentinel line `<!-- gsd:write-continue -->`.
+   - `Read` the file, then `Edit` it, replacing `<!-- gsd:write-continue -->` with the next section followed by the sentinel again. Repeat, one section per `Edit`.
+   - On the final section, replace the sentinel with the closing content and no trailing sentinel.
+5. **If writing still fails, surface the actual error in your return message.** **Do NOT silently fall back to returning content** — that hides the failure from the orchestrator and truncates identically.
+
 Update AI-SPEC.md at `ai_spec_path`. Add/update Section 1b:
 
 ```markdown

agents/gsd-eval-auditor.md

@@ -33,7 +33,7 @@ Every planned eval dimension must resolve to COVERED, PARTIAL (WARNING), or MISS
 </adversarial_stance>
 
 <required_reading>
-Read `~/.claude/get-shit-done/references/ai-evals.md` before auditing. This is your scoring framework.
+Read `~/.claude/gsd-core/references/ai-evals.md` before auditing. This is your scoring framework.
 </required_reading>
 
 **Context budget:** Load project skills first (lightweight). Read implementation files incrementally — load only what each check requires, not the full codebase upfront.

agents/gsd-eval-planner.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-eval-planner
 description: Designs a structured evaluation strategy for an AI phase. Identifies critical failure modes, selects eval dimensions with rubrics, recommends tooling, and specifies the reference dataset. Writes the Evaluation Strategy, Guardrails, and Production Monitoring sections of AI-SPEC.md. Spawned by /gsd:ai-integration-phase orchestrator.
-tools: Read, Write, Bash, Grep, Glob, AskUserQuestion
+tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion
 color: "#F59E0B"
 # hooks:
 #   PostToolUse:
@@ -17,7 +17,7 @@ Turn domain rubric ingredients into measurable, tooled evaluation criteria. Writ
 </role>
 
 <required_reading>
-Read `~/.claude/get-shit-done/references/ai-evals.md` before planning. This is your evaluation framework.
+Read `~/.claude/gsd-core/references/ai-evals.md` before planning. This is your evaluation framework.
 </required_reading>
 
 <input>

agents/gsd-executor.md

@@ -18,7 +18,7 @@ Spawned by `/gsd:execute-phase` orchestrator.
 
 Your job: Execute the plan completely, commit each task, create SUMMARY.md, update STATE.md.
 
-@~/.claude/get-shit-done/references/mandatory-initial-read.md
+@~/.claude/gsd-core/references/mandatory-initial-read.md
 </role>
 
 <documentation_lookup>
@@ -60,7 +60,7 @@ Before executing, discover project context:
 
 **Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
 
-**Project skills:** @~/.claude/get-shit-done/references/project-skills-discovery.md
+**Project skills:** @~/.claude/gsd-core/references/project-skills-discovery.md
 - Load `rules/*.md` as needed during **implementation**.
 - Follow skill rules relevant to the task you are about to commit.
 
@@ -116,10 +116,10 @@ grep -n "type=\"checkpoint" [plan-path]
 
 <step name="execute_tasks">
 At execution decision points, apply structured reasoning:
-@~/.claude/get-shit-done/references/thinking-models-execution.md
+@~/.claude/gsd-core/references/thinking-models-execution.md
 
 **iOS app scaffolding:** If this plan creates an iOS app target, follow ios-scaffold guidance:
-@~/.claude/get-shit-done/references/ios-scaffold.md
+@~/.claude/gsd-core/references/ios-scaffold.md
 
 For each task:
 
@@ -239,7 +239,7 @@ Track auto-fix attempts per task. After 3 auto-fix attempts on a single task:
 
 **Extended examples and edge case guide:**
 For detailed deviation rule examples, checkpoint examples, and edge case decision guidance:
-@~/.claude/get-shit-done/references/executor-examples.md
+@~/.claude/gsd-core/references/executor-examples.md
 </deviation_rules>
 
 <analysis_paralysis_guard>
@@ -285,7 +285,7 @@ Auto mode is active if either `AUTO_CHAIN` or `AUTO_CFG` is `"true"`. Store the
 Before any `checkpoint:human-verify`, ensure verification environment is ready. If plan lacks server startup before checkpoint, ADD ONE (deviation Rule 3).
 
 For full automation-first patterns, server lifecycle, CLI handling:
-**See @~/.claude/get-shit-done/references/checkpoints.md**
+**See @~/.claude/gsd-core/references/checkpoints.md**
 
 **Quick reference:** Users NEVER run CLI commands. Users ONLY visit URLs, click UI, evaluate visuals, provide secrets. Claude does all automation.
 
@@ -385,7 +385,7 @@ If RED or GREEN gate commits are missing, add a warning to SUMMARY.md under a `#
 
 ## MVP+TDD Gate
 
-**When the orchestrator passes both `MVP_MODE=true` and `TDD_MODE=true`:** Before running the implementation step of any task with `tdd="true"`, run the runtime gate from `@~/.claude/get-shit-done/references/execute-mvp-tdd.md`. If the gate trips, halt and report — do NOT proceed to the implementation step.
+**When the orchestrator passes both `MVP_MODE=true` and `TDD_MODE=true`:** Before running the implementation step of any task with `tdd="true"`, run the runtime gate from `@~/.claude/gsd-core/references/execute-mvp-tdd.md`. If the gate trips, halt and report — do NOT proceed to the implementation step.
 
 **Halt-and-report protocol:**
 
@@ -589,7 +589,20 @@ After all tasks complete, create `{phase}-{plan}-SUMMARY.md` at `.planning/phase
 
 Use the Write tool to create files — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
 
-**Use template:** @~/.claude/get-shit-done/templates/summary.md
+**Write contract (hard rules — must follow):**
+
+This file is the canonical output of this step. The orchestrator reads `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md` from disk after you return; it does NOT read your return message for the file content.
+
+1. **Default: write the whole file in a single `Write` call.** On most runtimes this is correct and reliable — do this unless rule 4 applies.
+2. **Do NOT return the SUMMARY.md content in your response.** Your return message is a brief confirmation; the content lives on disk.
+3. **Do NOT use `Bash(cat << 'EOF')` or heredoc** for file creation. Use the `Write` tool.
+4. **Large-file / truncation fallback.** Some runtimes (e.g. OpenCode) cap tool-call output, and a single oversized `Write` is truncated mid-payload — surfacing a tool error such as `JSON Parse error: Expected '}'`. If a `Write` fails with a truncation / invalid-tool error, **do NOT retry the same oversized call** (that loops forever). Instead build the file incrementally so no single tool call carries the whole payload:
+   - `Write` the file with only the first section, ending with the sentinel line `<!-- gsd:write-continue -->`.
+   - `Read` the file, then `Edit` it, replacing `<!-- gsd:write-continue -->` with the next section followed by the sentinel again. Repeat, one section per `Edit`.
+   - On the final section, replace the sentinel with the closing content and no trailing sentinel.
+5. **If writing still fails, surface the actual error in your return message.** **Do NOT silently fall back to returning content** — that hides the failure from the orchestrator and truncates identically.
+
+**Use template:** @~/.claude/gsd-core/templates/summary.md
 
 **Frontmatter:** phase, plan, subsystem, tags, dependency graph (requires/provides/affects), tech-stack (added/patterns), key-files (created/modified), decisions, metrics (duration, completed date).
 

agents/gsd-framework-selector.md

@@ -11,7 +11,7 @@ Run a ≤6-question interview, score frameworks, return a ranked recommendation
 </role>
 
 <required_reading>
-Read `~/.claude/get-shit-done/references/ai-frameworks.md` before asking questions. This is your decision matrix.
+Read `~/.claude/gsd-core/references/ai-frameworks.md` before asking questions. This is your decision matrix.
 </required_reading>
 
 <project_context>

agents/gsd-intel-updater.md

@@ -64,7 +64,7 @@ The /gsd:map-codebase --query command has already confirmed that intel.enabled i
 ```bash
 # Only run layout detection when analysing the GSD framework repo itself.
 if [[ "$(jq -r '.name // ""' package.json 2>/dev/null)" == "@opengsd/gsd-core" ]]; then
-  ls -d .kilo 2>/dev/null && echo "kilo" || (ls -d .claude/get-shit-done 2>/dev/null && echo "claude") || echo "unknown"
+  ls -d .kilo 2>/dev/null && echo "kilo" || (ls -d .claude/gsd-core 2>/dev/null && echo "claude") || echo "unknown"
 fi
 ```
 
@@ -76,9 +76,9 @@ Use the detected root (when applicable) to resolve all canonical paths below:
 |-------------|--------------------------|----------------|
 | Agent files | `agents/*.md` | `.kilo/agents/*.md` |
 | Command files | `commands/gsd/*.md` | `.kilo/command/*.md` |
-| CLI tooling | `get-shit-done/bin/` | `.kilo/get-shit-done/bin/` |
-| Workflow files | `get-shit-done/workflows/` | `.kilo/get-shit-done/workflows/` |
-| Reference docs | `get-shit-done/references/` | `.kilo/get-shit-done/references/` |
+| CLI tooling | `gsd-core/bin/` | `.kilo/gsd-core/bin/` |
+| Workflow files | `gsd-core/workflows/` | `.kilo/gsd-core/workflows/` |
+| Reference docs | `gsd-core/references/` | `.kilo/gsd-core/references/` |
 | Hook files | `hooks/*.js` | `.kilo/hooks/*.js` |
 
 When analyzing this project, use ONLY the canonical source locations matching the detected layout. Do not fall back to the standard layout paths if the `.kilo` root is detected — those paths will be empty and produce semantically empty intel.

agents/gsd-phase-researcher.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-phase-researcher
 description: Researches how to implement a phase before planning. Produces RESEARCH.md consumed by gsd-planner. Spawned by /gsd:plan-phase orchestrator.
-tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*
+tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*
 color: cyan
 # hooks:
 #   PostToolUse:
@@ -16,7 +16,7 @@ You are a GSD phase researcher. You answer "What do I need to know to PLAN this
 
 Spawned by `/gsd:plan-phase` (integrated) or `/gsd:plan-phase --research-phase <N>` (standalone).
 
-@~/.claude/get-shit-done/references/mandatory-initial-read.md
+@~/.claude/gsd-core/references/mandatory-initial-read.md
 
 **Core responsibilities:**
 - Investigate the phase's technical domain
@@ -72,7 +72,7 @@ Before researching, discover project context:
 
 **Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
 
-**Project skills:** @~/.claude/get-shit-done/references/project-skills-discovery.md
+**Project skills:** @~/.claude/gsd-core/references/project-skills-discovery.md
 - Load `rules/*.md` as needed during **research**.
 - Research output should account for project skill patterns and conventions.
 
@@ -586,7 +586,7 @@ Verified patterns from official sources:
 <execution_flow>
 
 At research decision points, apply structured reasoning:
-@~/.claude/get-shit-done/references/thinking-models-research.md
+@~/.claude/gsd-core/references/thinking-models-research.md
 
 ## Step 1: Receive Scope and Load Context
 
@@ -632,7 +632,7 @@ ls .planning/graphs/graph.json 2>/dev/null
 If graph.json exists, check freshness:
 
 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify status
+node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" graphify status
 ```
 
 If the status response has `stale: true`, note for later: "Graph is {age_hours}h old -- treat semantic relationships as approximate." Include this annotation inline with any graph context injected below.
@@ -640,7 +640,7 @@ If the status response has `stale: true`, note for later: "Graph is {age_hours}h
 Query the graph for each major capability in the phase scope (2-3 queries per D-05, discovery-focused):
 
 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify query "<capability-keyword>" --budget 1500
+node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" graphify query "<capability-keyword>" --budget 1500
 ```
 
 Derive query terms from the phase goal and requirement descriptions. Examples:
@@ -804,6 +804,19 @@ List missing test files, framework config, or shared fixtures needed before impl
 
 Use the Write tool to create files — never use `Bash(cat << 'EOF')` or heredoc commands for file creation. This rule applies regardless of `commit_docs` setting.
 
+**Write contract (hard rules — must follow):**
+
+This file is the canonical output of this agent. The orchestrator reads `$PHASE_DIR/$PADDED_PHASE-RESEARCH.md` from disk after you return; it does NOT read your return message for the file content.
+
+1. **Default: write the whole file in a single `Write` call.** On most runtimes this is correct and reliable — do this unless rule 4 applies.
+2. **Do NOT return the RESEARCH.md content in your response.** Your return message is a brief confirmation (see `<structured_returns>`); the content lives on disk.
+3. **Do NOT use `Bash(cat << 'EOF')` or heredoc** for file creation. Use the `Write` tool.
+4. **Large-file / truncation fallback.** Some runtimes (e.g. OpenCode) cap tool-call output, and a single oversized `Write` is truncated mid-payload — surfacing a tool error such as `JSON Parse error: Expected '}'`. If a `Write` fails with a truncation / invalid-tool error, **do NOT retry the same oversized call** (that loops forever). Instead build the file incrementally so no single tool call carries the whole payload:
+   - `Write` the file with only the first section, ending with the sentinel line `<!-- gsd:write-continue -->`.
+   - `Read` the file, then `Edit` it, replacing `<!-- gsd:write-continue -->` with the next section followed by the sentinel again. Repeat, one section per `Edit`.
+   - On the final section, replace the sentinel with the closing content and no trailing sentinel.
+5. **If writing still fails, surface the actual error in your return message.** **Do NOT silently fall back to returning content** — that hides the failure from the orchestrator and truncates identically.
+
 **If CONTEXT.md exists, FIRST content section MUST be `<user_constraints>`:**
 
 ```markdown

agents/gsd-plan-checker.md

@@ -43,7 +43,7 @@ Issues without a severity classification are not valid output.
 </adversarial_stance>
 
 <required_reading>
-@~/.claude/get-shit-done/references/gates.md
+@~/.claude/gsd-core/references/gates.md
 </required_reading>
 
 This agent implements the **Revision Gate** pattern (bounded quality loop with escalation on cap exhaustion).
@@ -103,10 +103,10 @@ Same methodology (goal-backward), different timing, different subject matter.
 <verification_dimensions>
 
 At decision points during plan verification, apply structured reasoning:
-@~/.claude/get-shit-done/references/thinking-models-planning.md
+@~/.claude/gsd-core/references/thinking-models-planning.md
 
 For calibration on scoring and issue identification, reference these examples:
-@~/.claude/get-shit-done/references/few-shot-examples/plan-checker.md
+@~/.claude/gsd-core/references/few-shot-examples/plan-checker.md
 
 ## Dimension 1: Requirement Coverage