@opengsd/gsd-core 1.4.4 → 1.5.0-rc.2

package/gsd-core/references/edge-probe-fixtures/03-truncate-graphemes/expected-coverage.json

@@ -0,0 +1,7 @@
+{
+  "items": [
+    { "requirement_id": "R1", "category": "empty", "status": "unresolved", "verification": null, "resolution": null, "reason": null, "probe": "What is the result for empty, single-element, or null input?" },
+    { "requirement_id": "R1", "category": "encoding", "status": "unresolved", "verification": null, "resolution": null, "reason": null, "probe": "Whose definition of length/equality applies — bytes, code points, grapheme clusters, or normalized form?" }
+  ],
+  "coverage": { "applicable": 2, "resolved": 0, "unresolved": 2, "byVerification": { "explicit": 0, "backstop": 0 } }
+}

package/gsd-core/references/edge-probe-fixtures/03-truncate-graphemes/requirements.json

@@ -0,0 +1 @@
+[{ "id": "R1", "text": "Truncate a display string to its first N characters" }]

package/gsd-core/references/edge-probe-fixtures/04-money-rounding/expected-coverage.json

@@ -0,0 +1,7 @@
+{
+  "items": [
+    { "requirement_id": "R1", "category": "boundary", "status": "unresolved", "verification": null, "resolution": null, "reason": null, "probe": "What happens exactly at each min/max/threshold — and one step either side?" },
+    { "requirement_id": "R1", "category": "precision", "status": "unresolved", "verification": null, "resolution": null, "reason": null, "probe": "Where can precision loss, overflow, or rounding/tie-breaking occur — and what is the exact contract (e.g. half-up vs half-to-even, ceil/floor/truncate)?" }
+  ],
+  "coverage": { "applicable": 2, "resolved": 0, "unresolved": 2, "byVerification": { "explicit": 0, "backstop": 0 } }
+}

package/gsd-core/references/edge-probe-fixtures/04-money-rounding/requirements.json

@@ -0,0 +1 @@
+[{ "id": "R1", "text": "Compute the total price as an amount rounded to two decimals" }]

package/gsd-core/references/edge-probe-fixtures/05-list-dedupe/expected-coverage.json

@@ -0,0 +1,8 @@
+{
+  "items": [
+    { "requirement_id": "R1", "category": "adjacency", "status": "unresolved", "verification": null, "resolution": null, "reason": null, "probe": "When two things are exactly equal or just touch, do they merge, collide, or separate?" },
+    { "requirement_id": "R1", "category": "empty", "status": "unresolved", "verification": null, "resolution": null, "reason": null, "probe": "What is the result for empty, single-element, or null input?" },
+    { "requirement_id": "R1", "category": "ordering", "status": "unresolved", "verification": null, "resolution": null, "reason": null, "probe": "When elements compare equal, is output order specified and stable?" }
+  ],
+  "coverage": { "applicable": 3, "resolved": 0, "unresolved": 3, "byVerification": { "explicit": 0, "backstop": 0 } }
+}

package/gsd-core/references/edge-probe-fixtures/05-list-dedupe/requirements.json

@@ -0,0 +1 @@
+[{ "id": "R1", "text": "Return all items in the list with duplicates removed" }]

package/gsd-core/references/edge-probe-fixtures/06-resolved-mixed/expected-coverage.json

@@ -0,0 +1,8 @@
+{
+  "items": [
+    { "requirement_id": "R1", "category": "adjacency", "status": "resolved", "verification": "explicit", "resolution": "AC#6: touching intervals merge", "reason": null, "probe": "When two things are exactly equal or just touch, do they merge, collide, or separate?" },
+    { "requirement_id": "R1", "category": "empty", "status": "unresolved", "verification": null, "resolution": null, "reason": null, "probe": "What is the result for empty, single-element, or null input?" },
+    { "requirement_id": "R1", "category": "ordering", "status": "dismissed", "verification": null, "resolution": null, "reason": "output is canonically sorted; no tie possible", "probe": "When elements compare equal, is output order specified and stable?" }
+  ],
+  "coverage": { "applicable": 3, "resolved": 2, "unresolved": 1, "byVerification": { "explicit": 1, "backstop": 0 } }
+}

package/gsd-core/references/edge-probe-fixtures/06-resolved-mixed/requirements.json

