63abcface9
* feat(#3146): resolve gsd_run so workflows cannot reach a foreign gsd-tools The predecessor package get-shit-done-cc publishes a colliding gsd-tools bin whose phases.clear DELETES where this package's ARCHIVES, and both print success-shaped output against a gitignored .planning/ -- which is how #3129 cost a user 43 phase directories with no error and nothing recoverable from git. The launcher's PATH branch now resolves gsd_run, published only by this package and self-locating via its own symlink chain to the sibling shim, instead of the colliding gsd-tools. A foreign handler becomes unreachable from PATH, and when no gsd_run is reachable the resolver fails closed rather than falling back -- that fallback was the vulnerability. This is smaller than the branch it replaces, which matters: the preamble is inlined into 113 shipped files and agents/gsd-verifier.md sits 2 bytes under a red-line size cap. unset -f gsd_run leads the preamble so a re-source is idempotent. Without it, command -v finds the shell function, returns a bare name, and the resolver falls through to an exit 1 that kills a sourced caller's shell. Adds gsd-tools runtime-identity, a manual diagnostic reporting this runtime's package coordinates over the baked package-identity (#498) and readHostVersion, with a strict total classifier: only a JSON object with an exact packageName verifies, since JSON.parse admits 0/"str"/[]/null/true. An inlined identity assertion was built and reviewed first, then withdrawn -- it breaks five frozen size ceilings and no assertion fits in 2 bytes. Closes #3146 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#3146): stop sync:launcher relocating a deliberate preamble placement Pre-existing defect, surfaced by this PR because sync is a no-op unless the snippet content actually changes. transformFile inserts the preamble into the first block that CALLS gsd_run, but gsd-core/workflows/explore.md deliberately places it in a bootstrap-only block that DEFINES gsd_run without calling it -- its own comment explains why: declining the research offer must not leave Step 5's commit call unbootstrapped. Stripping empties that block of calls, so the preamble migrated forward and broke the define-before-use invariant tests/explore-command.test.cjs pins. Reproduced on a pristine origin/next checkout with the base snippet and base file, so this was not introduced here. The insertion target now honours a block that already carried the preamble, falling back to the first calling block for files that have none yet. Adds a behavioral regression test over a two-block fixture. Also updates three runtime-launcher-parity tests that pinned the removed PATH fallback to gsd-tools. Their intent is preserved -- the PATH stub is renamed gsd_run so it is reachable by the new resolver, and the RUNTIME_DIR-wins test still asserts the stub is never invoked. Fixture shebangs move to an absolute /bin/sh, because the fixture PATH is deliberately restricted and #!/usr/bin/env sh could not resolve. Refs #3146 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * chore(#3146): backfill changeset PR number Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs(#3146): document the FEATURES.md section-numbering practice The monotonically increasing section number in docs/FEATURES.md is the most frequent merge-conflict source in this repo, and it has TWO conflict cells, not one: the ### N. heading and the hand-maintained table of contents. Two PRs adding differently numbered features still collide on the TOC, so renumbering alone does not make a branch safe. This branch alone was renumbered 165 -> 166 -> 167 -> 168 across successive rebases. Adds a CONTRIBUTING section stating the practice: allocate the number last, never pre-emptively renumber, take max+1 after a rebase and update the TOC in the same commit, and never renumber someone else's section. Fork contributors are told explicitly they may leave the number to a maintainer at merge rather than chasing the counter. Agents are told to lease the allocation and to include the file in their published touched set. Records the durable fix as planned rather than pretending it exists: FEATURES.md should be generated from per-feature fragments the way CHANGELOG.md is generated from .changeset/, and the way tests/emitted-drift-acks/ works (#2914). Also renumbers this branch's own section to 168, leaving 167 to the PR already in flight. Refs #3146 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: sim <sim@local> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
12 KiB
12 KiB
Capture a forward-looking idea as a structured seed file with trigger conditions.
Seeds auto-surface during /gsd:new-milestone when trigger conditions match the
new milestone's scope.
After writing the file, search the codebase for relevant references:
Seeds beat deferred items because they:
- Preserve WHY the idea matters (not just WHAT)
- Define WHEN to surface (trigger conditions, not manual scanning)
- Track breadcrumbs (code references, related decisions)
- Auto-present at the right time via new-milestone scan
One-shot capture: the seed file is written immediately from the idea text alone. Trigger / Why / Scope are optional enrichment — they can be provided now or added later. The file is never gated behind questions.
Parse `$ARGUMENTS` for the idea summary.First, check for an enrich flag:
if echo "$ARGUMENTS" | grep -qE '\-\-enrich[[:space:]]+SEED-[0-9]+'; then
ENRICH_TARGET=$(echo "$ARGUMENTS" | grep -oE 'SEED-[0-9]+')
SEED_FILE=$(ls .planning/seeds/${ENRICH_TARGET}-*.md 2>/dev/null | head -1)
# Skip to enrich-seed step — do not prompt for $IDEA
else
if [ -n "$ARGUMENTS" ]; then
IDEA="$ARGUMENTS"
else
# Ask only when no arguments at all
# What's the idea? (one sentence)
IDEA="<user response>"
fi
fi
If $ENRICH_TARGET is set, skip straight to the enrich-seed step. Do not set $IDEA and do not run create-seed-dir, generate-seed-id, write-seed, collect-breadcrumbs, commit-seed, or confirm.
If $ARGUMENTS is non-empty and contains no --enrich flag, treat the full value as $IDEA (no prompt).
Only prompt for the idea when $ARGUMENTS is empty and no enrich target is present. Store the response as $IDEA.
Generate slug from idea summary.
Write `.planning/seeds/SEED-{PADDED}-{slug}.md` immediately with sensible defaults:trigger_when: default is"when relevant"— the seed will surface during any new-milestone scan; the user can narrow it later via--enrichscope: default is"unknown"— the user can update it via--enrich
---
id: SEED-{PADDED}
status: dormant
planted: {ISO date}
planted_during: {current milestone/phase from STATE.md, or "unknown" if not in a GSD project}
trigger_when: when relevant
scope: unknown
---
# SEED-{PADDED}: {$IDEA}
## Why This Matters
_To be filled in. Run `/gsd:capture --seed --enrich SEED-{PADDED}` to add context._
## When to Surface
**Trigger:** when relevant
This seed will surface during `/gsd:new-milestone` when the milestone scope matches.
## Scope Estimate
**Unknown** — run `/gsd:capture --seed --enrich SEED-{PADDED}` to estimate effort.
## Breadcrumbs
_No breadcrumbs collected yet._
## Notes
_Captured via one-shot seed capture. Enrich with trigger, why, and scope at your convenience._
Extract one or two key terms from $IDEA (the most distinctive noun or phrase) and store as $KEYWORD.
# Derive a single keyword for breadcrumb search.
# Lower-case, strip punctuation, take the first token longer than 2 chars.
KEYWORD=$(printf '%s' "$IDEA" \
| tr '[:upper:]' '[:lower:]' \
| tr -cs 'a-z0-9' '\n' \
| awk 'length > 2 {print; exit}')
KEYWORD="${KEYWORD:-seed}" # fallback to literal "seed" if extraction yields nothing
# Find files related to the idea keywords ($KEYWORD derived from $IDEA)
grep -rl "$KEYWORD" --include="*.ts" --include="*.js" --include="*.md" . 2>/dev/null | head -10
Also check:
- Current STATE.md for related decisions
- ROADMAP.md for related phases
- todos/ for related captured ideas
If any breadcrumbs are found, update the Breadcrumbs section of the seed file.
Store relevant file paths as $BREADCRUMBS.
If response_language is set: All user-facing questions, prompts, and explanations in this workflow MUST be presented in {response_language}. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
"{$IDEA}" File: .planning/seeds/SEED-{PADDED}-{slug}.md
Trigger and scope are set to defaults. Run /gsd:capture --seed --enrich SEED-{PADDED}
to add trigger conditions, rationale, and scope estimate at your convenience.
This seed will surface automatically when you run /gsd:new-milestone.
</step>
<step name="enrich-seed">
**Optional enrichment — only run this step when `--enrich` flag is present.**
If `--enrich` flag is in `$ARGUMENTS`:
- `$ENRICH_TARGET` and `$SEED_FILE` are already set by `parse-idea`. Derive `$SEED_ID` from `$ENRICH_TARGET` (e.g. `SEED_ID="$ENRICH_TARGET"`). If `$SEED_FILE` is empty, fall back to the most-recently modified file in `.planning/seeds/` and set `$SEED_ID` from its filename.
- Ask focused questions to build a complete seed:
**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
```text
AskUserQuestion(
header: "Trigger",
question: "When should this idea surface? (e.g., 'when we add user accounts', 'next major version', 'when performance becomes a priority')",
options: [] // freeform
)
Store as $TRIGGER.
AskUserQuestion(
header: "Why",
question: "Why does this matter? What problem does it solve or what opportunity does it create?",
options: []
)
Store as $WHY.
AskUserQuestion(
header: "Scope",
question: "How big is this? (rough estimate)",
options: [
{ label: "Small", description: "A few hours — could be a quick task" },
{ label: "Medium", description: "A phase or two — needs planning" },
{ label: "Large", description: "A full milestone — significant effort" }
]
)
Store as $SCOPE.
Update the seed file's frontmatter and sections with the gathered values:
- Set
trigger_when: {$TRIGGER} - Set
scope: {$SCOPE} - Fill in
## Why This Matterswith{$WHY} - Fill in
## When to Surfacetrigger detail - Fill in
## Scope Estimateelaboration
Commit the update:
gsd_run query commit "docs: enrich seed ${SEED_ID} — trigger + why + scope" --files "$SEED_FILE"
Confirm:
✅ Seed enriched: ${SEED_ID}
Trigger: {$TRIGGER}
Scope: {$SCOPE}
<success_criteria>
- Seed file created in .planning/seeds/ in one step, no questions required
- Frontmatter includes status, trigger_when (default: "when relevant"), scope (default: "unknown")
- File is written BEFORE any optional enrichment questions are asked
- Committed to git
- User shown confirmation with file path
- Optional --enrich path available for adding trigger, why, scope post-capture </success_criteria>