feat(#22): plan-vs-codebase drift guard (source-grounded reviewer + intel surface) (#487)

* feat(#22): add plan_review.source_grounding + _authority config keys

Two additive opt-out keys for the drift guard: source_grounding (bool,
default true) gates the source-grounded reviewer pass; _authority (enum
grep|intel|treesitter|lsp|scip, default grep) selects the resolver rung.
No existing default changed.

Refs #22

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(#22): add intel api-surface renderer + CLI subcommand

Renders .planning/intel/api-map.json into a human-readable API-SURFACE.md
for planner injection. Empty/missing map still writes a surface that
announces itself incomplete (absence = unknown, not 'does not exist').
Gated on intel.enabled like all intel functions.

Refs #22

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(#22): add source-grounding pass to plan-review-convergence

Default-on reviewer pass (plan_review.source_grounding) that enumerates
every symbol a plan cites, excludes declared new artifacts, resolves each
against source via the configured authority adapter, and records
three-valued verdicts. rung-0/1 MISSING is needs-acknowledgement, not a
hard block; UNCHECKABLE is logged in a REVIEWS.md coverage section.

Refs #22

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(#22): inject API-SURFACE.md into planner + require Artifacts section

When intel.enabled, plan-phase regenerates API-SURFACE.md and injects it
as a HINT (prefer, may be incomplete, absence = unknown), never a hard
rule. Every plan must now emit an 'Artifacts this phase produces' section
so the source-grounding reviewer can separate new symbols from references
to existing code.

Refs #22

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(#22): surface drift-guard in setup + settings, add docs

/gsd:new-project asks to enable plan_review.source_grounding (default Y);
/gsd:settings exposes the toggle and authority knob. Documents both config
keys in CONFIGURATION.md, the intel api-surface command in COMMANDS.md,
the drift guard in USER-GUIDE.md, and links ADR 22 from ARCHITECTURE.md.

Refs #22

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(#22): respect AskUserQuestion 4-option cap and plan-phase XL line budget

settings drift-guard toggle moved to its own 2-option question; #22
plan-phase additions condensed to bring the file back under the 1810-line
XL budget without dropping the intel gate, the incomplete-surface hint, or
the Artifacts-section requirement.

Refs #22

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(#22): use live slash-command forms in drift-guard docs

Doc-parity gate requires every slash-command token in docs/*.md to resolve
to a registered command. Corrected the command form(s) referenced in the
#22 drift-guard / api-surface documentation.

The unresolved token was /gsd-core, matched from the GitHub repo reference
"open-gsd/gsd-core#22" in docs/adr/22-plan-drift-guard.md. This is the
same pattern as the existing 'test-runner' exemption (open-gsd/gsd-test-runner).
Added 'core' to INTERNAL_COMPONENT_SLUGS with a matching explanatory comment.

Refs #22

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore(#22): add changeset fragment for drift guard (PR #487)

Refs #22

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: CI Rebase Check <ci@gsd-redux>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-05-30 17:08:11 -04:00
committed by GitHub
parent 7fd71226b2
commit 05cdec5f47
20 changed files with 870 additions and 7 deletions

View File

@@ -992,3 +992,108 @@ describe('config-path command (#2282)', () => {
assert.strictEqual(configContent.model_profile, 'quality', 'config-path should point to the file config-set wrote');
});
});
// ─── plan_review.source_grounding + _authority (#22) ─────────────────────────
describe('plan_review.source_grounding and plan_review.source_grounding_authority (#22)', () => {
let tmpDir;
beforeEach(() => {
tmpDir = createTempProject();
runGsdTools('config-ensure-section', tmpDir, { HOME: tmpDir, USERPROFILE: tmpDir });
});
afterEach(() => {
cleanup(tmpDir);
});
// (a) Default of plan_review.source_grounding is true
test('plan_review.source_grounding defaults to true when not set in config.json', () => {
const config = readConfig(tmpDir);
assert.strictEqual(
config.plan_review?.source_grounding,
true,
'plan_review.source_grounding must default to true'
);
});
// (b) Default of plan_review.source_grounding_authority is "grep"
test('plan_review.source_grounding_authority defaults to "grep" when not set in config.json', () => {
const config = readConfig(tmpDir);
assert.strictEqual(
config.plan_review?.source_grounding_authority,
'grep',
'plan_review.source_grounding_authority must default to "grep"'
);
});
// (c) Both keys are recognized as valid config keys
test('plan_review.source_grounding is a valid config key accepted by config-set', () => {
const result = runGsdTools('config-set plan_review.source_grounding false', tmpDir);
assert.ok(result.success, `config-set plan_review.source_grounding failed: ${result.error}`);
const config = readConfig(tmpDir);
assert.strictEqual(config.plan_review.source_grounding, false);
});
test('plan_review.source_grounding_authority is a valid config key accepted by config-set', () => {
const result = runGsdTools('config-set plan_review.source_grounding_authority intel', tmpDir);
assert.ok(result.success, `config-set plan_review.source_grounding_authority failed: ${result.error}`);
const config = readConfig(tmpDir);
assert.strictEqual(config.plan_review.source_grounding_authority, 'intel');
});
// Enum positive: all valid authority values
test('plan_review.source_grounding_authority accepts all valid enum values', () => {
const validValues = ['grep', 'intel', 'treesitter', 'lsp', 'scip'];
for (const v of validValues) {
const result = runGsdTools(`config-set plan_review.source_grounding_authority ${v}`, tmpDir);
assert.ok(result.success, `config-set plan_review.source_grounding_authority ${v} failed: ${result.error}`);
const config = readConfig(tmpDir);
assert.strictEqual(config.plan_review.source_grounding_authority, v);
}
});
// (d) NEGATIVE MATRIX — invalid enum values are rejected
test('plan_review.source_grounding_authority rejects invalid value "bogus"', () => {
const result = runGsdTools('config-set plan_review.source_grounding_authority bogus', tmpDir);
assert.strictEqual(result.success, false, 'bogus should be rejected');
assert.ok(
result.error.includes('Invalid plan_review.source_grounding_authority'),
`Expected "Invalid plan_review.source_grounding_authority" in error: ${result.error}`
);
});
test('plan_review.source_grounding_authority rejects flag-looking value "--grep"', () => {
const result = runGsdTools(['config-set', 'plan_review.source_grounding_authority', '--grep'], tmpDir);
assert.strictEqual(result.success, false, '--grep should be rejected');
assert.ok(
result.error.includes('Invalid plan_review.source_grounding_authority'),
`Expected "Invalid plan_review.source_grounding_authority" in error: ${result.error}`
);
});
test('plan_review.source_grounding_authority rejects empty string', () => {
const result = runGsdTools(['config-set', 'plan_review.source_grounding_authority', ''], tmpDir);
assert.strictEqual(result.success, false, 'empty string should be rejected');
});
test('plan_review.source_grounding rejects non-boolean value "yes"', () => {
const result = runGsdTools('config-set plan_review.source_grounding yes', tmpDir);
assert.strictEqual(result.success, false, '"yes" should be rejected as non-boolean');
assert.ok(
result.error.includes('Invalid plan_review.source_grounding'),
`Expected "Invalid plan_review.source_grounding" in error: ${result.error}`
);
});
test('plan_review.source_grounding rejects numeric value 1', () => {
const result = runGsdTools('config-set plan_review.source_grounding 1', tmpDir);
assert.strictEqual(result.success, false, 'numeric 1 should be rejected as non-boolean');
assert.ok(
result.error.includes('Invalid plan_review.source_grounding'),
`Expected "Invalid plan_review.source_grounding" in error: ${result.error}`
);
});
});