54e6da3126
* fix(#2767): pass paths via --files to gsd-sdk query commit + lint guard Workflows, agents, commands, and references passed file paths positionally to `gsd-sdk query commit`, which silently appended them to the commit subject and triggered the `.planning/` wholesale-stage fallback in sdk/src/query/commit.ts:136. Regression of #733/#798. Inserted `--files` before the path list at every site (81 invocations across 50 files). Added tests/bug-2767-gsd-sdk-commit-files-flag.test.cjs as a permanent lint that scans every shipped .md file and asserts each `gsd-sdk query commit[-to-subrepo]` invocation either uses `--files` or carries no path arguments. Closes #2767 * test(#2767): replace source-grep with behavioral SDK test The original test walked every shipped .md file and regex-tokenized `gsd-sdk query commit` invocations to assert `--files` was present. CONTRIBUTING.md prohibits this source-grep pattern. Rewrite as behavioral SDK tests against `sdk/dist/cli.js` over a real tmp git project (createTempGitProject helper). Cover both the well-formed (`--files <paths>`) form — clean subject, exactly-staged files, .planning/ left untouched — and the buggy positional form, asserting the documented misbehavior (paths leak into subject + the `.planning/` wholesale-stage fallback at commit.ts:136). Also asserts `commit-to-subrepo` rejects when `--files` is omitted (commit.ts:258). The doc-lint is retained as a supplementary defense-in-depth guard since agent-prompt markdown invocations cannot be exercised end-to-end — but it is no longer the primary contract. * docs(#2767): correct contradictory --files guidance in zh-CN/en docs + fix test docstring
88 lines
2.3 KiB
Markdown
88 lines
2.3 KiB
Markdown
# Revision Mode — Planner Reference
|
|
|
|
Triggered when orchestrator provides `<revision_context>` with checker issues. NOT starting fresh — making targeted updates to existing plans.
|
|
|
|
**Mindset:** Surgeon, not architect. Minimal changes for specific issues.
|
|
|
|
### Step 1: Load Existing Plans
|
|
|
|
```bash
|
|
cat .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
|
|
```
|
|
|
|
Build mental model of current plan structure, existing tasks, must_haves.
|
|
|
|
### Step 2: Parse Checker Issues
|
|
|
|
Issues come in structured format:
|
|
|
|
```yaml
|
|
issues:
|
|
- plan: "16-01"
|
|
dimension: "task_completeness"
|
|
severity: "blocker"
|
|
description: "Task 2 missing <verify> element"
|
|
fix_hint: "Add verification command for build output"
|
|
```
|
|
|
|
Group by plan, dimension, severity.
|
|
|
|
### Step 3: Revision Strategy
|
|
|
|
| Dimension | Strategy |
|
|
|-----------|----------|
|
|
| requirement_coverage | Add task(s) for missing requirement |
|
|
| task_completeness | Add missing elements to existing task |
|
|
| dependency_correctness | Fix depends_on, recompute waves |
|
|
| key_links_planned | Add wiring task or update action |
|
|
| scope_sanity | Split into multiple plans |
|
|
| must_haves_derivation | Derive and add must_haves to frontmatter |
|
|
|
|
### Step 4: Make Targeted Updates
|
|
|
|
**DO:** Edit specific flagged sections, preserve working parts, update waves if dependencies change.
|
|
|
|
**DO NOT:** Rewrite entire plans for minor issues, add unnecessary tasks, break existing working plans.
|
|
|
|
### Step 5: Validate Changes
|
|
|
|
- [ ] All flagged issues addressed
|
|
- [ ] No new issues introduced
|
|
- [ ] Wave numbers still valid
|
|
- [ ] Dependencies still correct
|
|
- [ ] Files on disk updated
|
|
|
|
### Step 6: Commit
|
|
|
|
```bash
|
|
gsd-sdk query commit "fix($PHASE): revise plans based on checker feedback" --files .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
|
|
```
|
|
|
|
### Step 7: Return Revision Summary
|
|
|
|
```markdown
|
|
## REVISION COMPLETE
|
|
|
|
**Issues addressed:** {N}/{M}
|
|
|
|
### Changes Made
|
|
|
|
| Plan | Change | Issue Addressed |
|
|
|------|--------|-----------------|
|
|
| 16-01 | Added <verify> to Task 2 | task_completeness |
|
|
| 16-02 | Added logout task | requirement_coverage (AUTH-02) |
|
|
|
|
### Files Updated
|
|
|
|
- .planning/phases/16-xxx/16-01-PLAN.md
|
|
- .planning/phases/16-xxx/16-02-PLAN.md
|
|
|
|
{If any issues NOT addressed:}
|
|
|
|
### Unaddressed Issues
|
|
|
|
| Issue | Reason |
|
|
|-------|--------|
|
|
| {issue} | {why - needs user input, architectural change, etc.} |
|
|
```
|