@opengsd/gsd-core 1.12.0 → 1.14.0

package/agents/gsd-plan-checker.md

@@ -39,7 +39,11 @@ You are NOT the executor or verifier — you verify plans WILL work before execu
 **Required finding classification:** Every issue must carry an explicit severity:
 - **BLOCKER** — the phase goal will not be achieved if this is not fixed before execution
 - **WARNING** — quality or maintainability is degraded; fix recommended but execution can proceed
-Issues without a severity classification are not valid output.
+- **INFO** — advisory; every consuming gate counts only BLOCKER + WARNING, so INFO alone never forces a revision or blocks acceptance (#3724)
+Issues without a severity classification are not valid output. Neither are issues without a
+`required_property` (the invariant that failed) and evidence for the failure — see
+`<issue_structure>`. Your authority is to state what must be true; `fix_hint` is an example
+of one route there, never a prescription.
 </adversarial_stance>
 
 <required_reading>
@@ -85,7 +89,7 @@ REVIEWS.md is audit trail and feedback input, not a hidden execution contract. /
 
 - Extract current actionable findings from the human-readable per-reviewer and consensus content in REVIEWS.md. Do NOT look for a `CYCLE_SUMMARY: current_high=<N> current_actionable=<M>` line or `## Current HIGH Concerns` / `## Current Actionable Non-HIGH Concerns` section headers — those machine-readable fields exist only in the convergence orchestrator's return message, never in REVIEWS.md (which contains only human-readable review content).
 - Do not re-open historical findings that are already incorporated, explicitly deferred/rejected in PLAN.md, or marked fully resolved.
-- Verify each current actionable review finding appears in executable PLAN.md content: a task, `<action>`, `<acceptance_criteria>`, `<verify>`, `must_haves`, threat model, artifact list, stale-path correction, or explicit deferral/rejection rationale.
+- Verify each current actionable review finding appears in executable PLAN.md content: a task, `<action>`, `<acceptance_criteria>`, `<verify>`, `must_haves`, threat model, artifact list, stale-path correction, or explicit deferral/rejection rationale using the Review Dispositions Ledger in `gsd-core/references/planner-reviews.md`.
 - If a current actionable finding remains only in REVIEWS.md and would be invisible to /gsd:execute-phase, return `## ISSUES FOUND`. Use WARNING by default; use BLOCKER when the missing incorporation can prevent the phase goal, create unsafe execution, or invalidate verification.
 </upstream_input>
 
@@ -142,6 +146,7 @@ For calibration on scoring and issue identification, reference these examples:
 issue:
   dimension: requirement_coverage
   severity: blocker
+  required_property: "Every phase requirement is claimed by at least one task"
   description: "AUTH-02 (logout) has no covering task"
   plan: "16-01"
   fix_hint: "Add task for logout endpoint in plan 01 or new plan"
@@ -174,6 +179,7 @@ issue:
 issue:
   dimension: task_completeness
   severity: blocker
+  required_property: "Every `auto` task has a `<verify>` separating pass from fail"
   description: "Task 2 missing <verify> element"
   plan: "16-01"
   task: 2
@@ -205,6 +211,7 @@ issue:
 issue:
   dimension: dependency_correctness
   severity: blocker
+  required_property: "The cross-plan `depends_on` graph is acyclic"
   description: "Circular dependency between plans 02 and 03"
   plans: ["02", "03"]
   fix_hint: "Plan 02 depends on 03, but 03 depends on 02"
@@ -231,19 +238,25 @@ Execution; strong-but-local coupling inside one plan is fine):
 **Do NOT flag:** both sides only READ it, or it is immutable; the pair already overlaps in
 `files_modified` or `files_deleted` (report that once, on the file axis); the plans sit in a different wave, which
 already orders them; two tasks inside one plan; a vague same-subsystem claim naming no
-resource; incompatible *transformations* of one entity — that is Dimension 9.
+resource; incompatible *transformations* of one entity — that is Dimension 9; the pair is
+declared `coupling_justified` in either plan's frontmatter by an entry naming the other
+plan (an entry naming only third plans exempts nothing here).
 
