a3ca6ff6d6
Phase 4 of the CJS↔SDK hard-seam migration (parent #3524). Eliminates the `findProjectRoot` duplication that lived at bin/lib/core.cjs:74-140 and sdk/src/query/helpers.ts:497-590, the drift carrier behind historical bugs #1362 and #2561. - sdk/src/project-root/index.ts — source of truth (120 lines, pure-with-sync-fs). Exports findProjectRoot(startDir: string) and FIND_PROJECT_ROOT_MAX_DEPTH constant. - sdk/src/project-root/index.test.ts — 13 vitest pinning fixtures covering all four heuristics, the #1362 guard, malformed config fallback, empty sub_repos, deep nesting, and depth-limit enforcement. - sdk/scripts/gen-project-root.mjs — generator. Captures function body via Function.prototype.toString() from compiled sdk/dist/. Emits CJS preamble for destructured node:fs / node:path / node:os imports. - sdk/scripts/check-project-root-fresh.mjs — freshness check. Imports the generator function directly (Phase 3's cleaner pattern). - get-shit-done/bin/lib/project-root.generated.cjs — generator- emitted CJS mirror. - tests/project-root-generator.test.cjs — 11 parity assertions comparing SDK source and generated CJS for every fixture. - sdk/src/query/helpers.ts: -127 lines. The 94-line inline findProjectRoot plus the FIND_PROJECT_ROOT_MAX_DEPTH constant (originally at line 471) replaced by a single re-export: `export { findProjectRoot } from '../project-root/index.js';` Removed unused `parse as parsePath` import. - get-shit-done/bin/lib/core.cjs: -83 lines net. The 67-line inline findProjectRoot replaced by a single `require('./project-root.generated.cjs')`. The detectSubRepos helper at lines 40-56 stays (used by loadConfig migration). - sdk/package.json: gen:project-root + check:project-root-fresh scripts. - package.json: proxy for the freshness check. - .githooks/pre-commit: drift block. - .github/workflows/test.yml: drift check step after the state-document drift step. - CONTEXT.md: Project-Root Resolution Module entry. - docs/INVENTORY.md, docs/INVENTORY-MANIFEST.json: +1 module count, +1 row. - Full suite: 9226/9226 pass (baseline 9215 + 11 new parity fixtures). - SDK vitest: 1804/1804 pass. - Reader shrink: -127 SDK + -83 CJS = 210 lines of duplication deleted across the two Readers. New shared Module is 120 lines. 1. Depth limit canonicalization. CJS findProjectRoot previously had no explicit walk-up bound (walked until dir === root or homedir). The new Module uses FIND_PROJECT_ROOT_MAX_DEPTH = 10, matching the SDK's pre-existing value. Only affects paths nested more than 10 levels deep from a .planning/ root — a pathological case in practice. None of the existing 22 CJS findProjectRoot tests covered this; the new parity test does. 2. platformReadSync → readFileSync. The old CJS findProjectRoot used the platformReadSync wrapper from shell-command-projection.cjs for reading .planning/config.json, which returns null on read failure. The Module uses raw readFileSync, which throws — caught by the surrounding try/catch that already swallowed errors. Functionally equivalent for the existing code path; no test exercises the null-return semantic. Closes #3553.
GSD Documentation
Comprehensive documentation for the Get Shit Done (GSD) framework — a meta-prompting, context engineering, and spec-driven development system for AI coding agents.
Language versions: English · Português (pt-BR) · 日本語 · 简体中文
Documentation Index
| Document | Audience | Description |
|---|---|---|
| Architecture | Contributors, advanced users | System architecture, agent model, data flow, and internal design |
| Installer Migrations | Contributors | Architecture for safe install-time migrations, cleanup, preservation, dry-run planning, and rollback |
| Feature Reference | All users | Feature narratives and requirements for released features (see CHANGELOG for latest additions) |
| v1.42.1 Release Notes | All users | Stable release notes for the 1.42.1 release |
| Command Reference | All users | Stable commands with syntax, flags, options, and examples |
| Configuration Reference | All users | Full config schema, workflow toggles, model profiles, git branching |
| Custom PR Body Sections | All users | How to append project-specific PRD sections to /gsd-ship PR bodies |
| CLI Tools Reference | Contributors, agent authors | gsd-tools.cjs programmatic API for workflows and agents |
| JSON Error Mode | Contributors, agent authors | Machine-readable gsd-tools --json-errors failure envelopes |
| Agent Reference | Contributors, advanced users | Role cards for primary agents — roles, tools, spawn patterns (the agents/ filesystem is authoritative) |
| User Guide | All users | Workflow walkthroughs, troubleshooting, and recovery |
| Issue-Driven Orchestration | All users | Recipe for driving GSD from a tracker issue (GitHub / Linear / Jira) using existing primitives — no new commands or daemon |
| Context Monitor | All users | Context window monitoring hook architecture |
| Discuss Mode | All users | Assumptions vs interview mode for discuss-phase |
| Canary Stream | Contributors, early adopters | dev → @canary dist-tag policy, when to install, rollback path |
Quick Links
- What's new: see v1.42.1 Release Notes, CHANGELOG, and upstream README for release highlights
- Canary preview:
docs/CANARY.md— opt into the early-preview stream fromdev. Active cut:v1.50.0-canary.1 - Getting started: README → install →
/gsd-new-project - Full workflow walkthrough: User Guide
- All commands at a glance: Command Reference
- Configuring GSD: Configuration Reference
- Customizing ship PR bodies: Custom PR Body Sections
- How the system works internally: Architecture
- Contributing or extending: CLI Tools Reference + Agent Reference