Files

Tom Boucher debeabd524 enhance(#3587 ): add a per-phase commit_docs override (#3601 )

* 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>

2026-08-17 21:59:40 -04:00

1.8 KiB

Raw Blame History

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:

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:

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/)

1.8 KiB Raw Blame History