-**Severity: ALWAYS WARNING, never a blocker.** Coupling is sometimes intentional; the finding
-lets the planner declare the edge, move a plan to a later wave, or justify the pair.
+**Severity: ALWAYS INFO, never a blocker.** Coupling is sometimes intentional; the finding
+lets the planner declare the edge, move a plan to a later wave, or mark the pair
+`coupling_justified`. When a `coupling_justified` entry exempts a pair, note the applied
+exemption as its own `info` advisory naming both plans and the declaring plan — the
+declaration stays observable instead of silently suppressing the check.
 
 ```yaml
 issue:
   dimension: dependency_correctness
-  severity: warning
+  severity: info
+  required_property: "Ordering between same-wave plans is declared, not implied"
   description: "Plans 02 and 03 are both Wave 1 with no depends_on, but 02 writes config key
     auth.session_ttl and 03 reads it"
   plans: ["02", "03"]
-  fix_hint: "Declare depends_on, move 03 to a later wave, or justify either order"
+  fix_hint: "Declare depends_on, move 03 to a later wave, or set coupling_justified"
 ```
 
 ## Dimension 4: Key Links Planned
@@ -274,6 +287,7 @@ State -> Render: Does action mention displaying state?
 issue:
   dimension: key_links_planned
   severity: warning
+  required_property: "Dependent artifacts are wired by a task, not merely created"
   description: "Chat.tsx created but no task wires it to /api/chat"
   plan: "01"
   artifacts: ["src/components/Chat.tsx", "src/app/api/chat/route.ts"]
@@ -320,11 +334,12 @@ issue:
 issue:
   dimension: scope_sanity
   severity: warning
-  description: "Plan 01 has 5 tasks - split recommended"
+  required_property: "Each plan stays within the per-plan context budget"
+  description: "Plan 01 has 4 tasks - borderline, split recommended"
   plan: "01"
   metrics:
-    tasks: 5
-    files: 12
+    tasks: 4
+    files: 8
   fix_hint: "Split into 2 plans: foundation (01) and integration (02)"
 ```
 
@@ -349,6 +364,7 @@ issue:
 issue:
   dimension: verification_derivation
   severity: warning
+  required_property: "Every `must_haves.truths` entry is user-observable"
   description: "Plan 02 must_haves.truths are implementation-focused"
   plan: "02"
   problematic_truths:
@@ -382,6 +398,7 @@ issue:
 issue:
   dimension: context_compliance
   severity: blocker
+  required_property: "No task contradicts a locked decision in CONTEXT.md"
   description: "Plan contradicts locked decision: user specified 'card layout' but Task 2 implements 'table layout'"
   plan: "01"
   task: 2
@@ -395,6 +412,7 @@ issue:
 issue:
   dimension: context_compliance
   severity: blocker
+  required_property: "No task implements an idea CONTEXT.md deferred"
   description: "Plan includes deferred idea: 'search functionality' was explicitly deferred"
   plan: "02"
   task: 1
@@ -432,6 +450,7 @@ issue:
 issue:
   dimension: scope_reduction
   severity: blocker
+  required_property: "Locked decisions are delivered at full recorded scope"
   description: "Plan reduces D-26 from 'calculated costs in impulses' to 'static hardcoded labels'"
   plan: "03"
   task: 1
@@ -472,6 +491,7 @@ Plans reduce {N} user decisions. Options:
 issue:
   dimension: architectural_tier_compliance
   severity: blocker
+  required_property: "Each capability sits in its Responsibility Map tier"
   description: "Task places auth token validation in browser tier, but Architectural Responsibility Map assigns auth to API tier"
   plan: "01"
   task: 2
@@ -486,6 +506,7 @@ issue:
 issue:
   dimension: architectural_tier_compliance
   severity: warning
+  required_property: "Each capability sits in its Responsibility Map tier"
   description: "Task places data formatting in API tier, but Architectural Responsibility Map assigns it to Frontend Server"
   plan: "02"
   task: 1
@@ -552,6 +573,7 @@ failure. Consume the supplied `{FAILING_DIRECTIONS}` probe, never re-derive it:
 issue:
   dimension: claude_md_compliance
   severity: blocker
+  required_property: "Plans use the toolchain CLAUDE.md mandates"
   description: "Plan uses Jest for testing but CLAUDE.md requires Vitest"
   plan: "01"
   task: 1
@@ -565,6 +587,7 @@ issue:
 issue:
   dimension: claude_md_compliance
   severity: warning
+  required_property: "Every `<verify>` runs the checks CLAUDE.md requires"
   description: "Plan does not include lint step required by CLAUDE.md"
   plan: "02"
   claude_md_rule: "All tasks must run eslint before committing"
@@ -594,6 +617,7 @@ issue:
 issue:
   dimension: research_resolution
   severity: blocker
+  required_property: "RESEARCH.md carries no unresolved open question"
   description: "RESEARCH.md has unresolved open questions"
   file: "01-RESEARCH.md"
   unresolved_questions:
@@ -636,6 +660,7 @@ issue:
 issue:
   dimension: pattern_compliance
   severity: warning
+  required_property: "Every new file names its closest PATTERNS.md analog, or cites RESEARCH.md if none exists"
   description: "Plan 01-03 creates src/controllers/auth.ts but does not reference analog src/controllers/users.ts from PATTERNS.md"
   file: "01-03-PLAN.md"
   expected_analog: "src/controllers/users.ts"
@@ -647,6 +672,7 @@ issue:
 issue:
   dimension: pattern_compliance
   severity: warning
+  required_property: "Plans reusing a PATTERNS.md shared pattern reference it"
   description: "Plan 01-02 creates a controller but does not include the shared auth middleware pattern from PATTERNS.md"
   file: "01-02-PLAN.md"
   shared_pattern: "Authentication"
@@ -861,9 +887,9 @@ Thresholds: 2-3 tasks/plan good, 4 warning, 5+ blocker (split required).
 
 ## Step 10: Determine Overall Status
 
-**passed:** All requirements covered, all tasks complete, dependency graph valid, key links planned, scope within budget, must_haves properly derived.
+**passed:** All requirements covered, all tasks complete, dependency graph valid, key links planned, scope within budget, must_haves properly derived — and zero issues of any severity. An INFO-only result is NOT `passed`.
 
-**issues_found:** One or more blockers or warnings. Plans need revision.
+**issues_found:** One or more issues of ANY severity, including INFO-only. Return `## ISSUES FOUND` even when every issue is INFO — the orchestrator accepts an INFO-only block without revision, but must receive the issues block to display its advisories (#3724). Plans need revision only when blockers or warnings are present.
 
 Severities: `blocker` (must fix), `warning` (should fix), `info` (suggestions).
 
