* 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:
@@ -222,6 +222,15 @@ AskUserQuestion([
|
||||
{ label: "No", description: "Trust execution, skip verification" }
|
||||
]
|
||||
},
|
||||
{
|
||||
header: "Drift Guard",
|
||||
question: "Enable the plan drift-guard? It verifies that symbols your plans cite (decorators, classes, functions, CLI flags) actually exist in your source at review time, catching hallucinated names before execution. [Y/n]",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Yes (Recommended)", description: "Resolve symbol references against live source during plan review — catches hallucinated names before execution" },
|
||||
{ label: "No", description: "Skip symbol grounding — plan review proceeds without source verification" }
|
||||
]
|
||||
},
|
||||
{
|
||||
header: "AI Models",
|
||||
question: "Which AI models for planning agents?",
|
||||
@@ -264,7 +273,7 @@ Create `.planning/config.json` with all settings (CLI fills in remaining default
|
||||
|
||||
```bash
|
||||
mkdir -p .planning
|
||||
gsd_run query config-new-project '{"mode":"yolo","granularity":"[selected]","parallelization":true|false,"commit_docs":true|false,"model_profile":"quality|balanced|budget|inherit","workflow":{"research":true|false,"plan_check":true|false,"verifier":true|false,"nyquist_validation":true|false,"auto_advance":true},"ship":{"pr_body_sections":[{"heading":"User Stories & Acceptance Criteria","enabled":true|false,"source":"REQUIREMENTS.md ## User Stories || REQUIREMENTS.md ## Acceptance Criteria","fallback":"- Acceptance criteria are covered by the linked requirements and verification evidence."},{"heading":"Risks & Dependencies","enabled":true|false,"source":"PLAN.md ## Risks || PLAN.md ## Dependencies","fallback":"- No known high-risk rollout dependencies."},{"heading":"Success Metrics & Release Criteria","enabled":true|false,"source":"REQUIREMENTS.md ## Definition of Done || VERIFICATION.md ## Release Criteria","fallback":"- Release when automated verification and required manual checks pass."},{"heading":"Stakeholder Review & Approval","enabled":true|false,"template":"- Product owner approval pending for {phase_name}."}]}}'
|
||||
gsd_run query config-new-project '{"mode":"yolo","granularity":"[selected]","parallelization":true|false,"commit_docs":true|false,"model_profile":"quality|balanced|budget|inherit","workflow":{"research":true|false,"plan_check":true|false,"verifier":true|false,"nyquist_validation":true|false,"auto_advance":true},"plan_review":{"source_grounding":true|false},"ship":{"pr_body_sections":[{"heading":"User Stories & Acceptance Criteria","enabled":true|false,"source":"REQUIREMENTS.md ## User Stories || REQUIREMENTS.md ## Acceptance Criteria","fallback":"- Acceptance criteria are covered by the linked requirements and verification evidence."},{"heading":"Risks & Dependencies","enabled":true|false,"source":"PLAN.md ## Risks || PLAN.md ## Dependencies","fallback":"- No known high-risk rollout dependencies."},{"heading":"Success Metrics & Release Criteria","enabled":true|false,"source":"REQUIREMENTS.md ## Definition of Done || VERIFICATION.md ## Release Criteria","fallback":"- Release when automated verification and required manual checks pass."},{"heading":"Stakeholder Review & Approval","enabled":true|false,"template":"- Product owner approval pending for {phase_name}."}]}}'
|
||||
```
|
||||
|
||||
**If commit_docs = No:** Add `.planning/` to `.gitignore`.
|
||||
@@ -506,6 +515,7 @@ Format the JSON into human-readable bullets using these label mappings:
|
||||
- `workflow.research` → "Research" (`true` → "Yes", `false` → "No")
|
||||
- `workflow.plan_check` → "Plan Check" (`true` → "Yes", `false` → "No")
|
||||
- `workflow.verifier` → "Verifier" (`true` → "Yes", `false` → "No")
|
||||
- `plan_review.source_grounding` → "Drift Guard" (`true` → "Yes", `false` → "No")
|
||||
|
||||
Display above the prompt:
|
||||
|
||||
@@ -519,6 +529,7 @@ Your saved defaults (~/.gsd/defaults.json):
|
||||
• Research: [Yes|No]
|
||||
• Plan Check: [Yes|No]
|
||||
• Verifier: [Yes|No]
|
||||
• Drift Guard: [Yes|No]
|
||||
```
|
||||
|
||||
Then ask:
|
||||
@@ -555,6 +566,7 @@ Which settings do you want to change? (enter numbers, comma-separated)
|
||||
6. Research — Currently: [Yes|No]
|
||||
7. Plan Check — Currently: [Yes|No]
|
||||
8. Verifier — Currently: [Yes|No]
|
||||
9. Drift Guard — Currently: [Yes|No]
|
||||
```
|
||||
|
||||
**Otherwise** (Claude runtime with AskUserQuestion): use a two-block split
|
||||
@@ -626,6 +638,22 @@ AskUserQuestion([
|
||||
])
|
||||
```
|
||||
|
||||
Then ask:
|
||||
|
||||
```text
|
||||
AskUserQuestion([
|
||||
{
|
||||
question: "Do you want to change the Drift Guard setting (plan-review source-grounding)?",
|
||||
header: "Drift Guard",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Yes", description: "Toggle Drift Guard (currently: [Yes|No])" },
|
||||
{ label: "No", description: "Keep current Drift Guard setting" }
|
||||
]
|
||||
}
|
||||
])
|
||||
```
|
||||
|
||||
For each selected setting across both blocks, ask only that question using the
|
||||
option set from Round 1 / Round 2 below. Merge user answers over the saved
|
||||
defaults — unchanged settings retain their saved values. Then skip to
|
||||
@@ -745,7 +773,7 @@ Create `.planning/config.json` with all settings (CLI fills in remaining default
|
||||
|
||||
```bash
|
||||
mkdir -p .planning
|
||||
gsd_run query config-new-project '{"mode":"[yolo|interactive]","granularity":"[selected]","parallelization":true|false,"commit_docs":true|false,"model_profile":"quality|balanced|budget|inherit","workflow":{"research":true|false,"plan_check":true|false,"verifier":true|false,"nyquist_validation":[false if granularity=coarse, true otherwise]},"ship":{"pr_body_sections":[{"heading":"User Stories & Acceptance Criteria","enabled":true|false,"source":"REQUIREMENTS.md ## User Stories || REQUIREMENTS.md ## Acceptance Criteria","fallback":"- Acceptance criteria are covered by the linked requirements and verification evidence."},{"heading":"Risks & Dependencies","enabled":true|false,"source":"PLAN.md ## Risks || PLAN.md ## Dependencies","fallback":"- No known high-risk rollout dependencies."},{"heading":"Success Metrics & Release Criteria","enabled":true|false,"source":"REQUIREMENTS.md ## Definition of Done || VERIFICATION.md ## Release Criteria","fallback":"- Release when automated verification and required manual checks pass."},{"heading":"Stakeholder Review & Approval","enabled":true|false,"template":"- Product owner approval pending for {phase_name}."}]}}'
|
||||
gsd_run query config-new-project '{"mode":"[yolo|interactive]","granularity":"[selected]","parallelization":true|false,"commit_docs":true|false,"model_profile":"quality|balanced|budget|inherit","workflow":{"research":true|false,"plan_check":true|false,"verifier":true|false,"nyquist_validation":[false if granularity=coarse, true otherwise]},"plan_review":{"source_grounding":true|false},"ship":{"pr_body_sections":[{"heading":"User Stories & Acceptance Criteria","enabled":true|false,"source":"REQUIREMENTS.md ## User Stories || REQUIREMENTS.md ## Acceptance Criteria","fallback":"- Acceptance criteria are covered by the linked requirements and verification evidence."},{"heading":"Risks & Dependencies","enabled":true|false,"source":"PLAN.md ## Risks || PLAN.md ## Dependencies","fallback":"- No known high-risk rollout dependencies."},{"heading":"Success Metrics & Release Criteria","enabled":true|false,"source":"REQUIREMENTS.md ## Definition of Done || VERIFICATION.md ## Release Criteria","fallback":"- Release when automated verification and required manual checks pass."},{"heading":"Stakeholder Review & Approval","enabled":true|false,"template":"- Product owner approval pending for {phase_name}."}]}}'
|
||||
```
|
||||
|
||||
**Note:** Run `/gsd:settings` anytime to update model profile, workflow agents, branching strategy, and other preferences.
|
||||
|
||||
@@ -857,6 +857,18 @@ After pattern mapper completes, update the path variable:
|
||||
PATTERNS_PATH="${PHASE_DIR}/${PADDED_PHASE}-PATTERNS.md"
|
||||
```
|
||||
|
||||
## 7.9. Regenerate API-SURFACE.md (intel gate)
|
||||
|
||||
```bash
|
||||
INTEL_CFG=$(gsd_run query config-get intel.enabled 2>/dev/null || echo "false")
|
||||
# false (absent = false) → API_SURFACE_PATH stays empty; step-8 planner entry omitted
|
||||
if [ "$INTEL_CFG" = "true" ]; then
|
||||
gsd_run intel api-surface
|
||||
API_SURFACE_PATH=".planning/intel/API-SURFACE.md"
|
||||
echo "✓ API surface regenerated: ${API_SURFACE_PATH}" # injected into step 8 as HINT
|
||||
fi
|
||||
```
|
||||
|
||||
## 8. Spawn gsd-planner Agent
|
||||
|
||||
Display banner:
|
||||
@@ -888,6 +900,7 @@ Planner prompt:
|
||||
- {UI_SPEC_PATH} (UI Design Contract — visual/interaction specs, if exists)
|
||||
- {SPIKE_FINDINGS_PATH} (Spike Findings — validated patterns, constraints, landmines from experiments, if exists)
|
||||
- {SKETCH_FINDINGS_PATH} (Sketch Findings — validated design decisions, CSS patterns, visual direction, if exists)
|
||||
- {API_SURFACE_PATH} (API Surface — HINT ONLY, if intel.enabled; see <intel_surface_hint> below)
|
||||
${CONTEXT_WINDOW >= 500000 ? `
|
||||
**Cross-phase context (1M model enrichment):**
|
||||
- CONTEXT.md files from the 3 most recent completed phases (locked decisions — maintain consistency)
|
||||
@@ -897,7 +910,11 @@ ${CONTEXT_WINDOW >= 500000 ? `
|
||||
- Skip all other prior phases to stay within context budget
|
||||
` : ''}
|
||||
</files_to_read>
|
||||
|
||||
${API_SURFACE_PATH ? `
|
||||
<intel_surface_hint>
|
||||
**API Surface (HINT — may be incomplete):** When \`intel.enabled\` is true, \`.planning/intel/API-SURFACE.md\` lists symbols extracted from the codebase by regex/JS analysis. Prefer symbols listed there when referencing existing code. This surface is regex/JS-derived and MAY BE INCOMPLETE — a symbol's absence means *unknown*, not *nonexistent*. Never treat the surface as exhaustive. If you reference a symbol that is not in the surface and this phase creates it, list it under "Artifacts this phase produces".
|
||||
</intel_surface_hint>
|
||||
` : ''}
|
||||
${AGENT_SKILLS_PLANNER}
|
||||
|
||||
**Phase requirement IDs (every ID MUST appear in a plan's `requirements` field):** {phase_req_ids}
|
||||
@@ -932,6 +949,7 @@ Output consumed by /gsd:execute-phase. Plans need:
|
||||
- Tasks in XML format with read_first and acceptance_criteria fields (MANDATORY on every task)
|
||||
- Verification criteria
|
||||
- must_haves for goal-backward verification
|
||||
- **"Artifacts this phase produces" section (MANDATORY)** — list every symbol this phase creates: decorators, classes, functions, CLI flags, struct/dataclass fields, new file paths. The plan-review-convergence source-grounding pass reads this section to exclude newly-created symbols from drift verification; omitting it causes new symbols to be flagged for acknowledgement.
|
||||
</downstream_consumer>
|
||||
|
||||
<deep_work_rules>
|
||||
@@ -975,6 +993,7 @@ Every task MUST include these fields — they are NOT optional:
|
||||
- [ ] Dependencies correctly identified
|
||||
- [ ] Waves assigned for parallel execution
|
||||
- [ ] must_haves derived from phase goal
|
||||
- [ ] Every PLAN.md includes an "Artifacts this phase produces" section listing symbols created by this phase (decorators, classes, functions, CLI flags, struct/dataclass fields, new file paths)
|
||||
</quality_gate>
|
||||
```
|
||||
|
||||
|
||||
@@ -176,6 +176,22 @@ Your final response MUST also include this section immediately after the CYCLE_S
|
||||
)
|
||||
```
|
||||
|
||||
### Source-grounding pass (config: `plan_review.source_grounding`, default on)
|
||||
|
||||
Run this pass unless `plan_review.source_grounding` is `false`. It verifies every symbol the plan cites against the project source before approval, catching hallucinated symbols at review time instead of execution time.
|
||||
|
||||
1. **Enumerate cited symbols.** List every referenced symbol by kind, quoting the plan line for each (coverage must be auditable): decorators (`@name`), classes/methods (`Class.method`), functions (`module.function`), CLI flags (`--name`), file paths, dataclass/struct fields.
|
||||
2. **Exclude new artifacts.** Do NOT verify symbols the plan declares under its "Artifacts this phase produces" section — those are created by this phase, not references to existing code.
|
||||
3. **Resolve each remaining symbol** using the adapter named by `plan_review.source_grounding_authority` (default `grep`):
|
||||
- `grep` — ripgrep / Read the source; confirm the name appears as a real declaration.
|
||||
- `intel` — consult `.planning/intel/API-SURFACE.md` / `api-map.json` (only when `intel.enabled`).
|
||||
Record one verdict per symbol: **VERIFIED** (quote `file:line`), **MISSING** (adapter can check this language/kind and the symbol is absent), **AMBIGUOUS** (multiple candidates), or **UNCHECKABLE** (adapter cannot analyze this language/kind — e.g. non-JS under `intel`, or any signature under `grep`). Never treat UNCHECKABLE as verified or missing.
|
||||
4. **Severity & gating:**
|
||||
- **MISSING** at authority `grep`/`intel` → `needs-acknowledgement`: the plan proceeds only if the author confirms the symbol is genuinely new or dynamically resolved, and that acknowledgement is recorded. A hard block is reserved for higher-authority adapters (LSP/SCIP) that can prove absence.
|
||||
- **AMBIGUOUS** → MEDIUM. **UNCHECKABLE** → INFO.
|
||||
- Signature mismatches cannot be asserted under `grep`/`intel`; report the signature as UNCHECKABLE.
|
||||
5. **Coverage block.** Append a "Verification coverage" section to `REVIEWS.md` listing every UNCHECKABLE/skipped symbol and why — a clean review must never silently mean "nothing was checked."
|
||||
|
||||
After agent returns, verify REVIEWS.md exists:
|
||||
```bash
|
||||
REVIEWS_FILE=$(ls ${phase_dir}/${padded_phase}-REVIEWS.md 2>/dev/null)
|
||||
|
||||
@@ -40,6 +40,7 @@ Parse current values (default to `true` if not present):
|
||||
- `workflow.research` — spawn researcher during plan-phase
|
||||
- `workflow.plan_check` — spawn plan checker during plan-phase
|
||||
- `workflow.verifier` — spawn verifier during execute-phase
|
||||
- `plan_review.source_grounding` — verify plan symbols against live source during plan review (default: true if absent; set `plan_review.source_grounding_authority` to select the resolver adapter: `grep` (default), `intel`, `treesitter`, `lsp`, or `scip`)
|
||||
- `workflow.nyquist_validation` — validation architecture research during plan-phase (default: true if absent)
|
||||
- `workflow.pattern_mapper` — run gsd-pattern-mapper between research and planning (default: true if absent)
|
||||
- `workflow.ui_phase` — generate UI-SPEC.md design contracts for frontend phases (default: true if absent)
|
||||
@@ -83,7 +84,7 @@ Use AskUserQuestion with current values pre-selected. Questions are grouped into
|
||||
Section layout:
|
||||
|
||||
### Planning
|
||||
Research, Plan Checker, Pattern Mapper, Nyquist, UI Phase, UI Gate, AI Phase
|
||||
Research, Plan Checker, Drift Guard, Pattern Mapper, Nyquist, UI Phase, UI Gate, AI Phase
|
||||
|
||||
### Execution
|
||||
Verifier, TDD Mode, Code Review, Code Review Depth _(conditional — only when code_review=on)_, UI Review
|
||||
@@ -176,6 +177,15 @@ AskUserQuestion([
|
||||
{ label: "No", description: "Skip post-execution verification" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Enable Plan Drift Guard? (verifies that symbols cited in plans exist in source at review time)",
|
||||
header: "Drift Guard",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Yes (Recommended)", description: "Resolve symbol references (decorators, classes, functions, CLI flags) against live source — catches hallucinated names before execution. Authority controlled by plan_review.source_grounding_authority (default: grep)." },
|
||||
{ label: "No", description: "Skip symbol grounding. Plan review proceeds without source verification." }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Enable TDD Mode? (RED/GREEN/REFACTOR gates for eligible tasks)",
|
||||
header: "TDD",
|
||||
@@ -395,6 +405,9 @@ Merge new settings into existing config.json:
|
||||
"skip_discuss": true/false,
|
||||
"use_worktrees": true/false
|
||||
},
|
||||
"plan_review": {
|
||||
"source_grounding": true/false
|
||||
},
|
||||
"intel": {
|
||||
"enabled": true/false
|
||||
},
|
||||
@@ -468,6 +481,9 @@ Write `~/.gsd/defaults.json` with:
|
||||
"ui_review": <current>,
|
||||
"skip_discuss": <current>
|
||||
},
|
||||
"plan_review": {
|
||||
"source_grounding": <current>
|
||||
},
|
||||
"intel": {
|
||||
"enabled": <current>
|
||||
},
|
||||
@@ -496,6 +512,7 @@ Display:
|
||||
| Execution Verifier | {On/Off} |
|
||||
| TDD Mode | {On/Off} |
|
||||
| Code Review | {On/Off} |
|
||||
| Plan Drift Guard | {On/Off} |
|
||||
| Code Review Depth | {quick/standard/deep} |
|
||||
| UI Review | {On/Off} |
|
||||
| Commit Docs | {On/Off} |
|
||||
@@ -528,7 +545,7 @@ Quick commands:
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Current config read
|
||||
- [ ] User presented with 23 settings (profile + workflow toggles + features + git branching + git tagging + ctx warnings), grouped into six sections: Planning, Execution, Docs & Output, Features, Model & Pipeline, Misc. `code_review_depth` is conditional on `code_review=on`. Model profile uses a two-question split (Q1: Adaptive / Standard tier / Inherit; Q2: Quality / Balanced / Budget — only when Standard tier chosen) to stay within the 4-option AskUserQuestion cap while exposing all 5 valid profiles (#3784).
|
||||
- [ ] User presented with 24 settings (profile + workflow toggles + features + git branching + git tagging + ctx warnings), grouped into six sections: Planning, Execution, Docs & Output, Features, Model & Pipeline, Misc. `code_review_depth` is conditional on `code_review=on`. Model profile uses a two-question split (Q1: Adaptive / Standard tier / Inherit; Q2: Quality / Balanced / Budget — only when Standard tier chosen) to stay within the 4-option AskUserQuestion cap while exposing all 5 valid profiles (#3784). Drift Guard (`plan_review.source_grounding`) is in the Planning section.
|
||||
- [ ] Config updated with model_profile, workflow, and git sections
|
||||
- [ ] User offered to save as global defaults (~/.gsd/defaults.json)
|
||||
- [ ] Changes confirmed to user
|
||||
|
||||
Reference in New Issue
Block a user