@@ -0,0 +1 @@
+[{ "id": "R1", "text": "Merge a list of overlapping intervals into the minimal set" }]

package/gsd-core/references/edge-probe-fixtures/06-resolved-mixed/resolutions.json

@@ -0,0 +1,4 @@
+[
+  { "requirement_id": "R1", "category": "adjacency", "status": "resolved", "verification": "explicit", "resolution": "AC#6: touching intervals merge", "reason": null },
+  { "requirement_id": "R1", "category": "ordering", "status": "dismissed", "resolution": null, "reason": "output is canonically sorted; no tie possible" }
+]

package/gsd-core/references/edge-probe.md

@@ -0,0 +1,261 @@
+# Edge-Probe — Spec-Completeness Reference
+
+Shared reference for the spec/requirements phase. Companion to
+`@~/.claude/gsd-core/references/domain-probes.md`: `domain-probes` covers the
+**technology axis** (auth, search, caching, deployment); this covers the
+**data/behavior-shape axis** (boundaries, adjacency, encoding, ordering…). Walk each
+requirement against the closed taxonomy below, propose a concrete candidate edge for each
+applicable category, and resolve each to exactly one state. Adopt the established QA names
+verbatim — this is decades-old black-box test technique, moved upstream to the spec layer.
+
+This doc is written in generic `requirements → checks → verifier` terms with no
+tool-specific vocabulary, so it is portable: copy it into any spec/requirements process.
+A short mapping table at the end binds it to common host structures.
+
+## Why front-of-pipeline
+
+A goal-backward verifier only checks assertions that exist; an assertion only exists for a
+requirement that was written down. A domain-boundary edge the author never surfaced is
+invisible to the verifier — and worse, the verifier is *confidently wrong* about it
+(measured: ~0.93 confidence while catching 0/12 omitted-edge defects, an expected
+calibration error of 0.81 — worse than a coin flip — versus 100% / 0.03 on edges the spec
+did state). The fix is not a better verifier or a confidence gate; confidence is
+uninformative across these regimes. The fix is **spec completeness**: surface the omitted
+edge into an explicit, checkable assertion *before* any code exists, after which the
+verifier reliably catches it.
+
+The underlying techniques are classic and should be named as such — **Boundary Value
+Analysis**, **Equivalence Partitioning**, the **Category-Partition method**, and
+**Metamorphic Relations**; property-based testing (PBT) is the academic name for the
+held-out backstop. The literature applies these at the *test* layer (back of pipeline,
+generating checks). The differentiated move here is **placement, not technique**: apply the
+same edge taxonomy at the *spec* layer (front of pipeline, generating requirements), with
+the explicit goal of extending a verifier's reach. Recent LLM spec work corroborates the
+core finding that the spec layer is the measured weak point:
+
+- SLD-Spec — program slicing + logical deletion (code→spec): arXiv 2509.09917
+- Specine / AutoReSpec / SpecMind — spec alignment & postcondition inference
+- CodeSpecBench (2604.12268), OSVBench (2504.20964), VERINA (2505.23135) — benchmarks
+  showing models solve tasks far better than they generate precise behavioral specs
+- LLM property-based tests for edge cases: arXiv 2510.25297 (PBT+EBT ≈ 81% edge detection)
+
+## Inputs
+
+A list of requirements, each a `{ id, text, shapes? }` record where `text` is a testable
+statement and `shapes` is an optional author-supplied override of the data/behavior shape.
+The five shapes are: `numeric-range`, `collection`, `text`, `stateful`, `io`. When
+`shapes` is absent, a heuristic classifier proposes them from the requirement prose
+(propose-then-confirm) — the author may correct the shape.
+
+## Taxonomy (8 categories)
+
+Closed and small by design: a fixed eight the author must explicitly clear beats thirty
+nobody finishes. The failure mode being eliminated was never "too few categories" — it was
+that no taxonomy was *systematically applied at all*. Categories 1, 2, and 4 alone cover
+the three canonical corpus defects (banker's-rounding ties, touching intervals, grapheme
+truncation). Growth happens via optional domain packs, not by bloating the core.
+
+| id | name (QA term) | applies to shapes | probe question |
+|----|----------------|-------------------|----------------|
+| boundary | Boundary values | numeric-range | What happens exactly at each min/max/threshold — and one step either side? |
+| adjacency | Adjacency / touching | collection | When two things are exactly equal or just touch, do they merge, collide, or separate? |
+| empty | Empty / degenerate | collection, text | What is the result for empty, single-element, or null input? |
+| encoding | Encoding / representation | text | Whose definition of length/equality applies — bytes, code points, grapheme clusters, or normalized form? |
+| ordering | Ordering / stability | collection | When elements compare equal, is output order specified and stable? |
+| precision | Precision / overflow | numeric-range | Where can precision loss, overflow, or rounding/tie-breaking occur — and what is the exact contract (e.g. half-up vs half-to-even, ceil/floor/truncate)? |
+| idempotency | Idempotency / repetition | stateful | What happens if this runs twice on the same input? |
+| concurrency | Concurrency / effect ordering | stateful, io | If interrupted or run in parallel, what is guaranteed? |
+
+## Relevance filter + resolution states
+
+Two rules keep the probe honest and prevent an "everything is N/A" failure mode:
+
+1. **Relevance filter first.** Classify each requirement's shape, then raise only the
+   categories whose `applies to shapes` intersect that requirement's shapes. A pure-text
+   requirement is never asked about overflow. This is what makes an unresolved edge
+   meaningful: it is an edge that *applies* and was not addressed.
+2. **Dismissal requires a reason string.** "N/A — input is a bounded enum, no boundary
+   exists" is valid; silence is not. The reason string is the audit trail.
+
+Each raised edge carries two orthogonal axes — a resolution **lifecycle** and, when
+resolved, a **verification** tier (ADR-550 Decision 7, the shared probe-core model):
+
+- **status** — `resolved | dismissed | unresolved`:
+  - **resolved** — the edge is addressed; *how* it is addressed is the verification tier.
+  - **dismissed** — not applicable, accompanied by a required, non-empty reason string.
+  - **unresolved** — carried forward and flagged; the author chose not to resolve it yet.
+- **verification** (only when `status` is `resolved`; `null` otherwise) — `explicit | backstop`:
+  - **explicit** — a checkable assertion for the edge is written (a SPEC acceptance criterion).
+  - **backstop** — a held-out / property-based test stands in for an edge the author knows
+    but cannot fully articulate in prose (records intent; the test body is authored later).
+
+Splitting these axes keeps the lifecycle enum free of a verification fact (the old single
+enum smuggled `covered`/`backstop` — both *resolved* — into one flat list) and lets sibling
+probes add their own verification tiers (e.g. `test | judgment`) without a parallel enum.
+
+`coverage.resolved` is the count of **closed** edges — `resolved` + `dismissed` (the
+pre-re-cut "covered + dismissed + backstop" set, count-preserved). An `unresolved`
+*applicable* edge is the precise signal a soft completeness gate raises.
+
+## Output schema
+
+The probe emits, per edge, an item of the form:
+
+```
+{ requirement_id, category, status, verification, resolution, reason, probe }
+```
+
+plus a coverage summary:
+
+```
+coverage: { applicable, resolved, unresolved, byVerification: { explicit, backstop } }
+```
+
+`applicable` is the number of raised edges, `resolved` = closed (`resolved` + `dismissed`)
+status edges, `unresolved` is the remainder, and `byVerification` breaks the
+`resolved`-status edges down by tier (probe-agnostic in core; the edge adapter declares
+`{ explicit, backstop }`). This JSON is the stable contract both the reference
+implementation and any third-party port emit.
+
+## Generic mapping (requirements → checks → verifier)
+
+| Host structure | "requirement" | a `resolved`/`explicit` edge becomes | a `resolved`/`backstop` edge becomes |
+|----------------|---------------|--------------------------|---------------------------|
+| GSD SPEC | a SPEC Requirement | an Acceptance Criterion that `plan-phase` lifts into `must_haves.truths` | a non-inferable check in `must_haves.truths` (needs a held-out/PBT test) |
+| Gherkin feature | a Scenario | an additional `Then` assertion / Scenario Outline row | a tagged scenario routed to a property test |
+| OpenAPI operation | an operation | a response/constraint example + schema rule | a contract/property test on the operation |
+| Docstring contract | a documented behavior | an assertion in the contract test | a property-based test for the function |
+
+The portable invariant: a `resolved`/`explicit` edge produces **the unit your verifier
+iterates over** (GSD: a `must_haves.truth`); a `resolved`/`backstop` edge produces a test
+added to that same set as a non-inferable check. An `unresolved` edge is an explicit
+assumption the downstream planner must surface, not silently drop.
+
+## Worked example (merge-intervals)
+
+Given a single requirement with no resolutions yet:
+
+```
+[{ "id": "R1", "text": "Merge a list of overlapping intervals into the minimal set" }]
+```
+
+the requirement classifies as a `collection`, which raises `adjacency`, `empty`, and
+`ordering` (but not `boundary`/`precision`/`encoding`/`idempotency`/`concurrency`). With no
+resolutions supplied, every applicable edge is `unresolved`:
+
+```json edge-probe:02-merge-intervals/expected-coverage.json
+{
+  "items": [
+    { "requirement_id": "R1", "category": "adjacency", "status": "unresolved", "verification": null, "resolution": null, "reason": null, "probe": "When two things are exactly equal or just touch, do they merge, collide, or separate?" },
+    { "requirement_id": "R1", "category": "empty", "status": "unresolved", "verification": null, "resolution": null, "reason": null, "probe": "What is the result for empty, single-element, or null input?" },
+    { "requirement_id": "R1", "category": "ordering", "status": "unresolved", "verification": null, "resolution": null, "reason": null, "probe": "When elements compare equal, is output order specified and stable?" }
+  ],
+  "coverage": { "applicable": 3, "resolved": 0, "unresolved": 3, "byVerification": { "explicit": 0, "backstop": 0 } }
+}
+```
+
+The `adjacency` row is the one that catches the canonical defect: `[[1,2],[2,3]]` intervals
+that only *touch* — does the spec say they merge? Resolving it `resolved`/`explicit` writes
+that assertion, and the verifier can then enforce it. This worked-example block is kept
+byte-for-byte (parsed-JSON) identical to its fixture by `edge-probe-docs-fixtures.test.cjs`,
+so the doc and the reference implementation cannot silently drift.
+
+## Worked example (round-half-even)
+
+Given a requirement to round floating-point values using the banker's-rounding (half-even)
+rule, the requirement classifies as `numeric-range`, which raises `boundary` and `precision`
+(but not `adjacency`/`empty`/`ordering`/`encoding`/`idempotency`/`concurrency`):
+
+```json edge-probe:01-round-half-even/expected-coverage.json
+{
+  "items": [
+    { "requirement_id": "R1", "category": "boundary", "status": "unresolved", "verification": null, "resolution": null, "reason": null, "probe": "What happens exactly at each min/max/threshold — and one step either side?" },
+    { "requirement_id": "R1", "category": "precision", "status": "unresolved", "verification": null, "resolution": null, "reason": null, "probe": "Where can precision loss, overflow, or rounding/tie-breaking occur — and what is the exact contract (e.g. half-up vs half-to-even, ceil/floor/truncate)?" }
+  ],
+  "coverage": { "applicable": 2, "resolved": 0, "unresolved": 2, "byVerification": { "explicit": 0, "backstop": 0 } }
+}
+```
+
+The `precision` row surfaces the canonical defect for this requirement: IEEE 754 floating-point
+arithmetic rounds 2.5 to 2 (not 3) under half-even — the probe asks whether the spec
+states that contract explicitly, so the verifier can enforce it.
+
+## Worked example (truncate-graphemes)
+
+Given a requirement to truncate a string to N grapheme clusters (not bytes or code points),
+the requirement classifies as `text`, which raises `empty` and `encoding`:
+
+```json edge-probe:03-truncate-graphemes/expected-coverage.json
+{
+  "items": [
+    { "requirement_id": "R1", "category": "empty", "status": "unresolved", "verification": null, "resolution": null, "reason": null, "probe": "What is the result for empty, single-element, or null input?" },
+    { "requirement_id": "R1", "category": "encoding", "status": "unresolved", "verification": null, "resolution": null, "reason": null, "probe": "Whose definition of length/equality applies — bytes, code points, grapheme clusters, or normalized form?" }
+  ],
+  "coverage": { "applicable": 2, "resolved": 0, "unresolved": 2, "byVerification": { "explicit": 0, "backstop": 0 } }
+}
+```
+
+The `encoding` row is the load-bearing one: a requirement that says "truncate to 10
+characters" is ambiguous — the spec must state whether "character" means bytes, UTF-16
+code units, Unicode code points, or grapheme clusters (emoji sequences are 1 grapheme,
+multiple code points).
+
+## Worked example (money-rounding)
+
+Given a requirement to round monetary amounts to two decimal places, the requirement
+classifies as `numeric-range`, which raises `boundary` and `precision`:
+
+```json edge-probe:04-money-rounding/expected-coverage.json
+{
+  "items": [
+    { "requirement_id": "R1", "category": "boundary", "status": "unresolved", "verification": null, "resolution": null, "reason": null, "probe": "What happens exactly at each min/max/threshold — and one step either side?" },
+    { "requirement_id": "R1", "category": "precision", "status": "unresolved", "verification": null, "resolution": null, "reason": null, "probe": "Where can precision loss, overflow, or rounding/tie-breaking occur — and what is the exact contract (e.g. half-up vs half-to-even, ceil/floor/truncate)?" }
+  ],
+  "coverage": { "applicable": 2, "resolved": 0, "unresolved": 2, "byVerification": { "explicit": 0, "backstop": 0 } }
+}
+```
+
+The `boundary` row asks what the minimum and maximum representable values are (negative
+amounts? fractional cents?). The `precision` row asks whether IEEE 754 binary rounding
+can produce `$0.30000000000000004` — the spec must commit to a representation.
+
+## Worked example (list-dedupe)
+
+Given a requirement to deduplicate a list of items, the requirement classifies as
+`collection`, which raises `adjacency`, `empty`, and `ordering`:
+
+```json edge-probe:05-list-dedupe/expected-coverage.json
+{
+  "items": [
+    { "requirement_id": "R1", "category": "adjacency", "status": "unresolved", "verification": null, "resolution": null, "reason": null, "probe": "When two things are exactly equal or just touch, do they merge, collide, or separate?" },
+    { "requirement_id": "R1", "category": "empty", "status": "unresolved", "verification": null, "resolution": null, "reason": null, "probe": "What is the result for empty, single-element, or null input?" },
+    { "requirement_id": "R1", "category": "ordering", "status": "unresolved", "verification": null, "resolution": null, "reason": null, "probe": "When elements compare equal, is output order specified and stable?" }
+  ],
+  "coverage": { "applicable": 3, "resolved": 0, "unresolved": 3, "byVerification": { "explicit": 0, "backstop": 0 } }
+}
+```
+
+The `ordering` row is the non-obvious one: dedupe removes duplicates, but which copy is
+kept — first occurrence, last, or implementation-defined? The spec must commit.
+
+## Worked example (resolved-mixed)
+
+The same merge-intervals requirement after a resolution session where `adjacency` was
+resolved with an explicit acceptance criterion, `ordering` was dismissed, and `empty` was
+left unresolved:
+
+```json edge-probe:06-resolved-mixed/expected-coverage.json
+{
+  "items": [
+    { "requirement_id": "R1", "category": "adjacency", "status": "resolved", "verification": "explicit", "resolution": "AC#6: touching intervals merge", "reason": null, "probe": "When two things are exactly equal or just touch, do they merge, collide, or separate?" },
+    { "requirement_id": "R1", "category": "empty", "status": "unresolved", "verification": null, "resolution": null, "reason": null, "probe": "What is the result for empty, single-element, or null input?" },
+    { "requirement_id": "R1", "category": "ordering", "status": "dismissed", "verification": null, "resolution": null, "reason": "output is canonically sorted; no tie possible", "probe": "When elements compare equal, is output order specified and stable?" }
+  ],
+  "coverage": { "applicable": 3, "resolved": 2, "unresolved": 1, "byVerification": { "explicit": 1, "backstop": 0 } }
+}
+```
+
+`coverage.resolved` is 2 — the closed set (adjacency=`resolved`/`explicit` + ordering=`dismissed`);
+`unresolved` is 1 (empty); `byVerification.explicit` is 1 (the single explicitly-verified
+edge), `backstop` 0. The soft gate raises on this example because one applicable edge remains
+unresolved — the author must either specify, dismiss, or backstop it before writing the SPEC.

package/gsd-core/references/planner-antipatterns.md

@@ -87,3 +87,44 @@ A plan should not interleave multiple checkpoint types with implementation tasks
 - "will be wired later", "dynamic in future phase", "skip for now"
 
 If a decision from CONTEXT.md says "display cost calculated from billing table in impulses", the plan must deliver exactly that. Not "static label /min" as a "v1". If the phase is too complex, recommend a phase split instead of silently reducing scope.
+
+## Comment-Text Discipline (HARD GATE)
+
+> Enforced at plan-write time by `verify.plan-structure` (the `validate_plan` step). Issue #429.
+
+When an `<acceptance_criteria>` or `<verify>` block uses a **negative grep** — `grep -c 'LITERAL' file == 0`, meaning "this literal must NOT appear in the file" — that same `LITERAL` must not appear verbatim anywhere in an `<action>` body. Verbatim code blocks, JSDoc samples, head-comment references, and "what NOT to do" illustrations get echoed into the file the executor writes, so the executor's commit-time gate fails on the *comment text*, not on a real code regression. The work is correct; the gate output is semantically wrong; the executor wastes cycles and learns to distrust the gate.
+
+**The gate:** plan creation FAILS (error, `valid: false`) when a confidently-extracted (quoted) negative-grep literal also appears in an `<action>` block. When the grep literal is unquoted and cannot be extracted unambiguously, the gate WARNS instead of failing (so you still get the plan, with the risk surfaced).
+
+### Bad — JSDoc sample echoes the forbidden literal
+
+```xml
+<task>
+  <action>
+    Add a `?from=` query param to the share link. Do NOT reintroduce the old
+    `?from=` referrer hack the JSDoc warned about.   <!-- echoes ?from= -->
+  </action>
+  <verify><automated>grep -c '?from=' src/animal-detail.tsx == 0</automated></verify>
+</task>
+```
+
+### Good — rephrase the comment by concept
+
+```xml
+<task>
+  <action>
+    Add the share-link query param. Do NOT reintroduce the legacy referrer hack.
+  </action>
+  <verify><automated>grep -c '?from=' src/animal-detail.tsx == 0</automated></verify>
+</task>
+```
+
+### Allowlist escape hatch
+
+When the literal MUST appear in the plan body verbatim — e.g. the plan documents the test file that exercises the gate itself, or the literal is part of the verification command's own grep regex — add a marker on its own line so the gate skips that literal:
+
+```
+<!-- planner-discipline-allow: ?from= -->
+```
+
+One marker per literal. The marker exempts only the exact literal it names.

package/gsd-core/references/planner-guidance.md

@@ -0,0 +1,186 @@
+# Planner Guidance: Philosophy, Task Calibration, and Output Formats
+
+## Solo Developer + Claude Workflow
+
+Planning for ONE person (the user) and ONE implementer (Claude).
+- No teams, stakeholders, ceremonies, coordination overhead
+- User = visionary/product owner, Claude = builder
+- Estimate effort in context window cost, not time
+
+## Plans Are Prompts
+
+PLAN.md IS the prompt (not a document that becomes one). Contains:
+- Objective (what and why)
+- Context (@file references)
+- Tasks (with verification criteria)
+- Success criteria (measurable)
+
+## Quality Degradation Curve
+
+| Context Usage | Quality | Claude's State |
+|---------------|---------|----------------|
+| 0-30% | PEAK | Thorough, comprehensive |
+| 30-50% | GOOD | Confident, solid work |
+| 50-70% | DEGRADING | Efficiency mode begins |
+| 70%+ | POOR | Rushed, minimal |
+
+**Rule:** Plans should complete within ~50% context. More plans, smaller scope, consistent quality. Each plan: 2-3 tasks max.
+
+## Ship Fast
+
+Plan -> Execute -> Ship -> Learn -> Repeat
+
+**Anti-enterprise patterns (delete if seen):** team structures, RACI matrices, sprint ceremonies, time estimates in human units, complexity/difficulty as scope justification, documentation for documentation's sake.
+
+---
+
+## Task Types
+
+| Type | Use For | Autonomy |
+|------|---------|----------|
+| `auto` | Everything Claude can do independently | Fully autonomous |
+| `checkpoint:human-verify` | Visual/functional verification | Pauses for user |
+| `checkpoint:decision` | Implementation choices | Pauses for user |
+| `checkpoint:human-action` | Truly unavoidable manual steps (rare) | Pauses for user |
+
+**Automation-first rule:** If Claude CAN do it via CLI/API, Claude MUST do it. Checkpoints verify AFTER automation, not replace it.
+
+## Task Sizing
+
+Each task targets **10–30% context consumption**.
+
+| Context Cost | Action |
+|--------------|--------|
+| < 10% context | Too small — combine with a related task |
+| 10-30% context | Right size — proceed |
+| > 30% context | Too large — split into two tasks |
+
+**Context cost signals (use these, not time estimates):**
+- Files modified: 0-3 = ~10-15%, 4-6 = ~20-30%, 7+ = ~40%+ (split)
+- New subsystem: ~25-35%
+- Migration + data transform: ~30-40%
+- Pure config/wiring: ~5-10%
+
+**Too large signals:** Touches >3-5 files, multiple distinct chunks, action section >1 paragraph.
+
+**Combine signals:** One task sets up for the next, separate tasks touch same file, neither meaningful alone.
+
+## Interface-First Task Ordering
+
+When a plan creates new interfaces consumed by subsequent tasks:
+
+1. **First task: Define contracts** — Create type files, interfaces, exports
+2. **Middle tasks: Implement** — Build against the defined contracts
+3. **Last task: Wire** — Connect implementations to consumers
+
+This prevents the "scavenger hunt" anti-pattern where executors explore the codebase to understand contracts. They receive the contracts in the plan itself.
+
+## Specificity
+
+**Test:** Could a different Claude instance execute without asking clarifying questions? If not, add specificity. See @~/.claude/gsd-core/references/planner-antipatterns.md for vague-vs-specific comparison table.
+
+## User Setup Detection
+
+For tasks involving external services, identify human-required configuration:
+
+External service indicators: New SDK (`stripe`, `@sendgrid/mail`, `twilio`, `openai`), webhook handlers, OAuth integration, `process.env.SERVICE_*` patterns.
+
+For each external service, determine:
+1. **Env vars needed** — What secrets from dashboards?
+2. **Account setup** — Does user need to create an account?
+3. **Dashboard config** — What must be configured in external UI?
+
+Record in `user_setup` frontmatter. Only include what Claude literally cannot do. Do NOT surface in planning output — execute-plan handles presentation.
+
+---
+
+## Building the Dependency Graph
+
+**For each task, record:**
+- `needs`: What must exist before this runs
+- `creates`: What this produces
+- `has_checkpoint`: Requires user interaction?
+
+**Example:** A→C, B→D, C+D→E, E→F(checkpoint). Waves: {A,B} → {C,D} → {E} → {F}.
+
+**Prefer vertical slices** (User feature: model+API+UI) over horizontal layers (all models → all APIs → all UIs). Vertical = parallel. Horizontal = sequential. Use horizontal only when shared foundation is required.
+
+## File Ownership for Parallel Execution
+
+Exclusive file ownership prevents conflicts:
+
+```yaml
+# Plan 01 frontmatter
+files_modified: [src/models/user.ts, src/api/users.ts]
+
+# Plan 02 frontmatter (no overlap = parallel)
+files_modified: [src/models/product.ts, src/api/products.ts]
+```
+
+No overlap → can run parallel. File in multiple plans → later plan depends on earlier.
+
+---
+
+## Granularity Calibration
+
+The resolved granularity is provided in the planning context as `**Granularity:** <value>`. Read that value and apply the corresponding row below. When no explicit value is present, default to Standard.
+
+| Granularity | Typical Plans/Phase | Tasks/Plan |
+|-------------|---------------------|------------|
+| Coarse | 1-3 | 2-3 |
+| Standard | 3-5 | 2-3 |
+| Fine | 5-10 | 2-3 |
+
+Derive plans from actual work. Granularity determines compression tolerance, not a target.
+
+---
+
+## Planning Complete Return Format
+
+```markdown
+## PLANNING COMPLETE
+
+**Phase:** {phase-name}
+**Plans:** {N} plan(s) in {M} wave(s)
+
+### Wave Structure
+
+| Wave | Plans | Autonomous |
+|------|-------|------------|
+| 1 | {plan-01}, {plan-02} | yes, yes |
+| 2 | {plan-03} | no (has checkpoint) |
+
+### Plans Created
+
+| Plan | Objective | Tasks | Files |
+|------|-----------|-------|-------|
+| {phase}-01 | [brief] | 2 | [files] |
+| {phase}-02 | [brief] | 3 | [files] |
+
+### Next Steps
+
+Run `/clear` first for a fresh context window, then execute: `/gsd:execute-phase {phase}`
+```
+
+## Gap Closure Plans Created Return Format
+
+```markdown
+## GAP CLOSURE PLANS CREATED
+
+**Phase:** {phase-name}
+**Closing:** {N} gaps from {VERIFICATION|UAT}.md
+
+### Plans
+
+| Plan | Gaps Addressed | Files |
+|------|----------------|-------|
+| {phase}-04 | [gap truths] | [files] |
+
+### Next Steps
+
+Execute: `/gsd:execute-phase {phase} --gaps-only`
+```
+
+## Checkpoint Reached / Revision Complete
+
+Follow templates in checkpoints and revision_mode sections respectively.