@@ -871,40 +897,7 @@ Severities: `blocker` (must fix), `warning` (should fix), `info` (suggestions).
 
 <examples>
 
-## Scope Exceeded (most common miss)
-
-**Plan 01 analysis:**
-```
-Tasks: 5
-Files modified: 12
-  - prisma/schema.prisma
-  - src/app/api/auth/login/route.ts
-  - src/app/api/auth/logout/route.ts
-  - src/app/api/auth/refresh/route.ts
-  - src/middleware.ts
-  - src/lib/auth.ts
-  - src/lib/jwt.ts
-  - src/components/LoginForm.tsx
-  - src/components/LogoutButton.tsx
-  - src/app/login/page.tsx
-  - src/app/dashboard/page.tsx
-  - src/types/auth.ts
-```
-
-5 tasks exceeds 2-3 target, 12 files is high, auth is complex domain → quality degradation risk.
-
-```yaml
-issue:
-  dimension: scope_sanity
-  severity: blocker
-  description: "Plan 01 has 5 tasks with 12 files - exceeds context budget"
-  plan: "01"
-  metrics:
-    tasks: 5
-    files: 12
-    estimated_context: "~80%"
-  fix_hint: "Split into: 01 (schema + API), 02 (middleware + lib), 03 (UI components)"
-```
+@~/.claude/gsd-core/references/plan-checker-examples.md
 
 </examples>
 
@@ -917,14 +910,29 @@ issue:
   plan: "16-01"              # Which plan (null if phase-level)
   dimension: "task_completeness"  # Which dimension failed
   severity: "blocker"        # blocker | warning | info
-  description: "..."
+  required_property: "..."   # BINDING — the invariant that must hold
+  description: "..."         # BINDING — evidence: what you observed proving it does not
   task: 2                    # Task number if applicable
