Merge remote-tracking branch 'origin/next' into fix/1477-surface-source-marker
# Conflicts: # bin/install.js
This commit is contained in:
Joe Slitzker
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1367
|
||||
---
|
||||
**Project-local Claude Code install now produces `/gsd-<cmd>` (hyphen) slash commands** — the installer was writing command files to `.claude/commands/gsd/<cmd>.md` (subdirectory with bare names), causing Claude Code to namespace them as `/gsd:<cmd>` (colon form). The fix writes flat `gsd-<cmd>.md` files at `.claude/commands/` level so Claude Code registers `/gsd-<cmd>` (hyphen form), matching hooks, statusline, and all cross-command references. Legacy `commands/gsd/` directories from prior installs are cleaned up on reinstall and uninstall, with `dev-preferences.md` preserved. (#1367)
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1369
|
||||
---
|
||||
**`execute-phase` now re-checks the worktree fork base at the start of every wave and resets the wave manifest between waves (#1369)** — two compounding issues caused wave N+1 worktrees to be created from the stale pre-wave-N commit. First, the `worktree.base-check` auto-degrade only ran once at initialize time; after Wave N merged and tracking commits advanced orchestrator HEAD past `origin/HEAD`, Wave N+1 worktrees were still forked from `origin/HEAD` (Claude Code's "fresh" base), causing both agents to immediately halt with `FATAL: worktree base mismatch` from the `worktree_branch_check` guard. Second, `WAVE_WORKTREE_MANIFEST` was never unset between waves, so wave N+1 would reuse the consumed wave-N manifest file, causing the step 5.5 manifest guard (#3384) to block on subsequent waves. Two safeguards fix this: step 0.5 in the `execute_waves` "For each wave" loop re-runs `worktree.base-check` before every wave's dispatch (when divergence is detected, `USE_WORKTREES` is overridden to `false` for that wave); step 7c between waves unsets `WAVE_WORKTREE_MANIFEST` so wave N+1 creates a fresh per-wave manifest, and re-asserts `worktree.baseRef:"head"` (idempotent) so the Claude Code harness re-reads the live HEAD on the next dispatch. The permanent fix remains setting `worktree.baseRef:"head"` in `.claude/settings.local.json` (see #683).
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Added
|
||||
pr: 1452
|
||||
---
|
||||
**`workflow.context_guard_mode` config key** — proactive context-exhaustion guard for `execute-phase`. Before each wave, the orchestrator self-assesses context pressure using the degradation signals defined in `context-budget.md`. Values: `warn` (default — emit warning and recommend `/gsd:pause-work` when POOR tier detected), `auto` (automatically invoke `/gsd:pause-work` before next wave), `off` (disable). Set via `gsd config-set workflow.context_guard_mode auto` for fully autonomous checkpoint behaviour. (#1452)
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1532
|
||||
---
|
||||
**Core-path file locks now verify the holder process is alive before stealing a stale lock (#1532)** — the STATE.md write lock (`acquireStateLock`) and the `.planning/` workspace lock (`withPlanningLock`) previously stole locks on a bare `mtime` timer with no liveness check, so a live-but-slow holder (e.g. a deep `.planning/` scan on slow NFS) could have its lock stolen mid-write, corrupting STATE.md or losing an update. Both locks now gate stealing on `process.kill(pid,0)` liveness with a deadman ceiling above the wait budget (pid-reuse backstop), `withPlanningLock` no longer force-steals a live holder on timeout (and can no longer leak an uncaught `EEXIST`), `writeStateMd` computes its disk scan inside the lock, and `acquireStateLock` no longer leaks a file descriptor or strands an empty lock on a recoverable write error. The steal itself is now race-safe: a lock is never stolen while its body is still being written (the create→pid-write window), and stealing uses an atomic rename with an identity re-confirm so two waiters can no longer both reclaim the same lock and end up holding it concurrently. The uncontended path is unchanged.
|
||||
5
.changeset/1688-stale-bake-guard.md
Normal file
5
.changeset/1688-stale-bake-guard.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
type: Added
|
||||
pr: 1692
|
||||
---
|
||||
**GSD now warns when model config changed without re-running the installer on static-frontmatter runtimes** — on `codex` and `opencode`, editing `model_overrides` or `model_profile_overrides` or `model_policy.runtime_tiers` in `.planning/config.json` or `~/.gsd/defaults.json` previously had no effect until the user re-ran `gsd install <runtime>`, and the failure was silent: the sub-agent kept using the base model. Workflow entry points like `gsd-tools init *` now emit a one-line stderr warning naming the changed config file and the exact remediation command when they detect the config is newer than the baked agent files. The guard is read-only and warning-only by default, dedup'd per session, and skipped entirely on Claude Code because Claude Code resolves models at spawn time. Resolves #1688 as the structural follow-up to #1650.
|
||||
@@ -1,10 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1483
|
||||
---
|
||||
|
||||
fix(#1472): validate health is now workstream-aware — PROJECT.md and config.json are resolved from .planning/ root, while ROADMAP.md, STATE.md, and phases/ follow the workstream-scoped path; previously both sets were routed through planningDir() causing false E002/E003/E004/W003 when GSD_WORKSTREAM is set.
|
||||
|
||||
fix(#1454): validate health W017 no longer suggests removing the active session's worktree — stale-worktree findings are now skipped when the worktree path matches or is an ancestor of process.cwd().
|
||||
|
||||
<!-- docs-exempt: internal verify.cts fix — no public user-facing API or CLI change; behavior correction for workstream-scoped health validation -->
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1537
|
||||
---
|
||||
**Non-Claude runtime installs now resolve their own runtime and never attempt Claude-only worktree isolation** — on any non-Claude install (Cursor, Gemini, Qwen, etc.) a runtime-neutral `.planning/config.json` previously resolved `runtime=claude` and enabled git worktree isolation, which only Claude Code's `isolation="worktree"` can honor — risking main-checkout edits while the workflow believed agents were isolated. Every non-Claude install now resolves its own runtime identity, defaults `workflow.use_worktrees` to `false`, fails closed if worktrees are forced on, and runs plan/execute inline in the manager/autonomous flows since only Codex can background-nest the pipeline's subagents. (#1521)
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1456
|
||||
---
|
||||
Phase-aware commands now resolve project-code-prefixed ROADMAP headings such as MANIFOLD-117, while the roadmapper is instructed to keep project_code out of phase headings.
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
type: Changed
|
||||
pr: 1438
|
||||
---
|
||||
**Thread `isGlobal` install scope through the descriptor-driven `convertedAgentsKind` / `stageAgentsForRuntimeWithConverter` plumbing** — a prerequisite for the ADR-1235 agent-conversion cutover. No runtime declares a converted `agents` kind yet; the `capability.json` wiring is deferred to a follow-up that first ships the ADR-1235 §0 byte-for-byte parity harness (so the `/gsd:surface` / `--materialize` consumer can mirror the legacy agent pipeline before the kind goes live). The legacy `bin/install.js` agent loop remains authoritative, so installed agent output is unchanged. (#1173)
|
||||
|
||||
<!-- docs-exempt: internal install-path plumbing only (ADR-1235 cutover prerequisite); no runtime declares the converted agents kind, the legacy loop remains authoritative, and installed agent output is unchanged — no user-facing command/config/behavior surface. -->
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1500
|
||||
---
|
||||
**`workflow.mvp_mode` now accepted by `config-set`; three undocumented workflow keys added to references** — `workflow.mvp_mode`, `workflow.code_review_command`, and `workflow.plan_chunked` were consumed by planning-pipeline code but could not be set via `config-set` (they were missing from `VALID_CONFIG_KEYS`) or discovered via reference docs. All three are now in the schema and documented in `references/planning-config.md`. (#1500)
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1536
|
||||
---
|
||||
adr-parser now classifies 9 previously-dropped punctuated ADR headers (Trade-offs, Non-Goals, Won't Do, Follow-up, How We'll Know, etc.) into their intended buckets instead of leaving them unmapped.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Changed
|
||||
pr: 1421
|
||||
---
|
||||
**`/gsd-review` now asks external reviewers to verify plan claims against the source** — the reviewer prompt requires opening the referenced files, citing `file:line` evidence + mechanism, and tracing asserted behavior, with a graceful-degradation clause for reviewers that have no file access. This turns every capable agentic reviewer into a real second source instead of a plan-text paraphraser. (#1318)
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1534
|
||||
---
|
||||
Add prototype-pollution guard to the workstream/root config merge (_deepMergeConfig) so a config.json with a __proto__/constructor/prototype key can no longer spoof unset config flags.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1418
|
||||
---
|
||||
**All GSD agents load on Gemini again** — the Claude `Skill`/`SlashCommand` tools were converted to an invalid `skill` tool that Gemini rejects, aborting the load of 22 of 34 agents. They are now excluded from the Gemini and Gemini-backed Antigravity agent `tools:` frontmatter, the same way `AskUserQuestion` already is. (#1394)
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Added
|
||||
pr: 1425
|
||||
---
|
||||
**`agent-skills --json` IR gains an additive `value: { block, skills_count }` field** formalizing the `Resolution<T>` convention for config-interpreting read verbs; no breaking change. The new `src/resolution.cts` module exports `Resolution<T> { value, configured, reason, warnings }` (the canonical envelope) and `makeResolution<T>()` (the builder); `AgentSkillsValue { block, skills_count }` is the first adopter. All existing flat fields (`agent_type`, `block`, `skills_count`, `warnings`, `configured`, `reason`, `source`, `degraded`) are retained for back-compat. Capability-state and capability-writer keep their existing JSON shapes unchanged; only doc comments are added naming them the canonical read-verb and mutation-verb envelopes respectively. The shared seam across all shapes is `warnings: string[]`; a single generic across read+write verbs was rejected by the deletion test (ADR-1411 P3 amendment). (Part of #1411, P3 / #1416.)
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Added
|
||||
pr: 1488
|
||||
---
|
||||
**Added `gsd capability outdated`** — a new subcommand that light-peeks each installed overlay capability's recorded source for the latest version that re-resolving that source would install and reports which have an update available (ADR-1244 D6 per-source matrix: git `ls-remote --tags`, npm `view … version`, local re-read; tarball → `manual`, registry → `unknown`). A capability is reported `outdated` only if re-resolving its recorded source would fetch a newer version: an npm range (`@^1`) resolves to the highest version **matching the range** (read from each `npm view` line's canonical version field, so a version-like substring in the package name never poisons the result), and a source pinned to an immutable ref (git `#sha:`/`#tag:`) or an exact npm version is reported `pinned` — never `outdated`, since `update` will not move it. A bare git ref (`#<ref>`) is classified at the remote with a bounded `git ls-remote`: a ref that resolves to a tag is `pinned`, while a **mutable branch** ref is never `pinned` (it degrades to `unknown`, since the installed commit is not recorded to compare against). Each capability is classified `outdated` / `current` / `pinned` / `manual` / `unknown`; subprocesses are bounded (git ≤30s, npm ≤60s) and a failing or unsupported peek degrades that row to `unknown` instead of crashing the command. `--json` emits the records array; the default prints a table. (#1463)
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1442
|
||||
---
|
||||
**Antigravity config-dir resolution no longer shadows the active runtime** — when more than one of `~/.gemini/antigravity`, `antigravity-ide`, or `antigravity-cli` exists, GSD now resolves to the directory it actually installed into (marked by `gsd-core/VERSION`) instead of whichever directory existed first. Fixes silent misresolution where a CLI user who also had the Antigravity-IDE dir present was sent to the legacy dir (regression from #217).
|
||||
@@ -1,8 +0,0 @@
|
||||
---
|
||||
type: Changed
|
||||
pr: 1423
|
||||
---
|
||||
**`gsd-tools` now resolves the project root from a descendant subdirectory** — `findProjectRoot` walks up to the nearest ancestor directory containing `.planning/` so config loads correctly when invoked outside the project root; previously it fell through to defaults for plain descendant paths (cwd-drift gap #1366). Sub_repos, multiRepo, and `.git`-based heuristics retain priority. (Part of #1411, P1 / #1414)
|
||||
|
||||
<!-- docs-exempt: internal resolution heuristic in project-root.cts — no public docs surface for findProjectRoot; behavior change surfaced via config loading, not a user-visible API -->
|
||||
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1424
|
||||
---
|
||||
**`gsd-tools query agent-skills` no longer silently drops a configured agent's skills under cwd or workstream drift** — `cmdAgentSkills` now anchors to the project root via `findProjectRoot` before loading config, so invoking it from a descendant subdirectory or with a `GSD_WORKSTREAM` that has no scoped config correctly resolves the configured `agent_skills` block. A new `loadConfigResolved(cwd, options) → { config, source, degraded }` function reports provenance alongside the config object: `source` distinguishes `'root' | 'workstream' | 'builtin-defaults' | 'global-defaults'`; `degraded:true` signals a workstream was requested but its config.json was absent. The `--json` IR of `agent-skills` gains four new fields — `configured` (bool), `reason` (`'resolved' | 'not_configured' | 'configured_empty' | 'configured_unresolved'`), `source`, and `degraded` — making silent failures visible and testable. A `configured_empty` or `configured_unresolved` agent emits a `stderr WARNING`; an unconfigured agent stays silent. (Closes #1366. Part of #1411, P2 / #1415.)
|
||||
@@ -1,9 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1484
|
||||
---
|
||||
**`findProjectRoot` now respects explicit `sub_repos` config over implicit `.git`** — when a parent workspace's `.planning/config.json` lists a child directory in `sub_repos`, that declaration takes precedence over the child's own `.git/` directory. Previously, if the child had both `.planning/` and `.git/`, the `.git` heuristic fired first and resolved to the child rather than the parent workspace, making the `sub_repos` declaration ineffective. (#1422)
|
||||
|
||||
**`phases clear` now refuses to delete phase directories with uncommitted changes** — `cmdPhasesClear` runs `git status --porcelain` over the phases directory before executing any deletion. If uncommitted or staged-but-not-committed files are found it aborts with a clear error message, preventing silent data loss at `new-milestone` time. Pass `--force` to bypass the guard when archival is already complete. Non-git projects are unaffected. (#1447, data-loss fix)
|
||||
|
||||
<!-- docs-exempt: internal CLI guard in milestone.cts — no public docs surface change; --force flag is an operator escape hatch, not a user-visible API change -->
|
||||
@@ -1,6 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1490
|
||||
---
|
||||
|
||||
**999.x backlog phases are now excluded from `total_phases`, and `total_phases` can correct downward** — `deriveProgressFromRoadmap` counted all progress-table rows whose phase cell started with a digit, so a `999.1 Backlog` row inflated `total_phases` by one per entry (#1445). The same overcounting occurred in `getMilestonePhaseFilter` (which feeds `isDirInMilestone` and `phaseDirs`) and in the `roadmapPhaseCount` loop in `buildStateFrontmatter`. All three sites now filter phase tokens matching `/^999\b/`, consistent with the existing exclusion in `init.cts`. Additionally, `shouldPreserveExistingProgress` included `total_phases` in its ratchet check, preventing the counter from decreasing once set too high — e.g. after a 999.x fix or a ROADMAP correction (#1446). `total_phases` is now always taken from the freshly derived value; only `completed_phases`, `total_plans`, and `completed_plans` retain ratchet behaviour.
|
||||
File diff suppressed because one or more lines are too long
@@ -1,6 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1481
|
||||
---
|
||||
|
||||
**Capability `--integrity` is now verified or rejected per source, and hook commands are confined to the bundle** — a supplied `--integrity` pin was silently dropped for npm, git, and local capability sources (only the tarball source verified it), so a user could believe content was pinned when it was not. npm now verifies the pin over the `npm pack` `.tgz` bytes; git and local sources, which have no single hashable artifact, now reject a supplied `--integrity` with an actionable error instead of ignoring it. Separately, a capability hook's relative `script` was written verbatim as the hook command, so it resolved against the working directory (not the capability bundle) at hook-exec time and a crafted relative path could escape the bundle; the command is now resolved against the capability's own install dir and realpath-confined to it, then written as an absolute path. That absolute command is consumed by a shell, which exposed two further problems now fixed: (1) a manifest could ship a file literally named `run.sh; touch /tmp/pwn` (filenames may legally contain `;`, spaces, `$`, backtick, `|`, newline) and declare it as the hook `script`, so the emitted command injected a second shell command even though the file lived inside the bundle — the validator now rejects any hook script path outside a conservative `[A-Za-z0-9._/-]` allowlist (no whitespace, shell metacharacters, leading `-`, absolute path, or `..`), failing the install/load loudly, and the confinement helper mirrors the same rejection defensively; (2) the absolute path begins with the install-home directory, which commonly contains spaces (e.g. `/Users/Bob Smith/.claude/...`) and word-split or broke when written unquoted — the emitted command is now POSIX single-quoted so the install prefix can neither break nor inject. (#1460)
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1475
|
||||
---
|
||||
**The capability loader never crashes on a single malformed overlay, and untrusted manifest/tar reads are size-bounded (ADR-1244 D2 invariant)** — `loadRegistry` now makes the WHOLE per-candidate overlay-processing body total: ANY throw from ANY validator or step (including the committed `validateCapability`, which dereferences a malformed array entry such as `gates: [null]` / `steps: [null]` / `contributions: [null]` before its shape check) drops just that one overlay with a skip-warning instead of escaping the loader, while `gatePointsOf` is hardened to be total over null/non-array/malformed gates. The final canonical `buildRegistry` compose stays guarded: a throw on the merged set falls back to the frozen first-party registry plus a warning, records each dropped gate-declaring overlay's declared gate as blocked (`incompatibleGateCapIds` / `blockedGates`) so a dropped blocking gate FAILS CLOSED, AND now clears `_overlay.commandRoots` in the fallback so no dropped overlay retains a stale command root. Previously a malformed-array throw or a compose throw escaped the loader and crashed every consumer (loop-resolver, config-loader, surface, capability-state, gsd-tools). On the source side, the capability resolver/staging now reads every untrusted `capability.json` (tarball / npm / git / local) via the shared bounded fd-reader (regular-file + 8 MiB cap) instead of a raw `fs.readFileSync`, so an oversized or FIFO/non-regular extracted-or-local manifest can no longer OOM or hang the resolver; the fetch (`realHttpsGet`) bounds the downloaded response to 64 MiB; and `stageValidated` now enforces ONE uniform aggregate byte-budget (`MAX_STAGED_BUNDLE_BYTES`, 128 MiB) over the STAGED bundle directory via a bounded streaming walk (cumulative byte + entry counters; symlink / non-regular entries rejected) at the common staging chokepoint — AFTER staging and BEFORE validation/promotion — so a huge source tree, git repo, npm package, or gzip/tar bomb is rejected (and its staging dir cleaned up) before promotion, uniformly bounding the RESULT of `copyDirRecursive` / `git clone` / `npm pack` / `tar -x` that were previously only timeout-bounded. `copyDirRecursive` itself is now STREAMING and BUDGETED: it enumerates each directory via `fs.opendirSync` + `dir.readSync()` (one entry at a time) and threads CUMULATIVE entry (`MAX_STAGED_BUNDLE_ENTRIES`, 100k) and byte (`MAX_STAGED_BUNDLE_BYTES`) counters through the recursion, failing closed the MOMENT either cap is exceeded DURING the copy — closing a residual where the former `fs.readdirSync(src, { withFileTypes: true })` materialized the ENTIRE directory-entry array into memory at staging time (BEFORE the post-copy budget walk), so a hostile source whose tree held a directory of millions of tiny files (fetch < 64 MiB, but a colossal dirent array) could OOM the process during the copy before the budget could fail closed; the post-copy walk is retained as a cheap belt-and-suspenders re-verification on what actually landed in staging. The spoofable per-member `tar`-header size parse (`parseTarMemberSize`, which mis-anchored on BSD `tar -tv` owner/group columns such as a `Jan` group → fail-open) was REMOVED in favor of that non-spoofable staged-dir budget; `assertSafeTarMembers` keeps its unambiguous traversal / symlink / hardlink NAME and TYPE guards. (#1461)
|
||||
|
||||
<!-- docs-exempt: internal robustness hardening of the runtime capability loader/source seams (capability-loader.cts / capability-source.cts) — no user-visible API change; the never-crash + bounded-fetch guarantees are ADR-1244 D2 internal invariants -->
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1469
|
||||
---
|
||||
**Capability ledger: fail closed on corruption, with durable atomic writes and a race-safe install lock.** A corrupt or unreadable `.gsd-capabilities.json` is now left in place and surfaced (not silently overwritten) — `install`/`update`/`remove`/`list`/`reconcile` fail closed and report it, so a corrupt ledger can no longer wipe prior capabilities' tracked files and shared-config fragments (which previously left unremovable orphans in `settings.json`/`hooks.json`). Ledger writes are atomic and crash-durable (exclusive temp file + `fsync` of file and directory + rename, with temp cleanup on failure). The per-capability lock is race-safe: a holder is identified by `(pid, process start-time, hostname)`, so a reused PID cannot deadlock recovery and a verifiably-live holder is never stolen, with a hard deadman timeout for unverifiable or cross-host holders. Untrusted ledger and lock reads are bounded (regular-file + size caps; FIFOs/devices rejected) and validated through a single shared entry validator (prototype-safe ids, DoS length caps). (#1462, ADR-1244.)
|
||||
@@ -1,8 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1482
|
||||
---
|
||||
|
||||
fix(#1478,#1479,#1480): prohibit ungrounded baselines, error-suppressing fallbacks, and stale-artifact authority in planner verify blocks
|
||||
|
||||
<!-- docs-exempt: instruction-text updates to agents/gsd-planner.md, agents/gsd-plan-checker.md, and references/planner-antipatterns.md are themselves the documentation — no public user-facing API or CLI change -->
|
||||
@@ -1,6 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 667
|
||||
---
|
||||
|
||||
**`/gsd:pr-branch` now handles sub-repos defined in config** — when `planning.sub_repos` is set, the command scans each sub-repo for uncommitted changes and offers to create a branch, commit, push, and open a companion PR per sub-repo. Previously, sub-repos were silently ignored because all git commands ran against the shell's current directory instead of the intended repo path. All sub-repo git operations now use `git -C <repo>` so no shell-state assumptions are made.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1457
|
||||
---
|
||||
**`--raw` CLI commands no longer drop stdout on the error path** — a command that emitted a JSON result/error envelope and then exited non-zero previously lost all of stdout (the output-capture wrapper discarded its buffer when the command threw to set a non-zero exit); the buffer is now flushed before the error propagates. (#1457)
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Added
|
||||
pr: 1457
|
||||
---
|
||||
**`gsd capability` management command** — install, update, remove, list, disable, and enable GSD capabilities (first-party and third-party overlays) from a registry / git / npm / tarball / local source, wiring the ADR-1244 lifecycle (source resolver, ledger, consent + integrity trust gate) to a user-facing CLI. (#1457)
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Added
|
||||
pr: 1440
|
||||
---
|
||||
**Runtime capability registry overlay** — installed third-party capabilities (under `~/.gsd/capabilities/` or a project's `.gsd/capabilities/`) are now composed into the registry at runtime via `loadRegistry({ includeInstalled })`: validated against the same conformance invariants as first-party, first-party-wins on any collision, skipped-with-a-warning when incompatible with the running GSD version (`engines.gsd`), with gate-kind capabilities failing closed. Installed overlays are toggable via surface and federate their config keys (cwd-aware) exactly like first-party. Foundation (ADR-1244 Phase 2) for capability install/upgrade/remove.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1519
|
||||
---
|
||||
**Codex installs no longer run with unsafe Claude-style worktree isolation** — a Codex install with a runtime-neutral `.planning/config.json` was resolving its runtime as Claude and enabling git worktree isolation, which Codex's `spawn_agent` cannot honor; the Codex fail-closed guard was also silently dead because runtime/worktree config was read JSON-quoted and broke shell equality checks. Codex-emitted workflows now resolve `runtime=codex`, default `workflow.use_worktrees` to `false`, and fail closed when worktrees are forced on. (#1515)
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Added
|
||||
pr: 1436
|
||||
---
|
||||
**Capability manifests are now versioned** — every `capability.json` carries a required semver `version`, plus optional `engines.gsd`, `compatVersions`, `integrity` and `provenance` fields, enforced by the capability conformance validator. First-party capabilities are version-stamped in lockstep with the GSD release. Foundation (ADR-1244 Phase 1) for installing, upgrading, and removing capabilities in later releases.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Security
|
||||
pr: 1449
|
||||
---
|
||||
**Third-party capability trust gate (ADR-1244 Phase 4)** — installing a capability from a git/npm/tarball/local source now discloses every executable surface it ships (hooks, command modules, MCP servers, with the actual commands) and requires explicit consent before anything is promoted; integrity (sha512) and `engines.gsd` are verified before any code is staged, install never executes capability code, and reserved `gsd-`/`gsd-core-`/`anthropic-` namespaces are refused. `capabilities.strict_known_registries` gates which sources may be installed (`[]` = local-only lockdown; host-based allowlist otherwise) and `capabilities.auto_update` is off by default, re-prompting whenever a new version's executable set changes. An install ledger makes `remove` surgical (strips only the capability's own shared-config entries, preserving your hand-edits) and `update` an atomic, crash-safe stage-then-swap. (#1449)
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1504
|
||||
---
|
||||
`verify codebase-drift` now reads `workflow.drift_action` and `workflow.drift_threshold` from the correct nested config shape — previously both keys silently no-oped because `loadConfig()` returns a flattened object and `config?.workflow` was always `undefined`.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Added
|
||||
pr: 722
|
||||
---
|
||||
**`/gsd-capture --list-seeds` audits parked seeds** — a new read-only listing of `.planning/seeds/` showing each seed's ID, status, scope, and trigger, with an optional status filter (e.g. `--list-seeds dormant`). Backed by the `gsd-tools list-seeds` command. Previously seeds could only be created or auto-surfaced at `/gsd-new-milestone`, with no way to browse them on demand (#441).
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Added
|
||||
pr: 1443
|
||||
---
|
||||
**Capability source resolver + install ledger** — `resolveCapabilitySource(spec)` fetches a capability from a local path, git repo, npm package, or tarball URL, verifies it (sha512 integrity before staging, `engines.gsd` compatibility, full conformance validation) and stages a bundle **without executing any capability code** (copy/extract only — `npm pack --ignore-scripts`, never `npm install`; symlink/tar-slip/shell-metacharacter/unsafe-transport inputs rejected). A per-runtime ledger records what each install wrote for atomic, reversible upgrade/remove. Foundation (ADR-1244 Phase 3) for the upcoming `gsd capability install` command.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Added
|
||||
pr: 1458
|
||||
---
|
||||
**Capability matrix reference** — a generated catalogue (`docs/reference/capability-matrix.md`) of every first-party capability's role, tier, extension points, hook kinds, and `engines.gsd`, generated from the committed registry and kept honest by a CI drift guard so it can never fall out of sync with the actual capability set. (#1458)
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1499
|
||||
---
|
||||
**`npm version` no longer leaves `capability-registry.cjs` stale** — the `version` npm lifecycle script now regenerates and stages the capability registry after stamping new version strings into all capability manifests, preventing the 1.6.0-rc regression where `gen-capability-registry.cjs --check` failed. (#1498)
|
||||
|
||||
<!-- docs-exempt: internal release-tooling fix; no user-facing command or API change -->
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Added
|
||||
pr: 1450
|
||||
---
|
||||
**Third-party capabilities can ship dispatchable CLI commands (ADR-1244 Phase 5)** — a capability that declares a `commands` family is now dispatched by `gsd-tools <family>` via the registry, the same seam the first-party `graphify`/`intel`/`audit` commands already use. Third-party command dispatch runs only for an installed, consented capability (a committed ledger entry) and loads the router module strictly from that capability's own install root (basename + realpath confinement, rejecting `..` traversal and symlink escape); a bundle merely present on disk with no install record keeps its declarative surfaces but is never command-dispatchable. (#1450)
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Changed
|
||||
pr: 1518
|
||||
---
|
||||
**verify-phase test-tier prohibition fail-first can now prove the RED is caused by the violation's _content_** — the `node-test` machine-proof (#1279) confirmed a known-bad subject drives the negative test RED, but could not tell a genuine content-violation from a deceptive test that reds merely because `GSD_PROHIB_SUBJECT` is set. An optional fifth flat scalar `check_clean_fixture` (→ `CheckDescriptor.cleanFixture`) threads a KNOWN-CLEAN control subject through `projectProhibitions` + `descriptorFromProjection`; when present the prover also runs the check against it and requires GREEN, so fail-first is proven only when the check is RED on the violation **and** GREEN on the clean subject (content-dependent). It is opt-in and additive: absent a clean fixture the prover behaves exactly as it did post-#1314 (no control, documented residual), preserving the zero-authoring compose path; the lint-rule kind needs no analog. (#1346)
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1574
|
||||
---
|
||||
**OpenCode and other AGENTS-native runtimes now get a root `AGENTS.md` from `/gsd:new-project`** — the workflow hardcoded a codex-only branch that sent every other runtime to `.claude/CLAUDE.md`, a location OpenCode never loads. A shared `getProjectInstructionFile(runtime)` policy (claude→`.claude/CLAUDE.md`, codex/opencode/kilo/kimi→`AGENTS.md`, copilot→`.github/copilot-instructions.md`, antigravity/gemini→`GEMINI.md`) is now the single source of truth consumed by both the new-project workflow and the generate-claude-md path, with a parity test guarding drift.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1539
|
||||
---
|
||||
`roadmap upgrade` now rejects an unsupported or malformed `--convention` value (including the `--convention=` form) instead of silently running the milestone-prefixed migration, and no longer hard-exits inside the command-routing hub.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Added
|
||||
pr: 1597
|
||||
---
|
||||
**Plugin installs now expose GSD skills** — when GSD is installed as a Claude Code plugin (`claude plugin install`), its skills are available via `gsd-core:<skill>` the native way. Previously, plugin-only installs lacked the skill surface because `bin/install.js` never ran; agents that preload `global:gsd-core:<skill>` (PR #1261) now resolve against plugin-provided skills. (#1596)
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1543
|
||||
---
|
||||
A failed `roadmap upgrade --apply` now actually rolls back .planning/ even when it is gitignored (commit_docs:false), instead of reporting a successful rollback while leaving the workspace half-migrated. Rollback is surgical and no longer runs a whole-repo git reset --hard.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1409
|
||||
---
|
||||
**Codex runtime no longer crashes on startup** — every `gsd-tools` command previously aborted with `Cannot find module '../../../package.json'` on Codex, whose runtime root has no `package.json`, because a module in the loader chain did a top-level require of it. The version emitted into Hermes skill frontmatter is now sourced lazily from the installed `gsd-core/VERSION` (validated semver), so `gsd-tools` loads on every runtime and never emits `version: undefined`. (#1383)
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Added
|
||||
pr: 1448
|
||||
---
|
||||
Added a validated `gsd-tools worktree record-agent` writer verb that appends a per-agent entry to the wave cleanup manifest, validating every field at write time with the same rules the `cleanup-wave` reader enforces (write-strict `--agent-id`) and failing loudly with a recovery hint instead of silently appending an under-populated entry. The execute-phase orchestrator now records each spawned worktree through this verb. (#1448)
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1410
|
||||
---
|
||||
**`query agent-skills` no longer returns empty output on Windows** — the plain (non-`--json`) path wrote the `<agent_skills>` block then immediately called `process.exit(0)`, which truncated the async stdout buffer on Windows pipes/files so every `${AGENT_SKILLS_*}` workflow capture expanded empty and configured per-agent skills were silently dropped. It now flushes synchronously via the same `writeAllSync` helper the `--json` path uses. (#1400)
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1453
|
||||
---
|
||||
clean up stale get-shit-done paths in Codex and Kimi skill mirrors on upgrade (#1453)
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1437
|
||||
---
|
||||
add phase.list-plans to gsd-tools — the command was referenced in agents/gsd-plan-checker.md but was missing from the router, causing 'Unknown phase subcommand' on every invocation
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1552
|
||||
---
|
||||
roadmap analyze no longer reports phantom missing_phase_details for milestone-prefixed (M-NN) phase IDs
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
type: Added
|
||||
pr: 1419
|
||||
---
|
||||
**`gap-analysis --phase-req-ids` now expands numeric ID ranges** — a same-prefix ascending equal-width range like `SEL-01..SEL-03` expands to `SEL-01, SEL-02, SEL-03` (zero-pad preserved) instead of being treated as one literal ID that gap-analysis then reports as missing. Ambiguous tokens (mismatched prefix, descending, differing width, non-numeric, >1000 span) stay literal. (#1269)
|
||||
|
||||
<!-- docs-exempt: `--phase-req-ids` is an internal gsd-tools query flag consumed by GSD workflows, not part of the user-facing documented command surface; no docs/ entry exists for it. -->
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1541
|
||||
---
|
||||
Atomic file writes now retry a transient rename lock on Windows (a reader holding the target open) instead of falling back to a non-atomic write that could let a concurrent reader observe a truncated STATE.md/ROADMAP.md.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1376
|
||||
---
|
||||
**Misconfigured agent skills no longer fail silently** — when an agent's configured `agent_skills` paths all fail to resolve (e.g. a missing `SKILL.md`), `gsd-tools query agent-skills` now emits an aggregate warning to stderr and adds a `warnings[]` field to its `--json` output, instead of returning an empty block with no signal. (#1376)
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1386
|
||||
---
|
||||
**Decision-coverage gate now reads markdown-header and em-dash decisions, and fails loud when it can't parse them** — `check.decision-coverage-plan` (a blocking gate) and `gap-analysis` previously extracted **zero** decisions from a populated CONTEXT.md that recorded its decisions under markdown headers (`## Locked decisions`) or with em-dash bullets (`- **D-1 — title**`), and silently reported a clean pass — so real decisions went un-checked. Decisions in those shapes are now recognized, and when decision-shaped content cannot be parsed (or a `- **D-NN**` bullet is malformed), the gate fails loud with a format-mismatch message instead of passing. (#1386)
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "gsd-core",
|
||||
"displayName": "GSD Core",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
|
||||
"author": {
|
||||
"name": "open-gsd",
|
||||
|
||||
144
.github/workflows/pr-title-validator.yml
vendored
Normal file
144
.github/workflows/pr-title-validator.yml
vendored
Normal file
@@ -0,0 +1,144 @@
|
||||
name: PR Title Validator
|
||||
|
||||
# Enforce the PR-title convention the release changelog depends on (#1549).
|
||||
#
|
||||
# The changelog is entirely title-driven: release.yml runs
|
||||
# `gh release create --generate-notes` (GitHub builds "What's Changed" from PR
|
||||
# titles) and scripts/release-notes/format-github-release-notes.cjs reformats
|
||||
# it. Two independent rules are read off the title:
|
||||
# 1. Bucket — classifyBucket() anchors on the leading type (^feat / ^fix /
|
||||
# else Enhancement). A leading tag (e.g. `[security] `) defeats
|
||||
# the anchor and silently mis-files the entry.
|
||||
# 2. Issue link — the `(#<issue>)` in the title is what renders as a link to
|
||||
# the issue in the changelog line.
|
||||
#
|
||||
# This gate reuses the SAME matcher the changelog uses
|
||||
# (scripts/release-notes/conventional-title.cjs) — not a forked regex — so a title that
|
||||
# passes here cannot mis-bucket in the changelog.
|
||||
#
|
||||
# Trust boundary: the matcher is loaded from a BASE-branch checkout (the
|
||||
# already-merged, reviewed copy on the PR's target), exactly as
|
||||
# pr-target-validator loads its policy. The PR cannot edit the ruler that
|
||||
# measures its own title, so the gate is not self-bypassable. Until this
|
||||
# matcher lands on the base branch it does not exist there — the introducing
|
||||
# PR is skipped (bootstrap); every PR after merge is fully gated.
|
||||
#
|
||||
# Unlike pr-target-validator, this runs for ALL authors (including members):
|
||||
# the changelog drift that motivated #1549 came from member PRs.
|
||||
#
|
||||
# Phase-1 rollout: set WARN_ONLY=true to comment without failing the check.
|
||||
# Shipped enforcing (WARN_ONLY=false); flip to 'true' for a grace period.
|
||||
#
|
||||
# See: scripts/release-notes/conventional-title.cjs, CONTRIBUTING.md, issue #1549.
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
types: [opened, edited, reopened, synchronize]
|
||||
|
||||
concurrency:
|
||||
group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
|
||||
cancel-in-progress: true
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
pull-requests: write
|
||||
|
||||
jobs:
|
||||
validate-title:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 2
|
||||
env:
|
||||
# Phase-1: set to 'true' to warn only. Shipped enforcing.
|
||||
WARN_ONLY: 'false'
|
||||
steps:
|
||||
# Check out the BASE branch (the PR's merge target) as the trusted policy
|
||||
# source — not the PR head. The matcher that judges the title must be
|
||||
# already-merged, reviewed code so a PR cannot bypass the gate by editing
|
||||
# conventional-title.cjs to accept its own malformed title. Mirrors
|
||||
# pr-target-validator.yml. The introducing PR is handled by the bootstrap
|
||||
# guard in the script below (the matcher isn't on base yet).
|
||||
- name: Checkout base branch (trusted policy source)
|
||||
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
|
||||
with:
|
||||
ref: ${{ github.event.pull_request.base.ref }}
|
||||
persist-credentials: false
|
||||
|
||||
- name: Validate PR title
|
||||
uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
|
||||
env:
|
||||
WARN_ONLY: ${{ env.WARN_ONLY }}
|
||||
with:
|
||||
script: |
|
||||
const fs = require('fs');
|
||||
const matcherPath = `${process.env.GITHUB_WORKSPACE}/scripts/release-notes/conventional-title.cjs`;
|
||||
|
||||
const pr = context.payload.pull_request;
|
||||
const title = pr.title || '';
|
||||
const warnOnly = process.env.WARN_ONLY === 'true';
|
||||
|
||||
// Bootstrap: the matcher is loaded from the base-branch checkout, so it
|
||||
// is absent on the PR that first introduces it. Skip rather than fail —
|
||||
// once this lands on the base branch, every subsequent PR is gated.
|
||||
if (!fs.existsSync(matcherPath)) {
|
||||
core.info('conventional-title.cjs not on the base branch yet — bootstrap PR, skipping title check.');
|
||||
return;
|
||||
}
|
||||
const { evaluatePrTitle } = require(matcherPath);
|
||||
|
||||
const result = evaluatePrTitle({ title });
|
||||
|
||||
if (result.valid) {
|
||||
core.info(`PR title OK: ${title}`);
|
||||
return;
|
||||
}
|
||||
|
||||
const msg = [
|
||||
`### PR title needs the issue-ref convention`,
|
||||
``,
|
||||
`\`${title}\``,
|
||||
``,
|
||||
result.message,
|
||||
``,
|
||||
`**How to fix:** click "Edit" next to the PR title above and retitle it`,
|
||||
`as \`type(#<issue>): summary\`. No need to recreate the PR — this check`,
|
||||
`re-runs when you edit the title.`,
|
||||
``,
|
||||
`<details><summary>Why this is enforced</summary>`,
|
||||
``,
|
||||
`The release changelog is built from PR titles. A leading tag mis-files`,
|
||||
`the entry into the wrong section, and a scope without \`(#<issue>)\` leaves`,
|
||||
`the changelog line with no link back to the issue. See issue #1549.`,
|
||||
``,
|
||||
`</details>`,
|
||||
].join('\n');
|
||||
|
||||
// Post or update a sticky comment.
|
||||
const { data: comments } = await github.rest.issues.listComments({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
issue_number: pr.number,
|
||||
});
|
||||
const marker = '<!-- pr-title-validator -->';
|
||||
const existing = comments.find(c => c.body && c.body.includes(marker));
|
||||
const body = `${marker}\n${msg}`;
|
||||
if (existing) {
|
||||
await github.rest.issues.updateComment({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
comment_id: existing.id,
|
||||
body,
|
||||
});
|
||||
} else {
|
||||
await github.rest.issues.createComment({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
issue_number: pr.number,
|
||||
body,
|
||||
});
|
||||
}
|
||||
|
||||
if (warnOnly) {
|
||||
core.warning(`PR title convention (warning-only mode): ${result.reason} — ${title}`);
|
||||
} else {
|
||||
core.setFailed(`PR title does not follow the convention (${result.reason}): ${title}`);
|
||||
}
|
||||
3
.gitignore
vendored
3
.gitignore
vendored
@@ -174,6 +174,8 @@ build/
|
||||
/gsd-core/bin/lib/roadmap-upgrade.cjs
|
||||
/gsd-core/bin/lib/phases-command-router.cjs
|
||||
/gsd-core/bin/lib/verify-command-router.cjs
|
||||
/gsd-core/bin/lib/eval.cjs
|
||||
/gsd-core/bin/lib/eval-command-router.cjs
|
||||
/gsd-core/bin/lib/init-command-router.cjs
|
||||
/gsd-core/bin/lib/agent-command-router.cjs
|
||||
/gsd-core/bin/lib/agent-install-check.cjs
|
||||
@@ -192,6 +194,7 @@ build/
|
||||
/gsd-core/bin/lib/verify.cjs
|
||||
/gsd-core/bin/lib/init.cjs
|
||||
/gsd-core/bin/lib/uat.cjs
|
||||
/gsd-core/bin/lib/coverage.cjs
|
||||
/gsd-core/bin/lib/uat-predicate.cjs
|
||||
/gsd-core/bin/lib/workstream.cjs
|
||||
/gsd-core/bin/lib/roadmap.cjs
|
||||
|
||||
105
CHANGELOG.md
105
CHANGELOG.md
File diff suppressed because one or more lines are too long
49
CONTEXT.md
49
CONTEXT.md
@@ -20,6 +20,9 @@ Module owning the pure phase-id parsing and matching helpers: phase-name normali
|
||||
### Phase Lifecycle Module
|
||||
Module owning phase create, rename, complete, remove, list, and plan-index operations, plus phase-dir prefix validation, STATE.md staleness detection, and auto-prune behaviour. Entry point: `gsd-core/bin/lib/phase.cjs` (CJS surface). Typed phase events: `GSDPhaseStartEvent`, `GSDPhaseStepStartEvent`, `GSDPhaseStepCompleteEvent`, `GSDPhaseCompleteEvent`. (The SDK native-query surface, the `types.ts` event definitions, `phase-runner.ts`, and `phase-prompt.ts` were retired with the SDK package per ADR-0174.)
|
||||
|
||||
### Verification Module
|
||||
Module owning the canonical phase-verification status projection shared by phase transition, progress, manager, autonomous, and closeout readiness paths. `readVerificationStatus(phaseDir, opts?)` reads the first `*-VERIFICATION.md` frontmatter `status`, maps it through `VERIFICATION_ROUTING_TABLE`, and fail-closes — only `{passed}` satisfies the canonical gate; `missing`/`unknown`/`gaps_found`/`human_needed`/`stale` all route away from "complete" (#1522). `findStaleVerificationSummary` flags a SUMMARY newer than the VERIFICATION file (status `stale`). Both honor a no-throw, degrade-to-safe contract (any FS error → `missing` / not-stale) and an injectable `opts.fs` seam. Source of truth: `gsd-core/bin/lib/verification.cjs` (generated from `src/verification.cts`).
|
||||
|
||||
### Phase Locator Module
|
||||
Module owning phase-directory search and location: active-phase discovery against the `.planning/phases/` tree (`searchPhaseInDir`, `findPhaseInternal`) and archived-phase-dir enumeration (`getArchivedPhaseDirs`), matching phase ids/tokens against the filesystem. Depends only on leaf modules (`phase-id` for token/name matching, `core-utils` for fs-scan/path helpers, `planning-workspace` for `planningDir`) — no `loadConfig`, no other core dependency. Extracted from the Core module per ADR-857 rollout phase 2d (#881); the `core.cjs` re-export spine was retired in epic #1267, so callers import this leaf directly. Source of truth: `gsd-core/bin/lib/phase-locator.cjs` (generated from `src/phase-locator.cts`).
|
||||
|
||||
@@ -65,7 +68,7 @@ Module owning command resolution, policy projection (`mutation`, `output_mode`),
|
||||
Module owning the `init.*` family of query handlers that compose atomic queries into the flat JSON bundles consumed by init workflows (`/gsd-execute-phase`, `/gsd-plan-phase`, `/gsd-verify-work`, `/gsd-new-project`, `/gsd-manager`, `/gsd-progress`, `/gsd-resume`, etc.). Source of truth: `gsd-core/bin/lib/init.cjs` — the basic handlers (plus `withProjectRoot` project-identity injection) and the 3 heavyweight handlers (`initNewProject`, `initProgress`, `initManager`). All handlers return `{ data: <flat JSON> }`. Test seams: `tests/init.test.cjs` and `tests/init-manager.test.cjs` (cover withProjectRoot precedence, progress/manager precedence regression #2674, workstream scoping regression #3196, and cross-milestone dependency regression #2267). (The SDK `handlers/init/*.ts` sources and the `init*.test.ts` seams were retired with the SDK package per ADR-0174.)
|
||||
|
||||
### Command Routing Hub
|
||||
Single dispatch seam (`gsd-core/bin/lib/command-routing-hub.cjs`) that centralizes CJS routing, the no-throw pure-result contract, typed error variants, and dispatch-event emission for all command family adapters. Interface: `createHub({ cjsRegistry, manifest, logger }) → hub`; `hub.dispatch({ family, subcommand, args, cwd, raw, parentTraceId? }) → Result` where `Result = { ok: true, data } | { ok: false, kind, ...typedPayload }` and `kind ∈ { UnknownCommand, InvalidArgs, HandlerRefusal, HandlerFailure }`. The Hub is single-runtime (no mode selection, no sdkLoader), never prints, never exits, never throws. Adapters call `createHub`, dispatch, then translate the pure Result to `output()`/`error()` calls. Source: `gsd-core/bin/lib/command-routing-hub.cjs`; ADR: `docs/adr/0174-retire-gsd-sdk-package-boundary.md`.
|
||||
Single dispatch seam (`gsd-core/bin/lib/command-routing-hub.cjs`) that centralizes CJS routing, the no-throw pure-result contract, typed error variants, and dispatch-event emission for all command family adapters. Interface: `createHub({ cjsRegistry, manifest, logger }) → hub`; `hub.dispatch({ family, subcommand, args, cwd, raw, parentTraceId? }) → Result` where `Result = { ok: true, data } | { ok: false, kind, ...typedPayload }` and `kind ∈ { UnknownCommand, InvalidArgs, HandlerRefusal, HandlerFailure }`. The `InvalidArgs` variant carries an optional `exitReason?: string` field (amendment #1642 / #1644 Phase 1) holding the `ERROR_REASON` enum value, separate from `reason` (the explanation text); the `makeInvalidArgs(arg, reason, exitReason?)` factory omits the field when the third arg is absent, undefined, or empty — preserving the strict-keys invariant tested at `tests/command-routing-hub.test.cjs:444`. The Hub is single-runtime (no mode selection, no sdkLoader), never prints, never exits, never throws. Adapters call `createHub`, dispatch, then translate the pure Result to `output()`/`error()` calls; when an `InvalidArgs` Result carries `exitReason`, the adapter passes it as the second arg to `error(message, exitReason)` so the JSON-error envelope (`GSD_JSON_ERRORS=1`) preserves the typed reason. Source: `gsd-core/bin/lib/command-routing-hub.cjs`; ADR: `docs/adr/0174-retire-gsd-sdk-package-boundary.md` (§5 amended #1642).
|
||||
|
||||
### Runtime Source Layout Module
|
||||
Single-runtime seam layout for this repository after SDK retirement. Runtime execution paths live under `gsd-core/bin/lib/` and are grouped by seam concern (dispatch, manifest, handlers, runtime, observability, installer). ADR-0174 preserves the seam vocabulary and defines the canonical long-term shape as a seam-aligned TypeScript `src/` tree (`src/dispatch/`, `src/handlers/`, `src/errors/`, `src/manifest/`, `src/config/`, `src/state/`, `src/workstream/`, `src/runtime/`, `src/cli/`, `src/observability/`) compiled to CJS.
|
||||
@@ -284,6 +287,12 @@ The GSD-RESEARCH capability behind an L2-hybrid seam: code owns cache + provider
|
||||
### UAT-Passed Predicate
|
||||
Runtime-neutral predicate evaluating `*-UAT.md` / `*-VERIFICATION.md` result fields with markdown-aware parsing that ignores false-positive contexts (frontmatter body, fenced code, HTML comments, blockquotes). Returns `passed: true` only when all required checks pass; supports `--require-verification` to demand at least one VERIFICATION.md file alongside UAT results. Output envelope: `{ passed, uat_files[], verification_files[], checks[], blockers[], policy }`. Source: `gsd-core/bin/lib/uat-predicate.cjs` (generated from `src/uat-predicate.cts`). Wired via `phase uat-passed` alias → `phase-command-router` → `cmdPhaseUatPassed`.
|
||||
|
||||
### Coverage Metadata Module
|
||||
Deterministic classifier for the per-deliverable coverage RTM on SUMMARY.md (#1602). Parses the optional `coverage:` frontmatter block (a list-of-maps-with-nested-list-of-maps that `extractFrontmatter` cannot represent — so a dedicated indentation parser, sibling of `parseMustHavesBlock`), validates each entry's schema, and classifies each into `auto_passed` (deterministically covered) vs `present` (human UAT required). Output envelope: `{ mode, summary_file, total, all_auto_covered, auto_passed[], present[], errors[] }` with frozen `MODE`/`PRESENT_REASON`/`ERROR_CODE` enums. Auto-pass requires the narrow proven case (strict-boolean `human_judgment:false` AND non-empty all-`pass` verification AND zero errors); everything else, including a malformed entry, routes to `present` (fail-safe — never drops a deliverable, never false-auto-passes). `mode:legacy` (absent block) ⇒ caller falls back to prose `## Accomplishments` extraction, byte-identical for un-migrated phases. Source: `gsd-core/bin/lib/coverage.cjs` (generated from `src/coverage.cts`). Wired via `uat classify-coverage --summary <f>` → `cmdClassify`; authored by `execute-plan` create_summary, consumed by `verify-work` extract_tests. See `RULESET.WORKFLOW.COVERAGE-METADATA`.
|
||||
|
||||
### Eval Scoring Module
|
||||
Deterministic eval-scoring projection (#10 / #1579) that moves the `gsd-eval-auditor`'s weighted arithmetic out of the prompt into code. `computeEvalScore(covered, total, infra[])` returns `{ coverage_score, infra_score, overall_score, verdict }` — coverage = `covered/total*100`, infra = mean of per-item weights (`ok`=1, `partial`=0.5, `missing`=0) over exactly 5 items, `overall = coverage*0.6 + infra*0.4` (2-dp rounding), verdict banded at 80/60/40 (`PRODUCTION READY` / `NEEDS WORK` / `SIGNIFICANT GAPS` / `NOT IMPLEMENTED`). `cmdEvalScore` is the CLI guard: rejects empty/NaN flags, `infra.length !== 5`, and out-of-domain counts (requires `0 <= covered <= total`). Pure arithmetic — no `.planning/` access (it is in `SKIP_ROOT_RESOLUTION`), no `Date.now`/`Math.random`. Wired via the `eval.score` verb (and the `eval score` spaced alias) → `eval-command-router` → `cmdEvalScore`; consumed by `gsd-eval-auditor`. Source of truth: `gsd-core/bin/lib/eval.cjs` (generated from `src/eval.cts`, gitignored per ADR-457). Tests: `tests/eval.test.cjs`, `tests/eval.property.test.cjs`.
|
||||
|
||||
### Probe Core Module
|
||||
Generic spec-phase probe resolution model — the shared seam underlying spec-completeness probes (ADR-550 Decision 7). Owns the `status × verification` model (`status: resolved | dismissed | unresolved` × a per-probe `verification` tier), structural validation (`validateResolution`, `validateRequirement` — fail-closed: `verification` must be null unless status is `resolved`, and an out-of-enum status, a `dismissed`-without-`reason`, or an `unresolved` carrying a `resolution`/`reason`/tier payload all throw rather than silently miscount), the `analyzeCoverage(items, resolutions?, validators)` merge/rollup/orphan-reject pipeline, the `byVerification` per-tier rollup, and the `runProbeCli` I/O scaffold (parse → validate → analyze → emit, structurally guarding the report shape before write — a malformed report fails closed with stderr + exit 2 instead of stringifying as green). Adapter-agnostic: consumed by the Edge Probe Module today and the Prohibition Probe Module (#644) next. Exports (generic surface): `VALID_STATUS`, `validateResolution`, `validateRequirement`, `analyzeCoverage`, `runProbeCli` — the prohibition adapter exports that also ship from this module (`projectProhibitions`, `PROHIBITION_VALIDATORS`, `validateProhibitionResolution`, `dispositionForProhibition`) are documented under the Prohibition Probe Module's own locked-surface line. Source of truth: `gsd-core/bin/lib/probe-core.cjs` (generated from `src/probe-core.cts`, gitignored per ADR-457). Tests: `tests/probe-core.test.cjs`. See ADR-550 and Edge Probe Module. Under ADR-857 (phase-6 boundary, settled 2026-06-12) this seam is classified **core verification substrate** on the *contract* side: its deterministic validators are the verifier↔predicate contract's CI-testable surface (ADR-550 Decision 5) — core and non-toggleable, never an off-by-default Feature Capability. (The recall-gapped *generator* is the probe adapters that propose predicates, not this resolution engine — see Edge Probe Module and Verification substrate (predicate boundary).)
|
||||
|
||||
@@ -344,6 +353,9 @@ The canonical lint infrastructure adopted in ADR 452 (`docs/adr/452-eslint-lint-
|
||||
### External-job-waiting half-state
|
||||
A legal deferred state of an Execute step (`external_job_waiting`): the executor has dispatched a long-running async external job and committed an async-job manifest at `.planning/async-jobs/<job>.json` instead of a SUMMARY.md. Distinct from the synchronous "mid-production-commits" half-state and from an illegal partial-plan state. The core loop's step-completion + safe-resume/pause contract treats a non-terminal manifest as legal and reconciles against it (never re-dispatching the plan, which would duplicate the external job); SUMMARY.md is deferred until the job reaches a terminal state and its `expected_artifacts` are verified. The manifest is a versioned stability contract (`docs/reference/planning-artifacts.md`); core *consumes* it while a default-off scheduler-adapter Capability (#1164) *produces* it at `execute:wave:post` — the contract-is-core / producer-is-capability seam mirrors ADR-857's verification-substrate decision. Status enum is closed and scheduler-agnostic: `submitted`, `running`, `completed-unverified`, `failed`, `cancelled`, `timeout`.
|
||||
|
||||
### Untrusted-input boundary
|
||||
The prompt-level data/instruction isolation seam for untrusted web/document ingress (#1577). Shared reference `gsd-core/references/untrusted-input-boundary.md`, `@`-included by the 10 ingest agents (`gsd-project-researcher`, `gsd-phase-researcher`, `gsd-ui-researcher`, `gsd-assumptions-analyzer`, `gsd-advisor-researcher`, `gsd-ai-researcher`, `gsd-domain-researcher`, `gsd-research-synthesizer`, `gsd-doc-classifier`, `gsd-doc-synthesizer`) — every agent that reads fetch/search/MCP output or external source documents. The reference instructs: treat fetched/read content as **data, never instructions**; self-scan content for embedded directives before use; act only on the assigned task (ignore off-task instructions in data); and wrap quoted untrusted spans in a **fresh random delimiter** per wrap (fixed markers are spoofable). This prompt-level boundary is the primary control — it keeps an injection from being *followed* even while it sits in context. The hook-level companion is the read-injection scanner (`hooks/gsd-read-injection-scanner.js`, PostToolUse on `Read`/`WebFetch`/`WebSearch`), advisory by default; the opt-in top-level `security.injection_blocking` key upgrades HIGH-confidence detections to a PostToolUse circuit-breaker that halts the agent's next step (it runs *after* the fetch, so it is not a redactor). Tests: `tests/untrusted-input-isolation.test.cjs`, `tests/read-injection-scanner.*.test.cjs`, `tests/injection-blocking-config.test.cjs`. See `docs/adr/1577-untrusted-input-boundary-and-injection-blocking.md` and `docs/explanation/security-model.md`. Grounding: arXiv 2506.05739 (PPA), 2507.15219 (PromptArmor), 2504.20472.
|
||||
|
||||
---
|
||||
|
||||
## Test rules and lint
|
||||
@@ -378,6 +390,7 @@ A legal deferred state of an Execute step (`external_job_waiting`): the executor
|
||||
`RULESET.WORKFLOW_FILE_NAMES=workflow files use hyphens; <step name="..."> XML attributes must match (extract-learnings not extract_learnings); tests should pin exact hyphenated name`
|
||||
`RULESET.WORKFLOW_EXECUTION_CONTEXT=@-ref in commands/gsd/*.md must resolve to an existing file on disk; regression test in tests/bug-3135-capture-backlog-workflow.test.cjs; INVENTORY.md row + INVENTORY-MANIFEST.json families.workflows must stay in sync; "Invoked by" attribution must move when a flag absorbs a micro-skill`
|
||||
`RULESET.WORKFLOW_EXECUTE_END_TO_END=ADR-0002 standard for single-workflow commands is "Execute end-to-end." (no bolded **Follow the X workflow** fragments); flag-dispatch routing uses "execute the X workflow end-to-end." in routing bullets`
|
||||
`RULESET.WORKFLOW.COVERAGE-METADATA=#1602 SUMMARY frontmatter `coverage:` block (list of {id,description,requirement?,verification:[{kind∈unit|integration|e2e|automated_ui|manual_procedural|other, ref, status∈pass|fail|unknown}],human_judgment:bool,rationale?}) is the per-deliverable RTM consumed DETERMINISTICALLY by verify-work extract_tests via `gsd-tools uat classify-coverage --summary <f>` (src/coverage.cts → bin/lib/coverage.cjs). AUTHORING: execute-plan create_summary populates it from task <verify> results; every deliverable MUST be classified; fail-safe default = human_judgment:true + rationale. CLASSIFY CONTRACT: auto-pass (skip human) ONLY when human_judgment===false (strict boolean) AND verification non-empty AND every status==='pass' AND zero validation errors — else PRESENT to human. mode:legacy (no block) ⇒ byte-identical prose `## Accomplishments` fall-through; `coverage: []` ⇒ mode:coverage, zero entries (single-confirmation). Frozen IR: MODE/PRESENT_REASON/ERROR_CODE enums locked by tests/coverage-metadata-parser.test.cjs. extractFrontmatter CANNOT parse it (scalars-only `-` items) → dedicated parser, sibling of parseMustHavesBlock. Asymmetry by design: false-negative=redundant prompt (status quo); false-positive=shipped bug UAT existed to catch`
|
||||
|
||||
`RULESET.ALLOWED-TOOLS-FRONTMATTER=command's allowed-tools must cover every tool the workflow calls (including Write for file creation); thin-wrapper pattern makes this easy to miss`
|
||||
`RULESET.ARGUMENTS-SANITIZE=any workflow step constructing .planning/.../{SLUG}.md path from user input ($ARGUMENTS, parsed remainder) must sanitize inline ([a-z0-9-] only, reject ..//\\, max-length) — "(already sanitized)" must trace back to explicit guard; RESUME/fallback modes need own guards`
|
||||
@@ -713,11 +726,43 @@ A legal deferred state of an Execute step (`external_job_waiting`): the executor
|
||||
`DEFECT.TEST-SHELL-PIPELINE-NONPORTABLE.fix-forward=match the fence with \r?\n and normalize the captured block to LF; gate pipeline execution on process.platform !== 'win32' && hasBash since the extraction LOGIC is platform-independent and POSIX coverage suffices; run the full suite (or the parity/lint guards) before push when adding a test file`
|
||||
|
||||
`DEFECT.WINDOWS-TEST-PORTABILITY.symptom=local gsd-test runs Mac+Linux only (no Windows host); Windows-only test failures (chmod exec-bit not honored for PATH-executing extension-less scripts in Git Bash msys2; / vs \ path-separator in assertions; Git Bash msys2 shell semantics) surface ONLY in CI test (windows-latest,*) / full test (windows-latest,*) lanes, never locally`
|
||||
`DEFECT.WINDOWS-TEST-PORTABILITY.examples=PR #1084 (chmod 0o755 + bare-command execution failed on windows lane); test files that assert path.join result without normalizing to forward slashes`
|
||||
`DEFECT.WINDOWS-TEST-PORTABILITY.examples=PR #1084 (chmod 0o755 + bare-command execution failed on windows lane); PR #1692 tests/stale-bake-guard.test.cjs resolveAgentDir assertions hardcoded '/H/.config/opencode/agent' forward-slash literals against a path.join return — passed macOS/linux/ubuntu CI (incl. gsd-test docker mirror), failed windows-latest,24 + full test windows-latest,22 shard 2/3; test files that assert path.join result without normalizing to forward slashes`
|
||||
`DEFECT.WINDOWS-TEST-PORTABILITY.detect=npm run lint:windows-test-portability (tripwire: flags tests combining chmod exec-bit with sh/bash -c and no platform guard); watch CI windows matrix green before declaring a PR done`
|
||||
`DEFECT.WINDOWS-TEST-PORTABILITY.fix-forward=gate platform-specific execution with if (process.platform !== 'win32'); normalize path expectations to forward slashes with .replace(/\\/g, '/'); invoke scripts via explicit interpreter (sh <path>) rather than relying on exec-bit; annotate // windows-portability-ok: <reason> when a bypass is intentional`
|
||||
`DEFECT.WINDOWS-TEST-PORTABILITY.prevention=run lint:ci before opening a PR; treat the CI windows lane as the only true Windows signal — gsd-test (Mac/Linux only) cannot substitute for it`
|
||||
|
||||
`DEFECT.WINDOWS-POSIX-MODE-BIT-ASSERT.symptom=a test writes a file with a POSIX mode (fs.writeFileSync(p, data, {mode: 0o644}) or fs.chmodSync) then asserts fs.statSync(p).mode & 0o777 === <that exact octal>; passes on macOS/Linux/ubuntu CI, FAILS on the windows-latest CI lane — Windows fs does NOT honor POSIX write modes, Node reports the mode derived from the DOS readonly attribute (0o666 for writable / 0o444 for readonly), never the requested 0o644/0o755`
|
||||
`DEFECT.WINDOWS-POSIX-MODE-BIT-ASSERT.examples=#1634/PR #1638 tests/capability-lifecycle.test.cjs "a .cjs hook command is node-prefixed so it runs without the executable bit" failed windows-latest,24 on "precondition: file staged without +x" (expected 420/0o644, got 438/0o666); the node-prefix behavioral assertion was correct — only the mode-bit precondition was the POSIX-only fact`
|
||||
`DEFECT.WINDOWS-POSIX-MODE-BIT-ASSERT.detect=grep tests for \`.mode & 0o777\` / \`.mode) === 0o\` / \`writeFileSync(...{ mode: 0o\` / \`chmodSync\` paired with a strict-equality assertion on the resulting mode; any such assertion is a POSIX-only fact that will diverge on Windows (write reads back as 0o666)`
|
||||
`DEFECT.WINDOWS-POSIX-MODE-BIT-ASSERT.fix-forward=gate the mode-bit precondition on if (process.platform !== 'win32') — the executable-bit/mode is a POSIX concept meaningless on Windows; KEEP the platform-independent behavioral assertion (the actual behavior under test) running on every OS; do NOT delete the precondition, scope it to POSIX`
|
||||
`DEFECT.WINDOWS-POSIX-MODE-BIT-ASSERT.prevention=ref DEFECT.WINDOWS-TEST-PORTABILITY — gsd-test is Mac/Linux only (no Windows host), only the CI windows-latest lane catches this; run npm run lint:ci (lint-windows-test-portability) before push; prefer asserting the BEHAVIOR (command shape, runnability) over the filesystem mode bit`
|
||||
|
||||
`DEFECT.WINDOWS-PATH-LEAK-IN-MARKDOWN-CONTENT.symptom=path.join() result on Windows (backslashes) substituted verbatim into markdown body (@-references, workflow files, generated docs); content gains mixed separators; cross-platform substring assertions fail on windows-latest CI lane only; macOS/Linux CI green so defect ships undetected`
|
||||
`DEFECT.WINDOWS-PATH-LEAK-IN-MARKDOWN-CONTENT.examples=PR #1622 computePathPrefix returned ${resolvedTarget}/ verbatim — rewrites of @~/.claude/gsd-core/commands/gsd/X.md wrote @C:\...\gsd-ial-windsurf-XXX\gsd-core/commands/gsd/help.md (trailing forward slashes from the original literal survived, prefix backslashes did not); tests/install-runtime-artifacts.test.cjs:318 + tests/install.test.cjs:1323 failed on windows-latest only`
|
||||
`DEFECT.WINDOWS-PATH-LEAK-IN-MARKDOWN-CONTENT.detect=any function returning a filesystem path that flows into markdown/text body substitution; grep for path.join/raw resolvedTarget/${configDir}/ in code paths writing workflow .md, agent .md, or generated docs; smoke pattern is ${resolvedTarget}/ or ${configDir}/... templates that bypass normalization`
|
||||
`DEFECT.WINDOWS-PATH-LEAK-IN-MARKDOWN-CONTENT.fix-forward=normalize at the SOURCE not the test: posixTarget=String(resolvedTarget).replace(/\\/g,'/'), posixHome=homeDir?String(homeDir).replace(/\\/g,'/'):homeDir; markdown body is POSIX-only; .replace(/\\/g,'/') is idempotent on POSIX (no backslashes present) so safe to apply unconditionally; isWindowsHost arg is a no-op tripwire (enh-1511) — do NOT branch on it, normalize always`
|
||||
`DEFECT.WINDOWS-PATH-LEAK-IN-MARKDOWN-CONTENT.prevention=RULESET.CONTENT-PATH-NORMALIZATION; tests are downstream signal, never the fix; ref DEFECT.WINDOWS-TEST-PORTABILITY for test-side parity (normalize expected substrings too: ${configDir}/foo.replace(/\\/g,'/'))`
|
||||
|
||||
`RULESET.CONTENT-PATH-NORMALIZATION=filesystem paths substituted into markdown body text (@-references, workflow .md, agent .md, generated docs, command bodies) MUST be normalized to POSIX forward slashes via .replace(/\\/g,'/') at the production source BEFORE substitution; never push normalization to tests; cross-platform content is POSIX-only; applies to: computePathPrefix output, install-path rewrites, generated shim paths emitted into .md bodies; idempotent on POSIX so unconditional`
|
||||
|
||||
`DEFECT.WINDOWS-PATH-LITERAL-IN-ASSERT.symptom=an assertion compares the return value of a path-returning function (resolveAgentDir, path.join, path.resolve, getPathX, computePathPrefix, etc.) to a HARDCODED forward-slash string literal like '/H/.config/opencode/agent' or 'C:/Users/...' — passes on POSIX (macOS/linux/ubuntu CI incl. gsd-test docker mirror, where path.join emits forward slashes so literal == actual), FAILS on windows-latest CI lane where path.join emits backslashes so literal != actual`
|
||||
`DEFECT.WINDOWS-PATH-LITERAL-IN-ASSERT.examples=PR #1692 tests/stale-bake-guard.test.cjs resolveAgentDir suite: assert.equal(resolveAgentDir('opencode',{homedir:()=>'/H'}), '/H/.config/opencode/agent') — green on macOS+ubuntu (docker gate PASS 21101/21101), red on test (windows-latest,24) + full test (windows-latest,22, shard 2/3); same root cause as DEFECT.WINDOWS-PATH-LEAK-IN-MARKDOWN-CONTENT but on the TEST side against a function return, not the production-markdown side`
|
||||
`DEFECT.WINDOWS-PATH-LITERAL-IN-ASSERT.detect=any assert*/expect call whose ACTUAL operand is a call to a path-returning fn (path.join, path.resolve, resolveAgentDir, getPathX, computePathPrefix, os.homedir(), path.dirname/basename) AND whose EXPECTED operand is a string literal containing '/' that does NOT first flow through .replace(/\\/g,'/'); the literal-vs-fnCall shape is the tripwire — assert.equal(pathFn(...), '/hardcoded/posix/path') is the violation; assert.equal(String(pathFn(...)).replace(/\\/g,'/'), '/hardcoded/posix/path') is the compliant form`
|
||||
`DEFECT.WINDOWS-PATH-LITERAL-IN-ASSERT.fix-forward=normalize the ACTUAL value to POSIX before comparing: assert.equal(String(pathFn(...)).replace(/\\/g,'/'), '/posix/literal'). Do NOT instead path.join the expected value to match the platform separator — that passes on every platform but masks a malformed backslash-on-POSIX return (both sides wrong together). The .replace is idempotent on POSIX so it is safe unconditionally. For values that are conceptually never paths (null/undefined/numbers), no normalization needed.`
|
||||
`DEFECT.WINDOWS-PATH-LITERAL-IN-ASSERT.prevention=run npm run lint:ci (lint-windows-test-portability) before push — enhancement TBD to extend that lint to flag the literal-vs-pathFn assertion shape mechanically; treat the CI windows-latest lane as the only true Windows signal — gsd-test (Mac/Linux only) cannot substitute; ref umbrella DEFECT.WINDOWS-TEST-PORTABILITY and production-side analogue DEFECT.WINDOWS-PATH-LEAK-IN-MARKDOWN-CONTENT`
|
||||
|
||||
`DEFECT.PROMPT-INJECTION-SCAN-COLLISION-WITH-TESTS.symptom=scripts/prompt-injection-scan.sh flags a NEW test file as a finding because the test contains real injection payloads as fixtures (strings that match one of the scanner's PATTERNS — see scripts/prompt-injection-scan.sh lines 18-64) to prove the validator under test rejects them; scanner cannot distinguish fixture from real injection; CI security lane fails on the test that ADDS the security validation`
|
||||
`DEFECT.PROMPT-INJECTION-SCAN-COLLISION-WITH-TESTS.examples=PR #1622 commit 4ed208e74 added convertClaudeCommandToWindsurfWorkflow commandName validation with 22 malicious-name fixtures; scanner matched an instruction-override phrase at tests/windsurf-conversion.test.cjs:122; CI security lane failed even though the test is the security control`
|
||||
`DEFECT.PROMPT-INJECTION-SCAN-COLLISION-WITH-TESTS.detect=CI security lane (Prompt injection scan step) reports FAIL: tests/<not-in-allowlist>.test.cjs with a line number pointing at a string literal; the literal is inside an assert.throws() or array of malicious inputs; the test file name is not in scripts/prompt-injection-scan.sh ALLOWLIST`
|
||||
`DEFECT.PROMPT-INJECTION-SCAN-COLLISION-WITH-TESTS.fix-forward=ADD the test file to scripts/prompt-injection-scan.sh ALLOWLIST array with a comment citing this defect class; for large fixture sets, move them to tests/fixtures/adversarial/security/ (auto-allowlisted dir) and load via readFileSync; never weaken or fragment the payload to evade the scanner — that defeats the test's purpose; ALSO when documenting this defect in CONTEXT.md, do NOT quote the literal pattern — describe it generically (the scanner scans CONTEXT.md too)`
|
||||
`DEFECT.PROMPT-INJECTION-SCAN-COLLISION-WITH-TESTS.prevention=when writing a security regression test that uses real injection payloads as fixtures, immediately add the test file path to scripts/prompt-injection-scan.sh ALLOWLIST in the same commit; when documenting this defect class anywhere under scanner scope (CONTEXT.md, docs/, agent .md), use descriptive references like 'scanner-matching payload' rather than quoting the literal pattern; ref DEFECT.PROMPT-INJECTION-SCAN-COLLISION (the older XML-tag-collision variant)`
|
||||
|
||||
`DEFECT.WORKFLOW-DELEGATION-TARGET-NOT-INSTALLED.symptom=workflow wrapper file (e.g. Windsurf convertClaudeCommandToWindsurfWorkflow) delegates to a command body at <targetDir>/gsd-core/commands/gsd/X.md via a hardcoded @~/.claude/gsd-core/commands/gsd/ path that _applyRuntimeRewrites rewrites to the install target; the source gsd-core/ dir ships without commands/ (it lives at package-root commands/gsd/); install completes successfully, workflow files appear in the / menu, but invocation tells the LLM to read a file that does not exist; the slash commands silently fail`
|
||||
`DEFECT.WORKFLOW-DELEGATION-TARGET-NOT-INSTALLED.examples=PR #1622 (issue #1615) shipped Windsurf /gsd-* workflow wrappers that all reference <targetDir>/.windsurf/gsd-core/commands/gsd/X.md; that directory was never populated; none of the reviews (security, Codex adversarial, Memtrace) caught it; a #1629 regression test verifying 'every workflow @- reference target exists on disk' surfaced it post-merge`
|
||||
`DEFECT.WORKFLOW-DELEGATION-TARGET-NOT-INSTALLED.detect=after install, for every workflow .md file under <targetDir>/<runtime-config-dir>/workflows/, extract the @<path> reference from the body and assert fs.existsSync(path); if any reference target is absent, this defect is present`
|
||||
`DEFECT.WORKFLOW-DELEGATION-TARGET-NOT-INSTALLED.fix-forward=copy the canonical command source (commands/gsd/*.md) into <targetDir>/gsd-core/commands/gsd/ during install, gated on the runtime that uses workflow delegation (currently Windsurf local only); use copyWithPathReplacement to apply the same path+brand rewrites as the rest of the install; verify with a regression test that every workflow's @-reference resolves`
|
||||
`DEFECT.WORKFLOW-DELEGATION-TARGET-NOT-INSTALLED.prevention=any new converter that emits a wrapper file delegating to another file MUST verify the delegation target is actually written by the same install; add a post-install invariant test: for every @<path> reference in every generated wrapper, assert the target exists; the workflow converter's hardcoded path was copy-pasted from Claude's skill pattern without verifying the target exists for the new runtime`
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -228,6 +228,33 @@ node scripts/release-notes/format-github-release-notes.cjs \
|
||||
Omit `--apply` to print the reformatted body to stdout for review without
|
||||
publishing.
|
||||
|
||||
### PR title convention (enforced at open time)
|
||||
|
||||
Because the changelog is built from PR titles, your **PR title** must follow:
|
||||
|
||||
```
|
||||
type(#<issue>): short summary
|
||||
```
|
||||
|
||||
- **Start with the type** — `feat`, `fix`, or any other conventional type
|
||||
(`chore`, `docs`, `refactor`, …). No leading tags or prefixes: a title like
|
||||
`[security] fix(config): …` defeats the `^fix` bucket anchor and silently
|
||||
files the entry under the wrong changelog section.
|
||||
- **Put the linked issue ref in the scope** — `(#<digits>)`. This is what
|
||||
renders as a link to the issue in the changelog line. `fix(core): …` buckets
|
||||
correctly but produces a changelog entry with **no issue link**.
|
||||
- A breaking-change marker is fine: `feat(#42)!: …`.
|
||||
|
||||
Examples: `fix(#1542): roadmap rollback`, `feat(#39): milestone-prefixed phase IDs`,
|
||||
`enhance(#1549): add PR-title validator`.
|
||||
|
||||
**CI enforcement:** `pr-title-validator.yml` checks the title on open/edit and
|
||||
fails with the required format if it doesn't conform. It reuses the same matcher
|
||||
the changelog classifier uses (`scripts/release-notes/conventional-title.cjs`), so a title
|
||||
that passes the check is guaranteed to bucket and link correctly. Fix a flagged
|
||||
title by editing it in place — the check re-runs on edit, no need to recreate
|
||||
the PR.
|
||||
|
||||
## Documentation Updates — Update the Relevant Docs
|
||||
|
||||
If your PR adds, changes, deprecates, or removes user-visible behavior, you **must** update the relevant documentation in `docs/`. CI will fail any PR whose changeset fragment is typed `Added`, `Changed`, `Deprecated`, or `Removed` without also modifying at least one file under `docs/` ([#3213](https://github.com/open-gsd/gsd-core/issues/3213)).
|
||||
|
||||
@@ -17,6 +17,8 @@ Spawned by `discuss-phase` via `Task()`. You do NOT present output directly to t
|
||||
- Return structured markdown output for the main agent to synthesize
|
||||
</role>
|
||||
|
||||
@~/.claude/gsd-core/references/untrusted-input-boundary.md
|
||||
|
||||
<documentation_lookup>
|
||||
@~/.claude/gsd-core/references/research-documentation-lookup.md
|
||||
</documentation_lookup>
|
||||
|
||||
@@ -16,6 +16,8 @@ You are a GSD AI researcher. Answer: "How do I correctly implement this AI syste
|
||||
Write Sections 3–4b of AI-SPEC.md: framework quick reference, implementation guidance, and AI systems best practices.
|
||||
</role>
|
||||
|
||||
@~/.claude/gsd-core/references/untrusted-input-boundary.md
|
||||
|
||||
<documentation_lookup>
|
||||
@~/.claude/gsd-core/references/research-documentation-lookup.md
|
||||
</documentation_lookup>
|
||||
|
||||
@@ -18,6 +18,8 @@ Spawned by `discuss-phase-assumptions` via `Task()`. You do NOT present output d
|
||||
- Flag topics where codebase analysis alone is insufficient (needs external research)
|
||||
</role>
|
||||
|
||||
@~/.claude/gsd-core/references/untrusted-input-boundary.md
|
||||
|
||||
<input>
|
||||
Agent receives via prompt:
|
||||
|
||||
|
||||
@@ -18,6 +18,8 @@ You are a GSD doc classifier. You read ONE document and write a structured class
|
||||
If the prompt contains a `<required_reading>` block, use the `Read` tool to load every file listed there before doing anything else. That is your primary context.
|
||||
</role>
|
||||
|
||||
@~/.claude/gsd-core/references/untrusted-input-boundary.md
|
||||
|
||||
<why_this_matters>
|
||||
Your classification drives extraction. If you tag a PRD as a DOC, its requirements never make it into REQUIREMENTS.md. If you tag an ADR as a PRD, its decisions lose their LOCKED status and get overridden by weaker sources. Classification fidelity is load-bearing for the entire ingest pipeline.
|
||||
</why_this_matters>
|
||||
|
||||
@@ -20,6 +20,8 @@ You do NOT prompt the user. You do NOT write PROJECT.md, REQUIREMENTS.md, or ROA
|
||||
If the prompt contains a `<required_reading>` block, load every file listed there first — especially `references/doc-conflict-engine.md` which defines your conflict report format.
|
||||
</role>
|
||||
|
||||
@~/.claude/gsd-core/references/untrusted-input-boundary.md
|
||||
|
||||
<why_this_matters>
|
||||
You are the precedence-enforcing layer. Silent merges, lost locked decisions, or naive dedupes here corrupt every downstream plan. When in doubt, surface the conflict rather than pick.
|
||||
</why_this_matters>
|
||||
|
||||
@@ -16,6 +16,8 @@ You are a GSD domain researcher. Answer: "What do domain experts actually care a
|
||||
Research the business domain — not the technical framework. Write Section 1b of AI-SPEC.md.
|
||||
</role>
|
||||
|
||||
@~/.claude/gsd-core/references/untrusted-input-boundary.md
|
||||
|
||||
<documentation_lookup>
|
||||
@~/.claude/gsd-core/references/research-documentation-lookup.md
|
||||
</documentation_lookup>
|
||||
|
||||
@@ -109,17 +109,14 @@ Score 5 components (ok / partial / missing):
|
||||
</step>
|
||||
|
||||
<step name="calculate_scores">
|
||||
```
|
||||
coverage_score = covered_count / total_dimensions × 100
|
||||
infra_score = (tooling + dataset + cicd + guardrails + tracing) / 5 × 100
|
||||
overall_score = (coverage_score × 0.6) + (infra_score × 0.4)
|
||||
Do NOT compute scores by hand. Call the deterministic verb with your audited inputs:
|
||||
|
||||
```bash
|
||||
_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
|
||||
gsd_run query eval.score --covered <covered_count> --total <total_dimensions> --infra <tooling>,<dataset>,<cicd>,<guardrails>,<tracing> --raw
|
||||
```
|
||||
|
||||
Verdict:
|
||||
- 80-100: **PRODUCTION READY** — deploy with monitoring
|
||||
- 60-79: **NEEDS WORK** — address CRITICAL gaps before production
|
||||
- 40-59: **SIGNIFICANT GAPS** — do not deploy
|
||||
- 0-39: **NOT IMPLEMENTED** — review AI-SPEC.md and implement
|
||||
where each infra component is `ok`, `partial`, or `missing` (from the audit_infrastructure step). Parse the JSON result — it returns `coverage_score`, `infra_score`, `overall_score`, and `verdict` (PRODUCTION READY / NEEDS WORK / SIGNIFICANT GAPS / NOT IMPLEMENTED). Use those values verbatim in EVAL-REVIEW.md; never recompute or override them.
|
||||
</step>
|
||||
|
||||
<step name="write_eval_review">
|
||||
|
||||
@@ -35,6 +35,8 @@ Spawned by `/gsd:plan-phase` (integrated) or `/gsd:plan-phase --research-phase <
|
||||
Claims tagged `[ASSUMED]` signal to the planner and discuss-phase that the information needs user confirmation before becoming a locked decision. Never present assumed knowledge as verified fact — especially for compliance requirements, retention policies, security standards, or performance targets where multiple valid approaches exist.
|
||||
</role>
|
||||
|
||||
@~/.claude/gsd-core/references/untrusted-input-boundary.md
|
||||
|
||||
<documentation_lookup>
|
||||
@~/.claude/gsd-core/references/research-documentation-lookup.md
|
||||
</documentation_lookup>
|
||||
|
||||
@@ -380,11 +380,11 @@ Output: [Artifacts created]
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|-------------|-----------------|
|
||||
| T-{phase}-01 | {S/T/R/I/D/E} | {function/endpoint/file} | mitigate | {specific: e.g., "validate input with zod at route entry"} |
|
||||
| T-{phase}-02 | {category} | {component} | accept | {rationale: e.g., "no PII, low-value target"} |
|
||||
| T-{phase}-SC | Tampering | npm/pip/cargo installs | mitigate | slopcheck + blocking human checkpoint for [ASSUMED]/[SUS] |
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-{phase}-01 | {S/T/R/I/D/E} | {function/endpoint/file} | {critical\|high\|medium\|low} | mitigate | {specific mitigation action} |
|
||||
| T-{phase}-02 | {category} | {component} | low | accept | {rationale for acceptance} |
|
||||
| T-{phase}-SC | Tampering | npm/pip/cargo installs | high | mitigate | slopcheck + blocking human checkpoint for [ASSUMED]/[SUS] |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
@@ -459,7 +459,7 @@ Only include what Claude literally cannot do.
|
||||
**Step 0: Extract Requirement IDs**
|
||||
Read ROADMAP.md `**Requirements:**` line for this phase. Strip brackets if present (e.g., `[AUTH-01, AUTH-02]` → `AUTH-01, AUTH-02`). Distribute requirement IDs across plans — each plan's `requirements` frontmatter field MUST list the IDs its tasks address. **CRITICAL:** Every requirement ID MUST appear in at least one plan. Plans with an empty `requirements` field are invalid.
|
||||
|
||||
**Security (when `security_enforcement` enabled — absent = enabled):** Identify trust boundaries in this phase's scope. Map STRIDE categories to applicable tech stack from RESEARCH.md security domain. For each threat: assign disposition (mitigate if ASVS L1 requires it, accept if low risk, transfer if third-party). Every plan MUST include `<threat_model>` when security_enforcement is enabled.
|
||||
**Security (when `security_enforcement` enabled — absent = enabled):** Identify trust boundaries in this phase's scope. Map STRIDE categories to applicable tech stack from RESEARCH.md security domain. For each threat: assign a **severity** (critical|high|medium|low) based on impact × likelihood, and a disposition (`mitigate`/`accept`/`transfer`) per the configured OWASP ASVS level — see @~/.claude/gsd-core/references/security-asvs-levels.md. Every plan MUST include `<threat_model>` when security_enforcement is enabled.
|
||||
|
||||
**Package legitimacy gate (npm/pip/cargo only):**
|
||||
- Require RESEARCH.md `## Package Legitimacy Audit` before package-manager install tasks.
|
||||
@@ -477,66 +477,16 @@ Take phase goal from ROADMAP.md. Must be outcome-shaped, not task-shaped.
|
||||
**Step 2: Derive Observable Truths**
|
||||
"What must be TRUE for this goal to be achieved?" List 3-7 truths from USER's perspective.
|
||||
|
||||
For "working chat interface":
|
||||
- User can see existing messages
|
||||
- User can type a new message
|
||||
- User can send the message
|
||||
- Sent message appears in the list
|
||||
- Messages persist across page refresh
|
||||
|
||||
**Test:** Each truth verifiable by a human using the application.
|
||||
|
||||
**Step 3: Derive Required Artifacts**
|
||||
For each truth: "What must EXIST for this to be true?"
|
||||
|
||||
"User can see existing messages" requires:
|
||||
- Message list component (renders Message[])
|
||||
- Messages state (loaded from somewhere)
|
||||
- API route or data source (provides messages)
|
||||
- Message type definition (shapes the data)
|
||||
|
||||
**Test:** Each artifact = a specific file or database object.
|
||||
|
||||
**Step 4: Derive Required Wiring**
|
||||
For each artifact: "What must be CONNECTED for this to function?"
|
||||
|
||||
Message list component wiring:
|
||||
- Imports Message type (not using `any`)
|
||||
- Receives messages prop or fetches from API
|
||||
- Maps over messages to render (not hardcoded)
|
||||
- Handles empty state (not just crashes)
|
||||
|
||||
**Step 5: Identify Key Links**
|
||||
"Where is this most likely to break?" Key links = critical connections where breakage causes cascading failures.
|
||||
|
||||
## Must-Haves Output Format
|
||||
|
||||
```yaml
|
||||
must_haves:
|
||||
truths:
|
||||
- "User can see existing messages"
|
||||
- "User can send a message"
|
||||
- "Messages persist across refresh"
|
||||
artifacts:
|
||||
- path: "src/components/Chat.tsx"
|
||||
provides: "Message list rendering"
|
||||
min_lines: 30
|
||||
- path: "src/app/api/chat/route.ts"
|
||||
provides: "Message CRUD operations"
|
||||
exports: ["GET", "POST"]
|
||||
- path: "prisma/schema.prisma"
|
||||
provides: "Message model"
|
||||
contains: "model Message"
|
||||
key_links:
|
||||
- from: "src/components/Chat.tsx"
|
||||
to: "src/app/api/chat/route.ts"
|
||||
via: "fetch in useEffect — calls /api/chat endpoint"
|
||||
pattern: "fetch.*api/chat"
|
||||
- from: "src/app/api/chat/route.ts"
|
||||
to: "prisma/schema.prisma"
|
||||
via: "database query via prisma.message"
|
||||
pattern: "prisma\\.message\\.(find|create)"
|
||||
```
|
||||
See @~/.claude/gsd-core/references/planner-guidance.md for a worked example and the `must_haves` YAML format.
|
||||
|
||||
</goal_backward>
|
||||
|
||||
@@ -1037,6 +987,7 @@ Phase planning complete when:
|
||||
- [ ] User knows next steps and wave structure
|
||||
- [ ] `<threat_model>` present with STRIDE register (when `security_enforcement` enabled)
|
||||
- [ ] Every threat has a disposition (mitigate / accept / transfer)
|
||||
- [ ] Every threat has a Severity (critical|high|medium|low)
|
||||
- [ ] Mitigations reference specific implementation (not generic advice)
|
||||
|
||||
## Gap Closure Mode
|
||||
|
||||
@@ -32,6 +32,8 @@ Your files feed the roadmap:
|
||||
**Be comprehensive but opinionated.** "Use X because Y" not "Options are X, Y, Z."
|
||||
</role>
|
||||
|
||||
@~/.claude/gsd-core/references/untrusted-input-boundary.md
|
||||
|
||||
<documentation_lookup>
|
||||
@~/.claude/gsd-core/references/research-documentation-lookup.md
|
||||
</documentation_lookup>
|
||||
|
||||
@@ -32,6 +32,8 @@ If the prompt contains a `<required_reading>` block, you MUST use the `Read` too
|
||||
- Commit ALL research files (researchers write but don't commit — you commit everything)
|
||||
</role>
|
||||
|
||||
@~/.claude/gsd-core/references/untrusted-input-boundary.md
|
||||
|
||||
<downstream_consumer>
|
||||
Your SUMMARY.md is consumed by the gsd-roadmapper agent which uses it to:
|
||||
|
||||
|
||||
@@ -33,18 +33,19 @@ Does NOT scan blindly for new vulnerabilities. Verifies each threat in `<threat_
|
||||
- Marking CLOSED based on code structure ("looks like it validates input") without finding the actual validation call
|
||||
|
||||
**Required finding classification:**
|
||||
- **BLOCKER** — `OPEN_THREATS`: a declared mitigation is absent in implemented code; phase must not ship
|
||||
- **BLOCKER** — `OPEN_THREATS`: a declared mitigation is absent in implemented code AND the threat's severity ≥ `block_on` threshold; phase must not ship until resolved
|
||||
- **OPEN — non-blocking** — mitigation absent BUT the threat's severity is below the `block_on` threshold; tracked in SECURITY.md, does NOT count toward `threats_open`, does not block ship
|
||||
- **WARNING** — `unregistered_flag`: new attack surface appeared during implementation with no threat mapping
|
||||
Every threat must resolve to CLOSED, OPEN (BLOCKER), or documented accepted risk.
|
||||
Every threat must resolve to CLOSED, OPEN-blocking (severity ≥ block_on), OPEN-non-blocking (severity below block_on), or documented accepted risk.
|
||||
</adversarial_stance>
|
||||
|
||||
<execution_flow>
|
||||
|
||||
<step name="load_context">
|
||||
Read ALL files from `<required_reading>`. Extract:
|
||||
- PLAN.md `<threat_model>` block: full threat register with IDs, categories, dispositions, mitigation plans
|
||||
- PLAN.md `<threat_model>` block: full threat register with IDs, categories, severities, dispositions, mitigation plans
|
||||
- SUMMARY.md `## Threat Flags` section: new attack surface detected by executor during implementation
|
||||
- `<config>` block: `asvs_level` (1/2/3), `block_on` (open / unregistered / none)
|
||||
- `<config>` block: `asvs_level` (1/2/3), `block_on` (critical | high | medium | low | none) — severity ordering: critical > high > medium > low; none = never block
|
||||
- Implementation files: exports, auth patterns, input handling, data flows
|
||||
|
||||
**Context budget:** Load project skills first (lightweight). Read implementation files incrementally — load only what each check requires, not the full codebase upfront.
|
||||
@@ -60,7 +61,7 @@ This ensures project-specific patterns, conventions, and best practices are appl
|
||||
</step>
|
||||
|
||||
<step name="analyze_threats">
|
||||
For each threat in `<threat_model>`, determine verification method by disposition:
|
||||
For each threat in `<threat_model>`, read its `severity` field (critical|high|medium|low). If building the register retroactively (no `<threat_model>` in PLAN.md), assign a severity to each threat you construct based on impact × likelihood. Determine verification method by disposition:
|
||||
|
||||
| Disposition | Verification Method |
|
||||
|-------------|---------------------|
|
||||
@@ -69,16 +70,27 @@ For each threat in `<threat_model>`, determine verification method by dispositio
|
||||
| `transfer` | Verify transfer documentation present (insurance, vendor SLA, etc.) |
|
||||
|
||||
Classify each threat before verification. Record classification for every threat — no threat skipped.
|
||||
|
||||
**Verification depth scales with `asvs_level`** (see @~/.claude/gsd-core/references/security-asvs-levels.md for full definitions):
|
||||
- L1: verify mitigation is PRESENT in the cited file (grep-level — pattern exists).
|
||||
- L2: verify the mitigation ADDRESSES the threat vector and is placed at the correct boundary (a check in the wrong layer does not close the threat).
|
||||
- L3: deep trace — follow the data flow end-to-end, check edge cases and ordering, confirm no bypass path exists.
|
||||
</step>
|
||||
|
||||
<step name="verify_and_write">
|
||||
For each `mitigate` threat: grep for declared mitigation pattern in cited files → found = `CLOSED`, not found = `OPEN`.
|
||||
For each `mitigate` threat: grep for declared mitigation pattern in cited files → found = `CLOSED`, not found = `OPEN`. Apply depth per `asvs_level` (see analyze_threats step).
|
||||
For `accept` threats: check SECURITY.md accepted risks log → entry present = `CLOSED`, absent = `OPEN`.
|
||||
For `transfer` threats: check for transfer documentation → present = `CLOSED`, absent = `OPEN`.
|
||||
|
||||
For each `threat_flag` in SUMMARY.md `## Threat Flags`: if maps to existing threat ID → informational. If no mapping → log as `unregistered_flag` in SECURITY.md (not a blocker).
|
||||
|
||||
Write SECURITY.md. Set `threats_open` count. Return structured result.
|
||||
**Severity-aware `threats_open` computation (severity order: critical > high > medium > low):**
|
||||
`threats_open` (the SECURITY.md frontmatter gate field) = the count of threats whose status is OPEN AND whose severity rank ≥ the `block_on` rank. `block_on: none` ⇒ 0 (nothing ever blocks). `block_on: low` ⇒ all open threats block. `block_on: high` (default) ⇒ only high and critical open threats block.
|
||||
Open threats BELOW the block threshold are recorded in SECURITY.md as **open — below {block_on} threshold (non-blocking)** and MUST NOT be counted in `threats_open`.
|
||||
|
||||
**Fail-closed for missing severity:** if an OPEN threat has no severity or an unparseable severity (e.g. a legacy register predating the Severity column), treat it as `critical` for this computation — it COUNTS toward `threats_open` (blocking). Never silently drop an unranked open threat.
|
||||
|
||||
Write SECURITY.md. Set `threats_open` to the severity-filtered count. Return structured result.
|
||||
</step>
|
||||
|
||||
</execution_flow>
|
||||
@@ -95,9 +107,9 @@ Write SECURITY.md. Set `threats_open` count. Return structured result.
|
||||
**ASVS Level:** {1/2/3}
|
||||
|
||||
### Threat Verification
|
||||
| Threat ID | Category | Disposition | Evidence |
|
||||
|-----------|----------|-------------|----------|
|
||||
| {id} | {category} | {mitigate/accept/transfer} | {file:line or doc reference} |
|
||||
| Threat ID | Category | Severity | Disposition | Evidence |
|
||||
|-----------|----------|----------|-------------|----------|
|
||||
| {id} | {category} | {critical\|high\|medium\|low} | {mitigate/accept/transfer} | {file:line or doc reference} |
|
||||
|
||||
### Unregistered Flags
|
||||
{none / list from SUMMARY.md ## Threat Flags with no threat mapping}
|
||||
@@ -115,14 +127,21 @@ SECURITY.md: {path}
|
||||
**ASVS Level:** {1/2/3}
|
||||
|
||||
### Closed
|
||||
| Threat ID | Category | Disposition | Evidence |
|
||||
|-----------|----------|-------------|----------|
|
||||
| {id} | {category} | {disposition} | {evidence} |
|
||||
| Threat ID | Category | Severity | Disposition | Evidence |
|
||||
|-----------|----------|----------|-------------|----------|
|
||||
| {id} | {category} | {critical\|high\|medium\|low} | {disposition} | {evidence} |
|
||||
|
||||
### Open
|
||||
| Threat ID | Category | Mitigation Expected | Files Searched |
|
||||
|-----------|----------|---------------------|----------------|
|
||||
| {id} | {category} | {pattern not found} | {file paths} |
|
||||
### Open (blocking — severity ≥ block_on threshold)
|
||||
| Threat ID | Category | Severity | Mitigation Expected | Files Searched |
|
||||
|-----------|----------|----------|---------------------|----------------|
|
||||
| {id} | {category} | {critical\|high\|medium\|low} | {pattern not found} | {file paths} |
|
||||
|
||||
### Open (non-blocking — severity below block_on threshold)
|
||||
| Threat ID | Category | Severity | Mitigation Expected | Files Searched |
|
||||
|-----------|----------|----------|---------------------|----------------|
|
||||
| {id} | {category} | {critical\|high\|medium\|low} | {pattern not found} | {file paths} |
|
||||
|
||||
*Only blocking-open threats count toward `threats_open` in SECURITY.md frontmatter.*
|
||||
|
||||
Next: Implement mitigations or document as accepted in SECURITY.md accepted risks log, then re-run /gsd:secure-phase.
|
||||
|
||||
|
||||
@@ -27,6 +27,8 @@ If the prompt contains a `<required_reading>` block, you MUST use the `Read` too
|
||||
- Return structured result to orchestrator
|
||||
</role>
|
||||
|
||||
@~/.claude/gsd-core/references/untrusted-input-boundary.md
|
||||
|
||||
<documentation_lookup>
|
||||
@~/.claude/gsd-core/references/research-documentation-lookup.md
|
||||
</documentation_lookup>
|
||||
|
||||
514
bin/install.js
514
bin/install.js
@@ -630,6 +630,15 @@ const processAttribution = runtimeArtifactConversion.processAttribution;
|
||||
const computePathPrefix = runtimeArtifactConversion._computePathPrefix;
|
||||
const applyRuntimeContentRewritesInPlace = runtimeArtifactConversion.applyRuntimeContentRewritesInPlace;
|
||||
const applyRuntimeContentRewritesForCommandsInPlace = runtimeArtifactConversion.applyRuntimeContentRewritesForCommandsInPlace;
|
||||
// #1675 (ADR-1508): the augment converter family is single-sourced in the
|
||||
// conversion module. install.js re-binds (does not re-define) these so there
|
||||
// is exactly one body — the generative-drift hazard the dedup removes. The two
|
||||
// private helpers (getAugmentSkillAdapterHeader, convertSlashCommandsToAugmentSkillMentions)
|
||||
// live only in the conversion module now; they are no longer duplicated here.
|
||||
// (All call sites are below this line → no TDZ hazard.)
|
||||
const convertClaudeToAugmentMarkdown = runtimeArtifactConversion.convertClaudeToAugmentMarkdown;
|
||||
const convertClaudeCommandToAugmentSkill = runtimeArtifactConversion.convertClaudeCommandToAugmentSkill;
|
||||
const convertClaudeAgentToAugmentAgent = runtimeArtifactConversion.convertClaudeAgentToAugmentAgent;
|
||||
|
||||
function rewriteLegacyManagedNodeHookCommands(settings, absoluteRunner, opts) {
|
||||
return hooksSurface.rewriteLegacyManagedNodeHookCommands(settings, absoluteRunner, opts);
|
||||
@@ -2457,20 +2466,18 @@ function convertClaudeToWindsurfMarkdown(content) {
|
||||
// Replace subagent_type from Claude to Windsurf format
|
||||
converted = converted.replace(/subagent_type="general-purpose"/g, 'subagent_type="generalPurpose"');
|
||||
converted = converted.replace(/\$ARGUMENTS\b/g, '{{GSD_ARGS}}');
|
||||
// Replace project-level Claude conventions with Windsurf/Devin equivalents
|
||||
// Workspace skills install to .devin/ (Devin Desktop preferred dir, #1085).
|
||||
// Legacy .windsurf/ is still recognized on read but new installs use .devin/.
|
||||
converted = converted.replace(/`\.\/CLAUDE\.md`/g, '`.devin/rules`');
|
||||
converted = converted.replace(/\.\/CLAUDE\.md/g, '.devin/rules');
|
||||
converted = converted.replace(/`CLAUDE\.md`/g, '`.devin/rules`');
|
||||
converted = converted.replace(/\bCLAUDE\.md\b/g, '.devin/rules');
|
||||
converted = converted.replace(/\.claude\/skills\//g, '.devin/skills/');
|
||||
converted = converted.replace(/\.\/\.claude\//g, './.devin/');
|
||||
converted = converted.replace(/\.claude\//g, '.devin/');
|
||||
// Replace project-level Claude conventions with Windsurf equivalents.
|
||||
converted = converted.replace(/`\.\/CLAUDE\.md`/g, '`.windsurf/rules`');
|
||||
converted = converted.replace(/\.\/CLAUDE\.md/g, '.windsurf/rules');
|
||||
converted = converted.replace(/`CLAUDE\.md`/g, '`.windsurf/rules`');
|
||||
converted = converted.replace(/\bCLAUDE\.md\b/g, '.windsurf/rules');
|
||||
converted = converted.replace(/\.claude\/skills\//g, '.windsurf/skills/');
|
||||
converted = converted.replace(/\.\/\.claude\//g, './.windsurf/');
|
||||
converted = converted.replace(/\.claude\//g, '.windsurf/');
|
||||
// Bare forms (no trailing slash) — after slash forms to avoid double-rewrite.
|
||||
// Use negative lookahead (?![\w-]) to preserve .claude-plugin and .claudeignore.
|
||||
converted = converted.replace(/~\/\.claude(?![\w-])/g, '~/.devin');
|
||||
converted = converted.replace(/\$HOME\/\.claude(?![\w-])/g, '$HOME/.devin');
|
||||
converted = converted.replace(/~\/\.claude(?![\w-])/g, '~/.windsurf');
|
||||
converted = converted.replace(/\$HOME\/\.claude(?![\w-])/g, '$HOME/.windsurf');
|
||||
// Environment variable name rewrite
|
||||
converted = converted.replace(/\bCLAUDE_CONFIG_DIR\b/g, 'WINDSURF_CONFIG_DIR');
|
||||
// Remove Claude Code-specific bug workarounds before brand replacement
|
||||
@@ -2524,6 +2531,33 @@ function convertClaudeCommandToWindsurfSkill(content, skillName) {
|
||||
return `---\nname: ${yamlIdentifier(skillName)}\ndescription: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
|
||||
}
|
||||
|
||||
function convertClaudeCommandToWindsurfWorkflow(content, commandName) {
|
||||
// #1615 security: commandName flows unsanitized into a markdown body that
|
||||
// Windsurf loads as an LLM-readable workflow. Validate at entry to prevent
|
||||
// (a) prompt injection via newlines / markdown structure in the filename,
|
||||
// (b) path-component injection via .., /, \ in stem → @-reference target.
|
||||
// Pattern: optional gsd- prefix + lowercase alphanumeric + dashes; rejects
|
||||
// everything else. See DEFECT.PROMPT-INJECTION-SCAN-COLLISION and the
|
||||
// PR #1622 security review.
|
||||
if (typeof commandName !== 'string' || !/^(?:gsd-)?[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(commandName)) {
|
||||
const preview = typeof commandName === 'string' ? JSON.stringify(commandName.slice(0, 60)) : String(commandName);
|
||||
throw new Error(
|
||||
`convertClaudeCommandToWindsurfWorkflow: rejected commandName ${preview}; ` +
|
||||
'must match /^(?:gsd-)?[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/ (no slashes, backslashes, spaces, dots, trailing dash, or control chars — prevents prompt injection and path-component injection into the workflow body)'
|
||||
);
|
||||
}
|
||||
const converted = convertClaudeToWindsurfMarkdown(content);
|
||||
const { frontmatter } = extractFrontmatterAndBody(converted);
|
||||
const description = frontmatter ? extractFrontmatterField(frontmatter, 'description') : '';
|
||||
const stem = commandName.startsWith('gsd-') ? commandName.slice(4) : commandName;
|
||||
const workflow = `# ${commandName}\n\n${toSingleLine(description || `Run ${commandName}.`)}\n\nRead and execute the GSD command at @~/.claude/gsd-core/commands/gsd/${stem}.md end-to-end. Treat the user's message after /${commandName} as the command arguments.`;
|
||||
const byteLength = Buffer.byteLength(workflow, 'utf8');
|
||||
if (byteLength > 12000) {
|
||||
throw new Error(`Windsurf workflow ${commandName} exceeds 12000 bytes (${byteLength}); extract references before installing`);
|
||||
}
|
||||
return workflow;
|
||||
}
|
||||
|
||||
/**
|
||||
* Convert Claude Code agent markdown to Windsurf agent format.
|
||||
* Strips frontmatter fields Windsurf doesn't support (color, skills),
|
||||
@@ -2555,105 +2589,14 @@ const claudeToAugmentTools = {
|
||||
TodoWrite: 'add_tasks',
|
||||
};
|
||||
|
||||
function convertSlashCommandsToAugmentSkillMentions(content) {
|
||||
return content.replace(/gsd:/gi, 'gsd-');
|
||||
}
|
||||
|
||||
function convertClaudeToAugmentMarkdown(content) {
|
||||
let converted = convertSlashCommandsToAugmentSkillMentions(content);
|
||||
converted = converted.replace(/\bBash\(/g, 'launch-process(');
|
||||
converted = converted.replace(/\bEdit\(/g, 'str-replace-editor(');
|
||||
converted = converted.replace(/\bRead\(/g, 'view(');
|
||||
converted = converted.replace(/\bWrite\(/g, 'save-file(');
|
||||
converted = converted.replace(/\bTodoWrite\(/g, 'add_tasks(');
|
||||
converted = converted.replace(/\bAskUserQuestion\b/g, 'conversational prompting');
|
||||
// Replace subagent_type from Claude to Augment format
|
||||
converted = converted.replace(/subagent_type="general-purpose"/g, 'subagent_type="generalPurpose"');
|
||||
converted = converted.replace(/\$ARGUMENTS\b/g, '{{GSD_ARGS}}');
|
||||
// Replace project-level Claude conventions with Augment equivalents
|
||||
converted = converted.replace(/`\.\/CLAUDE\.md`/g, '`.augment/rules/`');
|
||||
converted = converted.replace(/\.\/CLAUDE\.md/g, '.augment/rules/');
|
||||
converted = converted.replace(/`CLAUDE\.md`/g, '`.augment/rules/`');
|
||||
converted = converted.replace(/\bCLAUDE\.md\b/g, '.augment/rules/');
|
||||
converted = converted.replace(/\.claude\/skills\//g, '.augment/skills/');
|
||||
// Remove Claude Code-specific bug workarounds before brand replacement
|
||||
converted = converted.replace(/\*\*Known Claude Code bug \(classifyHandoffIfNeeded\):\*\*[^\n]*\n/g, '');
|
||||
converted = converted.replace(/- \*\*classifyHandoffIfNeeded false failure:\*\*[^\n]*\n/g, '');
|
||||
// Replace "Claude Code" brand references with "Augment"
|
||||
converted = converted.replace(/\bClaude Code\b/g, 'Augment');
|
||||
return converted;
|
||||
}
|
||||
|
||||
function getAugmentSkillAdapterHeader(skillName) {
|
||||
return `<augment_skill_adapter>
|
||||
## A. Skill Invocation
|
||||
- This skill is invoked when the user mentions \`${skillName}\` or describes a task matching this skill.
|
||||
- Treat all user text after the skill mention as \`{{GSD_ARGS}}\`.
|
||||
- If no arguments are present, treat \`{{GSD_ARGS}}\` as empty.
|
||||
|
||||
## B. User Prompting
|
||||
When the workflow needs user input, prompt the user conversationally:
|
||||
- Present options as a numbered list in your response text
|
||||
- Ask the user to reply with their choice
|
||||
- For multi-select, ask for comma-separated numbers
|
||||
|
||||
## C. Tool Usage
|
||||
Use these Augment tools when executing GSD workflows:
|
||||
- \`launch-process\` for running commands (terminal operations)
|
||||
- \`str-replace-editor\` for editing existing files
|
||||
- \`view\` for reading files and listing directories
|
||||
- \`save-file\` for creating new files
|
||||
- \`grep\` for searching code (or use MCP servers for advanced search)
|
||||
- \`web-search\`, \`web-fetch\` for web queries
|
||||
- \`add_tasks\`, \`view_tasklist\`, \`update_tasks\` for task management
|
||||
|
||||
## D. Subagent Spawning
|
||||
When the workflow needs to spawn a subagent:
|
||||
- Use the built-in subagent spawning capability
|
||||
- Define agent prompts in \`.augment/agents/\` directory
|
||||
</augment_skill_adapter>`;
|
||||
}
|
||||
|
||||
function convertClaudeCommandToAugmentSkill(content, skillName) {
|
||||
const converted = convertClaudeToAugmentMarkdown(content);
|
||||
const { frontmatter, body } = extractFrontmatterAndBody(converted);
|
||||
let description = `Run GSD workflow ${skillName}.`;
|
||||
if (frontmatter) {
|
||||
const maybeDescription = extractFrontmatterField(frontmatter, 'description');
|
||||
if (maybeDescription) {
|
||||
description = maybeDescription;
|
||||
}
|
||||
}
|
||||
description = toSingleLine(description);
|
||||
const shortDescription = description.length > 180 ? `${description.slice(0, 177)}...` : description;
|
||||
const adapter = getAugmentSkillAdapterHeader(skillName);
|
||||
|
||||
return `---\nname: ${yamlIdentifier(skillName)}\ndescription: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Convert Claude Code agent markdown to Augment agent format.
|
||||
* Strips frontmatter fields Augment doesn't support (color, skills),
|
||||
* converts tool references, and cleans up for Augment agents.
|
||||
*/
|
||||
function convertClaudeAgentToAugmentAgent(content) {
|
||||
let converted = convertClaudeToAugmentMarkdown(content);
|
||||
|
||||
const { frontmatter, body } = extractFrontmatterAndBody(converted);
|
||||
if (!frontmatter) return converted;
|
||||
|
||||
const name = extractFrontmatterField(frontmatter, 'name') || 'unknown';
|
||||
const description = extractFrontmatterField(frontmatter, 'description') || '';
|
||||
|
||||
const cleanFrontmatter = `---\nname: ${yamlIdentifier(name)}\ndescription: ${yamlQuote(toSingleLine(description))}\n---`;
|
||||
|
||||
return `${cleanFrontmatter}\n${body}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Copy Claude commands as Augment skills — one folder per skill with SKILL.md.
|
||||
* Mirrors copyCommandsAsCursorSkills but uses Augment converters.
|
||||
*/
|
||||
// #1675 (ADR-1508): the augment converter family below was a byte-identical
|
||||
// duplicate of runtime-artifact-conversion.cjs:
|
||||
// convertSlashCommandsToAugmentSkillMentions, convertClaudeToAugmentMarkdown,
|
||||
// getAugmentSkillAdapterHeader, convertClaudeCommandToAugmentSkill,
|
||||
// convertClaudeAgentToAugmentAgent
|
||||
// Deleted here and bound from runtimeArtifactConversion above (single source).
|
||||
// The DEFECT.GENERATIVE-FIX parity guard in
|
||||
// tests/enh-1511-rewrite-engine-relocation.test.cjs asserts reference identity.
|
||||
|
||||
function convertSlashCommandsToTraeSkillMentions(content) {
|
||||
return content.replace(/\/gsd:([a-z0-9-]+)/g, (_, commandName) => {
|
||||
@@ -3229,6 +3172,66 @@ function cleanupCodexSkillMetadataSidecars(skillsDir) {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove legacy Windsurf skill artifacts from .devin/skills/gsd- directories.
|
||||
*
|
||||
* Pre-#1615 Windsurf installs wrote skills under .devin/ (Devin Desktop
|
||||
* preferred dir, #1085). #1615 moved Windsurf to .windsurf/workflows/.
|
||||
* Old .devin/skills/gsd- dirs linger on disk indefinitely and confuse
|
||||
* users who see two GSD trees.
|
||||
*
|
||||
* Preserves user-owned content:
|
||||
* - non-gsd-* dirs under .devin/skills/ (user-authored skills)
|
||||
* - gsd-dev-preferences/ (user-owned per #2973)
|
||||
* - any files (not dirs) under .devin/skills/
|
||||
*
|
||||
* @param {string} workspaceDir - workspace root (process.cwd() for local installs)
|
||||
* @returns {number} count of removed legacy gsd-* skill directories
|
||||
*/
|
||||
function cleanupWindsurfLegacyDevinSkills(workspaceDir) {
|
||||
const legacySkillsDir = path.join(workspaceDir, '.devin', 'skills');
|
||||
if (!fs.existsSync(legacySkillsDir)) return 0;
|
||||
|
||||
// Mirror the user-owned list from cleanupCodexSkillMetadataSidecars (#2973).
|
||||
const _userOwnedSkillDirs = new Set(['gsd-dev-preferences']);
|
||||
let removed = 0;
|
||||
|
||||
for (const entry of fs.readdirSync(legacySkillsDir, { withFileTypes: true })) {
|
||||
if (!entry.isDirectory() || !entry.name.startsWith('gsd-')) continue;
|
||||
if (_userOwnedSkillDirs.has(entry.name)) continue;
|
||||
|
||||
const dirToRemove = path.join(legacySkillsDir, entry.name);
|
||||
try {
|
||||
// Symlink guard: if the gsd-* dir is itself a symlink pointing outside
|
||||
// the .devin tree, deleting through it could escape the tree. Skip.
|
||||
const stat = fs.lstatSync(dirToRemove);
|
||||
if (stat.isSymbolicLink()) continue;
|
||||
|
||||
fs.rmSync(dirToRemove, { recursive: true, force: true });
|
||||
removed++;
|
||||
} catch (_err) {
|
||||
// Fail open — a single bad dir must not block the install.
|
||||
}
|
||||
}
|
||||
|
||||
// If .devin/skills/ is now empty, prune it. If .devin/ itself is then empty,
|
||||
// prune that too — leaves the workspace clean for the new .windsurf/ layout.
|
||||
// Never remove non-empty containers (user may have other Devin content).
|
||||
try {
|
||||
if (fs.existsSync(legacySkillsDir) && fs.readdirSync(legacySkillsDir).length === 0) {
|
||||
fs.rmdirSync(legacySkillsDir);
|
||||
const devinDir = path.join(workspaceDir, '.devin');
|
||||
if (fs.existsSync(devinDir) && fs.readdirSync(devinDir).length === 0) {
|
||||
fs.rmdirSync(devinDir);
|
||||
}
|
||||
}
|
||||
} catch (_err) {
|
||||
// best-effort container cleanup
|
||||
}
|
||||
|
||||
return removed;
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate the GSD config block for Codex config.toml.
|
||||
* @param {Array<{name: string, description: string}>} agents
|
||||
@@ -9598,6 +9601,17 @@ function install(isGlobal, runtime = 'claude', options = {}) {
|
||||
cleanupCodexSkillMetadataSidecars(path.join(targetDir, 'skills'));
|
||||
}
|
||||
|
||||
// #1629 Finding B: Windsurf local only — remove legacy .devin/skills/gsd-*
|
||||
// dirs from pre-#1615 installs. #1615 moved Windsurf to .windsurf/workflows/
|
||||
// but never cleaned up the old .devin/skills/ layout (#1085). User-owned
|
||||
// content is preserved (non-gsd- dirs, gsd-dev-preferences, symlinks).
|
||||
if (isWindsurf && !isGlobal) {
|
||||
const removedCount = cleanupWindsurfLegacyDevinSkills(process.cwd());
|
||||
if (removedCount > 0) {
|
||||
console.log(` ${green}✓${reset} Removed ${removedCount} legacy .devin/skills/gsd-* dir(s) (pre-#1615 Windsurf layout)`);
|
||||
}
|
||||
}
|
||||
|
||||
// Hermes only: write DESCRIPTION.md for the gsd/ category after layout install
|
||||
if (isHermes) {
|
||||
writeHermesCategoryDescription(path.join(targetDir, 'skills', 'gsd'));
|
||||
@@ -9638,6 +9652,23 @@ function install(isGlobal, runtime = 'claude', options = {}) {
|
||||
} else {
|
||||
failures.push('agents/gsd.yaml');
|
||||
}
|
||||
} else if (isWindsurf) {
|
||||
if (isGlobal) {
|
||||
console.log(` ${green}✓${reset} Windsurf global install skipped workflow artifacts (workspace-only)`);
|
||||
} else {
|
||||
const workflowsDir = path.join(targetDir, 'workflows');
|
||||
if (fs.existsSync(workflowsDir)) {
|
||||
const workflowCount = fs.readdirSync(workflowsDir)
|
||||
.filter(f => f.startsWith('gsd-') && f.endsWith('.md')).length;
|
||||
if (workflowCount > 0) {
|
||||
console.log(` ${green}✓${reset} Installed ${workflowCount} workflows to workflows/`);
|
||||
} else {
|
||||
failures.push('workflows/gsd-*');
|
||||
}
|
||||
} else {
|
||||
failures.push('workflows/gsd-*');
|
||||
}
|
||||
}
|
||||
} else {
|
||||
const skillsDir = path.join(targetDir, 'skills');
|
||||
if (fs.existsSync(skillsDir)) {
|
||||
@@ -9868,16 +9899,14 @@ function install(isGlobal, runtime = 'claude', options = {}) {
|
||||
// contexts,references,templates,workflows} but NOT the commands/gsd source
|
||||
// tree, and _runLegacyUninstallCleanup actively removes any commands/gsd/
|
||||
// for that scope — so findInstallSourceRoot's walk-up has nothing to find
|
||||
// and /gsd-surface (list/status and the write subcommands) throws. This is
|
||||
// the writer half of the marker that runtime-artifact-layout.cjs's finders
|
||||
// already read (the reader landed in #1476). It points at the package's own
|
||||
// commands/gsd source, whose parent also holds bin/install.js — the path
|
||||
// loadInstallExports derives the installer exports from. Scoped to the
|
||||
// Claude-global layout (issue #1477) — the only install path that ships the
|
||||
// skills layout without a commands/gsd source tree; every other runtime/scope
|
||||
// deploys commands/gsd, so its walk-up already resolves and needs no marker.
|
||||
// Guarded on source presence so a half-published package never writes a
|
||||
// dangling marker.
|
||||
// and /gsd-surface (list/status) throws. This is the writer half of the
|
||||
// marker that runtime-artifact-layout.cjs's finders already read (the reader
|
||||
// landed in #1476). It points at the package's own commands/gsd source.
|
||||
// Scoped to the Claude-global layout (issue #1477) — the only install path
|
||||
// that ships the skills layout without a commands/gsd source tree; every
|
||||
// other runtime/scope deploys commands/gsd, so its walk-up already resolves
|
||||
// and needs no marker. Guarded on source presence so a half-published
|
||||
// package never writes a dangling marker.
|
||||
if (runtime === 'claude' && isGlobal) {
|
||||
const gsdSourceCommands = path.join(src, 'commands', 'gsd');
|
||||
if (fs.existsSync(gsdSourceCommands)) {
|
||||
@@ -9887,6 +9916,23 @@ function install(isGlobal, runtime = 'claude', options = {}) {
|
||||
}
|
||||
}
|
||||
|
||||
// #1629 critical fix: Windsurf workflow wrappers (convertClaudeCommandToWindsurfWorkflow)
|
||||
// delegate to command bodies at <targetDir>/gsd-core/commands/gsd/${stem}.md via a
|
||||
// hardcoded @~/.claude/gsd-core/commands/gsd/ path that _applyRuntimeRewrites rewrites
|
||||
// to the install target. The source gsd-core/ dir does NOT ship with commands/ —
|
||||
// the canonical command source lives at the package root (commands/gsd/). Without
|
||||
// this copy, every /gsd-* workflow in Cascade references a missing file and the LLM
|
||||
// cannot execute the command body. Surfaced by the #1629 regression test after the
|
||||
// original adversarial review of #1622 missed it.
|
||||
if (isWindsurf && !isGlobal) {
|
||||
const commandsSrc = path.join(src, 'commands', 'gsd');
|
||||
const commandsDest = path.join(skillDest, 'commands', 'gsd');
|
||||
if (fs.existsSync(commandsSrc)) {
|
||||
copyWithPathReplacement(commandsSrc, commandsDest, pathPrefix, runtime, true, isGlobal);
|
||||
console.log(` ${green}✓${reset} Installed command bodies to gsd-core/commands/gsd/ (workflow delegation targets)`);
|
||||
}
|
||||
}
|
||||
|
||||
// Copy shared manifests into the gsd-core payload
|
||||
// at the co-located path that CJS modules resolve first:
|
||||
// gsd-core/bin/shared/*.json
|
||||
@@ -11201,10 +11247,14 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
|
||||
configureKiloPermissions(isGlobal, configDir);
|
||||
}
|
||||
|
||||
// For non-Claude runtimes, set resolve_model_ids: "omit" in ~/.gsd/defaults.json
|
||||
// so resolveModelInternal() returns '' instead of Claude aliases (opus/sonnet/haiku)
|
||||
// that the runtime can't resolve. Users can still use model_overrides for explicit IDs.
|
||||
// See #1156. Guard matches the #130-class pattern on configureOpencodePermissions above.
|
||||
// For non-Claude runtimes, DEFAULT resolve_model_ids to "omit" in ~/.gsd/defaults.json
|
||||
// when it is absent or falsy, so resolveModelInternal() returns '' instead of Claude
|
||||
// aliases (opus/sonnet/haiku) the runtime can't resolve. An explicit `true` opt-in
|
||||
// (resolveModelInternal returns full materialized model IDs) MUST be preserved —
|
||||
// rewriting it to "omit" would make generated agent manifests inherit the active
|
||||
// chat model instead of pinning the resolved model. See #1156 (default-to-omit
|
||||
// intent) and #1569 (preserve explicit true). Guard matches the #130-class pattern
|
||||
// on configureOpencodePermissions above.
|
||||
if (runtime !== 'claude' && !process.env.GSD_TEST_MODE) {
|
||||
const gsdDir = path.join(os.homedir(), '.gsd');
|
||||
const defaultsPath = path.join(gsdDir, 'defaults.json');
|
||||
@@ -11212,7 +11262,22 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
|
||||
fs.mkdirSync(gsdDir, { recursive: true });
|
||||
let defaults = {};
|
||||
try { defaults = JSON.parse(fs.readFileSync(defaultsPath, 'utf8')); } catch { /* new file */ }
|
||||
if (defaults.resolve_model_ids !== 'omit') {
|
||||
// Recover a malformed (valid-JSON-but-non-object) defaults.json to a fresh object so
|
||||
// the write below succeeds and the file is no longer broken. Without this, `null` /
|
||||
// `[]` / a number / a string bypass the parse catch and either throw a TypeError on
|
||||
// property access (swallowed by the outer try/catch, leaving the file broken) or get
|
||||
// a property set that won't round-trip through JSON.stringify. (#1657)
|
||||
if (defaults === null || typeof defaults !== 'object' || Array.isArray(defaults)) {
|
||||
defaults = {};
|
||||
}
|
||||
// Three-valued domain: false/absent → aliases; true → full IDs; "omit" → ''.
|
||||
// Honor ONLY an explicit canonical `true` opt-in (full model IDs) and an existing
|
||||
// "omit"; default everything else — absent, falsy, OR any non-canonical value — to
|
||||
// "omit", the safe non-Claude default. Allowlist-based so malformed values
|
||||
// (0, "", "yes", {}, …) don't leak Claude aliases the runtime can't resolve (#1569).
|
||||
const existing = defaults.resolve_model_ids;
|
||||
const shouldDefaultToOmit = existing !== true && existing !== 'omit';
|
||||
if (shouldDefaultToOmit) {
|
||||
defaults.resolve_model_ids = 'omit';
|
||||
fs.writeFileSync(defaultsPath, JSON.stringify(defaults, null, 2) + '\n');
|
||||
console.log(` ${green}✓${reset} Set resolve_model_ids: "omit" in ~/.gsd/defaults.json`);
|
||||
@@ -11668,6 +11733,189 @@ function homePathCoveredByRc(globalBin, homeDir, rcFileNames) {
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Decode fish's universal-variable value escaping (the inverse of fish's
|
||||
* `full_escape`). fish serializes every non-`[A-Za-z0-9/_]` byte in
|
||||
* `fish_variables` — e.g. space -> `\x20`, hyphen -> `\x2d`, dot -> `\x2e` —
|
||||
* and joins list elements with the literal 4-char token `\x1e` (NOT a raw
|
||||
* 0x1e byte). Callers split on `\x1e` first, then decode each element here.
|
||||
*
|
||||
* Pure and total: any unrecognised `\`-sequence is passed through verbatim,
|
||||
* so `decode(fishEscape(p)) === p` holds for every path string. Exported for
|
||||
* a fast-check round-trip property test (#323).
|
||||
*
|
||||
* @param {string} s A single (already `\x1e`-split) escaped value.
|
||||
* @returns {string} The decoded literal.
|
||||
*/
|
||||
function decodeFishUniversalValue(s) {
|
||||
let out = '';
|
||||
for (let i = 0; i < s.length; i++) {
|
||||
const c = s[i];
|
||||
if (c !== '\\') { out += c; continue; }
|
||||
const n = s[i + 1];
|
||||
if (n === 'n') { out += '\n'; i += 1; }
|
||||
else if (n === 'r') { out += '\r'; i += 1; }
|
||||
else if (n === 't') { out += '\t'; i += 1; }
|
||||
else if (n === '\\') { out += '\\'; i += 1; }
|
||||
else if (n === 'x' || n === 'X') {
|
||||
const hex = s.slice(i + 2, i + 4);
|
||||
if (/^[0-9a-fA-F]{2}$/.test(hex)) { out += String.fromCharCode(parseInt(hex, 16)); i += 3; }
|
||||
else { out += c; }
|
||||
} else if (n === 'u') {
|
||||
const hex = s.slice(i + 2, i + 6);
|
||||
if (/^[0-9a-fA-F]{4}$/.test(hex)) { out += String.fromCharCode(parseInt(hex, 16)); i += 5; }
|
||||
else { out += c; }
|
||||
} else if (n === 'U') {
|
||||
const hex = s.slice(i + 2, i + 10);
|
||||
if (/^[0-9a-fA-F]{8}$/.test(hex)) { out += String.fromCodePoint(parseInt(hex, 16)); i += 9; }
|
||||
else { out += c; }
|
||||
} else { out += c; }
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check whether fish's configuration already places `globalBin` on PATH (#323).
|
||||
*
|
||||
* fish does not use the sh-style `export PATH=` rc files that
|
||||
* `homePathCoveredByRc()` parses, so a fish user whose `fish_user_paths`
|
||||
* already covers the global bin would otherwise see a false-positive
|
||||
* "not on your PATH" warning on every install. Two detection routes,
|
||||
* mirroring how `fish_add_path` actually persists:
|
||||
*
|
||||
* 1. The universal-variable store `fish_variables` — a
|
||||
* `SETUVAR fish_user_paths:<a>\x1e<b>…` line whose `\x1e`-separated
|
||||
* entries are absolute paths (fish does not HOME-expand them here).
|
||||
* 2. `config.fish` — explicit `fish_add_path …`, `set -gx PATH …`, or
|
||||
* `set -Ux fish_user_paths …` lines that name the directory after
|
||||
* HOME expansion.
|
||||
*
|
||||
* Best-effort and side-effect-free: any unreadable / missing file is ignored
|
||||
* (no fish subprocess is spawned). Honours `$XDG_CONFIG_HOME` and always also
|
||||
* checks `~/.config/fish`. Pass `fishConfigDir` to override the lookup
|
||||
* directory (tests).
|
||||
*
|
||||
* @param {string} globalBin Absolute path to npm's global bin directory.
|
||||
* @param {string} homeDir Absolute path used to substitute HOME / ~.
|
||||
* @param {string} [fishConfigDir] Override the fish config directory.
|
||||
* @returns {boolean} true iff fish config adds globalBin to PATH.
|
||||
*/
|
||||
function homePathCoveredByFishConfig(globalBin, homeDir, fishConfigDir) {
|
||||
if (!globalBin || !homeDir) return false;
|
||||
const path = require('path');
|
||||
const fs = require('fs');
|
||||
|
||||
const normalise = (p) => {
|
||||
if (!p) return '';
|
||||
let n = p.replace(/[\\/]+$/g, '');
|
||||
if (n === '') n = p.startsWith('/') ? '/' : p;
|
||||
return n;
|
||||
};
|
||||
|
||||
const targetAbs = normalise(path.resolve(globalBin));
|
||||
const homeAbs = path.resolve(homeDir);
|
||||
|
||||
const baseDirs = [];
|
||||
if (fishConfigDir) {
|
||||
baseDirs.push(fishConfigDir);
|
||||
} else {
|
||||
if (process.env.XDG_CONFIG_HOME) {
|
||||
baseDirs.push(path.join(process.env.XDG_CONFIG_HOME, 'fish'));
|
||||
}
|
||||
baseDirs.push(path.join(homeAbs, '.config', 'fish'));
|
||||
}
|
||||
|
||||
const expandHome = (segment) => {
|
||||
let s = segment;
|
||||
s = s.replace(/\$\{HOME\}/g, homeAbs).replace(/\$HOME/g, homeAbs);
|
||||
if (s.startsWith('~/') || s === '~') {
|
||||
s = s === '~' ? homeAbs : path.join(homeAbs, s.slice(2));
|
||||
}
|
||||
return s;
|
||||
};
|
||||
|
||||
// Compare an already-resolved absolute literal (a decoded fish_user_paths
|
||||
// entry — fish stores these resolved, never as `$VAR`/`~`). A literal `$`
|
||||
// here is part of the directory name, so it must NOT be treated as an
|
||||
// unexpanded variable.
|
||||
const matchesLiteral = (segment) => {
|
||||
if (!segment || !path.isAbsolute(segment)) return false;
|
||||
try {
|
||||
return normalise(path.resolve(segment)) === targetAbs;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
};
|
||||
|
||||
// Compare a config.fish shell token: strip surrounding quotes, expand the
|
||||
// common HOME forms, and skip anything still holding a `$` (an unexpanded
|
||||
// variable such as `$PATH` / `$fish_user_paths`) or still relative.
|
||||
const matchesTarget = (rawSegment) => {
|
||||
if (!rawSegment) return false;
|
||||
let seg = rawSegment.trim();
|
||||
if ((seg.startsWith('"') && seg.endsWith('"')) ||
|
||||
(seg.startsWith("'") && seg.endsWith("'"))) {
|
||||
seg = seg.slice(1, -1);
|
||||
}
|
||||
const expanded = expandHome(seg);
|
||||
if (expanded.includes('$')) return false;
|
||||
return matchesLiteral(expanded);
|
||||
};
|
||||
|
||||
const readLines = (filePath) => {
|
||||
try {
|
||||
return fs.readFileSync(filePath, 'utf8').split(/\r?\n/);
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
};
|
||||
|
||||
for (const baseDir of baseDirs) {
|
||||
// Route 1: universal variable store.
|
||||
const uvarLines = readLines(path.join(baseDir, 'fish_variables'));
|
||||
if (uvarLines) {
|
||||
for (const rawLine of uvarLines) {
|
||||
const m = /^SETUVAR(?:\s+--\S+)*\s+fish_user_paths:(.*)$/.exec(rawLine);
|
||||
if (!m) continue;
|
||||
// Elements are joined by the literal `\x1e` token; decode each. The
|
||||
// decoded entry is an absolute literal — compare it directly.
|
||||
for (const entry of m[1].split('\\x1e')) {
|
||||
if (matchesLiteral(decodeFishUniversalValue(entry))) return true;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Route 2: config.fish explicit PATH mutations.
|
||||
const configLines = readLines(path.join(baseDir, 'config.fish'));
|
||||
if (configLines) {
|
||||
for (const rawLine of configLines) {
|
||||
const line = rawLine.replace(/^\s+/, '');
|
||||
if (line.startsWith('#')) continue;
|
||||
|
||||
let rest = null;
|
||||
let m;
|
||||
if ((m = /^fish_add_path\s+(.+)$/.exec(line))) {
|
||||
rest = m[1];
|
||||
} else if ((m = /^set\s+(?:-\S+\s+)*PATH\s+(.+)$/.exec(line))) {
|
||||
rest = m[1];
|
||||
} else if ((m = /^set\s+(?:-\S+\s+)*fish_user_paths\s+(.+)$/.exec(line))) {
|
||||
rest = m[1];
|
||||
}
|
||||
if (rest === null) continue;
|
||||
|
||||
// Tokens are whitespace-separated; flag tokens (`-g`, `--path`) and
|
||||
// variable references are skipped by matchesTarget / the `-` guard.
|
||||
for (const tok of rest.split(/\s+/)) {
|
||||
if (!tok || tok.startsWith('-')) continue;
|
||||
if (matchesTarget(tok)) return true;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Emit a PATH-export suggestion if globalBin is not already on PATH AND
|
||||
* the user's shell rc files do not already cover it via a HOME-relative
|
||||
@@ -11710,6 +11958,16 @@ function maybeSuggestPathExport(globalBin, homeDir) {
|
||||
return;
|
||||
}
|
||||
|
||||
// Same idea for fish users: fish_user_paths / config.fish already covers the
|
||||
// dir, the current session just predates it. fish has no sh-style rc file so
|
||||
// homePathCoveredByRc never sees it — check the fish config explicitly (#323).
|
||||
if (homePathCoveredByFishConfig(globalBin, homeDir)) {
|
||||
console.log('');
|
||||
console.log(` ${yellow}⚠${reset} ${bold}${globalBin}${reset}'s directory is already on your PATH via fish's universal variables — open a new fish session (or run ${cyan}exec fish${reset}).`);
|
||||
console.log('');
|
||||
return;
|
||||
}
|
||||
|
||||
console.log('');
|
||||
console.log(` ${yellow}⚠${reset} ${bold}${globalBin}${reset} is not on your PATH.`);
|
||||
console.log(` Add it with one of:`);
|
||||
@@ -11943,6 +12201,7 @@ module.exports = {
|
||||
convertClaudeAgentToCodexAgent,
|
||||
generateCodexAgentToml,
|
||||
cleanupCodexSkillMetadataSidecars,
|
||||
cleanupWindsurfLegacyDevinSkills,
|
||||
generateCodexConfigBlock,
|
||||
stripGsdFromCodexConfig,
|
||||
migrateCodexHooksMapFormat,
|
||||
@@ -12004,6 +12263,7 @@ module.exports = {
|
||||
skillFrontmatterName,
|
||||
convertClaudeToWindsurfMarkdown,
|
||||
convertClaudeCommandToWindsurfSkill,
|
||||
convertClaudeCommandToWindsurfWorkflow,
|
||||
convertClaudeAgentToWindsurfAgent,
|
||||
convertClaudeToAugmentMarkdown,
|
||||
convertClaudeCommandToAugmentSkill,
|
||||
@@ -12045,6 +12305,8 @@ module.exports = {
|
||||
USER_OWNED_ARTIFACTS,
|
||||
finishInstall,
|
||||
homePathCoveredByRc,
|
||||
homePathCoveredByFishConfig,
|
||||
decodeFishUniversalValue,
|
||||
maybeSuggestPathExport,
|
||||
runtimeMap,
|
||||
allRuntimes,
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "ai-integration",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "AI design contract",
|
||||
"description": "AI-SPEC design contract workflow for phases that build AI systems; owns the AI integration command, agents, and workflow.ai_integration_phase activation key.",
|
||||
"tier": "full",
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
{
|
||||
"id": "antigravity",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "Antigravity",
|
||||
"description": "Google Antigravity IDE — nested under ~/.gemini/antigravity; probed across 1.x and 2.x layouts; Gemini hook event dialect; nested skill layout; tier-1 support.",
|
||||
"description": "Google Antigravity IDE — nested under ~/.gemini/antigravity; probed across 1.x and 2.x layouts; Gemini hook event dialect; flat skill layout; tier-1 support.",
|
||||
"tier": "core",
|
||||
"requires": [],
|
||||
"engines": {
|
||||
@@ -31,7 +31,7 @@
|
||||
"kind": "skills",
|
||||
"destSubpath": "skills",
|
||||
"prefix": "gsd-",
|
||||
"nesting": "nested",
|
||||
"nesting": "flat",
|
||||
"recursive": false,
|
||||
"converter": "convertClaudeCommandToAntigravitySkill"
|
||||
}
|
||||
@@ -41,7 +41,7 @@
|
||||
"kind": "skills",
|
||||
"destSubpath": "skills",
|
||||
"prefix": "gsd-",
|
||||
"nesting": "nested",
|
||||
"nesting": "flat",
|
||||
"recursive": false,
|
||||
"converter": "convertClaudeCommandToAntigravitySkill"
|
||||
}
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "audit",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "Audit",
|
||||
"description": "Open-artifact audit and UAT-gap audit for milestone close gates; exposes `gsd-tools audit-uat` (cross-phase UAT outstanding items) and `gsd-tools audit-open` (structured open-artifact scan across debug, tasks, threads, todos, seeds, UAT, verification, context-questions).",
|
||||
"tier": "full",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "augment",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "Augment Code",
|
||||
"description": "Augment Code CLI — commands + nested-skill artifact layout; settings-json hook surface; Claude hook event dialect; tier-2 support.",
|
||||
"tier": "core",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "claude",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "Claude Code",
|
||||
"description": "Anthropic Claude Code — primary development runtime; tier-1 support with full hook surface and skills-based global install.",
|
||||
"tier": "core",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "cline",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "Cline",
|
||||
"description": "Cline (VS Code extension) — global-only nested-skill layout; cline-rules hook surface (.clinerules); no hook events emitted; tier-2 support.",
|
||||
"tier": "core",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "code-review",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "Code review",
|
||||
"description": "Source-file code review and review-fix workflow support for completed execution work.",
|
||||
"tier": "full",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "codebuddy",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "CodeBuddy",
|
||||
"description": "CodeBuddy (Tencent) — converted commands + skills artifact layout; settings-json hook surface; Claude hook event dialect; tier-2 support.",
|
||||
"tier": "core",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "codex",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "OpenAI Codex CLI",
|
||||
"description": "OpenAI Codex CLI — shell-var command style; per-agent sandbox tiers; config.toml + hooks.json hook surface; tier-1 support.",
|
||||
"tier": "core",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "copilot",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "GitHub Copilot",
|
||||
"description": "GitHub Copilot (VS Code) — markdown config format; copilot-inline hook surface; no hook events emitted; flat skill nesting (unconfirmed recursive loader); tier-2 support.",
|
||||
"tier": "core",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "cursor",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "Cursor",
|
||||
"description": "Cursor IDE — skills + converted commands artifact layout; hooks.json surface; Claude hook event dialect; recursive skill loader (flat nesting); tier-2 support.",
|
||||
"tier": "core",
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
{
|
||||
"id": "drift",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "Drift detection gates",
|
||||
"description": "Post-execution drift detection gates that run after each wave completes. Provides two gates at execute:wave:post: a blocking schema drift gate (detects schema files changed without a database push) and a non-blocking codebase drift gate (detects structural additions not reflected in STRUCTURE.md).",
|
||||
"description": "Drift detection gates for the planning loop. At execute:wave:post: a blocking schema drift gate (detects schema files changed without a database push) and a non-blocking codebase drift gate (detects structural additions not reflected in STRUCTURE.md). At plan:pre: a non-blocking, warn-only codebase drift gate (gated on workflow.plan_drift_precheck) that flags a stale codebase map before planning, so plans are authored against a fresh STRUCTURE.md instead of discovering drift mid-execution.",
|
||||
"tier": "full",
|
||||
"requires": [],
|
||||
"engines": {
|
||||
@@ -37,6 +37,11 @@
|
||||
"type": "boolean",
|
||||
"default": true,
|
||||
"description": "Enable the drift gates at execute:wave:post. When enabled, the schema drift gate blocks verification if schema-relevant files changed during execution but no database push command was executed; the codebase drift gate (non-blocking) warns when structural additions exceed the drift_threshold."
|
||||
},
|
||||
"workflow.plan_drift_precheck": {
|
||||
"type": "boolean",
|
||||
"default": true,
|
||||
"description": "Enable the non-blocking codebase drift pre-check at plan:pre, before /gsd:plan-phase spawns the planner. When enabled, a stale STRUCTURE.md (structural additions exceeding drift_threshold) is surfaced up front as a warn-only advisory pointing to /gsd:map-codebase; it never blocks planning and never spawns the mapper agent. Separate from schema_drift_gate so autonomous/CI runs can silence the plan-time advisory while keeping the execute:wave:post gates enabled."
|
||||
}
|
||||
},
|
||||
"steps": [],
|
||||
@@ -59,6 +64,15 @@
|
||||
"when": "workflow.schema_drift_gate",
|
||||
"blocking": false,
|
||||
"onError": "skip"
|
||||
},
|
||||
{
|
||||
"point": "plan:pre",
|
||||
"check": {
|
||||
"query": "verify.codebase-drift"
|
||||
},
|
||||
"when": "workflow.plan_drift_precheck",
|
||||
"blocking": false,
|
||||
"onError": "skip"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "gap-analysis",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "Post-planning gap analysis",
|
||||
"description": "Proactive, non-blocking post-planning coverage report. After all PLAN.md files are generated, cross-references every REQ-ID and D-ID from REQUIREMENTS.md and CONTEXT.md against plan bodies. Emits a Source | Item | Status table. Does not block phase advancement.",
|
||||
"tier": "standard",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "gemini",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "Gemini CLI",
|
||||
"description": "Google Gemini CLI — commands-only artifact layout (TOML); Gemini hook event dialect; settings-json hook surface; tier-2 support.",
|
||||
"tier": "core",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "graphify",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "Knowledge graph",
|
||||
"description": "Build, query, and inspect the project knowledge graph in `.planning/graphs/`; exposes graphify CLI subcommands (build, query, status, diff) and the /gsd-graphify skill.",
|
||||
"tier": "full",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "hermes",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "Hermes Agent",
|
||||
"description": "Hermes Agent (NousResearch) — skills nest under skills/gsd/ category bucket; nested skill layout; settings-json hook surface; Claude hook event dialect; tier-2 support.",
|
||||
"tier": "core",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "intel",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "Codebase intelligence",
|
||||
"description": "Code-intelligence store for codebase querying, diff, snapshot, and API-surface extraction; exposes `gsd-tools intel` subcommands (query, status, update, diff, snapshot, patch-meta, validate, extract-exports, api-surface) and backs `/gsd-map-codebase` and `gsd-intel-updater`.",
|
||||
"tier": "full",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "kilo",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "Kilo Code",
|
||||
"description": "Kilo Code — XDG-based config dir; global skills at ~/.kilo/skills (separate from XDG config); flat command/ + skills artifact layout; no lifecycle hook registration; tier-2 support.",
|
||||
"tier": "core",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "kimi",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "Kimi CLI",
|
||||
"description": "Kimi CLI (Moonshot AI) — generic agents root at ~/.config/agents; skills + kimi-agents artifact layout; no hook surface; no hook events; tier-2 support.",
|
||||
"tier": "core",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "mempalace",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "MemPalace memory",
|
||||
"description": "Cross-session, cross-project memory: deliberate recall before discuss/plan and verbatim capture + temporal-KG sync at phase boundaries, via the MemPalace MCP server and CLI.",
|
||||
"tier": "full",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "nyquist",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "Nyquist validation",
|
||||
"description": "Validation coverage audit that maps executed work back to tests and manual-only evidence.",
|
||||
"tier": "full",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "opencode",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "OpenCode",
|
||||
"description": "OpenCode — XDG-based config dir; flat command/ + skills artifact layout; settings-json config format; no lifecycle hook registration; tier-2 support.",
|
||||
"tier": "core",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "pattern-mapper",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "Pattern mapping",
|
||||
"description": "Optional codebase-pattern mapping before planning; owns the pattern mapper agent and workflow.pattern_mapper activation key.",
|
||||
"tier": "full",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "profile-pipeline",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "Developer profiling pipeline",
|
||||
"description": "Developer behavioral profiling from Claude Code session history; scans session JSONL files, extracts and samples user messages, and generates profile artifacts (USER-PROFILE.md, dev-preferences.md, CLAUDE.md sections). Exposes eight `gsd-tools` commands: scan-sessions, extract-messages, profile-sample (pipeline phase) and write-profile, profile-questionnaire, generate-dev-preferences, generate-claude-profile, generate-claude-md (output phase). Backs the /gsd-profile-user skill and gsd-user-profiler agent.",
|
||||
"tier": "full",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "qwen",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "Qwen Code",
|
||||
"description": "Qwen Code (Alibaba) — nested-skill artifact layout; settings-json hook surface; Claude hook event dialect; tier-2 support.",
|
||||
"tier": "core",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "research",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.2",
|
||||
"version": "1.6.0",
|
||||
"title": "Phase research",
|
||||
"description": "Optional phase research before planning; owns the phase researcher agent and workflow.research activation key.",
|
||||
"tier": "standard",
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user