package/gsd-core/references/planner-reviews.md

@@ -4,6 +4,8 @@ Triggered when orchestrator sets Mode to `reviews`. Replanning from scratch with
 
 **Mindset:** Fresh planner with review insights — not a surgeon making patches, but an architect who has read peer critiques.
 
+**Execution contract:** REVIEWS.md is audit trail and feedback input, not a second execution contract. /gsd:execute-phase primarily consumes PLAN.md plus the normal phase context. Every current actionable review finding must therefore be incorporated into the relevant PLAN.md or explicitly deferred/rejected in that PLAN.md.
+
 ### Step 1: Load REVIEWS.md
 Read the reviews file from `<files_to_read>`. Parse:
 - Per-reviewer feedback (strengths, concerns, suggestions)
@@ -13,13 +15,14 @@ Read the reviews file from `<files_to_read>`. Parse:
 ### Step 2: Categorize Feedback
 Group review feedback into:
 - **Must address**: HIGH severity consensus concerns
-- **Should address**: MEDIUM severity concerns from 2+ reviewers
+- **Must represent in PLAN.md**: actionable MEDIUM/LOW findings that require task, action, acceptance criteria, verify command, must_haves, threat-model, artifact, stale-path, or execution-contract changes
+- **Should address**: MEDIUM severity concerns from 2+ reviewers that improve quality but do not change the executable contract
 - **Consider**: Individual reviewer suggestions, LOW severity items
 
 ### Step 3: Plan Fresh with Review Context
 Create new plans following the standard planning process, but with review feedback as additional constraints:
 - Each HIGH severity consensus concern MUST have a task that addresses it