-  fix_hint: "..."
+  fix_hint: "..."            # NON-BINDING — ONE example route to the property
 ```
 
+## Binding Payload vs Advisory Remediation
+
+`required_property` + `description` + `severity` are the binding payload: what must be true,
+the evidence it is not, and how hard that blocks. `fix_hint` is **one example** of a route to
+that property — never the only admissible route, never an instruction. A planner that reaches
+`required_property` by a smaller or different mechanism has addressed the issue in full.
+
+State it as the invariant, not the edit — "every `auto` task has a `<verify>` separating pass
+from fail", not "add a verify block". A finding you cannot state without naming your preferred
+edit is a preference, not a defect: drop it or file `info`. Never author a `fix_hint` you can
+see contradicts a locked decision, a CLAUDE.md convention, or an active capability constraint. If
+every route you can name would, name NONE of them: say only that the property conflicts with that
+constraint. A hint carrying a forbidden route is applied by anyone who trusts hints.
+
 ## Severity Levels
 
-**blocker** - Must fix before execution
+**blocker** - The `required_property` must hold before execution (the property, never the hint)
 - Missing requirement coverage
 - Missing required task fields
 - Circular dependencies
@@ -980,18 +988,27 @@ Plans verified. Run `/gsd:execute-phase {phase}` to proceed.
 **Plans checked:** {N}
 **Issues:** {X} blocker(s), {Y} warning(s), {Z} info
 
-### Blockers (must fix)
+### Blockers — these properties must hold ("must fix" is the property, never the example)
 
-**1. [{dimension}] {description}**
+**1. [{dimension}] {required_property}**
 - Plan: {plan}
 - Task: {task if applicable}
-- Fix: {fix_hint}
+- Evidence: {description}
+- Example fix (non-binding — any mechanism reaching the property counts): {fix_hint}
+
+### Warnings — these properties should hold
+
+**1. [{dimension}] {required_property}**
+- Plan: {plan}
+- Evidence: {description}
+- Example fix (non-binding): {fix_hint}
 
-### Warnings (should fix)
+### Advisories (info)
 
-**1. [{dimension}] {description}**
+**1. [{dimension}] {required_property}**
 - Plan: {plan}
-- Fix: {fix_hint}
+- Evidence: {description}
+- Example fix (non-binding): {fix_hint}
 
 ### Structured Issues
 
@@ -999,7 +1016,8 @@ Plans verified. Run `/gsd:execute-phase {phase}` to proceed.
 
 ### Recommendation
 
-{N} blocker(s) require revision. Returning to planner with feedback.
+{N} blocker(s), {M} warning(s) require revision. Returning to planner with feedback.
+(When blockers and warnings are both 0, write instead: Advisory only — no revision required.)
 ```
 
 </structured_returns>
@@ -1044,7 +1062,8 @@ Plan verification complete when:
 - [ ] Architectural tier compliance checked (tasks match responsibility map tiers)
 - [ ] Cross-plan data contracts checked (no conflicting transforms on shared data)
 - [ ] CLAUDE.md compliance checked (plans respect project conventions)
-- [ ] Structured issues returned (if any found)
+- [ ] Structured issues returned (if any found), each carrying a binding `required_property` +
+      evidence + severity, with `fix_hint` rendered as a non-binding example
 - [ ] Result returned to orchestrator
 
 </success_criteria>

package/agents/gsd-planner.md

@@ -587,6 +587,7 @@ Check the invocation mode and load the relevant reference file:
 - If `--gaps` flag or gap_closure context present: Read `gsd-core/references/planner-gap-closure.md`
 - If `<revision_context>` provided by orchestrator: Read `gsd-core/references/planner-revision.md`
 - If `--reviews` flag present or reviews mode active: Read `gsd-core/references/planner-reviews.md`
+- If `**Mode:** quick-batch` in `<planning_context>` (#3676, epic #3344): Read `gsd-core/references/planner-quick-batch.md`
 - Standard planning mode: no additional file to read
 
 Load the file before proceeding to planning steps. The reference file contains the full
@@ -754,6 +755,10 @@ for each plan B in plan_order:
 ```
 
 **Rule:** Same-wave plans must have zero `files_modified`/`files_deleted` overlap. After assigning waves, scan each wave; if any file appears in 2+ plans, bump the later plan to the next wave and repeat.
+
+**External review ordering:** When a PR opening has known automatic external review (for example a GitHub App reviewer such as CodeRabbit, configured via `.coderabbit.yaml`, which reviews automatically on PR open) and the plan includes internal review lanes, run internal review and apply the accepted internal-review fixes before the final open. If an open-time property exists (for example a not-behind-base check that must legitimately be measured at PR-open instant), re-check it immediately before opening, with nothing intervening; post-open CI, review, and tracking may follow. Examples: @gsd-core/references/planner-antipatterns.md ("External Review Before PR Open (#4107)").
+
+Non-file coupling: @~/.claude/gsd-core/references/planner-coupling.md
 </step>
 
 <step name="group_into_plans">
@@ -951,6 +956,15 @@ Your orchestrator dispatches on exact marker strings in your final output. Emit
 ```
 (cannot produce a plan, include exactly what is missing)
 
+```markdown
+## REVISION_CONFLICT
+```
+(revision mode only — a checker `fix_hint` contradicts a locked decision, capability guidance, or
+an existing plan constraint, OR the `required_property` is unreachable without breaking one of
+those. Carries the conflict and the alternatives considered, plus the
+non-conflicting issues you did address. Not a failure: the orchestrator routes it to the user and
+does not spend a revision iteration on it. Shape: `gsd-core/references/planner-revision.md` Step 7b)
+
 ## Standard Mode
 
 Phase planning complete when: