diff --git a/CHANGELOG.md b/CHANGELOG.md index 025013e41..7dca5467c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,9 @@ All notable changes to GSD will be documented in this file. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). -## [Unreleased](https://github.com/gsd-build/get-shit-done/compare/v1.41.0...HEAD) +## [Unreleased](https://github.com/gsd-build/get-shit-done/compare/v1.42.1...HEAD) + +## [1.42.1](https://github.com/gsd-build/get-shit-done/compare/v1.41.0...v1.42.1) - 2026-05-15 ### Fixed @@ -2746,7 +2748,8 @@ Technical implementation details for Phase 2 appear in the **Changed** section b - YOLO mode for autonomous execution - Interactive mode with checkpoints -[Unreleased]: https://github.com/gsd-build/get-shit-done/compare/v1.38.4...HEAD +[Unreleased]: https://github.com/gsd-build/get-shit-done/compare/v1.42.1...HEAD +[1.42.1]: https://github.com/gsd-build/get-shit-done/compare/v1.41.0...v1.42.1 [1.38.4]: https://github.com/gsd-build/get-shit-done/compare/v1.38.2...v1.38.4 [1.38.2]: https://github.com/gsd-build/get-shit-done/compare/v1.37.1...v1.38.2 [1.37.1]: https://github.com/gsd-build/get-shit-done/compare/v1.37.0...v1.37.1 diff --git a/README.md b/README.md index 8c0a9850a..4275b2a0c 100644 --- a/README.md +++ b/README.md @@ -144,6 +144,8 @@ GSD is built for frictionless automation. Skip-permissions is how it's intended 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. +Current release highlights are in [docs/RELEASE-v1.42.1.md](docs/RELEASE-v1.42.1.md): package legitimacy checks, safer installer migrations, runtime surface control, custom ship PR sections, reviewer defaults, fallow structural review, and quota-aware execution recovery. + --- ## Commands @@ -196,6 +198,8 @@ Key dials: Optional structural review: set `code_quality.fallow.enabled` to `true` to add a fallow pre-pass to `/gsd-code-review`. GSD writes `.planning/phases//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)**. --- diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index bace7b30b..78d50b1ff 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -679,7 +679,7 @@ Debounce: 5 tool uses between repeated warnings. Severity escalation (WARNING→ - Missing bridge files handled gracefully (subagents, fresh sessions) - Context monitor is advisory — never issues imperative commands that override user preferences -### Package Legitimacy Gate (v1.51) +### Package Legitimacy Gate (v1.42.1) The researcher → planner → executor pipeline includes a supply-chain gate against slopsquatting (AI-hallucinated package names pre-registered with malicious post-install scripts). diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index d81ade661..434e362ab 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -164,7 +164,7 @@ Research, plan, and verify a phase. - With `--research`: force-refresh — re-spawn researcher unconditionally, no prompt. - With `--view`: print existing RESEARCH.md to stdout, no spawn. Errors if RESEARCH.md missing. -**Package Legitimacy Gate (v1.51):** +**Package Legitimacy Gate (v1.42.1):** When the researcher recommends external packages, it runs `slopcheck install --json` on each one and writes a `## Package Legitimacy Audit` table to RESEARCH.md recording Registry, Age, Downloads, Source Repo, and slopcheck verdict. Verdicts: - `[SLOP]` — package removed from RESEARCH.md entirely; never reaches the planner @@ -173,7 +173,7 @@ When the researcher recommends external packages, it runs `slopcheck install ` and persist the active profile in `.gsd-profile`. +- REQ-SURFACE-02: `--minimal` and `--core-only` MUST remain aliases for `--profile=core`. +- REQ-SURFACE-03: Runtime surface state MUST persist outside the install profile marker. + +**Reference:** [ADR-0011](adr/0011-skill-surface-budget-module.md) + +--- + +### 134. Installer Migrations + +**Purpose:** Make runtime config cleanup explicit, auditable, and rollback-aware during installs and updates. + +**Capabilities:** +- First-time baseline migration records managed files. +- Legacy stale-file cleanup uses ownership evidence before deleting or rewriting. +- User-owned artifacts are preserved. +- Ambiguous GSD-looking files block with a clear report instead of being silently overwritten. +- Migration plans support dry-run reporting and rollback protection. + +**Requirements:** +- REQ-INSTALL-MIGRATION-01: Migration records MUST include metadata, install scope, and ownership evidence. +- REQ-INSTALL-MIGRATION-02: Destructive actions MUST fail closed when ownership is ambiguous. +- REQ-INSTALL-MIGRATION-03: Install failures MUST restore the pre-install state when rollback data exists. + +**Reference:** [Installer Migrations](installer-migrations.md) + +--- + +### 135. Custom Ship PR Body Sections + +**Command:** `/gsd-ship` + +**Config key:** `ship.pr_body_sections` + +**Purpose:** Add project-specific PRD-style sections to generated PR bodies without editing GSD workflow files. + +**Behavior:** Configured sections append after the required `Summary`, `Changes`, `Requirements Addressed`, `Verification`, and `Key Decisions` sections. They can copy from artifact headings, render templates, or fall back to static text. + +**Requirements:** +- REQ-SHIP-SECTIONS-01: Custom sections MUST NOT replace, remove, or reorder required PR sections. +- REQ-SHIP-SECTIONS-02: Unknown template tokens MUST be rejected by config validation. +- REQ-SHIP-SECTIONS-03: Disabled sections MUST stay in config without appearing in PR output. + +**Reference:** [Custom PR Body Sections](ship-pr-body-sections.md) + +--- + +### 136. Review Default Reviewers + +**Command:** `/gsd-review` + +**Config key:** `review.default_reviewers` + +**Purpose:** Let teams choose the default reviewer subset for no-flag `/gsd-review` runs. + +**Precedence:** +```text +explicit reviewer flags -> --all -> review.default_reviewers -> all detected reviewers +``` + +**Requirements:** +- REQ-REVIEW-DEFAULTS-01: Missing `review.default_reviewers` MUST preserve the previous all-detected behavior. +- REQ-REVIEW-DEFAULTS-02: Empty arrays MUST be rejected; remove the key to restore all-detected behavior. +- REQ-REVIEW-DEFAULTS-03: Known but unavailable reviewers MUST be skipped with diagnostics rather than hard-failing the run. + +**Reference:** [Configuration Reference](CONFIGURATION.md#reviewer-defaults-for-gsd-review) + +--- + +### 137. Fallow Structural Review Pre-Pass + +**Command:** `/gsd-code-review` + +**Config keys:** `code_quality.fallow.*` + +**Purpose:** Add an optional structural analysis pass before the agent review. + +**Behavior:** When enabled, GSD resolves a `fallow` binary, runs a bounded audit, writes `FALLOW.json`, and embeds structural findings in `REVIEW.md`. + +**Requirements:** +- REQ-FALLOW-01: Fallow MUST be opt-in and disabled by default. +- REQ-FALLOW-02: Missing or failing fallow runs MUST produce clear diagnostics. +- REQ-FALLOW-03: Findings larger than the embed budget MUST be skipped with a warning, preserving the raw JSON artifact. + +**Reference:** [Configuration Reference](CONFIGURATION.md#code-quality-settings) + +--- + +### 138. End-of-Phase Human Verification Mode + +**Config key:** `workflow.human_verify_mode` + +**Purpose:** Reduce mid-flight human checkpoint interruptions while preserving human verification requirements. + +**Behavior:** The default `"end-of-phase"` mode embeds human checks into `` blocks for phase review. `"mid-flight"` restores blocking `checkpoint:human-verify` tasks. + +**Requirements:** +- REQ-HUMAN-VERIFY-01: `checkpoint:decision` and `checkpoint:human-action` MUST remain blocking regardless of mode. +- REQ-HUMAN-VERIFY-02: Human-needed verification MUST remain pending until the end-of-phase review resolves it. +- REQ-HUMAN-VERIFY-03: Configs without the key MUST use `"end-of-phase"`. + +**Reference:** [Checkpoints Reference](../get-shit-done/references/checkpoints.md) + +--- + +### 139. Quota and Rate-Limit Failure Classification + +**Command:** `/gsd-execute-phase` + +**Purpose:** Treat provider quota and rate-limit failures as wait-and-resume conditions, not normal executor failures. + +**Behavior:** Agent output is classified for signals such as `429`, `rate limit`, `usage limit`, `RESOURCE_EXHAUSTED`, and `usage_limit_reached`. Matching failures present a wait-for-reset recovery path. + +**Requirements:** +- REQ-QUOTA-01: Quota failures MUST NOT offer immediate retry as the primary recovery. +- REQ-QUOTA-02: Classification MUST cover Claude, Copilot, Codex, Gemini, and generic provider sentinels. +- REQ-QUOTA-03: Non-quota failures MUST continue through the normal execution failure path. + +**Reference:** [Provider Rate Limit Signals](research/provider-rate-limit-signals.md) + +--- + +### 140. Statusline Context Position + +**Config key:** `statusline.context_position` + +**Purpose:** Keep the context meter visible in narrow terminals. + +**Options:** +| Value | Behavior | +|-------|----------| +| `"end"` | Default; render context meter near the line tail | +| `"front"` | Render context meter immediately after the model name | + +**Requirements:** +- REQ-STATUSLINE-POS-01: Invalid values MUST be rejected by config validation. +- REQ-STATUSLINE-POS-02: Missing config MUST preserve existing end-position rendering. + +**Reference:** [Configuration Reference](CONFIGURATION.md#statusline-settings) + +--- + +### 141. Milestone Tag Creation Toggle + +**Command:** `/gsd-complete-milestone` + +**Config key:** `git.create_tag` + +**Purpose:** Let projects with external release automation complete milestones without creating local git tags. + +**Behavior:** `git.create_tag: false` skips milestone tag creation. The workflow still updates milestone artifacts and state. + +**Requirements:** +- REQ-MILESTONE-TAG-01: Missing config MUST preserve automatic tag creation. +- REQ-MILESTONE-TAG-02: Existing tag collisions MUST fail clearly instead of overwriting tags. +- REQ-MILESTONE-TAG-03: Disabling tag creation MUST NOT skip milestone archival. + +**Reference:** [Configuration Reference](CONFIGURATION.md#git-branching) + +--- + +### 142. Structured JSON Error Mode + +**CLI:** `gsd-tools --json-errors` + +**Purpose:** Give SDK and automation callers stable machine-readable error envelopes. + +**Behavior:** Commands that fail under `--json-errors` return structured `ok: false` payloads with error kind, message, command context, and exit mapping instead of prose-only stderr. + +**Requirements:** +- REQ-JSON-ERRORS-01: Unknown commands, validation errors, timeouts, native failures, fallback failures, and internal errors MUST map to canonical error kinds. +- REQ-JSON-ERRORS-02: CLI exit code mapping MUST remain stable for automation callers. +- REQ-JSON-ERRORS-03: Human-readable output MUST remain the default when `--json-errors` is absent. + +**Reference:** [JSON Error Mode](json-errors.md) diff --git a/docs/README.md b/docs/README.md index ad6f86ad0..63920ce96 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,10 +11,12 @@ Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md) | [Architecture](ARCHITECTURE.md) | Contributors, advanced users | System architecture, agent model, data flow, and internal design | | [Installer Migrations](installer-migrations.md) | Contributors | Architecture for safe install-time migrations, cleanup, preservation, dry-run planning, and rollback | | [Feature Reference](FEATURES.md) | All users | Feature narratives and requirements for released features (see [CHANGELOG](../CHANGELOG.md) for latest additions) | +| [v1.42.1 Release Notes](RELEASE-v1.42.1.md) | All users | Stable release notes for the 1.42.1 release | | [Command Reference](COMMANDS.md) | All users | Stable commands with syntax, flags, options, and examples | | [Configuration Reference](CONFIGURATION.md) | All users | Full config schema, workflow toggles, model profiles, git branching | | [Custom PR Body Sections](ship-pr-body-sections.md) | All users | How to append project-specific PRD sections to `/gsd-ship` PR bodies | | [CLI Tools Reference](CLI-TOOLS.md) | Contributors, agent authors | `gsd-tools.cjs` programmatic API for workflows and agents | +| [JSON Error Mode](json-errors.md) | Contributors, agent authors | Machine-readable `gsd-tools --json-errors` failure envelopes | | [Agent Reference](AGENTS.md) | Contributors, advanced users | Role cards for primary agents — roles, tools, spawn patterns (the `agents/` filesystem is authoritative) | | [User Guide](USER-GUIDE.md) | All users | Workflow walkthroughs, troubleshooting, and recovery | | [Issue-Driven Orchestration](issue-driven-orchestration.md) | All users | Recipe for driving GSD from a tracker issue (GitHub / Linear / Jira) using existing primitives — no new commands or daemon | @@ -24,7 +26,7 @@ Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md) ## Quick Links -- **What's new:** see [CHANGELOG](../CHANGELOG.md) for current release notes, and upstream [README](../README.md) for release highlights +- **What's new:** see [v1.42.1 Release Notes](RELEASE-v1.42.1.md), [CHANGELOG](../CHANGELOG.md), and upstream [README](../README.md) for release highlights - **Canary preview:** [`docs/CANARY.md`](CANARY.md) — opt into the early-preview stream from `dev`. Active cut: [`v1.50.0-canary.1`](RELEASE-v1.50.0-canary.1.md) - **Getting started:** [README](../README.md) → install → `/gsd-new-project` - **Full workflow walkthrough:** [User Guide](USER-GUIDE.md) diff --git a/docs/RELEASE-v1.42.1.md b/docs/RELEASE-v1.42.1.md new file mode 100644 index 000000000..f6ad86209 --- /dev/null +++ b/docs/RELEASE-v1.42.1.md @@ -0,0 +1,58 @@ +# v1.42.1 Release Notes + +Stable release. Published to npm under the `latest` tag. + +```bash +npx get-shit-done-cc@latest +``` + +--- + +## What's in this release + +1.42.1 is a safety, documentation, and control-surface release. The headline additions are the package legitimacy gate, skill-surface budgeting, installer migrations, configurable ship PR sections, reviewer defaults, and optional fallow structural review. It also includes execution and state hardening across quota handling, milestone tags, `project_code` phase directories, phase completion, nested git detection, Codex install migration, and SDK readiness. + +## Added + +- **Package legitimacy gate against slopsquatting** — researchers audit external packages with `slopcheck`, planners add human verification for unverified packages, and executors stop on package install failures instead of trying similarly named alternatives. +- **Skill surface budgeting** — install with `--profile=core`, `--profile=standard`, or the default `full`; profiles persist in `.gsd-profile`. Use `/gsd:surface` to list, enable, disable, or switch skill clusters without reinstalling. +- **Installer migrations** — install now has an explicit migration framework for baseline scanning, legacy cleanup, user-owned file preservation, rollback, and ambiguous stale-file guardrails. +- **Configurable `/gsd-ship` PR body sections** — `ship.pr_body_sections` appends project-specific PRD-style sections while preserving required review sections. +- **`review.default_reviewers`** — no-flag `/gsd-review` can default to a configured reviewer subset; explicit flags and `--all` still take precedence. +- **Optional fallow structural review** — `code_quality.fallow.*` runs a structural pre-pass for `/gsd-code-review`, writes `FALLOW.json`, and embeds findings in `REVIEW.md`. +- **Statusline context meter placement** — `statusline.context_position: "front"` keeps the context meter visible on narrow terminals. +- **Structured CLI errors** — `--json-errors` returns machine-readable error envelopes for `gsd-tools` callers. + +## Changed + +- **Human verification defaults to end-of-phase** — `workflow.human_verify_mode: "end-of-phase"` keeps human checks in verification blocks instead of scattering mid-flight checkpoint tasks. Set `"mid-flight"` to restore the older behavior. +- **Quota and rate-limit failures get a distinct recovery path** — execute-phase classifies provider quota failures and guides wait-and-resume rather than retry-now. +- **Milestone tags can be disabled** — `git.create_tag: false` prevents automatic tags for projects with their own release process. +- **Reasoning effort is transported with resolved model IDs** — runtime-aware model resolution now carries `reasoning_effort` where supported, including Codex config output and SDK query paths. +- **Shell command projection and SDK architecture seams were deepened** — hook commands, path actions, subprocess execution, platform file I/O, and SDK compatibility policy now flow through narrower typed modules. + +## Fixed + +- `project_code` phase directory prefixes now apply consistently across discuss, plan, import, gap-planning, and backlog creation paths. +- Phase completion is idempotent and refreshes stale `STATE.md` progress and focus fields. +- `/gsd-new-project` and ingest flows detect nested git worktrees and avoid creating nested `.git` directories. +- Codex install migration preserves user hooks, removes duplicate legacy hook entries, and emits correct event-name keys. +- SDK install readiness now requires durable shims before printing "GSD SDK ready", including Windows PATH repair. +- User custom skills are detected during update preservation scans. +- Decimal-phase short-form `depends_on` references resolve correctly. +- `gsd-sdk query commit --files --respect-staged` preserves interactive staging. + +## Installing + +```bash +# npm (global) +npm install -g get-shit-done-cc@latest + +# npx (one-shot) +npx get-shit-done-cc@latest + +# Pin to this exact version +npm install -g get-shit-done-cc@1.42.1 +``` + +The installer is idempotent. Re-running it updates in place while preserving `.planning/` and local patches. diff --git a/docs/USER-GUIDE.md b/docs/USER-GUIDE.md index 82a21c658..7d1fa0f1d 100644 --- a/docs/USER-GUIDE.md +++ b/docs/USER-GUIDE.md @@ -725,11 +725,11 @@ The `security.cjs` module scans for known injection patterns (role overrides, in --- -### Package Legitimacy Gate (v1.51) +### Package Legitimacy Gate (v1.42.1) AI coding tools hallucinate package names. Attackers pre-register those names on npm, PyPI, and crates.io with malicious post-install scripts — a technique called *slopsquatting*. A hallucinated name that passes `npm view` looks legitimate, so it would flow undetected through GSD's research → plan → execute pipeline all the way to `npm install ` running on your machine. -v1.51 adds a three-layer gate that stops this before it reaches your shell. +v1.42.1 adds a three-layer gate that stops this before it reaches your shell. #### What you'll see @@ -802,7 +802,7 @@ pip install slopcheck `slopcheck` is a MIT-licensed Python tool maintained by ToxSec (the researcher who documented the slopsquatting attack surface). It checks packages across npm, PyPI, crates.io, RubyGems, Go modules, Maven, and Packagist using multi-signal heuristics: registry age, download count, source-repo linkage, naming distance to popular packages, and registry-specific suspicion patterns. -If `slopcheck` is ever unavailable or abandoned, GSD's `[ASSUMED]`-gate fallback ensures you always get a human checkpoint before any install — the system never silently degrades to the pre-v1.51 behavior. +If `slopcheck` is ever unavailable or abandoned, GSD's `[ASSUMED]`-gate fallback ensures you always get a human checkpoint before any install — the system never silently degrades to the pre-v1.42.1 behavior. ---