-- MEDIUM concerns should be addressed where feasible without over-engineering
+- Each current actionable MEDIUM/LOW finding MUST either appear in the relevant PLAN.md executable content or have a deferral/rejection rationale in that PLAN.md
 - Note in task actions: "Addresses review concern: {concern}" for traceability
 
 ### Step 4: Return

package/gsd-core/templates/phase-prompt.md

@@ -568,12 +568,12 @@ must_haves:
       contains: "model Message"
   key_links:
     - from: "src/components/Chat.tsx"
-      to: "/api/chat"
-      via: "fetch in useEffect"
+      to: "src/app/api/chat/route.ts"
+      via: "fetch in useEffect — calls /api/chat endpoint"
       pattern: "fetch.*api/chat"
     - from: "src/app/api/chat/route.ts"
-      to: "prisma.message"
-      via: "database query"
+      to: "prisma/schema.prisma"
+      via: "database query via prisma.message"
       pattern: "prisma\\.message\\.(find|create)"
 ```
 
@@ -589,9 +589,9 @@ must_haves:
 | `artifacts[].exports` | Optional. Expected exports to verify. |
 | `artifacts[].contains` | Optional. Pattern that must exist in file. |
 | `key_links` | Critical connections between artifacts. |
-| `key_links[].from` | Source artifact. |
-| `key_links[].to` | Target artifact or endpoint. |
-| `key_links[].via` | How they connect (description). |
+| `key_links[].from` | Source file (relative path from project root). Describe components or symbols in `via:`. |
+| `key_links[].to` | Target file (relative path from project root). Describe endpoints, APIs, or modules in `via:`. |
+| `key_links[].via` | How they connect, including any endpoint or symbol name (e.g. `fetch in useEffect — calls /api/chat`, `Prisma query via prisma.message`). |
 | `key_links[].pattern` | Optional. Regex to verify connection exists. |
 
 **Why this matters:**