debeabd524
* feat(#3587): add a per-phase commit_docs override Delivers epic #2292's second user story: commit an architecture phase's artifacts while execution phases stay local. commit_docs was project-wide and binary, so the only choices were all phases or none. Shape is a config dynamic key phase_commit_docs.<phase-id>, following the 14 existing dynamicKeyPatterns precedents rather than inventing a PLAN.md frontmatter spec -- which #2292 itself flags as becoming its own maintenance surface. Tier 1 resolves in cmdCommit, NOT in loadConfig: loadConfig has no phase context and is called by nearly every command, so threading one through it to serve a single caller would be a far larger blast radius for no gain. The phase comes from detectPhaseNumberFromFiles, which cmdCommit already computes for branch naming and which is already hardened against the #2539 project-code bug. Suppression by the per-phase tier returns its own reason rather than reusing skipped_commit_docs_false -- telling a user their project setting is false when it is true would be actively misleading. Additive; the two existing reason strings that agents/gsd-executor.md matches on are unchanged. The manifest's phase-id pattern is a hand-copy of PHASE_NUMBER_TOKEN_SOURCE because the manifest is hand-maintained JSON, so a behavioral parity test asserts both surfaces accept and reject the same token shapes. * fix(#3587): fold tests, close review findings, update reference docs Fold: the new tests were added as their own file, which required loosening a grandfathered lint-test-file-count bucket 5-to-6. A ratchet exists to go down only. commit-docs-bypass.test.cjs is the established commit_docs test home and already hosts two folded suites, so the tests fold there as a third block and the allowlist is reverted untouched. Standards review: CONTEXT.md and the test header both cited a phase-commit-docs-manifest-parity.test.cjs that never existed; a repo-wide sweep found a fourth stale cite in the schema manifest description. All four now name the real location. Spec review: the issue's Scope of changes named planning-config.md and git-planning-commit.md and neither was touched. Both now document the four-tier precedence and the new skip reason. Security review, minor and unproven: detectPhaseNumberFromFiles returns the FIRST matching path's phase, so a --files list spanning two phases resolves the override against whichever comes first. That helper is hardened and widely used, so it is not changed; the behavior is pinned by a named test and disclosed in the design and user docs. A pinned behavior is not a bug; an unpinned surprise is. * chore(#3587): backfill changeset pr number to 3601 --------- Co-authored-by: sim <sim@local>
42 lines
1.8 KiB
Markdown
42 lines
1.8 KiB
Markdown
# Git Planning Commit
|
|
|
|
Commit planning artifacts via `gsd-tools query commit`, which checks `commit_docs` config and gitignore status (same behavior as legacy `gsd-tools.cjs commit`).
|
|
|
|
## Commit via CLI
|
|
|
|
Pass the message first, then file paths via `--files`. Both `commit` and `commit-to-subrepo` use `--files` to declare the paths to commit.
|
|
|
|
Always use this for `.planning/` files — it handles `commit_docs` and gitignore checks automatically:
|
|
|
|
```bash
|
|
gsd-tools query commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
|
|
```
|
|
|
|
The CLI will return `skipped` (with reason) if `commit_docs` is `false`, `.planning/` is gitignored, or a per-phase `phase_commit_docs.<phase-id>` override resolves `false` for the phase being committed. No manual conditional checks needed.
|
|
|
|
## Amend previous commit
|
|
|
|
To fold `.planning/` file changes into the previous commit:
|
|
|
|
```bash
|
|
gsd-tools query commit "" --files .planning/codebase/*.md --amend
|
|
```
|
|
|
|
## Commit Message Patterns
|
|
|
|
| Command | Scope | Example |
|
|
|---------|-------|---------|
|
|
| plan-phase | phase | `docs(phase-03): create authentication plans` |
|
|
| execute-phase | phase | `docs(phase-03): complete authentication phase` |
|
|
| new-milestone | milestone | `docs: start milestone v1.1` |
|
|
| remove-phase | chore | `chore: remove phase 17 (dashboard)` |
|
|
| insert-phase | phase | `docs: insert phase 16.1 (critical fix)` |
|
|
| add-phase | phase | `docs: add phase 07 (settings page)` |
|
|
|
|
## When to Skip
|
|
|
|
- `commit_docs: false` in config
|
|
- `.planning/` is gitignored
|
|
- `phase_commit_docs.<phase-id>` resolves `false` for the phase being committed — overrides the project-wide `commit_docs` for that phase only (reason `skipped_commit_docs_phase_false`)
|
|
- No changes to commit (check with `git status --porcelain .planning/`)
|