* fix(#2969): deterministic Step 5 verification gate for /gsd-reapply-patches
The prior Step 5 "Hunk Verification Gate" was prescribed correctly in the
workflow text — but executed laxly by the LLM, which filled in `verified: yes`
without actually checking content presence. The reporter observed three
distinct files (skills/gsd-discuss-phase/SKILL.md, skills/gsd-autonomous/
SKILL.md, get-shit-done/workflows/new-project.md) where archives contained
substantive user-added blocks that did not survive into the merged result, yet
the gate reported clean.
Move verification from LLM-driven prose into a deterministic Node script the
workflow calls. The script can't be shortcut.
Changes:
- scripts/verify-reapply-patches.cjs (new): pure Node, no external deps.
For each file in the patches dir, computes user-added significant lines as
the line-set diff between backup and pristine baseline (when available;
falls back to "every significant backup line" when no pristine — over-broad
but the safe direction for this bug class). Asserts each line appears
literally in the merged installed file via String.prototype.includes.
Filters trivial lines (length < 12 chars, pure punctuation, decorative
comments) so harmless drift doesn't trigger false failures. Exits 0 on
pass, 1 on any miss with per-file diagnostic, 2 on usage error.
Supports --json for workflow consumption.
- get-shit-done/workflows/reapply-patches.md: rewrite Step 5 to call the
script and parse its JSON output. The Step 4 Hunk Verification Table
remains as advisory Claude-readable summary, but the gate is now the
script's exit code.
- tests/bug-2969-verify-reapply-patches.test.cjs (new): 6 tests covering
(a) pass when every line survives, (b) fail when a line is missing,
(c) fail when the merged file is deleted entirely, (d) --json structured
report shape, (e) backup-meta.json is correctly skipped as metadata,
(f) no-pristine-dir fallback exercises the safe over-broad path. All pass.
Out of scope: the manifest-baseline tightening described in #2969 Failure 1
(saveLocalPatches comparing against the wrong baseline so prior silent wipes
poison subsequent updates). That's a separate, bigger architectural change
involving pristine-content infrastructure; this PR addresses the gate fidelity
half so users at least see the diagnostic when content goes missing.
Closes#2969 (partial — Failure 2 only)
* fix(#2969): preserve #1999 Hunk Verification Table assertions alongside new script gate
CI failure on PR #2972 surfaced that tests/reapply-patches.test.cjs (the
#1999 contract) asserts Step 5 references:
- "Hunk Verification Table"
- `verified: no` failure condition
- explicit STOP/halt/abort directive
- "table absent / missing" halt path
My initial Step 5 rewrite for #2969 substituted the deterministic script
for the table-based gate entirely, stripping those references. The script
is the strictly stronger gate, but the existing #1999 test enforces the
table-based safety net as a defense-in-depth contract.
Restore both gates as a layered Step 5:
- 5a (binding): deterministic verifier script — script gate, exits
non-zero on any miss, cannot be shortcut by the LLM
- 5b (advisory): Hunk Verification Table review — preserved as
redundant safety net for the case where the script has a bug or the
pristine baseline is unavailable
Both gates must pass. Verified: tests/reapply-patches.test.cjs (5 tests
in the #1999 suite) and tests/bug-2969-verify-reapply-patches.test.cjs
(6 tests in the #2969 suite) all pass — 21/21 total in this fixture.
* fix(#2969): address CodeRabbit findings on workflow + script
Five CR findings on PR #2972, all valid; addressed in this commit:
1. (Major) Stderr was merged into VERIFY_OUTPUT via `2>&1`, so any Node
warning, deprecation notice, or stack trace would corrupt the JSON
parse downstream. Capture stdout only; stderr remains on the
controlling terminal for operator visibility.
2. (Major) verifyFile() crashed with EISDIR/EACCES instead of producing
a structured diagnostic when the installed path was a directory or
unreadable. Wrap statSync/readFileSync in try/catch and emit a
per-file fail row; the whole-run gate continues with structured
output. Added test case asserting the directory-at-installed-path
case fails with `not a regular file` diagnostic instead of crashing.
3. (Minor) PRISTINE_FLAG built as a single string + unquoted expansion
would split paths with spaces. Switched to a bash array (VERIFY_ARGS)
that preserves whitespace through expansion.
4. (Minor) Fenced code block missing language tag (markdownlint MD040).
Added `text` tag to the error message block.
5. (Minor) Usage comment said pristine fallback was "backup-meta lookup"
but the actual code path falls back to significant-line checks from
backup content. Corrected the comment to match implementation.
Verified all 21 tests in tests/reapply-patches.test.cjs (#1999 contract)
+ tests/bug-2969-verify-reapply-patches.test.cjs (now 7 tests with the
new directory case) pass.
* test(#2969): structured JSON assertions, no substring matching on script output
Replace every assert.match(r.stdout, /pattern/) call with structured
assertions on the parsed JSON report from the script's own --json mode.
The script's --json contract IS the structured shape we test against —
the test author should never depend on the human-readable formatter
output, just as no test should depend on substring presence in source.
Changes:
- All 7 tests now run the verifier with --json (via a runVerifier()
helper) and parse the resulting JSON document into { status, report,
stderr }. Diagnostic stderr is preserved as a separate channel for
debug output but is not used for assertions.
- Each previously substring-matched diagnostic ("Failures: 1",
"not a regular file", "installed file missing after merge",
file path, dropped line) is now a deepEqual / equal / Array.includes
against typed report fields: report.failures, report.results[i].status,
report.results[i].reason, report.results[i].file,
report.results[i].missing[].
- Added an explicit "documented shape" test asserting the JSON output
has exactly the keys { file, missing, reason, status } per result —
locks the public contract of the --json mode.
- DRY'd up fixture reset into a resetFixture() helper since every test
starts with a fresh patches/installed/pristine triple.
Linter: scripts/lint-no-source-grep.cjs reports 0 violations across 348
test files. Combined run of bug-2969-...test.cjs (7 tests) +
reapply-patches.test.cjs (5 tests in the #1999 suite) all pass —
22/22 in the relevant fixture.
* fix(#2969): typed REASON enum + raw-text-matching rule shipped repo-wide
This commit closes the loop on the no-source-grep discipline:
1. scripts/verify-reapply-patches.cjs:
- Frozen REASON enum exposes the diagnostic surface as stable codes:
OK_NO_USER_LINES_VS_PRISTINE, OK_NO_SIGNIFICANT_BACKUP_LINES,
FAIL_INSTALLED_MISSING, FAIL_INSTALLED_NOT_REGULAR_FILE,
FAIL_READ_ERROR, FAIL_USER_LINES_MISSING.
- Each result.reason is now a code from this enum, not free text.
Tests assert via REASON.X equality, not regex on prose.
- REASON exported from module.exports.
2. tests/bug-2969-verify-reapply-patches.test.cjs:
- Full rewrite. Every assertion on typed structured fields:
report.results[0].status === 'fail',
report.results[0].reason === REASON.FAIL_INSTALLED_NOT_REGULAR_FILE,
report.results[0].missing.includes(droppedLine) (Array set membership,
not String substring).
- Locks the REASON enum surface via Object.keys(REASON).sort() deepEqual.
- Locks the JSON report shape via Object.keys(report).sort() deepEqual.
- Zero regex, zero String#includes, zero startsWith/endsWith on text.
3. CONTRIBUTING.md:
- New section "Prohibited: Raw Text Matching on Test Outputs" with
concrete BAD/GOOD examples (substring on file content; assert.match
on stdout; "structured parser" hiding string ops; regex on free-form
reason fields).
- The rule statement: "Tests assert on typed structured values. If
the code under test produces text, the code under test must also
expose a structured intermediate representation, and the test must
assert on that IR — never on the rendered text."
- Required structured-surface table: file IR, --json mode, frozen
enum, fs facts.
- "Hiding grep behind a function is still grep" callout — the
parser-wrapper anti-pattern.
- New `pre-existing-text-matching` exemption category for the 8
grandfathered files. Marked Transitional; new tests cannot use it.
4. scripts/lint-no-source-grep.cjs:
- Three new patterns enforced (in addition to the existing .cjs-source
readFileSync rule):
- assert.match/doesNotMatch on .stdout/.stderr
- .stdout/.stderr.<includes|startsWith|endsWith>(
- readFileSync(...).<includes|startsWith|endsWith>(
- Aggregated violations per file (multiple findings now report together).
- Updated diagnostic message references both CONTRIBUTING.md sections.
5. 8 pre-existing tests annotated with `// allow-test-rule:
pre-existing-text-matching` so the lint passes on this commit; each
carries the prose "Tracked for migration to typed-IR assertions; do
not copy this pattern." Files: bug-2649, bug-2687, bug-2796, bug-2838,
bug-2943, graphify, hooks-opt-in, security-scan.
Verification: lint 0 violations across 348 test files; full suite passes.
* fix(#2969): rename exemption category to pending-migration-to-typed-ir + cite tracking issue
Per maintainer feedback:
1. "Grandfathered" / "legacy" framing is wrong — both terms imply
permanent or condoned exemption. The 8 files are tracked for
correction, not exempted.
2. Each annotated file must cite the tracking issue so the migration
work is auditable.
Changes:
- CONTRIBUTING.md: rename exemption category from
`pre-existing-text-matching` to `pending-migration-to-typed-ir`. Update
prose to "Tracked for correction, not exempted" and require each
annotation to cite the open migration issue (e.g.
`// allow-test-rule: pending-migration-to-typed-ir [#NNNN]`).
- 8 test files: update annotation to cite #2974 (the tracking issue
opened for migrating these files to typed-IR assertions).
* docs(test-standards): enforce no-source-grep rule with CI linter + update CONTRIBUTING.md
Adds scripts/lint-no-source-grep.cjs — a static linter that detects readFileSync
on .cjs source files in tests without an allow-test-rule annotation. Wires it
into CI as a new lint-tests job in test.yml and as npm run lint:tests.
Resolves all 9 existing violations across the test suite:
- Rewrites workspace routing tests (3) as behavioral runGsdTools calls that
verify each command is router-recognized (exit != "Unknown init workflow")
- Adds allow-test-rule annotations with explanatory comments to 7 legitimate
structural tests: architectural invariants (locking, orphan-worktree),
structural regression guards (milestone-regex-global), docs-parity
(config-field-docs), integration-test-input (copilot-install), and
structural-implementation-guards (bug-1891, discuss-mode)
Updates CONTRIBUTING.md Testing Standards section with:
- "Prohibited: Source-Grep Tests" section with the before/after pattern,
root cause analysis of why it breaks (commit 990c3e64), and CI reference
- allow-test-rule exemption table (6 recognized categories with when-to-use)
- "CI Test Quality Checks" table showing lint-tests job and local run command
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix: resolve CodeRabbit findings on PR #2700
- CONTRIBUTING.md: "four recognized categories" → "six" (table has 6 rows)
- workspace.test.cjs: use positional args in routing tests (no --name flag)
- lint-no-source-grep.cjs: add source-dir guard to READ_WITH_INLINE_CJS_RE
(mirrors CJS_PATH_CONST_RE's protection against false positives on temp files)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(lint): tighten allow-test-rule and add recursive test discovery
- ALLOW_ANNOTATION now requires at least one non-whitespace char after the
colon so bare '// allow-test-rule:' cannot bypass the lint gate
- findTestFiles() recurses into subdirectories so nested *.test.cjs files
are covered if the tests/ tree ever grows subdirs
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* refactor(workflows): extract discuss-phase modes/templates/advisor for progressive disclosure (closes#2551)
Splits 1,347-line workflows/discuss-phase.md into a 495-line dispatcher plus
per-mode files in workflows/discuss-phase/modes/ and templates in
workflows/discuss-phase/templates/. Mirrors the progressive-disclosure
pattern that #2361 enforced for agents.
- Per-mode files: power, all, auto, chain, text, batch, analyze, default, advisor
- Templates lazy-loaded at the step that produces the artifact (CONTEXT.md
template at write_context, DISCUSSION-LOG.md template at git_commit,
checkpoint.json schema when checkpointing)
- Advisor mode gated behind `[ -f $HOME/.claude/get-shit-done/USER-PROFILE.md ]`
— inverse of #2174's --advisor flag (don't pay the cost when unused)
- scout_codebase phase-type→map selection table extracted to
references/scout-codebase.md
- New tests/workflow-size-budget.test.cjs enforces tiered budgets across
all workflows/*.md (XL=1700 / LARGE=1500 / DEFAULT=1000) plus the
explicit <500 ceiling for discuss-phase.md per #2551
- Existing tests updated to read from the new file locations after the
split (functional equivalence preserved — content moved, not removed)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(#2607): align modes/auto.md check_existing with parent (Update it, not Skip)
CodeRabbit flagged drift between the parent step (which auto-selects "Update
it") and modes/auto.md (which documented "Skip"). The pre-refactor file had
both — line 182 said "Skip" in the overview, line 250 said "Update it" in the
actual step. The step is authoritative. Fix the new mode file to match.
Refs: PR #2607 review comment 3127783430
* test(#2607): harden discuss-phase regression tests after #2551 split
CodeRabbit identified four test smells where the split weakened coverage:
- workflow-size-budget: assertion was unreachable (entered if-block on match,
then asserted occurrences === 0 — always failed). Now unconditional.
- bug-2549-2550-2552: bounded-read assertion checked concatenated source, so
src.includes('3') was satisfied by unrelated content in scout-codebase.md
(e.g., "3-5 most relevant files"). Now reads parent only with a stricter
regex. Also asserts SCOUT_REF exists.
- chain-flag-plan-phase: filter(existsSync) silently skipped a missing
modes/chain.md. Now fails loudly via explicit asserts.
- discuss-checkpoint: same silent-filter pattern across three sources. Now
asserts each required path before reading.
Refs: PR #2607 review comments 3127783457, 3127783452, plus nitpicks for
chain-flag-plan-phase.test.cjs:21-24 and discuss-checkpoint.test.cjs:22-27
* docs(#2607): fix INVENTORY count, context.md placeholders, scout grep portability
- INVENTORY.md: subdirectory note said "50 top-level references" but the
section header now says 51. Updated to 51.
- templates/context.md: footer hardcoded XX-name instead of declared
placeholders [X]/[Name], which would leak sample text into generated
CONTEXT.md files. Now uses the declared placeholders.
- references/scout-codebase.md: no-maps fallback used grep -rl with
"\\|" alternation (GNU grep only — silent on BSD/macOS grep). Switched
to grep -rlE with extended regex for portability.
Refs: PR #2607 review comments 3127783404, 3127783448, plus nitpick for
scout-codebase.md:32-40
* docs(#2607): label fenced examples + clarify overlay/advisor precedence
- analyze.md / text.md / default.md: add language tags (markdown/text) to
fenced example blocks to silence markdownlint MD040 warnings flagged by
CodeRabbit (one fence in analyze.md, two in text.md, five in default.md).
- discuss-phase.md: document overlay stacking rules in discuss_areas — fixed
outer→inner order --analyze → --batch → --text, with a pointer to each
overlay file for mode-specific precedence.
- advisor.md: add tie-breaker rules for NON_TECHNICAL_OWNER signals — explicit
technical_background overrides inferred signals; otherwise OR-aggregate;
contradictory explanation_depth values resolve by most-recent-wins.
Refs: PR #2607 review comments 3127783415, 3127783437, plus nitpicks for
default.md:24, discuss-phase.md:345-365, and advisor.md:51-56
* fix(#2607): extract codebase_drift_gate body to keep execute-phase under XL budget
PR #2605 added 80 lines to execute-phase.md (1622 -> 1702), pushing it over
the XL_BUDGET=1700 line cap enforced by tests/workflow-size-budget.test.cjs
(introduced by this PR). Per the test's own remediation hint and #2551's
progressive-disclosure pattern, extract the codebase_drift_gate step body to
get-shit-done/workflows/execute-phase/steps/codebase-drift-gate.md and leave
a brief pointer in the workflow. execute-phase.md is now 1633 lines.
Budget is NOT relaxed; the offending workflow is tightened.
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Documents that only agents/ at the repo root is tracked by git.
.claude/agents/, .cursor/agents/, and .github/agents/ are gitignored
install-sync outputs and must not be edited — they will be overwritten.
Closes#2365
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Node 22 is still in Active LTS until October 2026 and Maintenance LTS
until April 2027. Raising the engines floor to >=24.0.0 unnecessarily
locked out a fully-supported LTS version and produced EBADENGINE
warnings on install. Restore Node 22 support, add Node 22 to the CI
matrix, and update CONTRIBUTING.md to match.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Node 20 reached EOL April 30 2026. Node 22 is no longer the LTS
baseline — Node 24 is the current Active LTS. Update CI matrix to
run only Node 24, raise engines floor to >=24.0.0, and update
CONTRIBUTING.md node compatibility table accordingly.
Fixes#1847
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add close-draft-prs.yml workflow that auto-closes draft PRs with
explanatory comment directing contributors to submit completed PRs
- Update CONTRIBUTING.md with "No draft PRs" policy
- Update default PR template with draft PR warning
Closes#1762
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Overhaul CONTRIBUTING.md and all GitHub issue/PR templates to enforce a
structured, approval-gated contribution process that cuts down on drive-by
feature submissions.
Changes:
- CONTRIBUTING.md: add Types of Contributions section defining Fix,
Enhancement, and Feature with escalating requirements and explicit
rejection criteria; add Issue-First Rule section making clear that
enhancements require approved-enhancement and features require
approved-feature label before any code is written; backport gsd-2
testing standards (t.after() per-test cleanup, array join() fixture
pattern, Node 24 as primary CI target, test requirements by change type,
reviewer standards)
- .github/ISSUE_TEMPLATE/enhancement.yml: new template requiring current
vs. proposed behavior, reason/benefit narrative, full scope of changes,
and breaking changes assessment; cannot be clicked through
- .github/ISSUE_TEMPLATE/feature_request.yml: full rewrite requiring solo-
developer problem statement, what is being added, full file-level scope,
user stories, acceptance criteria, maintenance burden assessment, and
alternatives considered; incomplete specs are closed, not revised
- .github/pull_request_template.md: converted from general template to a
routing page directing contributors to the correct typed template;
using the default template for a feature or enhancement is a rejection
reason
- .github/PULL_REQUEST_TEMPLATE/fix.md: new typed template requiring
confirmed-bug label on linked issue and regression test confirmation
- .github/PULL_REQUEST_TEMPLATE/enhancement.md: new typed template with
hard gate on approved-enhancement label and scope confirmation section
- .github/PULL_REQUEST_TEMPLATE/feature.md: new typed template requiring
file inventory, spec compliance checklist from the issue, and scope
confirmation that nothing beyond the approved spec was added
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
- PR template: move "Closes #" to top as required field with explicit
warning that PRs without a linked issue are closed without review
- CONTRIBUTING.md: add mandatory issue-first policy with clear rationale
- Add require-issue-link.yml workflow: checks PR body for a closing
keyword (Closes/Fixes/Resolves #NNN) on open/edit/reopen/sync events;
posts a comment and fails CI if no reference is found
PR body is bound to an env var before shell use (injection-safe).
The github-script step uses the API SDK, not shell interpolation.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Test suite modernization:
- Converted all try/finally cleanup patterns to beforeEach/afterEach hooks
across 11 test files (core, copilot-install, config, workstream,
milestone-summary, forensics, state, antigravity, profile-pipeline,
workspace)
- Consolidated 40 inline mkdtempSync calls to use centralized helpers
- Added createTempDir() helper for bare temp directories
- Added optional prefix parameter to createTempProject/createTempGitProject
- Fixed config test HOME sandboxing (was reading global defaults.json)
New CONTRIBUTING.md:
- Test standards: hooks over try/finally, centralized helpers, HOME sandboxing
- Node 22/24 compatibility requirements with Node 26 forward-compat
- Code style, PR guidelines, security practices
- File structure overview
All 1382 tests pass, 0 failures.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add GitHub Actions CI for cross-platform testing (ubuntu/windows/macos × node 18/20/22)
- Add release workflow that auto-creates GitHub Releases and publishes to npm on tag push
- Add CONTRIBUTING.md with branching strategy (maintainers direct commit, contributors PR)
- Add MAINTAINERS.md with release workflows and recovery procedures
- Add PR template for contributors
Closes#221
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
