fix(#2767): pass paths via --files to gsd-sdk query commit + lint guard

[trek-e]

TL;DR

Every gsd-sdk query commit callsite that passed paths positionally was broken — paths were spliced into the commit subject and the SDK silently fell back to staging .planning/ wholesale. Fixed all 81 sites and added a permanent lint test.

What

• Inserted --files before the path list at 81 invocations across 50 files — workflows, agents, commands, references, and zh-CN docs.
• Added tests/bug-2767-gsd-sdk-commit-files-flag.test.cjs: scans every shipped .md file under agents/, commands/, get-shit-done/, docs/, scripts/ and asserts each gsd-sdk query commit[-to-subrepo] invocation either uses --files or has no path arguments.

Why

sdk/src/query/commit.ts parses argv as: everything before --files is the commit message, everything after is paths. Without --files:

1. Positional path tokens are joined into the commit subject (commit.ts:109-110).
2. The handler defaults filesToStage to ['.planning/'] (commit.ts:136), staging every untracked planning artifact instead of the targeted set.

The triage on #2767 identified 5 sites in discuss-phase.md and plan-phase.md; the actual blast radius was the entire workflow surface — every commit step except plan-phase.md:1422 (the one site already using --files, which was the discovery vector). This is a regression of #733 / #798 that crept back in via the #2122 "normalization" sweep, which standardized on the wrong form.

How

• Mechanical insertion of --files after the message token, before the first positional path. Trailing flags (--amend, --force, --no-verify) preserved at the tail.
• Multi-line continuations (\\) preserved and reformatted: message on its own line, --files on its own line, paths follow.
• Lint test parses each .md file, joins shell line continuations, tokenizes args with quote-aware splitting, and flags any non-flag token after the message when --files is absent.

Test plan

• node --test tests/bug-2767-gsd-sdk-commit-files-flag.test.cjs — passes (was RED before fix; 81 broken sites reported with file/line/cmd).
• npm test — full suite passes (5676 tests, 0 failures).
• Spot-checked rewrites in discuss-phase.md, plan-phase.md, gsd-executor.md, gsd-code-fixer.md (multi-line continuation), gsd-planner.md.

Knock-on audit

Audited every other gsd-sdk query <subcommand> invocation for the same positional-vs-flag drift. commit-to-subrepo already enforces --files at runtime (commit.ts:258) and is now also covered by the lint. No other subcommand exhibits the pattern — they take typed positional args (phase numbers, paths-as-first-arg) where the SDK explicitly distinguishes them from flags.

Closes #2767

Summary by CodeRabbit

• Documentation

  • Updated command examples across agent workflows, command documentation, and reference guides to use the --files flag when specifying target files for commit operations, replacing positional argument usage.

• Tests

  • Added validation test to ensure gsd-sdk query commit invocations in documentation properly use the --files flag for file argument specification.

[coderabbitai]

Warning

Rate limit exceeded

@trek-e has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 5 minutes and 36 seconds before requesting another review.

To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 6113e753-e043-4a81-b26a-5540ac4968e4

📥 Commits

Reviewing files that changed from the base of the PR and between 1eb67b7 and 7eea30f.

📒 Files selected for processing (3)

• docs/zh-CN/references/git-planning-commit.md
• get-shit-done/references/git-planning-commit.md
• tests/bug-2767-gsd-sdk-commit-files-flag.test.cjs

📝 Walkthrough

Walkthrough

This PR systematically updates all gsd-sdk query commit invocations across documentation, agent instructions, and workflows to pass file paths via an explicit --files flag instead of as positional arguments, fixing a regression where positional paths were incorrectly merged into commit messages and caused the SDK to stage entire .planning/ trees rather than specific files. A lint-style test is added to enforce this pattern going forward.

Changes

Cohort / File(s)	Summary
Agent instructions agents/gsd-code-fixer.md, agents/gsd-debugger.md, agents/gsd-executor.md, agents/gsd-phase-researcher.md, agents/gsd-planner.md, agents/gsd-research-synthesizer.md, agents/gsd-ui-researcher.md	Updated 7 agent instruction files to pass target markdown paths via --files flag instead of positional arguments in gsd-sdk query commit invocations.
Command documentation commands/gsd/add-backlog.md, commands/gsd/review-backlog.md, commands/gsd/thread.md	Updated 3 command documentation files to use --files flag for commit file paths, including handling multi-file scenarios in thread workflows.
Reference documentation (Chinese) docs/zh-CN/references/git-integration.md, docs/zh-CN/references/git-planning-commit.md, docs/zh-CN/references/planning-config.md	Updated 3 Chinese reference docs to change gsd-sdk query commit from positional to --files flag syntax for .planning/ directory and specific plan metadata files.
Reference documentation get-shit-done/references/autonomous-smart-discuss.md, get-shit-done/references/git-integration.md, get-shit-done/references/git-planning-commit.md, get-shit-done/references/planner-revision.md, get-shit-done/references/planning-config.md	Updated 5 reference documentation files to use --files flag for various commit scenarios including initialization, plan completion, and state management.
Workflow files (Part 1) get-shit-done/workflows/add-todo.md, get-shit-done/workflows/autonomous.md, get-shit-done/workflows/check-todos.md, get-shit-done/workflows/cleanup.md, get-shit-done/workflows/complete-milestone.md, get-shit-done/workflows/diagnose-issues.md, get-shit-done/workflows/discuss-phase-assumptions.md, get-shit-done/workflows/discuss-phase.md	Updated 8 workflow files to switch commit invocations to --files flag form, addressing the primary regression points identified in issue #2767.
Workflow files (Part 2) get-shit-done/workflows/execute-phase.md, get-shit-done/workflows/execute-plan.md, get-shit-done/workflows/explore.md, get-shit-done/workflows/import.md, get-shit-done/workflows/ingest-docs.md, get-shit-done/workflows/map-codebase.md, get-shit-done/workflows/milestone-summary.md, get-shit-done/workflows/new-milestone.md	Updated 8 workflow files with --files flag for artifact commits, including phase context, plan metadata, and documentation staging.
Workflow files (Part 3) get-shit-done/workflows/new-project.md, get-shit-done/workflows/pause-work.md, get-shit-done/workflows/plan-milestone-gaps.md, get-shit-done/workflows/plan-phase.md, get-shit-done/workflows/plant-seed.md, get-shit-done/workflows/quick.md, get-shit-done/workflows/remove-phase.md, get-shit-done/workflows/review.md	Updated 8 workflow files to use --files for diverse commit operations including phase creation, planning artifacts, and handoff files.
Workflow files (Part 4) get-shit-done/workflows/ship.md, get-shit-done/workflows/sketch-wrap-up.md, get-shit-done/workflows/sketch.md, get-shit-done/workflows/spike-wrap-up.md, get-shit-done/workflows/spike.md, get-shit-done/workflows/ui-phase.md, get-shit-done/workflows/ui-review.md, get-shit-done/workflows/verify-work.md	Updated 8 workflow files to route file paths through --files flag in commit commands for sketches, spikes, UI phases, and verification steps.
Test file tests/bug-2767-gsd-sdk-commit-files-flag.test.cjs	New lint-style test that scans 4 packaged directories for gsd-sdk query commit invocations, validates that each command includes --files or has no extra positional arguments beyond the message token, and reports violations with file locations and matched commands. Includes sanity check that at least one invocation was found.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

The changes are extensive in file count (50+) but highly homogeneous and repetitive — the same pattern (--files flag replacement) is applied consistently. Most edits are single-line command string modifications with predictable structure. The test file (185 lines) adds moderate complexity but is self-contained parsing/validation logic without branching logic. The consistency across changes and clear pattern reduce per-file cognitive load significantly.

Possibly related PRs

• feat(sdk): golden parity harness and query handler CJS alignment (#2302 Track A) #2341 — Implements --files-aware parsing in the SDK's commit and commit-to-subrepo handlers, complementing the workflow/documentation updates to use this flag.
• feat: /gsd-spec-phase — Socratic spec refinement with ambiguity scoring (#2213) #2322 — Modifies get-shit-done/workflows/discuss-phase.md to add SPEC-aware logic, sharing the same file modifications as this PR's commit invocation updates.
• fix(#2418,#2399,#2419,#2421): four workflow and installer bug fixes #2462 — Adds a new gsd-sdk query commit step in get-shit-done/workflows/plan-phase.md, overlapping with this PR's updates to the same file's commit invocations.

Suggested labels

bug, area: docs, needs-maintainer-review, size/L

Suggested reviewers

• glittercowboy

Poem

🐰 Files must march with flags in tow,
--files guides where they go,
No more paths that drift and sprawl,
The workflows commit clean and small,
Regression fixed with test to show! 📋✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main change: fixing 81 gsd-sdk query commit invocations to use the --files flag and adding a lint guard test for regression prevention.
Description check	✅ Passed	The description comprehensively covers TL;DR, what changed, why it matters, the implementation approach, and test validation, fully meeting the fix template requirements.
Linked Issues check	✅ Passed	The PR fixes all stated objectives from #2767: it updates all 81 affected workflow/markdown call-sites to use --files, prevents positional paths from corrupting commit messages, adds a permanent lint test covering all shipped markdown files, and closes the issue.
Out of Scope Changes check	✅ Passed	All changes are in-scope: 81 mechanical --files flag insertions across workflows/agents/commands/references/docs, and a lint test for regression prevention. No unrelated refactoring or scope creep detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/issue-2767-gsd-sdk-files-flag

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

get-shit-done/references/git-planning-commit.md (1)

7-13: ⚠️ Potential issue | 🟠 Major

Fix contradictory guidance in the same section.

Line 7 says not to use --files for commit, but Line 12 now uses --files (correctly). This contradiction will confuse users and can cause incorrect command usage. Please update the prose to match the examples.

✏️ Suggested doc fix

-Pass the message first, then file paths (positional). Do not use `--files` for `commit` (that flag is only for `commit-to-subrepo`).
+Pass the message first, then provide target paths after `--files`.
+Use `--files` whenever scoping `gsd-sdk query commit` to specific artifacts.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@get-shit-done/references/git-planning-commit.md` around lines 7 - 13, The
prose contradicts itself about using --files with the commit command; update the
text so it matches the example: state clearly that for commit you must pass the
message first and then positional file paths (do not use --files for commit
unless referring to commit-to-subrepo), and note that for .planning/ files the
recommended gsd-sdk query commit invocation is: gsd-sdk query commit
"docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
(explain this handles commit_docs and gitignore checks automatically); replace
the sentence on Line 7 with wording that instructs using positional files and
clarifies that --files is only for commit-to-subrepo, so the prose and the
example are consistent.

🧹 Nitpick comments (1)

tests/bug-2767-gsd-sdk-commit-files-flag.test.cjs (1)

109-109: --files position is not validated, so a misordered invocation slips through.

args.includes('--files') accepts the flag anywhere, including before the message (e.g. gsd-sdk query commit --files "subject"). Per the SDK at sdk/src/query/commit.ts:108-119, this would set endIndex = 0, leaving messageArgs empty and producing commit message required. The lint would still pass it as “well-formed”.

Low severity since this misordering is unlikely in hand-written workflow markdown, but the heuristic could be hardened to require --files to appear after at least one non-flag (message) token.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@tests/bug-2767-gsd-sdk-commit-files-flag.test.cjs` at line 109, The current
check "if (args.includes('--files')) return true;" accepts the flag in any
position; change it to require the "--files" flag appears after at least one
non-flag (message) token by computing const filesIdx = args.indexOf('--files')
and the index of the first non-flag token (e.g. first token where
!token.startsWith('-')), then return true only if filesIdx > -1 && filesIdx >
firstNonFlagIdx; update the test helper that contains the args array check to
use these indexes instead of args.includes('--files').

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/zh-CN/references/git-planning-commit.md`:
- Line 12: The sentence in the docs that claims the `commit` command should not
use `--files` is now contradictory with the examples; update the text in
docs/zh-CN/references/git-planning-commit.md so it matches the examples and
explicitly allow using `--files` with the `gsd-sdk query commit` invocation
(e.g., `gsd-sdk query commit "docs({scope}): {description}" --files
.planning/STATE.md .planning/ROADMAP.md`), replacing the old prohibition wording
with a short statement that `--files` is supported for targeting specific files.

In `@tests/bug-2767-gsd-sdk-commit-files-flag.test.cjs`:
- Around line 9-13: Update the test file docstring to match the actual behavior
of isWellFormed: remove the claim that message-only commits are "marked by `#
message-only`" and instead state that any `gsd-sdk query commit` invocation with
no positional path arguments is treated as message-only (i.e., the linter
accepts absent paths regardless of comments). Reference the isWellFormed
function in your commit message and docstring change so future contributors
understand the linting rule rather than assuming the nonexistent `#
message-only` marker is required.

---

Outside diff comments:
In `@get-shit-done/references/git-planning-commit.md`:
- Around line 7-13: The prose contradicts itself about using --files with the
commit command; update the text so it matches the example: state clearly that
for commit you must pass the message first and then positional file paths (do
not use --files for commit unless referring to commit-to-subrepo), and note that
for .planning/ files the recommended gsd-sdk query commit invocation is: gsd-sdk
query commit "docs({scope}): {description}" --files .planning/STATE.md
.planning/ROADMAP.md (explain this handles commit_docs and gitignore checks
automatically); replace the sentence on Line 7 with wording that instructs using
positional files and clarifies that --files is only for commit-to-subrepo, so
the prose and the example are consistent.

---

Nitpick comments:
In `@tests/bug-2767-gsd-sdk-commit-files-flag.test.cjs`:
- Line 109: The current check "if (args.includes('--files')) return true;"
accepts the flag in any position; change it to require the "--files" flag
appears after at least one non-flag (message) token by computing const filesIdx
= args.indexOf('--files') and the index of the first non-flag token (e.g. first
token where !token.startsWith('-')), then return true only if filesIdx > -1 &&
filesIdx > firstNonFlagIdx; update the test helper that contains the args array
check to use these indexes instead of args.includes('--files').

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 614c4dd1-1926-4653-93d2-182ea8d78c15

📥 Commits

Reviewing files that changed from the base of the PR and between dc9b712 and 1eb67b7.

📒 Files selected for processing (51)

• agents/gsd-code-fixer.md
• agents/gsd-debugger.md
• agents/gsd-executor.md
• agents/gsd-phase-researcher.md
• agents/gsd-planner.md
• agents/gsd-research-synthesizer.md
• agents/gsd-ui-researcher.md
• commands/gsd/add-backlog.md
• commands/gsd/review-backlog.md
• commands/gsd/thread.md
• docs/zh-CN/references/git-integration.md
• docs/zh-CN/references/git-planning-commit.md
• docs/zh-CN/references/planning-config.md
• get-shit-done/references/autonomous-smart-discuss.md
• get-shit-done/references/git-integration.md
• get-shit-done/references/git-planning-commit.md
• get-shit-done/references/planner-revision.md
• get-shit-done/references/planning-config.md
• get-shit-done/workflows/add-todo.md
• get-shit-done/workflows/autonomous.md
• get-shit-done/workflows/check-todos.md
• get-shit-done/workflows/cleanup.md
• get-shit-done/workflows/complete-milestone.md
• get-shit-done/workflows/diagnose-issues.md
• get-shit-done/workflows/discuss-phase-assumptions.md
• get-shit-done/workflows/discuss-phase.md
• get-shit-done/workflows/execute-phase.md
• get-shit-done/workflows/execute-plan.md
• get-shit-done/workflows/explore.md
• get-shit-done/workflows/import.md
• get-shit-done/workflows/ingest-docs.md
• get-shit-done/workflows/map-codebase.md
• get-shit-done/workflows/milestone-summary.md
• get-shit-done/workflows/new-milestone.md
• get-shit-done/workflows/new-project.md
• get-shit-done/workflows/pause-work.md
• get-shit-done/workflows/plan-milestone-gaps.md
• get-shit-done/workflows/plan-phase.md
• get-shit-done/workflows/plant-seed.md
• get-shit-done/workflows/quick.md
• get-shit-done/workflows/remove-phase.md
• get-shit-done/workflows/review.md
• get-shit-done/workflows/ship.md
• get-shit-done/workflows/sketch-wrap-up.md
• get-shit-done/workflows/sketch.md
• get-shit-done/workflows/spike-wrap-up.md
• get-shit-done/workflows/spike.md
• get-shit-done/workflows/ui-phase.md
• get-shit-done/workflows/ui-review.md
• get-shit-done/workflows/verify-work.md
• tests/bug-2767-gsd-sdk-commit-files-flag.test.cjs