* feat(#3840): generate docs/FEATURES.md from per-feature fragments docs/FEATURES.md was hand-maintained, and every feature PR wrote into two shared mutable cells: the '### N.' heading whose integer was hand-allocated at authoring time, and the hand-maintained table of contents. Concurrent PRs all picked the same next integer, and two PRs adding differently numbered features still collided on the TOC. #3831 was renumbered 165 -> 166 -> 167 -> 168 across successive rebases, each collision also costing a full matrix verification run because the sha-keyed pass marker dies with the rebase. Mechanism: one fragment per feature at docs/features/<slug>.md carrying id/title/group (and an optional order) in frontmatter, consolidated by scripts/gen-features.cjs --write|--check into a marker-delimited region of docs/FEATURES.md that holds BOTH the TOC and every section body. Group headings and their order are derived too - a group sorts by its lowest-ordered member - so there is no shared registry to edit either; optional per-group prose lives in docs/features/_groups/<slug>.md. A contributor adds exactly one new file. Wired into regen:derived and lint:generated-sync alongside the eight existing generators, matching gen-adr-index.cjs's CLI shape and typed-REASON reporting. Migration froze all 168 existing numbers verbatim: identical section set, identical order, identical bodies. Two defects found in the tree are fixed inline rather than carried forward - the '## Related' block had been spliced into the middle of the document, orphaning §142's Reference line, and four inbound anchors were already broken on next (FEATURES.md#runtime-identity in two files, and #143-spec-phase-edge-completeness-probe off by one). Since the repo has no link checker, --check now validates every inbound FEATURES.md#anchor by resolved target, so that class cannot ship silently again; locale FEATURES.md files resolve elsewhere and stay out of scope. Refs #3840 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#3840): carry upstream §69 delta into its fragment and harden the generator Review found section 69 missing '[--strict]' and REQ-STATE-05/06 versus origin/next. Root cause was a stale base, not extraction loss: those lines landed in394bf384b(#3844) AFTER this branch forked at63abcface, and 'git diff63abcfaceorigin/next -- docs/FEATURES.md' is exactly that hunk. Merging origin/next auto-applied the hunk into the GENERATED region, which --check immediately reported as stale; the delta is now carried in docs/features/statemd-consistency-gates.md and regenerated from there. --write is now fail-closed. It previously rendered the region even with violations outstanding, warning only on stderr and exiting 0, so a '--write && git commit' chain could commit a FEATURES.md carrying two colliding sections. It now refuses and exits 1; --force is the explicit override and says so in the report. The test that pinned the old behavior now pins the refusal, plus the --force override and its scoping. Marker forgery is rejected at two layers. A fragment body containing '<!-- FEATURES:START' or '<!-- FEATURES:END' is a typed body_forges_region_marker violation (fragments and group notes alike), and spliceIntoFeatures anchors the end boundary with lastIndexOf instead of indexOf, so a marker that reaches the document by any other route can only make the generated region grow, never shrink. Matching is on marker PREFIXES, so a decorated variant comment cannot slip past. Symlinked corpus entries are refused with a typed dirent_not_regular_file rather than read. A fork PR could otherwise commit docs/features/evil.md as a symlink to any readable path and have the generator inline those bytes into the committed docs/FEATURES.md on the next regen. Equivalence re-verified with a method that cannot cancel out. The first check extracted both operands with the same body-normalising helper, so anything that helper dropped was dropped on both sides. The replacement runs two independent passes: a global content-line multiset diff with no per-section logic at all (0 gained, 19 lost, all 19 the stale hand-written mini-TOC links this change deliberately deletes), and a per-section byte-exact body diff carrying a coverage assertion that fails loudly per file when the extractor accounts for fewer lines than the file contains. That assertion caught two blind spots in the checker itself. 168/168 sections present, order identical, one intended body difference (§142 regains the Reference line orphaned by the misplaced '## Related' block). Refs #3840 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * chore(#3840): backfill changeset PR number Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: sim <sim@local> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
5
.changeset/witty-tigers-romp.md
Normal file
5
.changeset/witty-tigers-romp.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
type: Changed
|
||||
pr: 3845
|
||||
---
|
||||
**`docs/FEATURES.md` is now generated from per-feature fragments** — a feature no longer hand-allocates a section number or hand-edits the table of contents, the two cells that made almost every concurrent feature PR conflict; contributors add one file under `docs/features/` with any unique `id` and regenerate. (#3840)
|
||||
100
CONTRIBUTING.md
100
CONTRIBUTING.md
@@ -303,50 +303,76 @@ When a change genuinely has no user-facing documentation impact (infrastructure
|
||||
|
||||
When unsure whether a change is user-facing, **update the docs**.
|
||||
|
||||
### Adding a section to `docs/FEATURES.md`
|
||||
### Adding a feature to `docs/FEATURES.md`
|
||||
|
||||
`docs/FEATURES.md` numbers each feature with a monotonically increasing integer (`### 164.`). That
|
||||
integer is the single most common source of merge conflicts in this repo — with several PRs in
|
||||
flight, everyone picks the same next number and everyone after the first has to renumber.
|
||||
**`docs/FEATURES.md` is generated. Do not edit it by hand.** Add one fragment
|
||||
under `docs/features/` and regenerate:
|
||||
|
||||
**There are two conflict cells, not one.** The `### N.` heading, and the hand-maintained table of
|
||||
contents at the top of the file. Two PRs adding *differently numbered* features still collide on
|
||||
the TOC, so renumbering alone does not make you safe.
|
||||
```
|
||||
docs/features/<kebab-slug>.md
|
||||
```
|
||||
|
||||
```markdown
|
||||
---
|
||||
id: 3840
|
||||
title: Runtime Identity
|
||||
group: v1.7.0 Features
|
||||
---
|
||||
|
||||
**Purpose:** …
|
||||
```
|
||||
|
||||
Then run `npm run regen:derived` (or just `npm run gen:features -- --write`) and
|
||||
commit both the fragment and the regenerated `docs/FEATURES.md`.
|
||||
`npm run lint:generated-sync` runs the `--check` twin, so a stale index cannot
|
||||
merge. `--write` is fail-closed: it refuses to emit `docs/FEATURES.md` while any
|
||||
fragment violation stands, so a `--write && git commit` chain cannot commit a
|
||||
corrupt file. Pass `--force` only to see what a broken corpus would render as.
|
||||
|
||||
**Why fragments.** The old practice hand-allocated a monotonically increasing
|
||||
integer at authoring time, and every feature PR wrote into *two* shared mutable
|
||||
cells: the `### N.` heading and the hand-maintained table of contents. With
|
||||
several PRs in flight everyone picked the same next integer, and two PRs adding
|
||||
*differently numbered* features still collided on the TOC. #3831 was renumbered
|
||||
165 → 166 → 167 → 168 across successive rebases — the last collision landing
|
||||
*during* a verification run — and because every rebase invalidates the sha-keyed
|
||||
pass marker, each collision also cost a full remote matrix run. This is the same
|
||||
fix `.changeset/` already applies to `CHANGELOG.md` and
|
||||
`tests/emitted-drift-acks/` applies to the ack ledger
|
||||
([#2914](https://github.com/open-gsd/gsd-core/issues/2914)): one file per
|
||||
contribution, consolidated by a generator. You add a new file and touch no
|
||||
shared file, so there is nothing to collide on.
|
||||
|
||||
**The rules:**
|
||||
|
||||
1. **Allocate the number LAST.** Write the section body first; pick the integer immediately before
|
||||
you open the PR, or immediately after your final rebase. A number chosen at branch time is
|
||||
already stale.
|
||||
2. **Never pre-emptively renumber to dodge a conflict.** When you hit one, rebase, take
|
||||
`max + 1` of what is now on `next`, and update the TOC in the same commit. Gaps are fine — 58 is
|
||||
already missing and `#27b-existing-codebase-onboarding` is a live non-integer id, so the
|
||||
sequence is not an invariant anyone depends on.
|
||||
3. **Fork contributors: you do not have to fight this.** If your PR conflicts only on the number or
|
||||
the TOC, say so in a comment and leave it — a maintainer will assign the final number at merge.
|
||||
Do not rebase repeatedly just to chase the counter.
|
||||
4. **Do not renumber someone else's section** to make room for yours. Take the next free integer
|
||||
above the current maximum.
|
||||
1. **Any unique `id` is legal.** It does not have to be contiguous or maximal —
|
||||
58, 113 and 131 are already absent, and `6.5`, `27a` and `27b` are live
|
||||
non-integer ids. **Use your issue number** and you never have to revisit the
|
||||
choice after a rebase. `--check` rejects a duplicate with an `id_duplicate`
|
||||
violation naming both fragments, so a collision is a loud one-line fix in
|
||||
your own file, not a merge conflict.
|
||||
2. **Never renumber a merged feature.** `id` is frozen once it ships: other docs
|
||||
link to `FEATURES.md#<id>-<slug>`, and `--check` now verifies every one of
|
||||
those inbound anchors resolves (`inbound_anchor_unresolved`). Renaming the
|
||||
*title* moves the anchor too — fix the inbound links in the same commit.
|
||||
3. **Groups are derived, not registered.** `group` is the `##` heading text.
|
||||
Groups are ordered by their lowest-ordered member, so adding a release bucket
|
||||
is just the first fragment that names it. Optional per-group prose lives in
|
||||
`docs/features/_groups/<slug>.md`, which a feature PR never touches.
|
||||
4. **`order` is optional.** It defaults to the numeric part of `id`, which is
|
||||
right for almost everything. Declare it only to place a section somewhere its
|
||||
number would not put it (`27b` precedes `27a` for historical reasons).
|
||||
5. **Bodies start at `####`.** A `##` or `###` inside a fragment body would
|
||||
forge a group or a sibling section with no id and no TOC entry; `--check`
|
||||
rejects it (`body_heading_too_shallow`).
|
||||
|
||||
**If you are an agent**, take an exclusive Fleet lease on the allocation before choosing a number,
|
||||
and include `docs/FEATURES.md` in your published `touched` set — a `touched` set of symbols alone
|
||||
leaves you invisible to a peer editing the same index:
|
||||
**Fork contributors:** there is nothing to coordinate and nothing to chase. Pick
|
||||
your issue number, add your file, regenerate. If `docs/FEATURES.md` conflicts on
|
||||
a rebase, discard your side and re-run `--write` — it is a derived artifact.
|
||||
|
||||
```
|
||||
fleet_acquire_lease({ repo_id, agent_id,
|
||||
scope: ["docs/FEATURES.md::section-number-allocation"], ttl_seconds: 1800 })
|
||||
… allocate, write, commit …
|
||||
fleet_release_lease({ lease_id })
|
||||
```
|
||||
|
||||
The lease serializes allocation between coordinating agents. It does not prevent a git conflict
|
||||
once two branches already carry adjacent text, and it cannot reach a fork PR.
|
||||
|
||||
> **Planned durable fix.** This whole class disappears if `FEATURES.md` becomes generated from
|
||||
> per-feature fragments the way `CHANGELOG.md` is generated from `.changeset/` (three random words
|
||||
> per fragment, so concurrent PRs cannot collide) and the way `tests/emitted-drift-acks/` works
|
||||
> ([#2914](https://github.com/open-gsd/gsd-core/issues/2914)). Until that lands, the rules above are
|
||||
> the practice.
|
||||
**Agents:** no Fleet allocation lease is needed for a feature number any more.
|
||||
The lease that used to serialize `docs/FEATURES.md::section-number-allocation`
|
||||
protected an invariant that no longer exists.
|
||||
|
||||
## Testing Standards
|
||||
|
||||
|
||||
@@ -2177,7 +2177,7 @@ package-collision failure structurally instead, by resolving `gsd_run` rather th
|
||||
on `PATH`.
|
||||
|
||||
See [Diagnose which gsd-tools is running](how-to/diagnose-a-foreign-gsd-tools.md) for using it,
|
||||
and [Runtime identity](FEATURES.md#runtime-identity) for the rationale.
|
||||
and [Runtime identity](FEATURES.md#168-runtime-identity) for the rationale.
|
||||
|
||||
---
|
||||
|
||||
|
||||
102
docs/FEATURES.md
102
docs/FEATURES.md
@@ -4,6 +4,8 @@
|
||||
|
||||
---
|
||||
|
||||
<!-- FEATURES:START — generated by scripts/gen-features.cjs; do not edit by hand -->
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Core Features](#core-features)
|
||||
@@ -13,6 +15,7 @@
|
||||
- [Phase Planning](#4-phase-planning)
|
||||
- [Phase Execution](#5-phase-execution)
|
||||
- [Work Verification](#6-work-verification)
|
||||
- [Ship](#65-ship)
|
||||
- [UI Review](#7-ui-review)
|
||||
- [Milestone Management](#8-milestone-management)
|
||||
- [Planning Features](#planning-features)
|
||||
@@ -39,6 +42,7 @@
|
||||
- [Brownfield Features](#brownfield-features)
|
||||
- [Codebase Mapping](#27-codebase-mapping)
|
||||
- [Existing Codebase Onboarding](#27b-existing-codebase-onboarding)
|
||||
- [Post-Execute Codebase Drift Detection](#27a-post-execute-codebase-drift-detection)
|
||||
- [Utility Features](#utility-features)
|
||||
- [Debug System](#28-debug-system)
|
||||
- [Todo Management](#29-todo-management)
|
||||
@@ -187,6 +191,12 @@
|
||||
- [Archive Quick Tasks at Milestone Close](#160-archive-quick-tasks-at-milestone-close)
|
||||
- [Verify-Command Path Grounding](#161-verify-command-path-grounding)
|
||||
- [Statusline STATE.md Freshness Marker](#162-statusline-statemd-freshness-marker)
|
||||
- [Read-Only Planning Snapshot (`planning inspect`)](#163-read-only-planning-snapshot-planning-inspect)
|
||||
- [Live-DOM UAT Capability](#164-live-dom-uat-capability)
|
||||
- [Opt-In Parallel Reviewer Lanes](#165-opt-in-parallel-reviewer-lanes)
|
||||
- [Machine-Readable State Contract (`.planning/state.json`)](#166-machine-readable-state-contract-planningstatejson)
|
||||
- [Stated Failing Direction](#167-stated-failing-direction)
|
||||
- [Runtime Identity](#168-runtime-identity)
|
||||
|
||||
---
|
||||
|
||||
@@ -583,6 +593,7 @@
|
||||
| Phase executed but no VERIFICATION.md | Run `/gsd-verify-work` |
|
||||
| All phases complete | Suggest `/gsd-complete-milestone` |
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Quality Assurance Features
|
||||
@@ -690,6 +701,7 @@
|
||||
|
||||
**When:** Runs automatically at the end of `/gsd-plan-phase` after the plan checker loop.
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Context Engineering Features
|
||||
@@ -802,6 +814,7 @@
|
||||
| gsd-integration-checker | Sonnet | Sonnet | Haiku | Inherit |
|
||||
| gsd-nyquist-auditor | Sonnet | Sonnet | Haiku | Inherit |
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Brownfield Features
|
||||
@@ -838,6 +851,8 @@ only the subtrees the phase actually changed. Each produced document carries
|
||||
`last_mapped_commit` in its YAML frontmatter so drift can be measured
|
||||
against the mapping point, not HEAD.
|
||||
|
||||
---
|
||||
|
||||
### 27b. Existing Codebase Onboarding
|
||||
|
||||
**Command:** `/gsd-onboard [--fast] [--text]`
|
||||
@@ -859,6 +874,8 @@ against the mapping point, not HEAD.
|
||||
| `.planning/PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md` | Planning setup produced by `/gsd-new-project` or `/gsd-ingest-docs` |
|
||||
| `.planning/onboarding/SUMMARY.md` | Onboarding status, artifact index, and next-command summary |
|
||||
|
||||
---
|
||||
|
||||
### 27a. Post-Execute Codebase Drift Detection
|
||||
|
||||
**Introduced by:** #2003
|
||||
@@ -890,6 +907,7 @@ continues. Drift detection cannot fail verification.
|
||||
- REQ-DRIFT-06: `last_mapped_commit` round-trip through YAML frontmatter
|
||||
on each `.planning/codebase/*.md` file
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Utility Features
|
||||
@@ -1006,6 +1024,7 @@ continues. Drift detection cannot fail verification.
|
||||
- REQ-TEST-02: System MUST generate tests based on UAT criteria and acceptance criteria
|
||||
- REQ-TEST-03: System MUST use existing test infrastructure patterns
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Infrastructure Features
|
||||
@@ -1138,6 +1157,8 @@ GSD update available: 1.39.0 → 1.40.0. Run /gsd-update.
|
||||
|
||||
The banner is silent when up-to-date and rate-limits "check failed" diagnostics to once per 24 hours. Removed cleanly by `npx @opengsd/gsd-core --uninstall` or by deleting the SessionStart entry that references `gsd-update-banner.js`.
|
||||
|
||||
---
|
||||
|
||||
### 38. Developer Profiling
|
||||
|
||||
**Command:** `/gsd-profile-user [--questionnaire] [--refresh]`
|
||||
@@ -1173,6 +1194,8 @@ The banner is silent when up-to-date and rate-limits "check failed" diagnostics
|
||||
- REQ-PROF-03: Questionnaire MUST be available as fallback when no session history exists
|
||||
- REQ-PROF-04: Generated artifacts MUST be discoverable by Claude Code (CLAUDE.md integration)
|
||||
|
||||
---
|
||||
|
||||
### 39. Execution Hardening
|
||||
|
||||
**Purpose:** Three additive quality improvements to the execution pipeline that catch cross-plan failures before they cascade.
|
||||
@@ -1226,6 +1249,7 @@ When verification returns `human_needed`, items are persisted as a trackable HUM
|
||||
- REQ-DEBT-05: System MUST warn (non-blocking) during phase completion and transition when verification debt exists
|
||||
- REQ-DEBT-06: `/gsd-audit-uat` MUST scan all phases, categorize items by testability, and produce a human test plan
|
||||
|
||||
|
||||
---
|
||||
|
||||
## v1.27 Features
|
||||
@@ -1393,6 +1417,7 @@ Test suite that scans all agent, workflow, and command files for embedded inject
|
||||
- REQ-DISCLOG-02: Log MUST capture questions asked, options presented, and decisions made
|
||||
- REQ-DISCLOG-03: Decision IDs MUST enable traceability from discuss-phase to plan-phase
|
||||
|
||||
|
||||
---
|
||||
|
||||
## v1.28 Features
|
||||
@@ -1549,6 +1574,7 @@ Test suite that scans all agent, workflow, and command files for embedded inject
|
||||
2. **Prompt** — Present multi-select interface for runtime selection
|
||||
3. **Install** — Configure GSD for all selected runtimes in a single session
|
||||
|
||||
|
||||
---
|
||||
|
||||
## v1.29 Features
|
||||
@@ -1583,6 +1609,7 @@ Test suite that scans all agent, workflow, and command files for embedded inject
|
||||
1. **Translate** — Convert core documentation into target languages
|
||||
2. **Publish** — Make translated documentation accessible alongside English originals
|
||||
|
||||
|
||||
---
|
||||
|
||||
## v1.31 Features
|
||||
@@ -1790,6 +1817,7 @@ Test suite that scans all agent, workflow, and command files for embedded inject
|
||||
3. **Clean** — Remove legacy `commands/gsd/` directory if skills are installed
|
||||
4. **Fallback** — Maintain legacy `commands/gsd/` path compatibility for older Claude Code versions
|
||||
|
||||
|
||||
---
|
||||
|
||||
## v1.32 Features
|
||||
@@ -2101,28 +2129,11 @@ Test suite that scans all agent, workflow, and command files for embedded inject
|
||||
|---------|------|---------|-------------|
|
||||
| `hooks.community` | boolean | `false` | Enable optional community hooks for commit validation, session state, and phase boundaries |
|
||||
|
||||
|
||||
---
|
||||
|
||||
## v1.34.0 Features
|
||||
|
||||
- [Global Learnings Store](#89-global-learnings-store)
|
||||
- [Queryable Codebase Intelligence](#90-queryable-codebase-intelligence)
|
||||
- [Execution Context Profiles](#91-execution-context-profiles)
|
||||
- [Gates Taxonomy](#92-gates-taxonomy)
|
||||
- [Code Review Pipeline](#93-code-review-pipeline)
|
||||
- [Socratic Exploration](#94-socratic-exploration)
|
||||
- [Safe Undo](#95-safe-undo)
|
||||
- [Plan Import](#96-plan-import)
|
||||
- [Rapid Codebase Scan](#97-rapid-codebase-scan)
|
||||
- [Autonomous Audit-to-Fix](#98-autonomous-audit-to-fix)
|
||||
- [Improved Prompt Injection Scanner](#99-improved-prompt-injection-scanner)
|
||||
- [Stall Detection in Plan-Phase](#100-stall-detection-in-plan-phase)
|
||||
- [Hard Stop Safety Gates in /gsd-progress --next](#101-hard-stop-safety-gates-in-gsd-progress---next)
|
||||
- [Adaptive Model Preset](#102-adaptive-model-preset)
|
||||
- [Post-Merge Hunk Verification](#103-post-merge-hunk-verification)
|
||||
|
||||
---
|
||||
|
||||
### 89. Global Learnings Store
|
||||
|
||||
**Commands:** Auto-triggered at phase completion; consumed by planner
|
||||
@@ -2380,17 +2391,11 @@ v1 supports **directory-prefix matching only, not glob syntax**: no glob engine
|
||||
- REQ-PATCH-VERIFY-02: Dropped or partial hunks MUST be reported to the user with file and line context
|
||||
- REQ-PATCH-VERIFY-03: Verification MUST run after all patches are applied, not per-patch
|
||||
|
||||
|
||||
---
|
||||
|
||||
## v1.35.0 Features
|
||||
|
||||
- [New Runtime Support (Cline, CodeBuddy, Qwen Code)](#104-new-runtime-support-cline-codebuddy-qwen-code)
|
||||
- [GSD-2 Reverse Migration](#105-gsd-2-reverse-migration)
|
||||
- [AI Integration Phase Wizard](#106-ai-integration-phase-wizard)
|
||||
- [AI Eval Review](#107-ai-eval-review)
|
||||
|
||||
---
|
||||
|
||||
### 104. New Runtime Support (Cline, CodeBuddy, Qwen Code)
|
||||
|
||||
**Part of:** `npx @opengsd/gsd-core`
|
||||
@@ -2465,6 +2470,7 @@ v1 supports **directory-prefix matching only, not glob syntax**: no glob engine
|
||||
|
||||
**Produces:** `{phase}-EVAL-REVIEW.md` with scored eval dimensions, gap analysis, and remediation steps
|
||||
|
||||
|
||||
---
|
||||
|
||||
## v1.36.0 Features
|
||||
@@ -2611,6 +2617,7 @@ With `features.global_learnings: true`, phase completion runs the extraction for
|
||||
**Configuration:** `workflow.tdd_mode`
|
||||
**Reference files:** `tdd.md`, `checkpoints.md`
|
||||
|
||||
|
||||
---
|
||||
|
||||
## v1.37.0 Features
|
||||
@@ -2708,6 +2715,7 @@ With `features.global_learnings: true`, phase completion runs the extraction for
|
||||
**Configuration:** `graphify.enabled`, `graphify.build_timeout`, `graphify.graph_path`
|
||||
**Reference files:** `commands/gsd/graphify.md`, `bin/lib/graphify.cjs`
|
||||
|
||||
|
||||
---
|
||||
|
||||
## v1.40.0 Features
|
||||
@@ -2760,7 +2768,6 @@ With `features.global_learnings: true`, phase completion runs the extraction for
|
||||
|
||||
---
|
||||
|
||||
|
||||
### 124. Context-Window Utilization Guard
|
||||
|
||||
**Command:** `/gsd-health --context`
|
||||
@@ -2791,6 +2798,7 @@ With `features.global_learnings: true`, phase completion runs the extraction for
|
||||
|
||||
**Reference issue:** [#2833](https://github.com/open-gsd/gsd-core/issues/2833) — see [`docs/STATE-MD-LIFECYCLE.md`](reference/state-md.md) for the full field reference and rendering rules.
|
||||
|
||||
|
||||
---
|
||||
|
||||
## v1.41.0 Features
|
||||
@@ -2919,6 +2927,7 @@ Source commit: abc1234 (3 commits behind HEAD)
|
||||
|
||||
**Reference issue:** [#3170](https://github.com/open-gsd/gsd-core/issues/3170)
|
||||
|
||||
|
||||
---
|
||||
|
||||
## v1.42.1 Features
|
||||
@@ -3131,6 +3140,8 @@ explicit reviewer flags -> --all -> review.default_reviewers -> all detected rev
|
||||
- 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)
|
||||
|
||||
---
|
||||
|
||||
### 143. UAT-Passed Predicate
|
||||
@@ -3165,16 +3176,6 @@ explicit reviewer flags -> --all -> review.default_reviewers -> all detected rev
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Commands](COMMANDS.md)
|
||||
- [Configuration](CONFIGURATION.md)
|
||||
- [docs index](README.md)
|
||||
|
||||
**Reference:** [JSON Error Mode](json-errors.md)
|
||||
|
||||
---
|
||||
|
||||
### 144. Spec-Phase Edge-Completeness Probe
|
||||
|
||||
**Command:** `/gsd-spec-phase`
|
||||
@@ -3213,6 +3214,7 @@ The load-bearing wire is the `plan-phase` lift: `covered` and `backstop` edges b
|
||||
|
||||
**Reference:** [Edge Probe](../gsd-core/references/edge-probe.md)
|
||||
|
||||
|
||||
---
|
||||
|
||||
## v1.43.0 Features
|
||||
@@ -3237,6 +3239,8 @@ The load-bearing wire is the `plan-phase` lift: `covered` and `backstop` edges b
|
||||
|
||||
See [Configuration Reference](CONFIGURATION.md#mempalace-settings) for full schema and [How to enable cross-session memory with MemPalace](how-to/enable-cross-session-memory-with-mempalace.md) for a setup walkthrough.
|
||||
|
||||
---
|
||||
|
||||
### 146. Spec-Phase Prohibition Probe
|
||||
|
||||
**Command:** `/gsd-spec-phase`
|
||||
@@ -3273,6 +3277,7 @@ The load-bearing wire is the `plan-phase` lift into `must_haves.prohibitions`, s
|
||||
|
||||
**Reference:** [Prohibition Probe](../gsd-core/references/prohibition-probe.md)
|
||||
|
||||
---
|
||||
|
||||
### 147. Capability Management Command
|
||||
|
||||
@@ -3291,6 +3296,9 @@ The load-bearing wire is the `plan-phase` lift into `must_haves.prohibitions`, s
|
||||
**Trust boundary:** install never executes capability code (copy-only staging); executable surfaces require explicit consent; sources are gated by the **project-scoped** `capabilities.strict_known_registries` policy (fail-closed on a malformed/unparseable value); every shared-config write/delete is realpath-confined to the scope root, and a name collision with a user's `mcpServers` entry is never clobbered.
|
||||
|
||||
**Reference:** [`gsd capability` command reference](reference/gsd-capability-command.md) · [ADR-1244](adr/1244-capability-ecosystem.md)
|
||||
|
||||
---
|
||||
|
||||
### 148. Smart Entry Launcher
|
||||
|
||||
**Command:** `/gsd-next`
|
||||
@@ -3310,6 +3318,7 @@ The load-bearing wire is the `plan-phase` lift into `must_haves.prohibitions`, s
|
||||
|
||||
**Reference:** [Smart Entry Design](superpowers/specs/2026-06-27-gsd-smart-entry-design.md)
|
||||
|
||||
|
||||
---
|
||||
|
||||
## v1.7.0 Features
|
||||
@@ -3410,6 +3419,8 @@ The load-bearing wire is the `plan-phase` lift into `must_haves.prohibitions`, s
|
||||
|
||||
**Configuration:** `graphify.graph_path`
|
||||
|
||||
---
|
||||
|
||||
### 159. Complexity-Triggered Refactor
|
||||
|
||||
**Behavior:** An `execute:post` step measures the complexity of the files a phase touched (decision-point counting over comment- and literal-stripped source, no external dependency) and surfaces a scoped refactor proposal at `.planning/phases/<N>/<NN>-REFACTOR.md` when a function's score exceeds `refactor.complexity_threshold` or its growth over its recorded anchor exceeds `refactor.complexity_jump_delta` — whichever trips first, both reported. Trigger semantics are strictly greater (ESLint's `complexity: {max: N}` convention), so a score exactly equal to the threshold does not trigger. The anchor is set the first time a function is observed and moves only when the proposal is dispositioned via `refactor accept` or `refactor decline` — never when the score alone improves — so the jump delta is cumulative growth since the last conscious decision about that function, not the change made in a single phase. Advisory by default: the proposal is informational only, never edits code, and never blocks. Opt-in `refactor.trigger_strict` records an untriaged proposal as an open `deviation` entry in the broken-windows ledger (#1950) instead — it does not block on its own; ship-blocking is broken-windows' existing `ship:pre` gate, enabled separately with `workflow.windows_enforce`. Without broken-windows installed, strict mode still records the proposal locally and says so. Enabling `refactor.trigger_strict` without `workflow.windows_enforce` also on (or with broken-windows absent) surfaces a typed `refactor_strict_not_enforcing` warning on every triggering evaluate, naming the exact remediation, so this enforcement gap is never silent. A declined proposal resolves its ledger entry as `waived` with the recorded reason; an accepted one resolves as `fixed`. The metric is approximate by construction: biased against a flat `switch`, blind to nesting depth, JS/TS-family only, and a renamed function loses its anchor (issue #1953).
|
||||
@@ -3487,6 +3498,8 @@ See [Resolve verify-command path findings](how-to/resolve-verify-command-path-fi
|
||||
|
||||
**Reference:** [Configuration](CONFIGURATION.md) · [Read the statusline freshness marker](how-to/read-the-statusline-freshness-marker.md) · [ADR-2164](adr/2164-statusline-scope-boundary.md)
|
||||
|
||||
---
|
||||
|
||||
### 163. Read-Only Planning Snapshot (`planning inspect`)
|
||||
|
||||
**Command:** `gsd-tools query planning inspect`
|
||||
@@ -3510,6 +3523,8 @@ See [Resolve verify-command path findings](how-to/resolve-verify-command-path-fi
|
||||
|
||||
**Reference:** [CLI Tools](CLI-TOOLS.md#planning-inspect) · [Consume the planning snapshot](how-to/consume-the-planning-snapshot.md)
|
||||
|
||||
---
|
||||
|
||||
### 164. Live-DOM UAT Capability
|
||||
|
||||
**Config key:** `workflow.live_dom_uat` (default `false`)
|
||||
@@ -3554,6 +3569,8 @@ See [Resolve verify-command path findings](how-to/resolve-verify-command-path-fi
|
||||
|
||||
**Reference:** [Configuration](CONFIGURATION.md#parallel-reviewer-lanes-for-gsd-review-3034) · [Enable parallel reviewer lanes](how-to/enable-parallel-reviewer-lanes.md) · [Commands](COMMANDS.md)
|
||||
|
||||
---
|
||||
|
||||
### 166. Machine-Readable State Contract (`.planning/state.json`)
|
||||
|
||||
**Purpose:** External tools that display GSD project state — a workbench, a dashboard, an editor extension — had to parse `STATE.md` and `ROADMAP.md` heuristically. Those are human surfaces: their shape drifts as the templates evolve, and every consumer ends up carrying a brittle second parser that silently reports wrong numbers after an upgrade. GSD now publishes a small, versioned JSON snapshot instead, so the reader binds to a contract rather than to markdown (#3227).
|
||||
@@ -3608,6 +3625,7 @@ See [Resolve verify-command path findings](how-to/resolve-verify-command-path-fi
|
||||
- The adjacent **vacuous pass** — a command that runs successfully and asserts nothing, such as a test-name filter matching zero tests and exiting 0 — is a distinct problem and is explicitly out of scope.
|
||||
|
||||
See [State a failing direction](how-to/state-a-failing-direction.md) and [`gsd-tools check verify-failure-directions`](COMMANDS.md#gsd-tools-check-verify-failure-directions).
|
||||
|
||||
---
|
||||
|
||||
### 168. Runtime Identity
|
||||
@@ -3625,3 +3643,15 @@ See [State a failing direction](how-to/state-a-failing-direction.md) and [`gsd-t
|
||||
**Known limits:** an installation of this package old enough to predate `bin/gsd_run` ([#381](https://github.com/open-gsd/gsd-core/issues/381)) is no longer reachable through the `PATH` branch and must be upgraded or invoked through one of the path-based branches. The `runtime-identity` verb is a manual diagnostic, not an automatic gate — nothing currently asserts identity on every invocation, which remains open for a future release now that the byte budget is understood. Path-based resolution branches are unchanged and still trust their configured location.
|
||||
|
||||
**Reference:** [`runtime-identity`](COMMANDS.md#runtime-identity) · [Diagnose which gsd-tools is running](how-to/diagnose-a-foreign-gsd-tools.md)
|
||||
|
||||
---
|
||||
|
||||
_Generated by `scripts/gen-features.cjs` — add a fragment under `docs/features/` and run `--write`._
|
||||
|
||||
<!-- FEATURES:END -->
|
||||
|
||||
## Related
|
||||
|
||||
- [Commands](COMMANDS.md)
|
||||
- [Configuration](CONFIGURATION.md)
|
||||
- [docs index](README.md)
|
||||
|
||||
5
docs/features/_groups/infrastructure-features.md
Normal file
5
docs/features/_groups/infrastructure-features.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
group: Infrastructure Features
|
||||
---
|
||||
|
||||
> **Looking for a third-party add-on instead?** See the [GSD Community Capability Registry & EoS Registry](registries/README.md) — non-endorsing discoverability catalogs for community-contributed Capabilities and EoS host integrations.
|
||||
5
docs/features/_groups/v170-features.md
Normal file
5
docs/features/_groups/v170-features.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
group: v1.7.0 Features
|
||||
---
|
||||
|
||||
> These are features new to **@opengsd/gsd-core 1.7.0** (the current release line: 1.0.0 → 1.2.0 → … → 1.6.1 → 1.7.0). The preceding `v1.27`–`v1.43.0` sections use the retired get-shit-done-cc / get-shit-done-redux feature numbering and are not gsd-core releases — see [Legacy Release Notes](RELEASE-NOTES-LEGACY.md).
|
||||
13
docs/features/adaptive-model-preset.md
Normal file
13
docs/features/adaptive-model-preset.md
Normal file
@@ -0,0 +1,13 @@
|
||||
---
|
||||
id: 102
|
||||
title: Adaptive Model Preset
|
||||
group: v1.34.0 Features
|
||||
---
|
||||
|
||||
**Config:** `model_profile: "adaptive"`
|
||||
|
||||
**Purpose:** Role-based model assignment that automatically selects the appropriate model tier based on the current agent's role, rather than applying a single tier to all agents.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-ADAPTIVE-01: `adaptive` preset MUST assign model tiers based on agent role (planner → quality tier, executor → balanced tier, etc.)
|
||||
- REQ-ADAPTIVE-02: `adaptive` MUST be selectable via `/gsd-config --profile adaptive`
|
||||
15
docs/features/agent-size-budget-enforcement.md
Normal file
15
docs/features/agent-size-budget-enforcement.md
Normal file
@@ -0,0 +1,15 @@
|
||||
---
|
||||
id: 119
|
||||
title: Agent Size-Budget Enforcement
|
||||
group: v1.37.0 Features
|
||||
---
|
||||
|
||||
**Purpose:** Keep agent prompt files lean with tiered line-count limits enforced in CI. Oversized agents are caught before they bloat context windows in production.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-BUDGET-01: `agents/gsd-*.md` files are classified into three tiers: XL (≤ 1 600 lines), Large (≤ 1 000 lines), Default (≤ 500 lines)
|
||||
- REQ-BUDGET-02: Tier assignment is declared in the file's YAML frontmatter (`size: xl | large | default`)
|
||||
- REQ-BUDGET-03: `tests/agent-size-budget.test.cjs` enforces limits and fails CI on violation
|
||||
- REQ-BUDGET-04: Files without a `size` frontmatter key default to the Default (500-line) limit
|
||||
|
||||
**Test file:** `tests/agent-size-budget.test.cjs`
|
||||
17
docs/features/ai-eval-review.md
Normal file
17
docs/features/ai-eval-review.md
Normal file
@@ -0,0 +1,17 @@
|
||||
---
|
||||
id: 107
|
||||
title: AI Eval Review
|
||||
group: v1.35.0 Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-eval-review [N]`
|
||||
|
||||
**Purpose:** Retroactively audit an executed AI phase's evaluation coverage against the `AI-SPEC.md` plan. Identifies gaps between planned and implemented evaluation before the phase is closed.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-EVALREVIEW-01: Review MUST read `AI-SPEC.md` from the specified phase
|
||||
- REQ-EVALREVIEW-02: Each eval dimension MUST be scored as COVERED, PARTIAL, or MISSING
|
||||
- REQ-EVALREVIEW-03: Output MUST include findings, gap descriptions, and remediation guidance
|
||||
- REQ-EVALREVIEW-04: `EVAL-REVIEW.md` MUST be written to the phase directory
|
||||
|
||||
**Produces:** `{phase}-EVAL-REVIEW.md` with scored eval dimensions, gap analysis, and remediation steps
|
||||
17
docs/features/ai-integration-phase-wizard.md
Normal file
17
docs/features/ai-integration-phase-wizard.md
Normal file
@@ -0,0 +1,17 @@
|
||||
---
|
||||
id: 106
|
||||
title: AI Integration Phase Wizard
|
||||
group: v1.35.0 Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-ai-integration-phase [N]`
|
||||
|
||||
**Purpose:** Guide developers through selecting, integrating, and planning evaluation for AI/LLM capabilities in a project phase. Produces a structured `AI-SPEC.md` that feeds into planning and verification.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-AISPEC-01: Wizard MUST present an interactive decision matrix covering framework selection, model choice, and integration approach
|
||||
- REQ-AISPEC-02: System MUST surface domain-specific failure modes and eval criteria relevant to the project type
|
||||
- REQ-AISPEC-03: System MUST spawn 3 parallel specialist agents: domain-researcher, framework-selector, and eval-planner
|
||||
- REQ-AISPEC-04: Output MUST produce `{phase}-AI-SPEC.md` with framework recommendation, implementation guidance, and evaluation strategy
|
||||
|
||||
**Produces:** `{phase}-AI-SPEC.md` in the phase directory
|
||||
14
docs/features/anti-pattern-severity-levels.md
Normal file
14
docs/features/anti-pattern-severity-levels.md
Normal file
@@ -0,0 +1,14 @@
|
||||
---
|
||||
id: 78
|
||||
title: Anti-Pattern Severity Levels
|
||||
group: v1.32 Features
|
||||
---
|
||||
|
||||
**Part of:** `/gsd-resume-work`
|
||||
|
||||
**Purpose:** Mandatory understanding checks at resume with severity-based anti-pattern enforcement.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-ANTI-01: System MUST classify anti-patterns by severity level
|
||||
- REQ-ANTI-02: System MUST enforce mandatory understanding checks at session resume
|
||||
- REQ-ANTI-03: Higher severity anti-patterns MUST block workflow progression until acknowledged
|
||||
9
docs/features/api-coverage-gate.md
Normal file
9
docs/features/api-coverage-gate.md
Normal file
@@ -0,0 +1,9 @@
|
||||
---
|
||||
id: 156
|
||||
title: API-Coverage Gate
|
||||
group: v1.7.0 Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-verify-work`
|
||||
|
||||
**Purpose:** A phase that integrates an external API, SDK, or service can no longer seal verification without a decided coverage matrix (#1562).
|
||||
16
docs/features/architectural-responsibility-mapping.md
Normal file
16
docs/features/architectural-responsibility-mapping.md
Normal file
@@ -0,0 +1,16 @@
|
||||
---
|
||||
id: 111
|
||||
title: Architectural Responsibility Mapping
|
||||
group: v1.36.0 Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-plan-phase` (enhanced research step)
|
||||
|
||||
**Purpose:** During phase research, the phase-researcher now maps each capability to its architectural tier owner (browser, frontend server, API, CDN/static, database). The planner cross-references tasks against this map, and the plan-checker enforces tier compliance as Dimension 7c.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-ARM-01: Phase researcher produces an Architectural Responsibility Map table in RESEARCH.md (Step 1.5)
|
||||
- REQ-ARM-02: Planner sanity-checks task-to-tier assignments against the map
|
||||
- REQ-ARM-03: Plan checker validates tier compliance as Dimension 7c (WARNING for general mismatches, BLOCKER for security-sensitive ones)
|
||||
|
||||
**Produces:** `## Architectural Responsibility Map` section in `{phase}-RESEARCH.md`
|
||||
22
docs/features/archive-quick-tasks-at-milestone-close.md
Normal file
22
docs/features/archive-quick-tasks-at-milestone-close.md
Normal file
@@ -0,0 +1,22 @@
|
||||
---
|
||||
id: 160
|
||||
title: Archive Quick Tasks at Milestone Close
|
||||
group: v1.7.0 Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-complete-milestone` (forward path), `/gsd-cleanup` (retroactive path), `gsd-tools milestone complete --archive-quick` / `gsd-tools milestone archive-quick <version>` (#2142)
|
||||
|
||||
**Behavior:** `.planning/quick/` otherwise accumulates one directory per `/gsd-quick` task forever. `/gsd-complete-milestone` now offers a Yes/Skip prompt — when accepted, it moves every directory under `.planning/quick/` into `.planning/milestones/<version>-quick/`, (re)writes that archive directory's `README.md` (an index built by scanning the archive directory, one entry per task, linked to its `SUMMARY.md` when one exists), and clears the data rows of `STATE.md`'s `### Quick Tasks Completed` table while preserving its header and detected column variant. `/gsd-cleanup` offers the same archival retroactively, for milestones that were already closed before their quick tasks were swept, via the narrower `milestone archive-quick <version>` command — identical move/index/reset behavior, but without touching `ROADMAP.md`, `REQUIREMENTS.md`, `MILESTONES.md`, or milestone-completion guards, so it can be re-run safely against an already-completed milestone.
|
||||
|
||||
**Why opt-in.** Phase-directory archival is default-ON (#1871) — omitting a phase directory from an archive would silently leave stale execution history in the way of the next milestone's roadmap. Quick tasks carry no such downstream conflict, so archival here defaults OFF: a user who never passes `--archive-quick` sees zero behavior change. This is a deliberate asymmetry with phase archival, not an oversight.
|
||||
|
||||
**Why bucket-all, not per-milestone.** `.planning/quick/` is a flat directory with no on-disk record of which milestone a given task belongs to. Splitting tasks per milestone was considered and rejected — inferring provenance from dates (creation time vs. a milestone's shipped date) is a proxy, not a fact, and a wrong inference on a one-way `mv` is silently irreversible. Archival instead buckets everything currently in `.planning/quick/` into the one milestone being completed (or, on the retroactive path, the one milestone chosen), and says so in the confirmation prompt.
|
||||
|
||||
**Why the index is built from disk, not from `STATE.md`'s table.** The `### Quick Tasks Completed` table is a running log a workflow step appends to — it demonstrably drifts from what's actually in `.planning/quick/` (the motivating case: 53 rows against 49 directories, ~22 rows pointing at directories that no longer existed, 18 directories with no row at all). Building the archive's `README.md` index by scanning the archive directory itself, rather than trusting the table, means the index can never inherit that drift; a re-run's index also naturally includes entries a prior run already archived, since it's re-derived from what's physically present.
|
||||
|
||||
**Known limits:**
|
||||
- No per-milestone provenance — bucket-all is the only option (see above).
|
||||
- A `### Quick Tasks Completed` table whose columns match neither registered variant (with/without a Status column) is left untouched with a warning rather than reset, since clearing it would risk destroying rows under a schema GSD doesn't recognize.
|
||||
- A `STATE.md` with no `### Quick Tasks Completed` section at all is a normal, silent no-op for the reset step — the section is created lazily by `/gsd-quick`, not present in the project template.
|
||||
|
||||
See [Archiving quick tasks](how-to/handle-quick-and-fast-tasks.md#archiving-quick-tasks) for the full walkthrough.
|
||||
27
docs/features/assumptions-discussion-mode.md
Normal file
27
docs/features/assumptions-discussion-mode.md
Normal file
@@ -0,0 +1,27 @@
|
||||
---
|
||||
id: 53
|
||||
title: Assumptions Discussion Mode
|
||||
group: v1.28 Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-discuss-phase` with `workflow.discuss_mode: 'assumptions'`
|
||||
|
||||
**Purpose:** Replace interview-style questioning with codebase-first assumption analysis.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-ASSUME-01: System MUST analyze codebase to generate structured assumptions before asking questions
|
||||
- REQ-ASSUME-02: System MUST classify assumptions by confidence level (Confident/Likely/Unclear)
|
||||
- REQ-ASSUME-03: System MUST produce identical CONTEXT.md format as default discuss mode
|
||||
- REQ-ASSUME-04: System MUST support confidence-based skip gate (all HIGH = no questions)
|
||||
|
||||
**Produces:**
|
||||
| Artifact | Description |
|
||||
|----------|-------------|
|
||||
| `{phase}-CONTEXT.md` | Same format as default discuss mode |
|
||||
|
||||
**Process:**
|
||||
1. **Analyze** — Scan codebase to generate structured assumptions about implementation approach
|
||||
2. **Classify** — Categorize assumptions by confidence level: Confident, Likely, Unclear
|
||||
3. **Gate** — If all assumptions are HIGH confidence, skip questioning entirely
|
||||
4. **Confirm** — Present unclear assumptions as targeted questions to the user
|
||||
5. **Output** — Produce `{phase}-CONTEXT.md` in identical format to default discuss mode
|
||||
26
docs/features/auto-advance-next.md
Normal file
26
docs/features/auto-advance-next.md
Normal file
@@ -0,0 +1,26 @@
|
||||
---
|
||||
id: 14
|
||||
title: Auto-Advance (Next)
|
||||
group: Planning Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-progress --next`
|
||||
|
||||
**Purpose:** Automatically detect current project state and advance to the next logical workflow step, eliminating the need to remember which phase/step you're on.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-NEXT-01: System MUST read STATE.md, ROADMAP.md, and phase directories to determine current position
|
||||
- REQ-NEXT-02: System MUST detect whether discuss, plan, execute, or verify is needed
|
||||
- REQ-NEXT-03: System MUST invoke the correct command automatically
|
||||
- REQ-NEXT-04: System MUST suggest `/gsd-new-project` if no project exists
|
||||
- REQ-NEXT-05: System MUST suggest `/gsd-complete-milestone` when all phases are complete
|
||||
|
||||
**State Detection Logic:**
|
||||
| State | Action |
|
||||
|-------|--------|
|
||||
| No `.planning/` directory | Suggest `/gsd-new-project` |
|
||||
| Phase has no CONTEXT.md | Run `/gsd-discuss-phase` |
|
||||
| Phase has no PLAN.md files | Run `/gsd-plan-phase` |
|
||||
| Phase has plans but no SUMMARY.md | Run `/gsd-execute-phase` |
|
||||
| Phase executed but no VERIFICATION.md | Run `/gsd-verify-work` |
|
||||
| All phases complete | Suggest `/gsd-complete-milestone` |
|
||||
16
docs/features/autonomous-audit-to-fix.md
Normal file
16
docs/features/autonomous-audit-to-fix.md
Normal file
@@ -0,0 +1,16 @@
|
||||
---
|
||||
id: 98
|
||||
title: Autonomous Audit-to-Fix
|
||||
group: v1.34.0 Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-audit-fix [--source <audit>] [--severity high|medium|all] [--max N] [--dry-run]`
|
||||
|
||||
**Purpose:** End-to-end pipeline that runs an audit, classifies findings as auto-fixable vs. manual-only, then autonomously fixes auto-fixable issues with test verification and atomic commits.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-AUDITFIX-01: Findings MUST be classified as auto-fixable or manual-only before any changes
|
||||
- REQ-AUDITFIX-02: Each fix MUST be verified with tests before committing
|
||||
- REQ-AUDITFIX-03: Each fix MUST be committed atomically
|
||||
- REQ-AUDITFIX-04: `--dry-run` MUST show classification table without applying any fixes
|
||||
- REQ-AUDITFIX-05: `--max N` MUST limit the number of fixes applied in one run (default: 5)
|
||||
20
docs/features/autonomous-interactive-flag.md
Normal file
20
docs/features/autonomous-interactive-flag.md
Normal file
@@ -0,0 +1,20 @@
|
||||
---
|
||||
id: 86
|
||||
title: Autonomous `--interactive` Flag
|
||||
group: v1.32 Features
|
||||
---
|
||||
|
||||
**Flag:** `/gsd-autonomous --interactive`
|
||||
|
||||
**Purpose:** Lean-context autonomous mode that keeps discuss-phase interactive (user answers questions) while dispatching plan and execute as background agents on runtimes that support nested background dispatch; on Claude Code, plan and execute run inline to preserve worktree isolation and independent verification.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-INTERACT-01: `--interactive` MUST run discuss-phase inline with interactive questions (not auto-answered)
|
||||
- REQ-INTERACT-02: `--interactive` MUST dispatch plan-phase and execute-phase as background agents for context isolation on runtimes where a backgrounded agent can spawn subagents; on Claude Code, plan and execute run inline
|
||||
- REQ-INTERACT-03: `--interactive` MUST enable pipeline parallelism — discuss Phase N+1 while Phase N builds (applies on runtimes that support nested background dispatch; on Claude Code, discuss does not overlap planning/execution)
|
||||
- REQ-INTERACT-04: Main context MUST only accumulate discuss conversations (lean context) on runtimes that support nested background dispatch; on Claude Code, inline plan/execute also accumulate in the main context
|
||||
|
||||
**Process:**
|
||||
1. **Discuss inline** — Run discuss-phase in the main context with user interaction
|
||||
2. **Dispatch** — On runtimes that support nested background dispatch: send plan and execute to background agents with fresh context windows. On Claude Code: run plan and execute inline.
|
||||
3. **Pipeline** — On runtimes with background dispatch: while background agents build Phase N, begin discussing Phase N+1. On Claude Code: phases run sequentially.
|
||||
16
docs/features/autonomous-mode.md
Normal file
16
docs/features/autonomous-mode.md
Normal file
@@ -0,0 +1,16 @@
|
||||
---
|
||||
id: 11
|
||||
title: Autonomous Mode
|
||||
group: Planning Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-autonomous [--from N]`
|
||||
|
||||
**Purpose:** Run all remaining phases autonomously — discuss → plan → execute per phase.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-AUTO-01: System MUST iterate through all incomplete phases in roadmap order
|
||||
- REQ-AUTO-02: System MUST run discuss → plan → execute for each phase
|
||||
- REQ-AUTO-03: System MUST pause for explicit user decisions (gray area acceptance, blockers, validation)
|
||||
- REQ-AUTO-04: System MUST re-read ROADMAP.md after each phase to catch dynamically inserted phases
|
||||
- REQ-AUTO-05: `--from N` flag MUST start from a specific phase number
|
||||
19
docs/features/autonomous-to-n-flag.md
Normal file
19
docs/features/autonomous-to-n-flag.md
Normal file
@@ -0,0 +1,19 @@
|
||||
---
|
||||
id: 70
|
||||
title: Autonomous `--to N` Flag
|
||||
group: v1.32 Features
|
||||
---
|
||||
|
||||
**Flag:** `/gsd-autonomous --to N`
|
||||
|
||||
**Purpose:** Stop autonomous execution after completing a specific phase, allowing partial autonomous runs.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-TO-01: System MUST stop execution after the specified phase number completes
|
||||
- REQ-TO-02: System MUST follow the same discuss -> plan -> execute flow for each phase up to N
|
||||
- REQ-TO-03: `--to N` MUST be combinable with `--from N` for bounded autonomous ranges
|
||||
|
||||
**Process:**
|
||||
1. **Bound** — Set the upper phase limit from `--to N` argument
|
||||
2. **Execute** — Run autonomous flow for each phase up to and including phase N
|
||||
3. **Stop** — Halt after phase N completes
|
||||
24
docs/features/backlog-parking-lot.md
Normal file
24
docs/features/backlog-parking-lot.md
Normal file
@@ -0,0 +1,24 @@
|
||||
---
|
||||
id: 43
|
||||
title: Backlog Parking Lot
|
||||
group: v1.27 Features
|
||||
---
|
||||
|
||||
**Commands:** `/gsd-capture --backlog <description>`, `/gsd-review-backlog`, `/gsd-capture --seed <idea>`, `/gsd-capture --list-seeds [status]`
|
||||
|
||||
**Purpose:** Capture ideas that aren't ready for active planning. Backlog items use 999.x numbering to stay outside the active phase sequence. Seeds are forward-looking ideas with trigger conditions that surface automatically at the right milestone. `--list-seeds` provides a read-only audit of all parked seeds (with optional status filter) without waiting for the next milestone.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-BACKLOG-01: Backlog items MUST use 999.x numbering to stay outside active phase sequence
|
||||
- REQ-BACKLOG-02: Phase directories MUST be created immediately so `/gsd-discuss-phase` and `/gsd-plan-phase` work on them
|
||||
- REQ-BACKLOG-03: `/gsd-review-backlog` MUST support promote, keep, and remove actions per item
|
||||
- REQ-BACKLOG-04: Promoted items MUST be renumbered into the active milestone sequence
|
||||
- REQ-SEED-01: Seeds MUST capture the full WHY and WHEN to surface conditions
|
||||
- REQ-SEED-02: `/gsd-new-milestone` MUST scan seeds and present matches
|
||||
- REQ-SEED-03: `/gsd-capture --list-seeds` MUST list seeds with status, scope, and trigger for audit, with optional status filtering
|
||||
|
||||
**Produces:**
|
||||
| Artifact | Description |
|
||||
|----------|-------------|
|
||||
| `.planning/phases/999.x-slug/` | Backlog item directory |
|
||||
| `.planning/seeds/SEED-NNN-slug.md` | Seed with trigger conditions |
|
||||
15
docs/features/broken-windows-ledger.md
Normal file
15
docs/features/broken-windows-ledger.md
Normal file
@@ -0,0 +1,15 @@
|
||||
---
|
||||
id: 158
|
||||
title: Broken-Windows Ledger
|
||||
group: v1.7.0 Features
|
||||
---
|
||||
|
||||
**Behavior:** A cross-phase defect register at `.planning/WINDOWS.md` accumulates stubs, TODOs, skipped tests, unrun verifies, and unmet truths (#1950). `/gsd-ship` blocks while any entry is `open`; an entry can be `waived` only with a recorded reason (auditable) or marked `fixed` (removed from the blocking set). `/gsd-progress` surfaces the open + waived counts.
|
||||
|
||||
**Commands:** `gsd-tools windows status | append | waive | fixed`.
|
||||
|
||||
**Config:** `workflow.windows_enforce` (gate active, default `false` — opt-in enforcement). Enable with `gsd config-set workflow.windows_enforce true`. Tracking (the ledger itself, populated by the executor) is always on; only the ship gate is opt-in.
|
||||
|
||||
**Backward compatibility:** A project with no `.planning/WINDOWS.md` reports `open_count: 0` and ships cleanly; the gate only activates once windows are recorded.
|
||||
|
||||
**Configuration:** `graphify.graph_path`
|
||||
21
docs/features/capability-management-command.md
Normal file
21
docs/features/capability-management-command.md
Normal file
@@ -0,0 +1,21 @@
|
||||
---
|
||||
id: 147
|
||||
title: Capability Management Command
|
||||
group: v1.43.0 Features
|
||||
---
|
||||
|
||||
**Command:** `gsd capability install | update | remove | list | outdated | disable | enable`
|
||||
|
||||
**Purpose:** The user-facing CLI for the ADR-1244 capability ecosystem — install, upgrade, remove, list, check for updates, and toggle GSD capabilities (first-party and third-party overlays) from a registry / git / npm / tarball / local source. Wires the Phase-3/4 lifecycle library (source resolver, install ledger, trust gate) to a command users actually run.
|
||||
|
||||
**Behavior:**
|
||||
- `install <spec> [--integrity sha512-…] [--scope global|project] [--yes] [--shared-file <rel>]…` — resolve (copy-only) → verify integrity / SHA pin → `engines.gsd` gate → disclose executable surfaces → consent (`--yes` grants; without it an executable install aborts after printing the disclosure and writes nothing) → validate → extract → record the ledger.
|
||||
- `update [<id> | --all] [--scope] [--yes]` — re-resolve the capability's recorded source and upgrade via atomic stage-then-swap; re-consent when the executable set changed; `--all` reports a per-capability outcome and exits non-zero on any partial failure.
|
||||
- `remove <id> [--purge-data] [--scope]` — strip the ledger-recorded files + marker-isolated shared edits; first-party capabilities are rejected (use the product uninstaller).
|
||||
- `list [--json]` — first-party + installed overlay capabilities (both scopes) as a JSON array.
|
||||
- `outdated [--json] [--scope]` — light remote peek of each installed overlay's recorded source (ADR-1244 D6 per-source matrix: git `ls-remote --tags`, npm `view … version` resolving the highest version matching the recorded range, local re-read; tarball → `manual`, registry → `unknown`) reporting `outdated` / `current` / `pinned` / `manual` / `unknown` per capability. A source pinned to an immutable ref (git `#sha:` or `#tag:`, or an exact npm version) is reported `pinned`. A bare git `#<ref>` is classified at the remote: if it resolves exclusively under `refs/tags/` it is an immutable tag → `pinned`; if it resolves to a mutable branch (or is ambiguous) it is `unknown`. Bounded subprocesses (git ≤30s, npm ≤60s) and a failing peek degrades that row to `unknown` without crashing the command. `--json` for machine output, default for a table.
|
||||
- `disable | enable <id>` — toggle activation state (equivalent to `gsd capability set <id> --off` / `--on`).
|
||||
|
||||
**Trust boundary:** install never executes capability code (copy-only staging); executable surfaces require explicit consent; sources are gated by the **project-scoped** `capabilities.strict_known_registries` policy (fail-closed on a malformed/unparseable value); every shared-config write/delete is realpath-confined to the scope root, and a name collision with a user's `mcpServers` entry is never clobbered.
|
||||
|
||||
**Reference:** [`gsd capability` command reference](reference/gsd-capability-command.md) · [ADR-1244](adr/1244-capability-ecosystem.md)
|
||||
19
docs/features/claim-provenance-tagging.md
Normal file
19
docs/features/claim-provenance-tagging.md
Normal file
@@ -0,0 +1,19 @@
|
||||
---
|
||||
id: 65
|
||||
title: Claim Provenance Tagging
|
||||
group: v1.31 Features
|
||||
---
|
||||
|
||||
**Part of:** `/gsd-plan-phase --research-phase <N>`
|
||||
|
||||
**Purpose:** Ensure research claims are tagged with source evidence and assumptions are logged separately.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-PROVENANCE-01: Researcher MUST mark claims with source evidence references
|
||||
- REQ-PROVENANCE-02: Assumptions MUST be logged separately from sourced claims
|
||||
- REQ-PROVENANCE-03: System MUST distinguish between evidenced facts and inferred assumptions
|
||||
|
||||
**Process:**
|
||||
1. **Research** — Researcher gathers information from codebase and domain sources
|
||||
2. **Tag** — Each claim is annotated with its source (file path, documentation, API response)
|
||||
3. **Separate** — Assumptions without direct evidence are logged in a distinct section
|
||||
20
docs/features/claude-code-skills-migration.md
Normal file
20
docs/features/claude-code-skills-migration.md
Normal file
@@ -0,0 +1,20 @@
|
||||
---
|
||||
id: 68
|
||||
title: Claude Code Skills Migration
|
||||
group: v1.31 Features
|
||||
---
|
||||
|
||||
**Part of:** `npx @opengsd/gsd-core`
|
||||
|
||||
**Purpose:** Migrate GSD commands to Claude Code 2.1.88+ skills format with backward compatibility.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-SKILLS-01: Installer MUST write `skills/gsd-*/SKILL.md` for Claude Code 2.1.88+
|
||||
- REQ-SKILLS-02: Installer MUST auto-clean legacy `commands/gsd/` directory
|
||||
- REQ-SKILLS-03: Installer MUST maintain backward compatibility with older Claude Code versions via the legacy `commands/gsd/` path
|
||||
|
||||
**Process:**
|
||||
1. **Detect** — Check Claude Code version to determine skills support
|
||||
2. **Migrate** — Write `skills/gsd-*/SKILL.md` files for each GSD command
|
||||
3. **Clean** — Remove legacy `commands/gsd/` directory if skills are installed
|
||||
4. **Fallback** — Maintain legacy `commands/gsd/` path compatibility for older Claude Code versions
|
||||
9
docs/features/claude-orchestration-capability-beta.md
Normal file
9
docs/features/claude-orchestration-capability-beta.md
Normal file
@@ -0,0 +1,9 @@
|
||||
---
|
||||
id: 154
|
||||
title: Claude Orchestration Capability (BETA)
|
||||
group: v1.7.0 Features
|
||||
---
|
||||
|
||||
**Purpose:** A default-off, BETA, Claude-only capability that adopts Claude Code's Workflow tool for parallel sub-agent orchestration (#1143).
|
||||
|
||||
**Reference:** [The Claude orchestration capability](explanation/claude-orchestration-capability.md)
|
||||
16
docs/features/cli-tools.md
Normal file
16
docs/features/cli-tools.md
Normal file
@@ -0,0 +1,16 @@
|
||||
---
|
||||
id: 35
|
||||
title: CLI Tools
|
||||
group: Infrastructure Features
|
||||
---
|
||||
|
||||
**Purpose:** Programmatic utilities for workflows and agents, replacing repetitive inline bash patterns.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-CLI-01: System MUST provide atomic commands for state, config, phase, roadmap operations
|
||||
- REQ-CLI-02: System MUST provide compound `init` commands that load all context for each workflow
|
||||
- REQ-CLI-03: System MUST support `--raw` flag for machine-readable output
|
||||
- REQ-CLI-04: System MUST support `--cwd` flag for sandboxed subagent operation
|
||||
- REQ-CLI-05: All operations MUST use forward-slash paths on Windows
|
||||
|
||||
**Command Categories:** State (11 subcommands), Phase (5), Roadmap (3), Verify (8), Template (2), Frontmatter (4), Scaffold (4), Init (12), Validate (2), Progress, Stats, Todo
|
||||
33
docs/features/code-review-pipeline.md
Normal file
33
docs/features/code-review-pipeline.md
Normal file
@@ -0,0 +1,33 @@
|
||||
---
|
||||
id: 93
|
||||
title: Code Review Pipeline
|
||||
group: v1.34.0 Features
|
||||
---
|
||||
|
||||
**Commands:** `/gsd-code-review`, `/gsd-code-review --fix`
|
||||
|
||||
**Purpose:** Structured review of source files changed during a phase, with a separate auto-fix pass that commits each fix atomically.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-REVIEW-01: `gsd-code-review` MUST scope files to the phase using SUMMARY.md and git diff fallback
|
||||
- REQ-REVIEW-02: Review MUST support three depth levels: `quick`, `standard`, `deep`
|
||||
- REQ-REVIEW-03: Findings MUST be severity-classified: Critical, Warning, Info
|
||||
- REQ-REVIEW-04: `gsd-code-review --fix` MUST read REVIEW.md and fix Critical + Warning findings by default
|
||||
- REQ-REVIEW-05: Each fix MUST be committed atomically with a descriptive message
|
||||
- REQ-REVIEW-06: `--auto` flag MUST enable fix + re-review iteration loop, capped at 3 iterations
|
||||
- REQ-REVIEW-07: Feature MUST be gated by `workflow.code_review` config flag
|
||||
|
||||
**Config:**
|
||||
| Setting | Type | Default | Description |
|
||||
|---------|------|---------|-------------|
|
||||
| `workflow.code_review` | boolean | `true` | Enable code review commands |
|
||||
| `workflow.code_review_depth` | string | `standard` | Default review depth: `quick`, `standard`, or `deep` |
|
||||
| `workflow.code_review_depth_overrides` | array | `[]` | Ordered `{ paths, depth }` rules that escalate depth for directories matched by path prefix against the changed-file set (#2554). See below. |
|
||||
|
||||
**Path-scoped code review depth overrides**
|
||||
|
||||
`workflow.code_review_depth_overrides` matches rules against the review's changed-file set by whole-segment directory-path prefix — `src/auth` matches `src/auth/token.ts` and `src/auth` itself, never `src/authfoo/x.ts` or `docs/src/auth/x.ts` — and is case-sensitive, following git.
|
||||
|
||||
Escalation is **whole-review, not per-file**: depth is a single scalar handed to the reviewer agent, not a per-file setting, so the strongest matching tier across the whole rule set applies to every file in the review — a sensitive file is never reviewed shallowly because it shared a review with an unrelated one.
|
||||
|
||||
v1 supports **directory-prefix matching only, not glob syntax**: no glob engine (`minimatch`, `picomatch`, `fast-glob`) exists in this project and none was added for this feature. A path containing `*` or `?` (e.g. `src/auth/**`) is a configuration error rather than a silent near-miss, because accepting it as sugar for a prefix would make unsupported patterns look armed when they match nothing. Every use case in the issue is expressible as a directory prefix. See [Scope code review depth by path](how-to/scope-code-review-depth-by-path.md) for the resolution order, error table, and a worked example.
|
||||
35
docs/features/codebase-mapping.md
Normal file
35
docs/features/codebase-mapping.md
Normal file
@@ -0,0 +1,35 @@
|
||||
---
|
||||
id: 27
|
||||
title: Codebase Mapping
|
||||
group: Brownfield Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-map-codebase [area]`
|
||||
|
||||
**Purpose:** Analyze an existing codebase before starting a new project or as the mapping handoff from `/gsd-onboard`, so GSD understands what exists.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-MAP-01: System MUST spawn parallel mapper agents for each analysis area
|
||||
- REQ-MAP-02: System MUST produce structured documents in `.planning/codebase/`
|
||||
- REQ-MAP-03: System MUST detect: tech stack, architecture patterns, coding conventions, concerns
|
||||
- REQ-MAP-04: Subsequent `/gsd-new-project` MUST load codebase mapping and focus questions on what's being added
|
||||
- REQ-MAP-05: Optional `[area]` argument MUST scope mapping to a specific area
|
||||
|
||||
**Produces:**
|
||||
| Document | Content |
|
||||
|----------|---------|
|
||||
| `STACK.md` | Languages, frameworks, databases, infrastructure |
|
||||
| `ARCHITECTURE.md` | Patterns, layers, data flow, boundaries |
|
||||
| `CONVENTIONS.md` | Naming, file organization, code style, testing patterns |
|
||||
| `CONCERNS.md` | Technical debt, security issues, performance bottlenecks |
|
||||
| `STRUCTURE.md` | Directory layout and file organization |
|
||||
| `TESTING.md` | Test infrastructure, coverage, patterns |
|
||||
| `INTEGRATIONS.md` | External services, APIs, third-party dependencies |
|
||||
|
||||
**Incremental remap — `--paths` (#2003):** The mapper accepts an optional
|
||||
`--paths <p1,p2,...>` scope hint. When provided, it restricts exploration
|
||||
to the listed repo-relative prefixes instead of scanning the whole tree.
|
||||
This is the pathway used by the post-execute codebase-drift gate to refresh
|
||||
only the subtrees the phase actually changed. Each produced document carries
|
||||
`last_mapped_commit` in its YAML frontmatter so drift can be measured
|
||||
against the mapping point, not HEAD.
|
||||
14
docs/features/commit-docs-guard-hook.md
Normal file
14
docs/features/commit-docs-guard-hook.md
Normal file
@@ -0,0 +1,14 @@
|
||||
---
|
||||
id: 87
|
||||
title: Commit-Docs Guard Hook
|
||||
group: v1.32 Features
|
||||
---
|
||||
|
||||
**Hook:** `gsd-commit-docs.js`
|
||||
|
||||
**Purpose:** PreToolUse hook that enforces the `commit_docs` configuration, preventing `.planning/` files from being committed when `planning.commit_docs` is `false`.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-COMMITDOCS-01: Hook MUST intercept git commit commands that stage `.planning/` files
|
||||
- REQ-COMMITDOCS-02: Hook MUST block commits containing `.planning/` files when `commit_docs` is `false`
|
||||
- REQ-COMMITDOCS-03: Hook MUST be advisory — does not block when `commit_docs` is `true` or absent
|
||||
20
docs/features/community-hooks-opt-in.md
Normal file
20
docs/features/community-hooks-opt-in.md
Normal file
@@ -0,0 +1,20 @@
|
||||
---
|
||||
id: 88
|
||||
title: Community Hooks Opt-In
|
||||
group: v1.32 Features
|
||||
---
|
||||
|
||||
**Hooks:** `gsd-validate-commit.sh`, `gsd-session-state.sh`, `gsd-phase-boundary.sh`
|
||||
|
||||
**Purpose:** Optional git and session hooks for GSD projects, gated behind `hooks.community: true` in config.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-COMMUNITY-01: All community hooks MUST be no-ops unless `hooks.community` is `true` in `.planning/config.json`
|
||||
- REQ-COMMUNITY-02: `gsd-validate-commit.sh` MUST enforce Conventional Commits format on git commit messages
|
||||
- REQ-COMMUNITY-03: `gsd-session-state.sh` MUST track session state transitions
|
||||
- REQ-COMMUNITY-04: `gsd-phase-boundary.sh` MUST enforce phase boundary checks
|
||||
|
||||
**Config:**
|
||||
| Setting | Type | Default | Description |
|
||||
|---------|------|---------|-------------|
|
||||
| `hooks.community` | boolean | `false` | Enable optional community hooks for commit validation, session state, and phase boundaries |
|
||||
11
docs/features/companion-mcp-server.md
Normal file
11
docs/features/companion-mcp-server.md
Normal file
@@ -0,0 +1,11 @@
|
||||
---
|
||||
id: 151
|
||||
title: Companion MCP Server
|
||||
group: v1.7.0 Features
|
||||
---
|
||||
|
||||
**Command:** `gsd-mcp-server`
|
||||
|
||||
**Purpose:** A companion MCP server exposing GSD over stdio JSON-RPC 2.0, covering interface points 1 and 5 (#1681).
|
||||
|
||||
**Behavior:** OpenCode installs auto-register it as `mcp.gsd` (#1682). OpenCode also gained the `opencode-subset` hook dialect plus `session.idle` handling (#1682) and now runs GSD's lifecycle safety hooks — prompt-injection guard, read-before-edit guard, and injection scanner (#1923).
|
||||
13
docs/features/complexity-triggered-refactor.md
Normal file
13
docs/features/complexity-triggered-refactor.md
Normal file
@@ -0,0 +1,13 @@
|
||||
---
|
||||
id: 159
|
||||
title: Complexity-Triggered Refactor
|
||||
group: v1.7.0 Features
|
||||
---
|
||||
|
||||
**Behavior:** An `execute:post` step measures the complexity of the files a phase touched (decision-point counting over comment- and literal-stripped source, no external dependency) and surfaces a scoped refactor proposal at `.planning/phases/<N>/<NN>-REFACTOR.md` when a function's score exceeds `refactor.complexity_threshold` or its growth over its recorded anchor exceeds `refactor.complexity_jump_delta` — whichever trips first, both reported. Trigger semantics are strictly greater (ESLint's `complexity: {max: N}` convention), so a score exactly equal to the threshold does not trigger. The anchor is set the first time a function is observed and moves only when the proposal is dispositioned via `refactor accept` or `refactor decline` — never when the score alone improves — so the jump delta is cumulative growth since the last conscious decision about that function, not the change made in a single phase. Advisory by default: the proposal is informational only, never edits code, and never blocks. Opt-in `refactor.trigger_strict` records an untriaged proposal as an open `deviation` entry in the broken-windows ledger (#1950) instead — it does not block on its own; ship-blocking is broken-windows' existing `ship:pre` gate, enabled separately with `workflow.windows_enforce`. Without broken-windows installed, strict mode still records the proposal locally and says so. Enabling `refactor.trigger_strict` without `workflow.windows_enforce` also on (or with broken-windows absent) surfaces a typed `refactor_strict_not_enforcing` warning on every triggering evaluate, naming the exact remediation, so this enforcement gap is never silent. A declined proposal resolves its ledger entry as `waived` with the recorded reason; an accepted one resolves as `fixed`. The metric is approximate by construction: biased against a flat `switch`, blind to nesting depth, JS/TS-family only, and a renamed function loses its anchor (issue #1953).
|
||||
|
||||
**Commands:** `gsd-tools refactor evaluate | status | accept | decline`.
|
||||
|
||||
**Config:** `refactor.trigger_enabled` (master gate, default `false`), `refactor.complexity_threshold` (default `15`), `refactor.complexity_jump_delta` (default `5`), `refactor.trigger_strict` (default `false`). See [Configuration Reference](CONFIGURATION.md#refactor-trigger-settings).
|
||||
|
||||
**Backward compatibility:** Off by default. When `refactor.trigger_enabled` is `false` the hook never runs and writes nothing; a project that never enables it is completely unaffected.
|
||||
15
docs/features/configurable-claudemd-path.md
Normal file
15
docs/features/configurable-claudemd-path.md
Normal file
@@ -0,0 +1,15 @@
|
||||
---
|
||||
id: 115
|
||||
title: Configurable CLAUDE.md Path
|
||||
group: v1.36.0 Features
|
||||
---
|
||||
|
||||
**Purpose:** Allow projects to store their CLAUDE.md in a non-root location. The `claude_md_path` config key controls where `/gsd-profile-user` and related commands write the generated CLAUDE.md file.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-CMDPATH-01: `claude_md_path` defaults to `./.claude/CLAUDE.md` (a valid project-scoped memory location; changed from `./CLAUDE.md` in v1.5 per [#1098](https://github.com/open-gsd/gsd-core/issues/1098) so generated content does not pollute a hand-crafted repo-root `CLAUDE.md`)
|
||||
- REQ-CMDPATH-02: Profile generation commands read the path from config and write to the specified location
|
||||
- REQ-CMDPATH-03: Relative paths are resolved from the project root
|
||||
- REQ-CMDPATH-04: `generate-claude-md` never overwrites an existing instruction file that lacks GSD section markers (a hand-crafted file) unless `--force` is passed
|
||||
|
||||
**Configuration:** `claude_md_path`
|
||||
20
docs/features/context-reduction.md
Normal file
20
docs/features/context-reduction.md
Normal file
@@ -0,0 +1,20 @@
|
||||
---
|
||||
id: 74
|
||||
title: Context Reduction
|
||||
group: v1.32 Features
|
||||
---
|
||||
|
||||
**Part of:** prompt assembly pipeline
|
||||
|
||||
**Purpose:** Reduce context prompt sizes through markdown truncation and cache-friendly prompt ordering.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-CTXRED-01: System MUST truncate oversized markdown artifacts to fit within context budgets
|
||||
- REQ-CTXRED-02: System MUST order prompts for cache-friendly assembly (stable prefixes first)
|
||||
- REQ-CTXRED-03: Reduction MUST preserve essential information (headings, requirements, task structure)
|
||||
- REQ-CTXRED-04: Skill `description:` fields MUST be ≤ 100 chars; enforced by `npm run lint:descriptions` (see `scripts/lint-descriptions.cjs` and `tests/skill-frontmatter-contract.test.cjs`)
|
||||
|
||||
**Process:**
|
||||
1. **Measure** — Calculate total prompt size for the workflow
|
||||
2. **Truncate** — Apply markdown-aware truncation to oversized artifacts
|
||||
3. **Order** — Arrange prompt sections for optimal KV-cache reuse
|
||||
15
docs/features/context-window-aware-prompt-thinning.md
Normal file
15
docs/features/context-window-aware-prompt-thinning.md
Normal file
@@ -0,0 +1,15 @@
|
||||
---
|
||||
id: 114
|
||||
title: Context-Window-Aware Prompt Thinning
|
||||
group: v1.36.0 Features
|
||||
---
|
||||
|
||||
**Purpose:** Reduce static prompt overhead by ~40% for models with context windows under 200K tokens. Extended examples and anti-pattern lists are extracted from agent definitions into reference files loaded on demand via `@` required_reading.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-THIN-01: When `CONTEXT_WINDOW < 200000`, executor and planner agent prompts omit inline examples
|
||||
- REQ-THIN-02: Extracted content lives in `references/executor-examples.md` and `references/planner-antipatterns.md`
|
||||
- REQ-THIN-03: Standard (200K-500K) and enriched (500K+) tiers are unaffected
|
||||
- REQ-THIN-04: Core rules and decision logic remain inline; only verbose examples are extracted
|
||||
|
||||
**Reference files:** `executor-examples.md`, `planner-antipatterns.md`
|
||||
21
docs/features/context-window-monitoring.md
Normal file
21
docs/features/context-window-monitoring.md
Normal file
@@ -0,0 +1,21 @@
|
||||
---
|
||||
id: 22
|
||||
title: Context Window Monitoring
|
||||
group: Context Engineering Features
|
||||
---
|
||||
|
||||
**Purpose:** Prevent context rot by alerting both user and agent when context is running low.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-CTX-01: Statusline MUST display context usage percentage to user
|
||||
- REQ-CTX-02: Context monitor MUST inject agent-facing warnings at ≤35% remaining (WARNING)
|
||||
- REQ-CTX-03: Context monitor MUST inject agent-facing warnings at ≤25% remaining (CRITICAL)
|
||||
- REQ-CTX-04: Warnings MUST debounce (5 tool uses between repeated warnings)
|
||||
- REQ-CTX-05: Severity escalation (WARNING→CRITICAL) MUST bypass debounce
|
||||
- REQ-CTX-06: Context monitor MUST differentiate GSD-active vs non-GSD-active projects
|
||||
- REQ-CTX-07: Warnings MUST be advisory, never imperative commands that override user preferences
|
||||
- REQ-CTX-08: All hooks MUST fail silently and never block tool execution
|
||||
|
||||
**Architecture:** Two-part bridge system:
|
||||
1. Statusline writes metrics to `/tmp/claude-ctx-{session}.json`
|
||||
2. Context monitor reads metrics and injects `additionalContext` warnings
|
||||
16
docs/features/context-window-utilization-guard.md
Normal file
16
docs/features/context-window-utilization-guard.md
Normal file
@@ -0,0 +1,16 @@
|
||||
---
|
||||
id: 124
|
||||
title: Context-Window Utilization Guard
|
||||
group: v1.40.0 Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-health --context`
|
||||
|
||||
**Purpose:** Quality guard against context-window saturation. Two thresholds: 60 % utilization warns ("consider `/gsd-thread`"), 70 % is critical ("reasoning quality may degrade"; matches the fracture-point per recent context-attention research).
|
||||
|
||||
**Requirements:**
|
||||
- REQ-CTX-GUARD-01: `/gsd-health --context` prints a structured status line with current utilization, threshold tier (`ok` / `warn` / `critical`), and a remediation suggestion.
|
||||
- REQ-CTX-GUARD-02: The same triage is exposed as `gsd-tools.cjs validate context --tokens-used <int> --context-window <int>` — a structured envelope for status-line and hook callers (#125). Both flags are required; the handler returns the same `{ percent, state }` envelope as the pure classifier in REQ-CTX-GUARD-03.
|
||||
- REQ-CTX-GUARD-03: The classifier (`bin/lib/context-utilization.cjs`) is pure: input `(tokensUsed, contextWindow)`, output `{ percent, state }`. Easy to unit-test, easy to reuse from any caller.
|
||||
|
||||
**Reference issue:** [#2792](https://github.com/open-gsd/gsd-core/issues/2792)
|
||||
18
docs/features/cross-ai-execution-delegation.md
Normal file
18
docs/features/cross-ai-execution-delegation.md
Normal file
@@ -0,0 +1,18 @@
|
||||
---
|
||||
id: 110
|
||||
title: Cross-AI Execution Delegation
|
||||
group: v1.36.0 Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-execute-phase N --cross-ai`
|
||||
|
||||
**Purpose:** Delegate individual plans to an external AI runtime for execution. Plans with `cross_ai: true` in their frontmatter (or all plans when `--cross-ai` is used) are sent to the configured command via stdin. Successfully handled plans are removed from the normal executor queue.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-CROSSAI-01: `--cross-ai` forces all plans through cross-AI; `--no-cross-ai` disables it
|
||||
- REQ-CROSSAI-02: `workflow.cross_ai_execution: true` and plan frontmatter `cross_ai: true` required for per-plan activation
|
||||
- REQ-CROSSAI-03: Task prompt is piped via stdin to prevent injection
|
||||
- REQ-CROSSAI-04: Dirty working tree produces a warning before execution
|
||||
- REQ-CROSSAI-05: On failure, user chooses: retry, skip (fall back to normal executor), or abort
|
||||
|
||||
**Configuration:** `workflow.cross_ai_execution`, `workflow.cross_ai_command`, `workflow.cross_ai_timeout`
|
||||
34
docs/features/cross-ai-peer-review.md
Normal file
34
docs/features/cross-ai-peer-review.md
Normal file
@@ -0,0 +1,34 @@
|
||||
---
|
||||
id: 42
|
||||
title: Cross-AI Peer Review
|
||||
group: v1.27 Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-review --phase N [--gemini] [--claude] [--codex] [--coderabbit] [--opencode] [--qwen] [--cursor] [--agy] [--antigravity] [--ollama] [--lm-studio] [--llama-cpp] [--kimi-code] [--all]`
|
||||
|
||||
**Purpose:** Invoke external AI CLIs (Gemini, Claude, Codex, CodeRabbit, OpenCode, Qwen Code, Cursor, Antigravity, Kimi Code) and local OpenAI-compatible servers (Ollama, LM Studio, llama.cpp) to independently review phase plans. Produces structured REVIEWS.md with per-reviewer feedback.
|
||||
|
||||
Each reviewer is a **declared lane**: its binary, prompt and output channels, timeout, availability probe, and empty-output policy come from a capability manifest rather than hand-written per-CLI logic, so a reviewer can be shipped as an installable capability instead of a core change.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-REVIEW-01: System MUST detect available AI CLIs on the system
|
||||
- REQ-REVIEW-02: System MUST build a structured review prompt from phase plans
|
||||
- REQ-REVIEW-03: System MUST invoke each selected CLI independently
|
||||
- REQ-REVIEW-04: System MUST collect responses and produce `REVIEWS.md`
|
||||
- REQ-REVIEW-05: Reviews MUST be consumable by `/gsd-plan-phase --reviews`
|
||||
- REQ-REVIEW-06: System MUST support project-level no-flag defaults via `review.default_reviewers`
|
||||
- REQ-REVIEW-07: Reviewer precedence MUST be explicit flags > `--all` > `review.default_reviewers` > all detected reviewers
|
||||
|
||||
**Produces:** `{phase}-REVIEWS.md` — Per-reviewer structured feedback
|
||||
|
||||
**User configuration note:**
|
||||
- Set `review.default_reviewers` in `.planning/config.json` (or via `gsd config-set`) to control no-flag `/gsd-review` fan-out.
|
||||
- `review.default_reviewers` may include configured `review.reviewer_instances` names; each instance runs as an independent reviewer identity backed by its configured adapter/model. Instance names are not CLI flags.
|
||||
- Use `--all` for a full pre-merge sweep without changing project defaults.
|
||||
- For local model servers with small context windows, set `review.max_prompt_tokens_per_reviewer` to auto-trim prompts per reviewer — see [Prompt budgets for small-context reviewers](../docs/CONFIGURATION.md#prompt-budgets-for-small-context-reviewers) in CONFIGURATION.md.
|
||||
|
||||
**Why record which model produced a review (#2295):** `reviewers:` in the frontmatter recorded which CLIs ran, but not which model each one resolved to. Without a pin, the model is whatever the CLI's own config or internal default happens to pick, so a "Codex vs Antigravity" comparison could quietly be a frontier model against a cheap-tier default with nothing in the record to say so — and a CLI update, or an unrelated config edit, could silently make past and future reviews incomparable.
|
||||
|
||||
The fix records the model *and its provenance*. Provenance is what makes the value trustworthy: `pinned` (from `review.models.<slug>`) is certain, while `banner` and `transcript` are recovered from third-party CLI output this project does not own — a startup banner or an undocumented session log.
|
||||
|
||||
That third-party dependence is a real trade-off, held honestly rather than papered over: the `banner` and `transcript` arms read formats GSD does not control, so they are best-effort by design and degrade to `unknown` rather than guessing or failing the run. A recorded `unknown` is a real answer — a wrong model name attributed to a review would be worse than none.
|
||||
15
docs/features/cross-phase-regression-gate.md
Normal file
15
docs/features/cross-phase-regression-gate.md
Normal file
@@ -0,0 +1,15 @@
|
||||
---
|
||||
id: 20
|
||||
title: Cross-Phase Regression Gate
|
||||
group: Quality Assurance Features
|
||||
---
|
||||
|
||||
**Purpose:** Prevent regressions from compounding across phases by running prior phases' test suites after execution.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-REGR-01: System MUST run test suites from all completed prior phases after phase execution
|
||||
- REQ-REGR-02: System MUST report any test failures as cross-phase regressions
|
||||
- REQ-REGR-03: Regressions MUST be surfaced before post-execution verification
|
||||
- REQ-REGR-04: System MUST identify which prior phase's tests were broken
|
||||
|
||||
**When:** Runs automatically during `/gsd-execute-phase` before the verifier step.
|
||||
20
docs/features/custom-ship-pr-body-sections.md
Normal file
20
docs/features/custom-ship-pr-body-sections.md
Normal file
@@ -0,0 +1,20 @@
|
||||
---
|
||||
id: 135
|
||||
title: Custom Ship PR Body Sections
|
||||
group: v1.42.1 Features
|
||||
---
|
||||
|
||||
**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)
|
||||
14
docs/features/debug-diagnose-flag.md
Normal file
14
docs/features/debug-diagnose-flag.md
Normal file
@@ -0,0 +1,14 @@
|
||||
---
|
||||
id: 76
|
||||
title: Debug `--diagnose` Flag
|
||||
group: v1.32 Features
|
||||
---
|
||||
|
||||
**Flag:** `/gsd-debug --diagnose`
|
||||
|
||||
**Purpose:** Diagnosis-only mode that investigates without attempting fixes.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-DIAG-01: System MUST perform full debug investigation (hypotheses, evidence, root cause)
|
||||
- REQ-DIAG-02: System MUST NOT attempt any code modifications
|
||||
- REQ-DIAG-03: System MUST produce a diagnostic report with findings and recommended fixes
|
||||
19
docs/features/debug-system.md
Normal file
19
docs/features/debug-system.md
Normal file
@@ -0,0 +1,19 @@
|
||||
---
|
||||
id: 28
|
||||
title: Debug System
|
||||
group: Utility Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-debug [description]`
|
||||
|
||||
**Purpose:** Systematic debugging with persistent state across context resets.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-DEBUG-01: System MUST create debug session file in `.planning/debug/`
|
||||
- REQ-DEBUG-02: System MUST track hypotheses, evidence, and eliminated theories
|
||||
- REQ-DEBUG-03: System MUST persist state so debugging survives context resets
|
||||
- REQ-DEBUG-04: System MUST require human verification before marking resolved
|
||||
- REQ-DEBUG-05: Resolved sessions MUST append to `.planning/debug/knowledge-base.md`
|
||||
- REQ-DEBUG-06: Knowledge base MUST be consulted on new debug sessions to prevent re-investigation
|
||||
|
||||
**Debug Session States:** `gathering` → `investigating` → `fixing` → `verifying` → `awaiting_human_verify` → `resolved`
|
||||
38
docs/features/developer-profiling.md
Normal file
38
docs/features/developer-profiling.md
Normal file
@@ -0,0 +1,38 @@
|
||||
---
|
||||
id: 38
|
||||
title: Developer Profiling
|
||||
group: Infrastructure Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-profile-user [--questionnaire] [--refresh]`
|
||||
|
||||
**Purpose:** Analyze Claude Code session history to build behavioral profiles across 8 dimensions, generating artifacts that personalize Claude's responses to the developer's style.
|
||||
|
||||
**Dimensions:**
|
||||
1. Communication style (terse vs verbose, formal vs casual)
|
||||
2. Decision patterns (rapid vs deliberate, risk tolerance)
|
||||
3. Debugging approach (systematic vs intuitive, log preference)
|
||||
4. UX preferences (design sensibility, accessibility awareness)
|
||||
5. Vendor/technology choices (framework preferences, ecosystem familiarity)
|
||||
6. Frustration triggers (what causes friction in workflows)
|
||||
7. Learning style (documentation vs examples, depth preference)
|
||||
8. Explanation depth (high-level vs implementation detail)
|
||||
|
||||
**Generated Artifacts:**
|
||||
- `USER-PROFILE.md` — Full behavioral profile with evidence citations
|
||||
- `CLAUDE.md` profile section — Auto-discovered by Claude Code
|
||||
|
||||
**Flags:**
|
||||
- `--questionnaire` — Interactive questionnaire fallback when session history is unavailable
|
||||
- `--refresh` — Re-analyze sessions and regenerate profile
|
||||
|
||||
**Pipeline Modules:**
|
||||
- `profile-pipeline.cjs` — Session scanning, message extraction, sampling
|
||||
- `profile-output.cjs` — Profile rendering, questionnaire, artifact generation
|
||||
- `gsd-user-profiler` agent — Behavioral analysis from session data
|
||||
|
||||
**Requirements:**
|
||||
- REQ-PROF-01: Session analysis MUST cover at least 8 behavioral dimensions
|
||||
- REQ-PROF-02: Profile MUST cite evidence from actual session messages
|
||||
- REQ-PROF-03: Questionnaire MUST be available as fallback when no session history exists
|
||||
- REQ-PROF-04: Generated artifacts MUST be discoverable by Claude Code (CLAUDE.md integration)
|
||||
11
docs/features/discoverability-registries.md
Normal file
11
docs/features/discoverability-registries.md
Normal file
@@ -0,0 +1,11 @@
|
||||
---
|
||||
id: 150
|
||||
title: Discoverability Registries
|
||||
group: v1.7.0 Features
|
||||
---
|
||||
|
||||
**Purpose:** Two non-endorsing catalogs for third-party extensions (#2182).
|
||||
|
||||
**Behavior:** The **Community Capability Registry** (#2188) lists third-party Feature Capabilities installed with `gsd capability install`; the **EoS Registry** (#2193) lists third-party host integrations built on the ADR-1239 interface. Every entry embeds a live release badge and links to a GitHub Discussion. Registration is a documentation PR, regenerated with `npm run gen:registry`.
|
||||
|
||||
**Reference:** [GSD Registries](registries/README.md)
|
||||
19
docs/features/discuss-chain-mode.md
Normal file
19
docs/features/discuss-chain-mode.md
Normal file
@@ -0,0 +1,19 @@
|
||||
---
|
||||
id: 62
|
||||
title: Discuss Chain Mode
|
||||
group: v1.31 Features
|
||||
---
|
||||
|
||||
**Flag:** `/gsd-discuss-phase <N> --chain`
|
||||
|
||||
**Purpose:** Auto-chain discuss, plan, and execute phases in one flow to reduce manual command sequencing.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-CHAIN-01: System MUST auto-chain discuss → plan → execute when `--chain` flag is provided
|
||||
- REQ-CHAIN-02: System MUST respect all gate settings between chained phases
|
||||
- REQ-CHAIN-03: System MUST halt the chain if any phase fails
|
||||
|
||||
**Process:**
|
||||
1. **Discuss** — Run discuss-phase to gather context
|
||||
2. **Plan** — Automatically invoke plan-phase with gathered context
|
||||
3. **Execute** — Automatically invoke execute-phase with generated plan
|
||||
14
docs/features/discuss-phase-power-flag.md
Normal file
14
docs/features/discuss-phase-power-flag.md
Normal file
@@ -0,0 +1,14 @@
|
||||
---
|
||||
id: 75
|
||||
title: Discuss-Phase `--power` Flag
|
||||
group: v1.32 Features
|
||||
---
|
||||
|
||||
**Flag:** `/gsd-discuss-phase --power`
|
||||
|
||||
**Purpose:** File-based bulk question answering for discuss-phase, enabling batch input from a prepared answers file.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-POWER-01: System MUST accept a file containing pre-written answers to discussion questions
|
||||
- REQ-POWER-02: System MUST map answers to the corresponding gray area questions
|
||||
- REQ-POWER-03: System MUST produce CONTEXT.md identical to interactive discuss-phase
|
||||
12
docs/features/discussion-audit-trail.md
Normal file
12
docs/features/discussion-audit-trail.md
Normal file
@@ -0,0 +1,12 @@
|
||||
---
|
||||
id: 48
|
||||
title: Discussion Audit Trail
|
||||
group: v1.27 Features
|
||||
---
|
||||
|
||||
**Purpose:** Auto-generate `DISCUSSION-LOG.md` during `/gsd-discuss-phase` for full audit trail of decisions made during discussion.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-DISCLOG-01: System MUST auto-generate DISCUSSION-LOG.md during discuss-phase
|
||||
- REQ-DISCLOG-02: Log MUST capture questions asked, options presented, and decisions made
|
||||
- REQ-DISCLOG-03: Decision IDs MUST enable traceability from discuss-phase to plan-phase
|
||||
24
docs/features/documentation-generation.md
Normal file
24
docs/features/documentation-generation.md
Normal file
@@ -0,0 +1,24 @@
|
||||
---
|
||||
id: 61
|
||||
title: Documentation Generation
|
||||
group: v1.31 Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-docs-update`
|
||||
|
||||
**Purpose:** Generate and verify project documentation with accuracy checks.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-DOCS-01: System MUST spawn `gsd-doc-writer` agent to generate documentation
|
||||
- REQ-DOCS-02: System MUST spawn `gsd-doc-verifier` agent to check accuracy
|
||||
- REQ-DOCS-03: System MUST verify generated documentation against actual implementation
|
||||
|
||||
**Produces:**
|
||||
| Artifact | Description |
|
||||
|----------|-------------|
|
||||
| Updated project documentation | Generated and verified documentation files |
|
||||
|
||||
**Process:**
|
||||
1. **Generate** — Spawn `gsd-doc-writer` to create or update documentation from implementation
|
||||
2. **Verify** — Spawn `gsd-doc-verifier` to check documentation accuracy against codebase
|
||||
3. **Output** — Produce verified documentation with accuracy annotations
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
id: 127
|
||||
title: Dynamic Routing with Failure-Tier Escalation
|
||||
group: v1.41.0 Features
|
||||
---
|
||||
|
||||
**Purpose:** Pay for the cheap tier by default; escalate to a more capable model automatically when the orchestrator detects a soft failure (verification inconclusive, plan-check FLAG, etc.).
|
||||
|
||||
**Config key:** `dynamic_routing` in `.planning/config.json`
|
||||
|
||||
**Behavior:**
|
||||
- `enabled: false` (default) — feature is off; all agents use the precedence chain unchanged.
|
||||
- `enabled: true` — the resolver picks `tier_models[default_tier]` for the first spawn and escalates one tier up on orchestrator-detected soft failure, capped by `max_escalations`.
|
||||
|
||||
**Composition:** `model_overrides` always wins; `dynamic_routing.tier_models[<tier>]` resolves above `models.<phase_type>` and `model_profile`.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-DYNROUTE-01: `dynamic_routing.enabled` acts as a master switch; when `false` or block is absent, zero behavior change.
|
||||
- REQ-DYNROUTE-02: New resolver `resolveModelForTier(cwd, agent, attempt)` in `core.cjs` is the single call-site for orchestrator integration.
|
||||
- REQ-DYNROUTE-03: `max_escalations` caps the escalation chain to prevent runaway cost.
|
||||
|
||||
**Reference issue:** [#3024](https://github.com/open-gsd/gsd-core/pull/3031)
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
id: 149
|
||||
title: Embeddable Orchestration System (Host-Integration Interface)
|
||||
group: v1.7.0 Features
|
||||
---
|
||||
|
||||
**Purpose:** Express every host integration against one public, versioned contract (ADR-1239 Phase A, #1690) instead of bespoke per-host wiring, so onboarding a new host becomes additive descriptor work.
|
||||
|
||||
**Behavior:** The interface exposes six interface points (`command`, `dispatch`, `model`, `hooks`, `state`, `artifact`), eight negotiated axes, and a `PROTOCOL_VERSION` handshake that negotiates down to `min(host, engine)`. In 1.7.0, 14 runtimes were migrated onto the interface via imperative adapters (OpenCode #2087, Cursor #2089, Cline #2090, Hermes #2091, Qwen #2092, Kilo #2093, Trae #2094, Kimi #2095, Antigravity #2096, Augment #2097), a declarative adapter (Codex #2088), plus full lifecycle-hook wiring for CodeBuddy (#2098), GitHub Copilot (#2099), and Windsurf (#2100). Descriptors gained an `extensionEvents` vocabulary (#1946), and `/gsd-surface` now reproduces a runtime's agent output byte-for-byte from the installer's descriptors (#1575).
|
||||
|
||||
**New runtimes:** ZCode (Z.ai — Agentic Development Environment for GLM-5.2, #1925), pi (`npx @opengsd/gsd-core --pi`, #2102), and a repo-local VS Code extension driven through the adapter (#2103). The retired Gemini CLI now redirects to Antigravity CLI, its official successor (#1928).
|
||||
|
||||
**Reference:** [The Embeddable Orchestration System](explanation/embeddable-orchestration-system.md) · [Host-Integration Interface](reference/host-integration-interface.md) · [Interface versioning policy](explanation/interface-versioning-policy.md)
|
||||
18
docs/features/end-of-phase-human-verification-mode.md
Normal file
18
docs/features/end-of-phase-human-verification-mode.md
Normal file
@@ -0,0 +1,18 @@
|
||||
---
|
||||
id: 138
|
||||
title: End-of-Phase Human Verification Mode
|
||||
group: v1.42.1 Features
|
||||
---
|
||||
|
||||
**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 `<verify><human-check>` 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](../gsd-core/references/checkpoints.md)
|
||||
21
docs/features/execution-context-profiles.md
Normal file
21
docs/features/execution-context-profiles.md
Normal file
@@ -0,0 +1,21 @@
|
||||
---
|
||||
id: 91
|
||||
title: Execution Context Profiles
|
||||
group: v1.34.0 Features
|
||||
---
|
||||
|
||||
**Config:** `context_profile`
|
||||
|
||||
**Purpose:** Select a pre-configured execution context (mode, model, workflow settings) tuned for a specific type of work without manually adjusting individual settings.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-CTX-01: `dev` profile MUST optimize for iterative development (balanced model, plan_check enabled)
|
||||
- REQ-CTX-02: `research` profile MUST optimize for research-heavy work (higher model tier, research enabled)
|
||||
- REQ-CTX-03: `review` profile MUST optimize for code review work (verifier and code_review enabled)
|
||||
|
||||
**Available profiles:** `dev`, `research`, `review`
|
||||
|
||||
**Config:**
|
||||
| Setting | Type | Default | Description |
|
||||
|---------|------|---------|-------------|
|
||||
| `context_profile` | string | (none) | Execution context preset: `dev`, `research`, or `review` |
|
||||
23
docs/features/execution-hardening.md
Normal file
23
docs/features/execution-hardening.md
Normal file
@@ -0,0 +1,23 @@
|
||||
---
|
||||
id: 39
|
||||
title: Execution Hardening
|
||||
group: Infrastructure Features
|
||||
---
|
||||
|
||||
**Purpose:** Three additive quality improvements to the execution pipeline that catch cross-plan failures before they cascade.
|
||||
|
||||
**Components:**
|
||||
|
||||
**1. Pre-Wave Dependency Check** (execute-phase)
|
||||
Before spawning wave N+1, verify key-links from prior wave artifacts exist and are wired correctly. Catches cross-plan dependency gaps before they cascade into downstream failures.
|
||||
|
||||
**2. Cross-Plan Data Contracts — Dimension 9** (plan-checker)
|
||||
New analysis dimension that checks plans sharing data pipelines have compatible transformations. Flags when one plan strips data that another plan needs in its original form.
|
||||
|
||||
**3. Export-Level Spot Check** (verify-phase)
|
||||
After Level 3 wiring verification passes, spot-check individual exports for actual usage. Catches dead stores that exist in wired files but are never called.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-HARD-01: Pre-wave check MUST verify key-links from all prior wave artifacts before spawning next wave
|
||||
- REQ-HARD-02: Cross-plan contract check MUST detect incompatible data transformations between plans
|
||||
- REQ-HARD-03: Export spot-check MUST identify dead stores in wired files
|
||||
25
docs/features/existing-codebase-onboarding.md
Normal file
25
docs/features/existing-codebase-onboarding.md
Normal file
@@ -0,0 +1,25 @@
|
||||
---
|
||||
id: 27b
|
||||
title: Existing Codebase Onboarding
|
||||
group: Brownfield Features
|
||||
order: 27.1
|
||||
---
|
||||
|
||||
**Command:** `/gsd-onboard [--fast] [--text]`
|
||||
|
||||
**Purpose:** Guide first-time setup for an existing repository by checking brownfield state, routing through codebase mapping and docs ingest, then handing off to project initialization without silently overwriting planning artifacts.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-ONBOARD-01: System MUST detect existing code, package manifests, planning documents, partial `.planning/` state, and complete or missing codebase-map files.
|
||||
- REQ-ONBOARD-02: System MUST hand off to `/gsd-map-codebase` or `/gsd-map-codebase --fast` when brownfield code lacks the required `.planning/codebase/` map files; fast-map readiness is partial and MUST NOT be treated as sufficient for `/gsd-new-project`.
|
||||
- REQ-ONBOARD-03: System MUST offer `/gsd-ingest-docs` before `/gsd-new-project` when ADR/PRD/SPEC/RFC candidates exist and no project exists.
|
||||
- REQ-ONBOARD-04: System MUST refuse to report onboarding complete until `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, and `STATE.md` all exist.
|
||||
- REQ-ONBOARD-05: System MUST create or confirm `.planning/onboarding/SUMMARY.md` only after project setup exists.
|
||||
- REQ-ONBOARD-06: System MUST support `--text` for numbered plain-text gates on runtimes without interactive menus.
|
||||
|
||||
**Produces:**
|
||||
| Artifact | Description |
|
||||
|----------|-------------|
|
||||
| `.planning/codebase/` | Codebase map produced by the `/gsd-map-codebase` handoff |
|
||||
| `.planning/PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md` | Planning setup produced by `/gsd-new-project` or `/gsd-ingest-docs` |
|
||||
| `.planning/onboarding/SUMMARY.md` | Onboarding status, artifact index, and next-command summary |
|
||||
18
docs/features/external-code-review-command.md
Normal file
18
docs/features/external-code-review-command.md
Normal file
@@ -0,0 +1,18 @@
|
||||
---
|
||||
id: 109
|
||||
title: External Code Review Command
|
||||
group: v1.36.0 Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-ship` (enhanced)
|
||||
|
||||
**Purpose:** Before the manual review step in `/gsd-ship`, automatically run an external code review command if configured. The command receives the diff and phase context via stdin and returns a JSON verdict (`APPROVED` or `REVISE`). Falls through to the existing manual review flow regardless of outcome.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-EXTREVIEW-01: `workflow.code_review_command` must be set to a command string; null means skip
|
||||
- REQ-EXTREVIEW-02: Diff is generated against `BASE_BRANCH` with `--stat` summary included
|
||||
- REQ-EXTREVIEW-03: Review prompt is piped via stdin (never shell-interpolated)
|
||||
- REQ-EXTREVIEW-04: 120-second timeout; stderr captured on failure
|
||||
- REQ-EXTREVIEW-05: JSON output parsed for `verdict`, `confidence`, `summary`, `issues` fields
|
||||
|
||||
**Configuration:** `workflow.code_review_command`
|
||||
9
docs/features/external-job-capability.md
Normal file
9
docs/features/external-job-capability.md
Normal file
@@ -0,0 +1,9 @@
|
||||
---
|
||||
id: 155
|
||||
title: External-Job Capability
|
||||
group: v1.7.0 Features
|
||||
---
|
||||
|
||||
**Purpose:** A default-off capability that externalizes long-running compute as asynchronous external jobs, e.g. SLURM submission (#1165).
|
||||
|
||||
**Configuration:** `external_job.submit_timeout_ms`, `external_job.poll_timeout_ms`, `external_job.artifact_dir` (#1164)
|
||||
34
docs/features/extract-learnings.md
Normal file
34
docs/features/extract-learnings.md
Normal file
@@ -0,0 +1,34 @@
|
||||
---
|
||||
id: 112
|
||||
title: Extract Learnings
|
||||
group: v1.36.0 Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-extract-learnings N`
|
||||
|
||||
**Purpose:** Extract structured knowledge from completed phase artifacts. Reads PLAN.md and SUMMARY.md (required) plus VERIFICATION.md, UAT.md, and STATE.md (optional) to produce four categories of learnings: decisions, lessons, patterns, and surprises. Optionally captures each item to an external knowledge base via `capture_thought` tool.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-LEARN-01: Requires PLAN.md and SUMMARY.md; exits with clear error if missing
|
||||
- REQ-LEARN-02: Each extracted item includes source attribution (artifact and section)
|
||||
- REQ-LEARN-03: If `capture_thought` tool is available, captures items with `source`, `project`, and `phase` metadata
|
||||
- REQ-LEARN-04: If `capture_thought` is unavailable, completes successfully and logs that external capture was skipped
|
||||
- REQ-LEARN-05: Running twice overwrites the previous `LEARNINGS.md`
|
||||
|
||||
**Produces:** `{phase}-LEARNINGS.md` with YAML frontmatter (phase, project, counts per category, missing_artifacts)
|
||||
|
||||
**Optional integration — `capture_thought`:** `capture_thought` is a **convention, not a bundled tool**. GSD does not ship one and does not require one. The workflow checks whether any MCP server in the current session exposes a tool named `capture_thought` and, if so, calls it once per extracted learning with the signature below. If no such tool is present, the step is skipped silently and `LEARNINGS.md` remains the primary output.
|
||||
|
||||
Expected tool signature:
|
||||
```javascript
|
||||
capture_thought({
|
||||
category: "decision" | "lesson" | "pattern" | "surprise",
|
||||
phase: <phase_number>,
|
||||
content: <learning_text>,
|
||||
source: <artifact_name>
|
||||
})
|
||||
```
|
||||
|
||||
Users who run a memory / knowledge-base MCP server (for example, ExoCortex-style servers, `claude-mem`, or `mem0`-style servers) can implement this tool name to have learnings routed into their knowledge base automatically with `project`, `phase`, and `source` metadata. Everyone else can use `/gsd-extract-learnings` without any extra setup — the `LEARNINGS.md` artifact is the feature.
|
||||
|
||||
With `features.global_learnings: true`, phase completion runs the extraction for the just-completed phase automatically and copies the artifact to the global store at `~/.gsd/knowledge/` (#3683) — extraction and copy failures never block completion. With the gate off (the default), extraction stays fully manual.
|
||||
20
docs/features/fallow-structural-review-pre-pass.md
Normal file
20
docs/features/fallow-structural-review-pre-pass.md
Normal file
@@ -0,0 +1,20 @@
|
||||
---
|
||||
id: 137
|
||||
title: Fallow Structural Review Pre-Pass
|
||||
group: v1.42.1 Features
|
||||
---
|
||||
|
||||
**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)
|
||||
19
docs/features/fast-mode.md
Normal file
19
docs/features/fast-mode.md
Normal file
@@ -0,0 +1,19 @@
|
||||
---
|
||||
id: 41
|
||||
title: Fast Mode
|
||||
group: v1.27 Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-fast [task description]`
|
||||
|
||||
**Purpose:** Execute trivial tasks inline without spawning subagents or generating PLAN.md files. For tasks too small to justify planning overhead: typo fixes, config changes, small refactors, forgotten commits, simple additions.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-FAST-01: System MUST execute the task directly in the current context without subagents
|
||||
- REQ-FAST-02: System MUST produce an atomic git commit for the change
|
||||
- REQ-FAST-03: System MUST track the task in `.planning/quick/` for state consistency
|
||||
- REQ-FAST-04: System MUST NOT be used for tasks requiring research, multi-step planning, or verification
|
||||
|
||||
**When to use vs `/gsd-quick`:**
|
||||
- `/gsd-fast` — One-sentence tasks executable in under 2 minutes (typo, config change, small addition)
|
||||
- `/gsd-quick` — Anything needing research, multi-step planning, or verification
|
||||
27
docs/features/forensics.md
Normal file
27
docs/features/forensics.md
Normal file
@@ -0,0 +1,27 @@
|
||||
---
|
||||
id: 49
|
||||
title: Forensics
|
||||
group: v1.28 Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-forensics [description]`
|
||||
|
||||
**Purpose:** Post-mortem investigation of failed or stuck GSD workflows.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-FORENSICS-01: System MUST analyze git history for anomalies (stuck loops, long gaps, repeated commits)
|
||||
- REQ-FORENSICS-02: System MUST check artifact integrity (completed phases have expected files)
|
||||
- REQ-FORENSICS-03: System MUST generate a markdown report saved to `.planning/forensics/`
|
||||
- REQ-FORENSICS-04: System MUST offer to create a GitHub issue with findings
|
||||
- REQ-FORENSICS-05: System MUST NOT modify project files (read-only investigation)
|
||||
|
||||
**Produces:**
|
||||
| Artifact | Description |
|
||||
|----------|-------------|
|
||||
| `.planning/forensics/report-{timestamp}.md` | Post-mortem investigation report |
|
||||
|
||||
**Process:**
|
||||
1. **Scan** — Analyze git history for anomalies: stuck loops, long gaps between commits, repeated identical commits
|
||||
2. **Integrity Check** — Verify completed phases have expected artifact files
|
||||
3. **Report** — Generate markdown report with findings, saved to `.planning/forensics/`
|
||||
4. **Issue** — Offer to create a GitHub issue with findings for team visibility
|
||||
15
docs/features/freeform-routing.md
Normal file
15
docs/features/freeform-routing.md
Normal file
@@ -0,0 +1,15 @@
|
||||
---
|
||||
id: 12
|
||||
title: Freeform Routing
|
||||
group: Planning Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-progress --do` (see also `/gsd-manager` for interactive routing)
|
||||
|
||||
**Purpose:** Analyze freeform text and route to the appropriate GSD command.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-DO-01: System MUST parse user intent from natural language input
|
||||
- REQ-DO-02: System MUST map intent to the best matching GSD command
|
||||
- REQ-DO-03: System MUST confirm the routing with the user before executing
|
||||
- REQ-DO-04: System MUST handle project-exists vs no-project contexts differently
|
||||
23
docs/features/gates-taxonomy.md
Normal file
23
docs/features/gates-taxonomy.md
Normal file
@@ -0,0 +1,23 @@
|
||||
---
|
||||
id: 92
|
||||
title: Gates Taxonomy
|
||||
group: v1.34.0 Features
|
||||
---
|
||||
|
||||
**References:** `gsd-core/references/gates.md`
|
||||
**Agents:** plan-checker, verifier
|
||||
|
||||
**Purpose:** Define 4 canonical gate types that structure all workflow decision points, enabling plan-checker and verifier agents to apply consistent gate logic.
|
||||
|
||||
**Gate types:**
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| **Confirm** | User approves before proceeding (e.g., roadmap review) |
|
||||
| **Quality** | Automated quality check must pass (e.g., plan verification loop) |
|
||||
| **Safety** | Hard stop on detected risk or policy violation |
|
||||
| **Transition** | Phase or milestone boundary acknowledgment |
|
||||
|
||||
**Requirements:**
|
||||
- REQ-GATES-01: plan-checker MUST classify each checkpoint as one of the 4 gate types
|
||||
- REQ-GATES-02: verifier MUST apply gate logic appropriate to the gate type
|
||||
- REQ-GATES-03: Hard stop safety gates MUST never be bypassed by `--auto` flags
|
||||
27
docs/features/git-integration.md
Normal file
27
docs/features/git-integration.md
Normal file
@@ -0,0 +1,27 @@
|
||||
---
|
||||
id: 34
|
||||
title: Git Integration
|
||||
group: Infrastructure Features
|
||||
---
|
||||
|
||||
**Purpose:** Atomic commits, branching strategies, and clean history management.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-GIT-01: Each task MUST get its own atomic commit
|
||||
- REQ-GIT-02: Commit messages MUST follow structured format: `type(scope): description`
|
||||
- REQ-GIT-03: System MUST support 3 branching strategies: `none`, `phase`, `milestone`
|
||||
- REQ-GIT-04: Phase strategy MUST create one branch per phase
|
||||
- REQ-GIT-05: Milestone strategy MUST create one branch per milestone
|
||||
- REQ-GIT-06: Complete-milestone MUST offer squash merge (recommended) or merge with history
|
||||
- REQ-GIT-07: System MUST respect `commit_docs` setting for `.planning/` files
|
||||
- REQ-GIT-08: System MUST auto-detect `.planning/` in `.gitignore` and skip commits
|
||||
|
||||
**Commit Format:**
|
||||
```
|
||||
type(phase-plan): description
|
||||
|
||||
# Examples:
|
||||
docs(08-02): complete user registration plan
|
||||
feat(08-02): add email confirmation flow
|
||||
fix(03-01): correct auth token expiry
|
||||
```
|
||||
22
docs/features/global-learnings-store.md
Normal file
22
docs/features/global-learnings-store.md
Normal file
@@ -0,0 +1,22 @@
|
||||
---
|
||||
id: 89
|
||||
title: Global Learnings Store
|
||||
group: v1.34.0 Features
|
||||
---
|
||||
|
||||
**Commands:** Auto-triggered at phase completion; consumed by planner
|
||||
**Config:** `features.global_learnings`
|
||||
|
||||
**Purpose:** Persist cross-session, cross-project learnings in a global store so the planner agent can learn from patterns across the entire project history — not just the current session.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-LEARN-01: Learnings MUST be auto-copied from `.planning/` to the global store at phase completion
|
||||
- REQ-LEARN-02: The planner agent MUST receive relevant learnings at spawn time via injection
|
||||
- REQ-LEARN-03: Injection MUST be capped by `learnings.max_inject` to avoid context bloat
|
||||
- REQ-LEARN-04: Feature MUST be opt-in via `features.global_learnings: true`
|
||||
|
||||
**Config:**
|
||||
| Setting | Type | Default | Description |
|
||||
|---------|------|---------|-------------|
|
||||
| `features.global_learnings` | boolean | `false` | Enable cross-project learnings pipeline |
|
||||
| `learnings.max_inject` | number | (system default) | Maximum learnings entries injected into planner |
|
||||
29
docs/features/graphify-commit-based-staleness.md
Normal file
29
docs/features/graphify-commit-based-staleness.md
Normal file
@@ -0,0 +1,29 @@
|
||||
---
|
||||
id: 130
|
||||
title: Graphify Commit-Based Staleness
|
||||
group: v1.41.0 Features
|
||||
---
|
||||
|
||||
**Purpose:** Surface whether the architecture graph was built from the current commit or an older one, complementing the existing mtime-based stale signal.
|
||||
|
||||
**Command:** `/gsd-graphify status`
|
||||
|
||||
**New fields returned (graphify v0.7+ graphs):**
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `built_at_commit` | string | Commit SHA the graph was built from |
|
||||
| `current_commit` | string | Current `git HEAD` |
|
||||
| `commits_behind` | number | How many commits behind HEAD the graph is |
|
||||
| `commit_stale` | boolean \| null | `true`=stale, `false`=current, `null`=unavailable (pre-v0.7, non-git) |
|
||||
|
||||
**Rendered output (when signal is available):**
|
||||
```
|
||||
Source commit: abc1234 (3 commits behind HEAD)
|
||||
```
|
||||
|
||||
**Security:** `built_at_commit` validated as 4–40 hex chars before reaching `git` — a hostile `graph.json` cannot inject dashed options into argv.
|
||||
|
||||
**Fallback:** pre-v0.7 graphs and non-git checkouts return `commit_stale: null`; callers fall back to the existing mtime-based `stale` flag. No behavior change for existing users.
|
||||
|
||||
**Reference issue:** [#3170](https://github.com/open-gsd/gsd-core/issues/3170)
|
||||
24
docs/features/gsd-2-reverse-migration.md
Normal file
24
docs/features/gsd-2-reverse-migration.md
Normal file
@@ -0,0 +1,24 @@
|
||||
---
|
||||
id: 105
|
||||
title: GSD-2 Reverse Migration
|
||||
group: v1.35.0 Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-import --from-gsd2 [--dry-run] [--force] [--path <dir>]`
|
||||
|
||||
**Purpose:** Migrate a project from GSD-2 format (`.gsd/` directory with Milestone→Slice→Task hierarchy) back to the v1 `.planning/` format, restoring full compatibility with all GSD v1 commands.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-FROM-GSD2-01: Importer MUST read `.gsd/` from the specified or current directory
|
||||
- REQ-FROM-GSD2-02: Milestone→Slice hierarchy MUST be flattened to sequential phase numbers (M001/S01→phase 01, M001/S02→phase 02, M002/S01→phase 03, etc.)
|
||||
- REQ-FROM-GSD2-03: System MUST guard against overwriting an existing `.planning/` directory without `--force`
|
||||
- REQ-FROM-GSD2-04: `--dry-run` MUST preview all changes without writing any files
|
||||
- REQ-FROM-GSD2-05: Migration MUST produce `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, and sequential phase directories
|
||||
|
||||
**Flags:**
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--dry-run` | Preview migration output without writing files |
|
||||
| `--force` | Overwrite an existing `.planning/` directory |
|
||||
| `--path <dir>` | Specify the GSD-2 root directory |
|
||||
14
docs/features/hard-stop-safety-gates-in-gsd-progress-next.md
Normal file
14
docs/features/hard-stop-safety-gates-in-gsd-progress-next.md
Normal file
@@ -0,0 +1,14 @@
|
||||
---
|
||||
id: 101
|
||||
title: Hard Stop Safety Gates in /gsd-progress --next
|
||||
group: v1.34.0 Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-progress --next`
|
||||
|
||||
**Purpose:** Prevent `/gsd-progress --next` from entering runaway loops by adding hard stop safety gates and a consecutive-call guard that interrupts autonomous chaining when repeated identical steps are detected.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-NEXT-GATE-01: `/gsd-progress --next` MUST track consecutive same-step calls
|
||||
- REQ-NEXT-GATE-02: On repeated same-step, system MUST present a hard stop gate to the user
|
||||
- REQ-NEXT-GATE-03: User MUST explicitly confirm to continue past a hard stop gate
|
||||
17
docs/features/health-validation.md
Normal file
17
docs/features/health-validation.md
Normal file
@@ -0,0 +1,17 @@
|
||||
---
|
||||
id: 19
|
||||
title: Health Validation
|
||||
group: Quality Assurance Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-health [--repair] [--backfill]`
|
||||
|
||||
**Purpose:** Validate `.planning/` directory integrity and auto-repair issues.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-HEALTH-01: System MUST check for missing required files
|
||||
- REQ-HEALTH-02: System MUST validate configuration consistency
|
||||
- REQ-HEALTH-03: System MUST detect orphaned plans without summaries
|
||||
- REQ-HEALTH-04: System MUST check phase numbering and roadmap sync
|
||||
- REQ-HEALTH-05: `--repair` flag MUST auto-fix recoverable issues except DESTRUCTIVE-risk ones, which it MUST report but never auto-apply
|
||||
- REQ-HEALTH-06: `--backfill` flag MUST synthesize missing MILESTONES.md entries from archived milestone snapshots
|
||||
34
docs/features/hook-system.md
Normal file
34
docs/features/hook-system.md
Normal file
@@ -0,0 +1,34 @@
|
||||
---
|
||||
id: 37
|
||||
title: Hook System
|
||||
group: Infrastructure Features
|
||||
---
|
||||
|
||||
**Purpose:** Runtime event hooks for context monitoring, status display, and update checking.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-HOOK-01: Statusline MUST display model, current task, directory, and context usage
|
||||
- REQ-HOOK-02: Context monitor MUST inject agent-facing warnings at threshold levels
|
||||
- REQ-HOOK-03: Update checker MUST run in background on session start
|
||||
- REQ-HOOK-04: All hooks MUST respect `CLAUDE_CONFIG_DIR` env var
|
||||
- REQ-HOOK-05: All hooks MUST include 3-second stdin timeout guard
|
||||
- REQ-HOOK-06: All hooks MUST fail silently on any error
|
||||
- REQ-HOOK-07: Context usage MUST normalize for autocompact buffer (16.5% reserved)
|
||||
- REQ-HOOK-08: Update banner MUST be opt-in and silent unless an update is available (PR #2795)
|
||||
|
||||
**Statusline Display:**
|
||||
```text
|
||||
[⬆ /gsd-update │] model │ [current task │] directory [█████░░░░░ 50%]
|
||||
```
|
||||
|
||||
Color coding: <50% green, <65% yellow, <80% orange, ≥80% red with skull emoji
|
||||
|
||||
**Update Banner (opt-in, when GSD statusline isn't used):**
|
||||
|
||||
When the user declines (or keeps a non-GSD) statusline, the installer offers a SessionStart banner that surfaces update availability without occupying statusline real estate. The banner reads `~/.cache/gsd/gsd-update-check.json` (written by `gsd-check-update-worker.js`) and emits one line only when an update is available:
|
||||
|
||||
```text
|
||||
GSD update available: 1.39.0 → 1.40.0. Run /gsd-update.
|
||||
```
|
||||
|
||||
The banner is silent when up-to-date and rate-limits "check failed" diagnostics to once per 24 hours. Removed cleanly by `npx @opengsd/gsd-core --uninstall` or by deleting the SessionStart entry that references `gsd-update-banner.js`.
|
||||
16
docs/features/improved-prompt-injection-scanner.md
Normal file
16
docs/features/improved-prompt-injection-scanner.md
Normal file
@@ -0,0 +1,16 @@
|
||||
---
|
||||
id: 99
|
||||
title: Improved Prompt Injection Scanner
|
||||
group: v1.34.0 Features
|
||||
---
|
||||
|
||||
**Hook:** `gsd-prompt-guard.js`, `gsd-read-injection-scanner.js`
|
||||
**Script:** `scripts/prompt-injection-scan.sh`, `scripts/base64-scan.sh`
|
||||
|
||||
**Purpose:** Defense-in-depth detection of prompt injection attempts in planning artifacts and ingested content. Live hooks inline their own pattern subsets for hook independence (they do not import from `security.cts`). The CI scanner (`scanForInjection` in `security.cts`) provides a centralized engine for codebase-wide scanning in tests.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-SCAN-INJ-01: Live hooks MUST detect invisible Unicode characters (zero-width spaces, soft hyphens, Unicode tag block U+E0000–E007F)
|
||||
- REQ-SCAN-INJ-02: Live hooks MUST detect known injection patterns (instruction override, role manipulation, system-prompt extraction, fake message boundaries). Base64-decode scanning is a CI-time control (`scripts/base64-scan.sh`), not a live hook — live hooks match a base64-exfiltration phrase regex only, they do not decode.
|
||||
- REQ-SCAN-INJ-03: ~~Scanner MUST apply entropy analysis~~ — Entropy analysis (`scanEntropyAnomalies`) was removed in #2198 as dead code (zero production callers; live hooks do not perform entropy analysis). This requirement is deferred pending a maintainable live implementation.
|
||||
- REQ-SCAN-INJ-04: Scanner MUST remain advisory-only — detection is logged, not blocking
|
||||
21
docs/features/installer-migrations.md
Normal file
21
docs/features/installer-migrations.md
Normal file
@@ -0,0 +1,21 @@
|
||||
---
|
||||
id: 134
|
||||
title: Installer Migrations
|
||||
group: v1.42.1 Features
|
||||
---
|
||||
|
||||
**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)
|
||||
17
docs/features/internationalized-documentation.md
Normal file
17
docs/features/internationalized-documentation.md
Normal file
@@ -0,0 +1,17 @@
|
||||
---
|
||||
id: 57
|
||||
title: Internationalized Documentation
|
||||
group: v1.29 Features
|
||||
---
|
||||
|
||||
**Part of:** `docs/`
|
||||
|
||||
**Purpose:** Provide GSD documentation in Portuguese, Korean, and Japanese.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-I18N-01: Documentation MUST be available in Portuguese (pt), Korean (ko), and Japanese (ja)
|
||||
- REQ-I18N-02: Translations MUST stay synchronized with English source documents
|
||||
|
||||
**Process:**
|
||||
1. **Translate** — Convert core documentation into target languages
|
||||
2. **Publish** — Make translated documentation accessible alongside English originals
|
||||
20
docs/features/issue-driven-orchestration-guide.md
Normal file
20
docs/features/issue-driven-orchestration-guide.md
Normal file
@@ -0,0 +1,20 @@
|
||||
---
|
||||
id: 129
|
||||
title: Issue-Driven Orchestration Guide
|
||||
group: v1.41.0 Features
|
||||
---
|
||||
|
||||
**Purpose:** Document a recipe for driving the full GSD workflow from a GitHub / Linear / Jira issue, mapping tracker-centric concepts onto existing GSD primitives.
|
||||
|
||||
**Document:** [`docs/issue-driven-orchestration.md`](issue-driven-orchestration.md)
|
||||
|
||||
**Covered workflow:**
|
||||
1. Create an isolated workspace per issue (`/gsd-workspace --new`)
|
||||
2. Run the manager dashboard to get oriented (`/gsd-manager`)
|
||||
3. Execute autonomously (`/gsd-autonomous`)
|
||||
4. Verify and review (`/gsd-verify-work`, `/gsd-review`)
|
||||
5. Ship and close the issue (`/gsd-ship`)
|
||||
|
||||
No new commands or daemon process — purely a documentation artifact that maps existing primitives onto a tracker-driven workflow.
|
||||
|
||||
**Reference issue:** [#2840](https://github.com/open-gsd/gsd-core/pull/2840)
|
||||
18
docs/features/knowledge-graph-integration.md
Normal file
18
docs/features/knowledge-graph-integration.md
Normal file
@@ -0,0 +1,18 @@
|
||||
---
|
||||
id: 121
|
||||
title: Knowledge Graph Integration
|
||||
group: v1.37.0 Features
|
||||
---
|
||||
|
||||
**Purpose:** Build, query, and inspect a lightweight knowledge graph of the project in `.planning/graphs/`. Opt-in per project. Exposed as the `/gsd-graphify` user-facing command and the `gsd-tools.cjs graphify …` programmatic verb family. Complements `/gsd-map-codebase --query` (snapshot-oriented) with a graph-oriented view of nodes and edges across commands, agents, workflows, and phases.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-GRAPH-01: Opt-in via `graphify.enabled: true` in `.planning/config.json`. When disabled, `/gsd-graphify` prints an activation hint and stops without writing.
|
||||
- REQ-GRAPH-02: Slash-command `/gsd-graphify` exposes subcommands `build`, `query <term>`, `status`, `diff`. The programmatic CLI `node gsd-tools.cjs graphify …` additionally exposes `snapshot`, which is also invoked automatically as the final step of `graphify build`.
|
||||
- REQ-GRAPH-03: Build runs within the configurable `graphify.build_timeout` (seconds); exceeding the timeout aborts cleanly without leaving a partial graph.
|
||||
- REQ-GRAPH-04: `graphify.cjs` falls back to `graph.links` when `graph.edges` is absent so older graph artifacts keep rendering.
|
||||
- REQ-GRAPH-05: Graphify is invoked through `gsd-tools.cjs graphify ...` command handlers.
|
||||
- REQ-GRAPH-06: The knowledge-graph location is configurable via `graphify.graph_path` (issue #1825) so one umbrella-level cross-repo graph can serve multiple sibling projects; `query`/`status`/`diff` read the configured graph (relative to project root), with a byte-identical `.planning/graphs/` default when unset.
|
||||
|
||||
**Configuration:** `graphify.enabled`, `graphify.build_timeout`, `graphify.graph_path`
|
||||
**Reference files:** `commands/gsd/graphify.md`, `bin/lib/graphify.cjs`
|
||||
25
docs/features/live-dom-uat-capability.md
Normal file
25
docs/features/live-dom-uat-capability.md
Normal file
@@ -0,0 +1,25 @@
|
||||
---
|
||||
id: 164
|
||||
title: Live-DOM UAT Capability
|
||||
group: v1.7.0 Features
|
||||
---
|
||||
|
||||
**Config key:** `workflow.live_dom_uat` (default `false`)
|
||||
|
||||
**Purpose:** A phase with a live-UI acceptance criterion could not be finished by the agent that executed it. `gsd-executor` carries no browser tools, so it correctly returned a `checkpoint:human-action` — even though the work was not human-only, just tool-less. Every such phase quietly degraded from *executed by the executor* to *executed, then finished by hand in the orchestrator*, and the plan's `autonomous: false` marker could not distinguish "a human must judge this" from "the executor lacks the tool" (#2856).
|
||||
|
||||
**Behavior:** A default-off capability owns one boolean key, one agent, and one additive step. When the key is on, `gsd-dom-verifier` runs at `execute:wave:post` and writes `{phase}-DOM-VERIFY.md`; the orchestrator's `automated_ui_verification` step additionally considers `mcp__chrome-devtools__*` / `mcp__claude-in-chrome__*` when present.
|
||||
|
||||
**The executor's tool surface is unchanged in every configuration.** Widening it was the reported proposal and was refused: for a first-party agent the static `tools:` list is the only control that exists — no capability can grant tools to one ([ADR-1244](adr/1244-capability-ecosystem.md) D2), no hook kind grants tool permissions ([ADR-857](adr/857-capability-system.md) D4), and there is no per-dispatch override. Browser reach lives in one purpose-built agent that carries no `Bash`.
|
||||
|
||||
**Two independent gates, both fail-closed.** The capability's `activationKey` makes it resolve inactive when the key is off — `resolveLoopHooks` renders a hook only on `state.active === true` — and the step carries its own `when` guard. Tool presence alone never activates it: a browser MCP configured for unrelated work is not driven by default.
|
||||
|
||||
**The pre-existing Playwright path is untouched.** `mcp__playwright__*` keeps the gating it already had (presence plus an active UI phase). Pulling it behind a new default-off key would have silently removed working behavior from current users on upgrade; the key gates only the newly added families.
|
||||
|
||||
**It tolerates the browser-profile lock rather than coordinating it.** `chrome-devtools-mcp` holds an exclusive lock on its profile, so parallel waves collide. `--isolated` is a flag on the operator's own MCP server registration — GSD neither launches that server nor passes its arguments — so the verifier reports `could_not_look` / `profile_locked`, names the flag, and stops. No retry, no held-up wave.
|
||||
|
||||
**`nothing_to_report` is never conflated with `could_not_look`.** A report claiming no issues when it never opened a browser is worse than no report; the artifact carries a closed reason enum so the two are always distinguishable.
|
||||
|
||||
**Known limits:** no sandbox — once enabled, nothing constrains which origins are reached ([ADR-1244](adr/1244-capability-ecosystem.md) D5); DOM observation only, no screenshot diffing, accessibility audit, or performance tracing.
|
||||
|
||||
**Reference:** [Configuration](CONFIGURATION.md) · [Enable live-DOM verification](how-to/enable-live-dom-verification.md) · [Explanation](explanation/live-dom-uat-capability.md) · [Agents](AGENTS.md)
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
id: 166
|
||||
title: Machine-Readable State Contract (`.planning/state.json`)
|
||||
group: v1.7.0 Features
|
||||
---
|
||||
|
||||
**Purpose:** External tools that display GSD project state — a workbench, a dashboard, an editor extension — had to parse `STATE.md` and `ROADMAP.md` heuristically. Those are human surfaces: their shape drifts as the templates evolve, and every consumer ends up carrying a brittle second parser that silently reports wrong numbers after an upgrade. GSD now publishes a small, versioned JSON snapshot instead, so the reader binds to a contract rather than to markdown (#3227).
|
||||
|
||||
**Behavior:** At every step boundary, GSD writes `.planning/state.json` — `contract`, `flavor`, `milestone`, `phases[]`, `next`, `updated_at`. The boundaries are `state begin-phase` / `planned-phase` / `advance-plan` / `complete-phase` / `milestone-switch`, `phase add` / `add-batch` / `insert` / `remove` / `complete`, and `milestone complete`. The write is best-effort and completely invisible to the command that triggered it: it cannot change an exit code, cannot change stdout, and cannot fail a workflow. Readers prefer the file when it is present and fall back to markdown when it is not.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-SC-01: `contract` is semver, `1.0.0` at introduction. Consumers gate on the MAJOR version; `1.x` changes are additive only. Every key is ALWAYS present — an unknown value is `null`, never an omitted key, because an omitted key is itself an observable a consumer would bind to.
|
||||
- REQ-SC-02: `phases[]` carries `{number, name, status}` per phase, `status` drawn from exactly `complete | in_progress | pending`. `number` is a string (`"01"` and `"2.1"` are both real ids and neither survives a number cast); `name` is `null` when the roadmap gives a phase no name, never a fabricated placeholder.
|
||||
- REQ-SC-03: `next` is the same recommended action the `/gsd` front door routes, derived from the smart-entry classifier itself rather than from a second copy of its routing table.
|
||||
- REQ-SC-04: A missing `ROADMAP.md`, a missing or unreadable `.planning/`, an unwritable target, or any other failure NEVER errors the parent command. A directory that is not a GSD project stays untouched — the publisher will not create `.planning/` in order to publish into it.
|
||||
- REQ-SC-05: The skills own the file; readers never write it. It is a derived cache — safe to delete, regenerated at the next boundary.
|
||||
|
||||
**Composed, never re-derived.** Milestone identity comes from `getMilestoneInfo`; phase rows from `locateProgressTable`, the same `## Progress` locator the progress counters use, so `state.json` can never disagree with the rest of GSD about which phases are complete; the recommended action from `classifyProject`. This module introduces no second answer to any question GSD already answers.
|
||||
|
||||
**Why it does not reuse `planning inspect`'s schema.** The two surfaces answer different questions and have opposite shapes. `planning inspect` is a rich, diagnostic-carrying **pull** query a consumer runs; this is a small **push** artifact a consumer watches. Publishing `planning inspect`'s payload at every `phase add` would mean opening every plan, summary and requirements document on a hot path, and freezing a much larger surface as a contract.
|
||||
|
||||
**It costs up to three bounded git calls per boundary.** Deriving `next` from the smart-entry classifier means inheriting its git signals — `git status --porcelain`, and `git log @{u}..HEAD`. Each is timeout-bounded and swallows every error, so nothing can hang or fail because of it, but a command like `phase add` did not previously touch git at all. "Invisible to the parent command" is exact about exit code and output; it is not a claim about latency.
|
||||
|
||||
**Known limits:** an empty `phases: []` cannot be told apart from "no `ROADMAP.md`" or "roadmap unreadable" — the `1.0` schema carries no diagnostic channel, and `planning inspect` is the surface that does. A roadmap phase marked `Deferred` is reported as `pending`, because the roadmap vocabulary has four values and this contract has three; inventing a fourth wire value would break every existing reader. `phases[]` is not milestone-scoped, so a long-running project lists every phase it has ever had.
|
||||
|
||||
**Reference:** [Consume the state contract](how-to/consume-the-state-contract.md) · [Consume the planning snapshot](how-to/consume-the-planning-snapshot.md)
|
||||
21
docs/features/manager-dashboard.md
Normal file
21
docs/features/manager-dashboard.md
Normal file
@@ -0,0 +1,21 @@
|
||||
---
|
||||
id: 52
|
||||
title: Manager Dashboard
|
||||
group: v1.28 Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-manager`
|
||||
|
||||
**Purpose:** Interactive command center for managing multiple phases from one terminal.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-MGR-01: System MUST show overview of all phases with status
|
||||
- REQ-MGR-02: System MUST filter to current milestone scope
|
||||
- REQ-MGR-03: System MUST show phase dependencies and conflicts
|
||||
|
||||
**Produces:** Interactive terminal output
|
||||
|
||||
**Process:**
|
||||
1. **Scan** — Load all phases in the current milestone with their statuses
|
||||
2. **Display** — Render overview showing phase dependencies, conflicts, and progress
|
||||
3. **Interact** — Accept commands to navigate, inspect, or act on individual phases
|
||||
13
docs/features/manual-update-procedure.md
Normal file
13
docs/features/manual-update-procedure.md
Normal file
@@ -0,0 +1,13 @@
|
||||
---
|
||||
id: 84
|
||||
title: Manual Update Procedure
|
||||
group: v1.32 Features
|
||||
---
|
||||
|
||||
**Part of:** `docs/manual-update.md`
|
||||
|
||||
**Purpose:** Document a manual update path for environments where `npx` is unavailable or npm publish is experiencing outages.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-MANUAL-01: Documentation MUST describe step-by-step manual update procedure
|
||||
- REQ-MANUAL-02: Procedure MUST work without npm access
|
||||
23
docs/features/mempalace-memory-capability.md
Normal file
23
docs/features/mempalace-memory-capability.md
Normal file
@@ -0,0 +1,23 @@
|
||||
---
|
||||
id: 145
|
||||
title: MemPalace Memory Capability
|
||||
group: v1.43.0 Features
|
||||
---
|
||||
|
||||
**Purpose:** Opt-in cross-session and cross-project memory via the [MemPalace](https://github.com/MemPalace/mempalace) external service (local-first, MCP + CLI). Wires deliberate recall before discuss/plan and verbatim capture + temporal-KG sync at phase boundaries through the ADR-857 capability mechanism. Default-resilient: disabled by default, every hook is `onError: skip`, and an absent MemPalace installation leaves the loop unchanged.
|
||||
|
||||
**Commands:** `/gsd-mempalace-recall`, `/gsd-mempalace-capture`
|
||||
|
||||
**Requirements:**
|
||||
- REQ-MP-01: Opt-in via `mempalace.enabled: true`. Default `false` — the loop is unchanged when unset.
|
||||
- REQ-MP-02: At `plan:pre`, skill `mempalace-recall` produces `MEMORY-RECALL.md` from prior decisions, patterns, and surprises retrieved via wake-up + semantic search + KG timeline. When MemPalace is unreachable, writes an "unavailable" stub and continues.
|
||||
- REQ-MP-03: At `discuss:post`, `plan:post`, and `verify:post`, skill `mempalace-capture` files the phase artifact verbatim into the appropriate MemPalace room (`decisions`, `planning`, `milestones`). Capture is idempotent via `mempalace_check_duplicate`.
|
||||
- REQ-MP-04: At `ship:post`, agent `gsd-mempalace-curator` writes a diary entry, proposes cross-project tunnels (when `mempalace.cross_project_tunnels: true`), and runs wing-scoped sync pruning.
|
||||
- REQ-MP-05: `mempalace.memory_mode` has three wired values: `augment` (default — palace is an additive recall layer alongside GSD native memory, which stays authoritative), `kg_backend` (knowledge-graph queries resolve against the palace's temporal KG as the primary source, `.planning/graphs/` as fallback; non-KG drawer recall stays additive), `replace` (recall resolves through the palace as the source of truth, native memory as fallback). Every mode is `onError:skip` and default-resilient — an unreachable palace degrades to native memory and GSD keeps writing `.planning/graphs/`, so no mode loses memory. Cross-mode migration of existing `.planning/graphs/` into the palace is out of scope (not yet implemented).
|
||||
- REQ-MP-06: Every hook is `onError: skip`. No hook carries `blocking: true`. Memory never halts or fails a phase.
|
||||
- REQ-MP-07: Interactive runs prefer MCP tools; headless/cron runs prefer the MemPalace CLI (`mempalace wake-up`, `mempalace search`, `mempalace mine`, `mempalace sync`).
|
||||
- REQ-MP-08: `mempalace.auto_capture_hooks` is **forward-declared and not yet functional**. No native Claude Code hooks (`stop`, `precompact`, `session-start`) are installed by this key; the capability's hooks array is empty. This key is reserved for the future "Connected Capability" phase. Default `false`.
|
||||
|
||||
**Configuration:** `mempalace.enabled`, `mempalace.memory_mode`, `mempalace.wing`, `mempalace.recall_on_discuss`, `mempalace.recall_on_plan`, `mempalace.capture_artifacts`, `mempalace.mirror_kg`, `mempalace.cross_project_tunnels`, `mempalace.diary_journal`, `mempalace.auto_capture_hooks`
|
||||
|
||||
See [Configuration Reference](CONFIGURATION.md#mempalace-settings) for full schema and [How to enable cross-session memory with MemPalace](how-to/enable-cross-session-memory-with-mempalace.md) for a setup walkthrough.
|
||||
13
docs/features/methodology-artifact-type.md
Normal file
13
docs/features/methodology-artifact-type.md
Normal file
@@ -0,0 +1,13 @@
|
||||
---
|
||||
id: 79
|
||||
title: Methodology Artifact Type
|
||||
group: v1.32 Features
|
||||
---
|
||||
|
||||
**Part of:** Planning artifacts
|
||||
|
||||
**Purpose:** Define consumption mechanisms for methodology documents, ensuring they are consumed correctly by agents.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-METHOD-01: System MUST support methodology as a distinct artifact type
|
||||
- REQ-METHOD-02: Methodology artifacts MUST have defined consumption mechanisms for agents
|
||||
20
docs/features/milestone-management.md
Normal file
20
docs/features/milestone-management.md
Normal file
@@ -0,0 +1,20 @@
|
||||
---
|
||||
id: 8
|
||||
title: Milestone Management
|
||||
group: Core Features
|
||||
---
|
||||
|
||||
**Commands:** `/gsd-audit-milestone`, `/gsd-complete-milestone`, `/gsd-new-milestone [name]`
|
||||
|
||||
**Purpose:** Verify milestone completion, archive, tag release, and start the next development cycle.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-MILE-01: Audit MUST verify all milestone requirements are met
|
||||
- REQ-MILE-02: Audit MUST detect stubs, placeholder implementations, and untested code
|
||||
- REQ-MILE-03: Audit MUST check Nyquist validation compliance across phases
|
||||
- REQ-MILE-04: Complete MUST archive milestone data to MILESTONES.md
|
||||
- REQ-MILE-05: Complete MUST offer git tag creation for the release
|
||||
- REQ-MILE-06: Complete MUST offer squash merge or merge with history for branching strategies
|
||||
- REQ-MILE-07: Complete MUST clean up UI review screenshots
|
||||
- REQ-MILE-08: New milestone MUST follow same flow as new-project (questions → research → requirements → roadmap)
|
||||
- REQ-MILE-09: New milestone MUST NOT reset existing workflow configuration
|
||||
24
docs/features/milestone-summary.md
Normal file
24
docs/features/milestone-summary.md
Normal file
@@ -0,0 +1,24 @@
|
||||
---
|
||||
id: 50
|
||||
title: Milestone Summary
|
||||
group: v1.28 Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-milestone-summary [version]`
|
||||
|
||||
**Purpose:** Generate comprehensive project summary from milestone artifacts for team onboarding.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-SUMMARY-01: System MUST aggregate phase plans, summaries, and verification results
|
||||
- REQ-SUMMARY-02: System MUST work for both current and archived milestones
|
||||
- REQ-SUMMARY-03: System MUST produce a single navigable document
|
||||
|
||||
**Produces:**
|
||||
| Artifact | Description |
|
||||
|----------|-------------|
|
||||
| `MILESTONE-SUMMARY.md` | Comprehensive navigable summary of milestone artifacts |
|
||||
|
||||
**Process:**
|
||||
1. **Collect** — Aggregate phase plans, summaries, and verification results from the target milestone
|
||||
2. **Synthesize** — Combine artifacts into a single navigable document with cross-references
|
||||
3. **Output** — Write `MILESTONE-SUMMARY.md` suitable for team onboarding and stakeholder review
|
||||
20
docs/features/milestone-tag-creation-toggle.md
Normal file
20
docs/features/milestone-tag-creation-toggle.md
Normal file
@@ -0,0 +1,20 @@
|
||||
---
|
||||
id: 141
|
||||
title: Milestone Tag Creation Toggle
|
||||
group: v1.42.1 Features
|
||||
---
|
||||
|
||||
**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)
|
||||
11
docs/features/model-catalog-advances.md
Normal file
11
docs/features/model-catalog-advances.md
Normal file
@@ -0,0 +1,11 @@
|
||||
---
|
||||
id: 153
|
||||
title: Model Catalog Advances
|
||||
group: v1.7.0 Features
|
||||
---
|
||||
|
||||
**Purpose:** Refresh the default model tiers and how models are surfaced.
|
||||
|
||||
**Behavior:** Codex/OpenAI defaults advance to the **GPT-5.6 family (Sol / Terra / Luna)** (#2122); the verbose `(1M context)` model suffix collapses to a compact `(1M)` badge (#2160). GSD warns when model config changes without re-running the installer on static-frontmatter runtimes such as Codex and OpenCode (#1688).
|
||||
|
||||
**Reference:** [Configuration](CONFIGURATION.md) · [Configure model profiles](how-to/configure-model-profiles.md)
|
||||
35
docs/features/model-profiles.md
Normal file
35
docs/features/model-profiles.md
Normal file
@@ -0,0 +1,35 @@
|
||||
---
|
||||
id: 26
|
||||
title: Model Profiles
|
||||
group: Context Engineering Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-config --profile <quality|balanced|budget|adaptive|inherit>`
|
||||
|
||||
**Purpose:** Control which AI model each agent uses, balancing quality vs cost.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-MODEL-01: System MUST support 4 profiles: `quality`, `balanced`, `budget`, `inherit`
|
||||
- REQ-MODEL-02: Each profile MUST define model tier per agent (see profile table)
|
||||
- REQ-MODEL-03: Per-agent overrides MUST take precedence over profile
|
||||
- REQ-MODEL-04: `inherit` profile MUST defer to runtime's current model selection
|
||||
- REQ-MODEL-04a: `inherit` profile MUST be used when running non-Anthropic providers (OpenRouter, local models) to avoid unexpected API costs
|
||||
- REQ-MODEL-05: Profile switch MUST be programmatic (script, not LLM-driven)
|
||||
- REQ-MODEL-06: Model resolution MUST happen once per orchestration, not per spawn
|
||||
|
||||
**Profile Assignments:**
|
||||
|
||||
| Agent | `quality` | `balanced` | `budget` | `inherit` |
|
||||
|-------|-----------|------------|----------|-----------|
|
||||
| gsd-planner | Opus | Opus | Sonnet | Inherit |
|
||||
| gsd-roadmapper | Opus | Sonnet | Sonnet | Inherit |
|
||||
| gsd-executor | Opus | Sonnet | Sonnet | Inherit |
|
||||
| gsd-phase-researcher | Opus | Sonnet | Haiku | Inherit |
|
||||
| gsd-project-researcher | Opus | Sonnet | Haiku | Inherit |
|
||||
| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | Inherit |
|
||||
| gsd-debugger | Opus | Sonnet | Sonnet | Inherit |
|
||||
| gsd-codebase-mapper | Sonnet | Haiku | Haiku | Inherit |
|
||||
| gsd-verifier | Sonnet | Sonnet | Haiku | Inherit |
|
||||
| gsd-plan-checker | Sonnet | Sonnet | Haiku | Inherit |
|
||||
| gsd-integration-checker | Sonnet | Sonnet | Haiku | Inherit |
|
||||
| gsd-nyquist-auditor | Sonnet | Sonnet | Haiku | Inherit |
|
||||
15
docs/features/multi-agent-orchestration.md
Normal file
15
docs/features/multi-agent-orchestration.md
Normal file
@@ -0,0 +1,15 @@
|
||||
---
|
||||
id: 25
|
||||
title: Multi-Agent Orchestration
|
||||
group: Context Engineering Features
|
||||
---
|
||||
|
||||
**Purpose:** Coordinate specialized agents with fresh context windows for each task.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-ORCH-01: Each agent MUST receive a fresh context window
|
||||
- REQ-ORCH-02: Orchestrators MUST be thin — spawn agents, collect results, route next
|
||||
- REQ-ORCH-03: Context payload MUST include all relevant project artifacts
|
||||
- REQ-ORCH-04: Parallel agents MUST be truly independent (no shared mutable state)
|
||||
- REQ-ORCH-05: Agent results MUST be written to disk before orchestrator processes them
|
||||
- REQ-ORCH-06: Failed agents MUST be detected (spot-check actual output vs reported failure)
|
||||
12
docs/features/multi-repo-workspace-support.md
Normal file
12
docs/features/multi-repo-workspace-support.md
Normal file
@@ -0,0 +1,12 @@
|
||||
---
|
||||
id: 47
|
||||
title: Multi-Repo Workspace Support
|
||||
group: v1.27 Features
|
||||
---
|
||||
|
||||
**Purpose:** Auto-detection and project root resolution for monorepos and multi-repo setups. Supports workspaces where `.planning/` may need to resolve across repository boundaries.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-MULTIREPO-01: System MUST auto-detect multi-repo workspace configuration
|
||||
- REQ-MULTIREPO-02: System MUST resolve project root across repository boundaries
|
||||
- REQ-MULTIREPO-03: Executor MUST record per-repo commit hashes in multi-repo mode
|
||||
18
docs/features/multi-runtime-installer-selection.md
Normal file
18
docs/features/multi-runtime-installer-selection.md
Normal file
@@ -0,0 +1,18 @@
|
||||
---
|
||||
id: 55
|
||||
title: Multi-Runtime Installer Selection
|
||||
group: v1.28 Features
|
||||
---
|
||||
|
||||
**Part of:** `npx @opengsd/gsd-core`
|
||||
|
||||
**Purpose:** Select multiple runtimes in a single interactive install session.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-MULTI-RT-01: Interactive prompt MUST support multi-select (e.g., Claude Code + Antigravity)
|
||||
- REQ-MULTI-RT-02: CLI flags MUST continue to work for non-interactive installs
|
||||
|
||||
**Process:**
|
||||
1. **Detect** — Identify available AI CLI runtimes on the system
|
||||
2. **Prompt** — Present multi-select interface for runtime selection
|
||||
3. **Install** — Configure GSD for all selected runtimes in a single session
|
||||
55
docs/features/multi-runtime-support.md
Normal file
55
docs/features/multi-runtime-support.md
Normal file
@@ -0,0 +1,55 @@
|
||||
---
|
||||
id: 36
|
||||
title: Multi-Runtime Support
|
||||
group: Infrastructure Features
|
||||
---
|
||||
|
||||
**Purpose:** Run GSD across multiple AI coding agent runtimes.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-RUNTIME-01: System MUST support Claude Code, OpenCode, Kilo, Codex, Copilot, Antigravity, Trae, Cline, Augment Code, CodeBuddy, Qwen Code
|
||||
- REQ-RUNTIME-02: Installer MUST transform content per runtime (tool names, paths, frontmatter)
|
||||
- REQ-RUNTIME-03: Installer MUST support interactive and non-interactive (`--claude --global`) modes
|
||||
- REQ-RUNTIME-04: Installer MUST support both global and local installation
|
||||
- REQ-RUNTIME-05: Uninstall MUST cleanly remove all GSD files without affecting other configurations
|
||||
- REQ-RUNTIME-06: Installer MUST handle platform differences (Windows, macOS, Linux, WSL, Docker)
|
||||
- REQ-RUNTIME-07: Runtimes with lifecycle hook support MUST register per-turn context-headroom tracking events at install time
|
||||
- REQ-RUNTIME-08: Native packaging manifests MUST be version-stamped and enable runtime-native install/update/uninstall flows
|
||||
|
||||
**Runtime Transformations:**
|
||||
|
||||
| Aspect | Claude Code | OpenCode | Kilo | Codex | Copilot | Antigravity | Cursor | Trae | Cline | Augment | CodeBuddy | Qwen Code |
|
||||
|--------|------------|----------|-------|-------|---------|-------------|--------|------|-------|---------|-----------|-----------|
|
||||
| Commands | Slash commands | Slash commands | Slash commands | Skills (TOML) | Slash commands | Skills | Skills + Slash commands | Skills | Rules | Skills + Slash commands | Slash commands | Skills |
|
||||
| Agent format | Claude native | `mode: subagent` | `mode: subagent` | Skills | Tool mapping | Skills | Skills | Skills | Rules | Skills | Skills | Skills |
|
||||
| Skills emission | N/A | On-demand SKILL.md (1.4.0) | On-demand SKILL.md (1.4.0) | `/skills` picker (1.4.0) | N/A | N/A | SKILL.md | N/A | On-demand SKILL.md (1.4.0) | N/A | N/A | N/A |
|
||||
| Hook events | `SessionStart`, `PreToolUse`, `PostToolUse`, `SubagentStop`, `Stop`, `PreCompact`, `FileChanged` | N/A | N/A | `SessionStart`, `SubagentStart`, `Stop`, `PostToolUse` | `sessionStart` | N/A | `sessionStart`, `postToolUse` | N/A | `PreToolUse` | N/A | N/A | `SessionStart`, `PreToolUse`, `PostToolUse`, `SubagentStop`, `Stop`, `PreCompact` |
|
||||
| Config | `settings.json` | `opencode.json(c)` | `kilo.json(c)` | TOML | Instructions | Config | Config | Config | `.clinerules` | Config | Config | Config |
|
||||
|
||||
**Cursor artifact surfaces:** `gsd install --cursor` writes two artifact kinds:
|
||||
- `~/.cursor/skills/gsd-<name>/SKILL.md` — rich skills with YAML frontmatter, Cursor tool-name mapping, and adapter context header (existing surface)
|
||||
- `~/.cursor/commands/gsd-<name>.md` — plain markdown slash commands (no frontmatter) invocable via `/` in the Agent input (Cursor 1.6+)
|
||||
|
||||
**Native skills emission (1.4.0):** Three runtimes now emit GSD as on-demand native skills (`skills/<name>/SKILL.md`) at install time, in addition to their existing command and agent surfaces. Skills respect the active install profile and are removed on uninstall.
|
||||
- **Cline** (global installs, Cline >= v3.48.0) — emits skills alongside the existing `.clinerules/` directory
|
||||
- **Kilo** — emits skills alongside `command/` and `agents/`
|
||||
- **OpenCode** — emits skills alongside its existing surfaces
|
||||
|
||||
**New slash-command surfaces (1.4.0):**
|
||||
- **CodeBuddy** — `/gsd-*` slash commands written to `~/.codebuddy/commands/`
|
||||
- **Augment** — `commands/gsd-<name>.md` written to `~/.augment/commands/`
|
||||
- **Cursor** (Cursor >= 1.6) — `.cursor/commands/gsd-<name>.md` so GSD appears in the `/` command menu
|
||||
|
||||
**Cross-runtime lifecycle hooks (1.4.0):** Each supported runtime registers lifecycle hook events for per-turn context-headroom tracking and workflow state management. Notable registrations:
|
||||
- **Claude Code:** `SubagentStop`, `Stop`, `PreCompact` (context-headroom warnings), `FileChanged` (hot-reloads `.planning/config.json` mid-session)
|
||||
- **Qwen Code:** `SubagentStop`, `Stop`, `PreCompact`
|
||||
- **Codex:** `SubagentStart`, `Stop`, `PostToolUse` (new in 1.4.0); on Windows the `SessionStart` hook entry gains a `commandWindows` field so the `.cmd` shim is used for native execution
|
||||
- **Cline:** `PreToolUse`
|
||||
- **Cursor:** `sessionStart` (injects workflow state), `postToolUse` (nudges `.planning` updates)
|
||||
- **Copilot:** `sessionStart`
|
||||
|
||||
**Runtime-specific enrichments (1.4.0):**
|
||||
- Codex emits `service_tier: flex` for light-tier agents; GSD skills appear in the Codex `/skills` picker via `SKILL.md` (no `agents/openai.yaml` sidecar is emitted — doing so caused duplicate autocomplete entries, #1326)
|
||||
|
||||
**Native packaging:**
|
||||
- **Claude Code:** GSD Core ships a `.claude-plugin/plugin.json` manifest, enabling installation and lifecycle management via `claude plugin install|enable|disable|update gsd-core`. Commands load under the `/gsd-core:` namespace (e.g. `/gsd-core:plan-phase`), avoiding slash-command collisions with the classic npm installer which uses `/gsd:`. Always-on guard and update hooks are wired automatically via `hooks/hooks.json`. The plugin path is additive — the npm installer (`npx @opengsd/gsd-core`) remains fully supported.
|
||||
30
docs/features/namespace-meta-skills-two-stage-routing.md
Normal file
30
docs/features/namespace-meta-skills-two-stage-routing.md
Normal file
@@ -0,0 +1,30 @@
|
||||
---
|
||||
id: 123
|
||||
title: Namespace Meta-Skills (Two-Stage Routing)
|
||||
group: v1.40.0 Features
|
||||
---
|
||||
|
||||
**Purpose:** Replace the flat eager skill listing with a two-stage hierarchical routing layer. The model sees 6 namespace routers instead of 86 entries, selects a namespace, then routes to the sub-skill. Descriptions use pipe-separated keyword tags (≤ 60 chars) for routing density.
|
||||
|
||||
**Commands:**
|
||||
- `/gsd-workflow` — phase pipeline router (discuss / plan / execute / verify / phase / progress / next)
|
||||
- `/gsd-project` — project lifecycle (milestones, audits, summary)
|
||||
- `/gsd-quality` — quality gates (code review, debug, audit, security, eval, ui)
|
||||
- `/gsd-context` — codebase intelligence (map, graphify, docs, learnings)
|
||||
- `/gsd-manage` — config / workspace / workstreams / thread / update / ship / inbox
|
||||
- `/gsd-ideate` — exploration & capture (explore, sketch, spike, spec, capture)
|
||||
|
||||
**Token cost:**
|
||||
|
||||
| | Entries | Approx tokens |
|
||||
|---|---|---|
|
||||
| Pre-1.40 full install | 86 | ~2,150 |
|
||||
| Namespace meta-skills | 6 | ~120 |
|
||||
|
||||
**Requirements:**
|
||||
- REQ-NS-01: Six `commands/gsd/ns-*.md` namespace routers ship with pipe-separated keyword-tag descriptions (≤ 60 chars).
|
||||
- REQ-NS-02: Existing sub-skills are unchanged and still invocable directly — namespace skills are additive, not a replacement for direct slash forms.
|
||||
- REQ-NS-03: The body of each namespace router contains a routing table that maps user intent to the correct concrete sub-skill on the post-#2790 consolidated surface.
|
||||
- REQ-NS-04: Tests validate namespace files exist, include matching command `requires`, and reference only existing sub-skill files.
|
||||
|
||||
**Reference issue:** [#2792](https://github.com/open-gsd/gsd-core/issues/2792)
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
id: 104
|
||||
title: New Runtime Support (Cline, CodeBuddy, Qwen Code)
|
||||
group: v1.35.0 Features
|
||||
---
|
||||
|
||||
**Part of:** `npx @opengsd/gsd-core`
|
||||
|
||||
**Purpose:** Extend GSD installation to Cline, CodeBuddy, and Qwen Code runtimes.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-CLINE-02: Cline install MUST write `.clinerules` to `~/.cline/` (global) or `./.cline/` (local). No custom slash commands — rules-based integration only. Flag: `--cline`.
|
||||
- REQ-CODEBUDDY-01: CodeBuddy install MUST deploy skills to `~/.codebuddy/skills/gsd-*/SKILL.md` (emitted `user-invocable: false`), `/gsd-*` slash commands to `~/.codebuddy/commands/gsd-*.md`, and subagents to `~/.codebuddy/agents/gsd-*.md`. The commands surface is the sole `/` menu entry point. No `mcp.json` is written (gsd ships no MCP server). Flag: `--codebuddy`.
|
||||
- REQ-QWEN-01: Qwen Code install MUST deploy skills to `~/.qwen/skills/gsd-*/SKILL.md`, following the open standard used by Claude Code 2.1.88+. `QWEN_CONFIG_DIR` env var overrides the default path. Flag: `--qwen`.
|
||||
|
||||
**Runtime summary:**
|
||||
|
||||
| Runtime | Install Format | Config Path | Flag |
|
||||
|---------|---------------|-------------|------|
|
||||
| Cline | `.clinerules` | `~/.cline/` or `./.cline/` | `--cline` |
|
||||
| CodeBuddy | Skills (`SKILL.md`) | `~/.codebuddy/skills/` | `--codebuddy` |
|
||||
| Qwen Code | Skills (`SKILL.md`) | `~/.qwen/skills/` | `--qwen` |
|
||||
14
docs/features/new-runtime-support-trae-cline-augment-code.md
Normal file
14
docs/features/new-runtime-support-trae-cline-augment-code.md
Normal file
@@ -0,0 +1,14 @@
|
||||
---
|
||||
id: 85
|
||||
title: New Runtime Support (Trae, Cline, Augment Code)
|
||||
group: v1.32 Features
|
||||
---
|
||||
|
||||
**Part of:** `npx @opengsd/gsd-core`
|
||||
|
||||
**Purpose:** Extend GSD installation to Trae IDE, Cline, and Augment Code runtimes.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-TRAE-01: Installer MUST support `--trae` flag for Trae IDE installation
|
||||
- REQ-CLINE-01: Installer MUST support Cline via `.clinerules` configuration
|
||||
- REQ-AUGMENT-01: Installer MUST support Augment Code with skill conversion and config management
|
||||
15
docs/features/node-repair.md
Normal file
15
docs/features/node-repair.md
Normal file
@@ -0,0 +1,15 @@
|
||||
---
|
||||
id: 18
|
||||
title: Node Repair
|
||||
group: Quality Assurance Features
|
||||
---
|
||||
|
||||
**Purpose:** Autonomous recovery when task verification fails during execution.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-REPAIR-01: System MUST analyze failure and choose one strategy: RETRY, DECOMPOSE, or PRUNE
|
||||
- REQ-REPAIR-02: RETRY MUST attempt with a concrete adjustment
|
||||
- REQ-REPAIR-03: DECOMPOSE MUST break task into smaller verifiable sub-steps
|
||||
- REQ-REPAIR-04: PRUNE MUST remove unachievable tasks and escalate to user
|
||||
- REQ-REPAIR-05: System MUST respect repair budget (default: 2 attempts per task)
|
||||
- REQ-REPAIR-06: System MUST be configurable via `workflow.node_repair_budget` and `workflow.node_repair`
|
||||
16
docs/features/note-capture.md
Normal file
16
docs/features/note-capture.md
Normal file
@@ -0,0 +1,16 @@
|
||||
---
|
||||
id: 13
|
||||
title: Note Capture
|
||||
group: Planning Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-capture`
|
||||
|
||||
**Purpose:** Zero-friction idea capture without interrupting workflow. Append timestamped notes, list all notes, or promote notes to structured todos.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-NOTE-01: System MUST save timestamped note files with a single Write call
|
||||
- REQ-NOTE-02: System MUST support `list` subcommand to show all notes from project and global scopes
|
||||
- REQ-NOTE-03: System MUST support `promote N` subcommand to convert a note into a structured todo
|
||||
- REQ-NOTE-04: System MUST support `--global` flag for global scope operations
|
||||
- REQ-NOTE-05: System MUST NOT use Task, AskUserQuestion, or Bash — runs inline only
|
||||
24
docs/features/nyquist-validation.md
Normal file
24
docs/features/nyquist-validation.md
Normal file
@@ -0,0 +1,24 @@
|
||||
---
|
||||
id: 15
|
||||
title: Nyquist Validation
|
||||
group: Quality Assurance Features
|
||||
---
|
||||
|
||||
**Purpose:** Map automated test coverage to phase requirements before any code is written. Named after the Nyquist sampling theorem — ensures a feedback signal exists for every requirement.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-NYQ-01: System MUST detect existing test infrastructure during plan-phase research
|
||||
- REQ-NYQ-02: System MUST map each requirement to a specific test command
|
||||
- REQ-NYQ-03: System MUST identify Wave 0 tasks (test scaffolding needed before implementation)
|
||||
- REQ-NYQ-04: Plan checker MUST enforce Nyquist compliance as 8th verification dimension
|
||||
- REQ-NYQ-05: System MUST support retroactive validation via `/gsd-validate-phase`
|
||||
- REQ-NYQ-06: System MUST be disableable via `workflow.nyquist_validation: false`
|
||||
|
||||
**Produces:** `{phase}-VALIDATION.md` — Test coverage contract
|
||||
|
||||
**Retroactive Validation (`/gsd-validate-phase [N]`):**
|
||||
- Scans implementation and maps requirements to tests
|
||||
- Identifies gaps where requirements lack automated verification
|
||||
- Spawns auditor to generate tests (max 3 attempts)
|
||||
- Never modifies implementation code — only test files and VALIDATION.md
|
||||
- Flags implementation bugs as escalations for user to address
|
||||
23
docs/features/opt-in-parallel-reviewer-lanes.md
Normal file
23
docs/features/opt-in-parallel-reviewer-lanes.md
Normal file
@@ -0,0 +1,23 @@
|
||||
---
|
||||
id: 165
|
||||
title: Opt-In Parallel Reviewer Lanes
|
||||
group: v1.7.0 Features
|
||||
---
|
||||
|
||||
**Command:** `/gsd-review`, `/gsd-plan-review-convergence`
|
||||
|
||||
**Config key:** `review.parallel_lanes` (default `false`)
|
||||
|
||||
**Purpose:** Reviewer lanes within one review pass have no data dependency on each other — they all inspect the same immutable plan snapshot — but were dispatched strictly one at a time, so a pass with Codex, Gemini and Claude cost roughly the sum of three long reviewer calls. The serialization was a deliberate, unconditional protection against provider rate limits, which made it a global policy imposed on users whose providers could comfortably take concurrent requests, or who run local model servers with no limits at all (#3034).
|
||||
|
||||
**Behavior:** With the key enabled, the `invoke_reviewers` step dispatches each selected lane as a background job and joins all of them before `REVIEWS.md` and consensus are rendered. Wall-clock cost falls toward the slowest lane rather than the sum. Default remains `false`, preserving the existing sequential dispatch and its rate-limit protection.
|
||||
|
||||
**The guard is strict equality, and it fails safe.** Only the exact value `true` opts in — `"1"`, `"yes"` and `"TRUE"` all stay sequential, so a mistyped config gets the conservative behavior rather than concurrent requests at a rate-limited provider. A failure to read the config falls back to sequential too. This polarity is deliberately the opposite of the `commit_docs` guard, which fails open: there, failing open preserves user intent; here it would fire the very requests the default exists to prevent.
|
||||
|
||||
**Result ordering is unchanged in both modes.** Per-lane results are written to slug-scoped files and concatenated in reviewer-selection order after the join, so `gsd-review-lane-results.jsonl` reads identically whether lanes ran sequentially or concurrently. Completion order never reaches the artifact. This also means concurrent lanes never share an append handle — a lane result larger than the pipe-atomicity bound cannot interleave and corrupt the `models:` / `model_sources:` frontmatter that `write_reviews` renders from that file.
|
||||
|
||||
**Per-lane semantics are untouched.** Timeouts, prompt budgets, the diagnostic stub for an empty or failed lane, explicit-lane failure ([ADR-2782](adr/2782-reviewer-lane-capability-surface.md) D4), trust/egress checks and result-file layout all behave exactly as they do sequentially. A failing lane does not abort its siblings.
|
||||
|
||||
**Known limits:** convergence cycles stay sequential by design (`review → replan → re-review` has a genuine data dependency), so this speeds up each pass rather than reducing the number of passes; there is no concurrency bound, so every selected lane dispatches at once; and reviewer instances sharing one adapter dispatch concurrently against that single provider, which is the most likely way to hit a limit.
|
||||
|
||||
**Reference:** [Configuration](CONFIGURATION.md#parallel-reviewer-lanes-for-gsd-review-3034) · [Enable parallel reviewer lanes](how-to/enable-parallel-reviewer-lanes.md) · [Commands](COMMANDS.md)
|
||||
21
docs/features/package-legitimacy-gate.md
Normal file
21
docs/features/package-legitimacy-gate.md
Normal file
@@ -0,0 +1,21 @@
|
||||
---
|
||||
id: 132
|
||||
title: Package Legitimacy Gate
|
||||
group: v1.42.1 Features
|
||||
---
|
||||
|
||||
**Purpose:** Stop hallucinated, suspicious, or slopsquatting package names before they reach a shell install command.
|
||||
|
||||
**Behavior:**
|
||||
- Phase research writes a `## Package Legitimacy Audit` table for recommended packages.
|
||||
- Packages verified only through search are treated as `[ASSUMED]`, not trusted.
|
||||
- `[SLOP]` packages are removed from recommendations.
|
||||
- Plans that need `[ASSUMED]` or suspicious packages add a human verification checkpoint.
|
||||
- Executor install failures stop for human verification instead of auto-trying similarly named packages.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-PKG-GATE-01: Research MUST record package registry, age, download/source signals, legitimacy verdict, and disposition.
|
||||
- REQ-PKG-GATE-02: Planner MUST gate unverified or suspicious package installs before execution.
|
||||
- REQ-PKG-GATE-03: Executor MUST NOT auto-substitute package names after failed package-manager installs.
|
||||
|
||||
**Reference:** [v1.42.1 Release Notes](RELEASE-NOTES-LEGACY.md)
|
||||
13
docs/features/pause-work-expansion.md
Normal file
13
docs/features/pause-work-expansion.md
Normal file
@@ -0,0 +1,13 @@
|
||||
---
|
||||
id: 82
|
||||
title: Pause-Work Expansion
|
||||
group: v1.32 Features
|
||||
---
|
||||
|
||||
**Part of:** `/gsd-pause-work`
|
||||
|
||||
**Purpose:** Support non-phase contexts with richer handoff data for broader pause-work applicability.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-PAUSE-01: System MUST support pausing in non-phase contexts (quick tasks, debug sessions, threads)
|
||||
- REQ-PAUSE-02: Handoff data MUST include richer context appropriate to the current work type
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user