@opengsd/gsd-core 1.12.0 → 1.14.0

package/gsd-core/references/planner-quick-batch.md

@@ -0,0 +1,71 @@
+# Quick-Batch Mode — Planner Reference
+
+Triggered when `<planning_context>` declares `**Mode:** quick-batch`
+(#3676, epic #3344, ADR-1239 "Quick-batch binding"). One dispatch = one
+item's plan — the SAME single-plan, 1-3-task scope as `/gsd:quick`'s own
+`quick`/`quick-full` modes, with one fixed difference: **`depends_on` and
+`files_modified` frontmatter are ALWAYS required, regardless of whether
+`--validate` was requested.** This reuses the EXISTING frontmatter grammar
+(the same keys full phase planning already emits — see the frontmatter
+schema table above); it is not a new schema.
+
+**Why always, not gated on `--validate`.** The coordinating workflow
+(`gsd-core/workflows/quick-batch.md`) recomputes every item's execution wave
+from these two fields after each DAG layer's planners return (`quick-batch
+update`, wrapping `updateBatchItems`) — without them, every item stays in
+wave 0 forever and the batch cannot parallelize independent items or
+sequence dependent ones correctly. This is load-bearing dispatch input, not
+an optional quality signal.
+
+### `depends_on` — reference SIBLING items by `quick_id`, never invent one
+
+The `<planning_context>` you receive includes a **full batch task catalog** —
+every item's `quick_id` + description, not just your own. When your item's
+implementation genuinely requires another item's item to land first (shared
+file, prerequisite API, sequencing the user implied), declare it:
+
+```yaml
+depends_on: ["260101-abc"]   # a quick_id from the task catalog
+```
+
+- Reference ONLY `quick_id`s from the task catalog you were given. Never
+  reference a plan id from a phase, another batch, or a value you invented.
+- Empty array (`depends_on: []`) is the correct, common answer when your item
+  is genuinely independent — do not manufacture a dependency to seem
+  thorough.
+- A dependency on your OWN `quick_id` (self-reference) or on an id outside
+  the catalog is rejected by `quick-batch update` and blocks the whole
+  layer's persistence — when uncertain, prefer `[]` over a guess.
+
+### `files_modified` — every path your plan's tasks will touch
+
+```yaml
+files_modified: ["src/foo.ts", "tests/foo.test.ts"]
+```
+
+Used two ways downstream, both from THIS field (never re-derived from your
+plan's prose): (1) `partitionByFileOverlap` splits same-wave items that
+would touch the same file into separate waves, so two isolated worktrees
+never race on one path; (2) at merge time the coordinator reads it FRESH from
+your PLAN.md (not from what you declared here at planning time — keep the
+frontmatter accurate if you revise the plan) for the advisory scope-
+conformance check.
+
+### `files_deleted` — only if your plan removes a file
+
+```yaml
+files_deleted: ["legacy/old-module.ts"]
+```
+
+Optional; omit entirely when your plan deletes nothing. If your plan DOES
+delete a file and you omit this, the merge's deletions guard blocks that
+deletion as undeclared — there is no "authorize everything" fallback.
+
+### What quick-batch mode does NOT need
+
+Same exclusions as `/gsd:quick`'s own modes: no `requirements` (no ROADMAP
+linkage — a quick-batch item is not a phase), no `estimate` block, no
+`user_setup` unless genuinely needed. `must_haves` is required only when the
+calling prompt's own `<constraints>` says so (mirrors `--validate`'s
+existing quick-full behavior) — that instruction rides the prompt, not this
+reference.

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

@@ -40,3 +40,50 @@ Use standard PLANNING COMPLETE return format, adding a reviews section:
 |---------|--------|
 | {concern} | {why — out of scope, disagree, etc.} |
 ```
+
+### Step 5: Write the ledger into PLAN.md (#3806)
+
+The two tables above are not only the planner's return payload — they are also the **canonical
+Review Dispositions Ledger**, and they belong in the affected PLAN.md itself, in this exact shape.
+`gsd-core/workflows/plan-phase.md` (`<review_incorporation_contract>`) and
+`agents/gsd-plan-checker.md` (Review Incorporation dimension) both point back to this section for
+the ledger's shape rather than restating it — this is the one place it is defined.
+
+## Review Dispositions Ledger
+
+Add or extend a `## Review Dispositions Ledger` section in the affected PLAN.md, containing one
+`### Round {N} — {REVIEWS_sha}` subsection per reviews-mode round that touched this plan, where
+`{REVIEWS_sha}` is the commit that wrote the REVIEWS.md snapshot being ruled on (the short sha from
+`git log -1 --format=%h -- <phase_dir>/<NN>-REVIEWS.md`, after `workflows/review.md`'s REVIEWS.md
+commit step). Under each round heading, use the two tables from Step 4 above, unchanged in shape:
+
+```markdown
+## Review Dispositions Ledger
+
+### Round 1 — a1b2c3d
+
+### Review Feedback Addressed
+| Concern | Severity | How Addressed |
+|---------|----------|---------------|
+| {concern} | HIGH | Plan {N}, Task {M}: {how} |
+
+### Review Feedback Deferred
+| Concern | Reason |
+|---------|--------|
+| {concern} | {why — out of scope, disagree, etc.} |
+```
+
+**Anchoring.** Any reference to a specific REVIEWS.md line cites `L##@{REVIEWS_sha}` (e.g.
+`L32@a1b2c3d`) — a bare line number is meaningless once the next round rewrites REVIEWS.md
+wholesale. `{Concern}` and `{Reason}` stay free text; do not invent a reviewer/severity enum — the
+reviewer roster is capability-owned and open to third-party additions (see each capability's
+`reviewer.reviewsSection`).
+
+**Append-only.** A later round never edits or deletes a prior round's tables. To overturn a prior
+round's verdict, add a new row in the current round's table whose Reason/How Addressed names the
+round and concern it supersedes (e.g. "Supersedes Round 1 Deferred: {concern} — now addressed in
+Plan 3").
+
+**Out of scope for this contract.** A deterministic lint/check verb that mechanically enforces this
+shape is a separate, later addition (#3806 part 2) — this section defines the format only. Legacy
+PLAN.md content written before this convention existed is not migrated or flagged by it.

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

@@ -21,12 +21,43 @@ issues:
   - plan: "16-01"
     dimension: "task_completeness"
     severity: "blocker"
+    required_property: "Every `auto` task has a `<verify>` separating pass from fail"
     description: "Task 2 missing <verify> element"
     fix_hint: "Add verification command for build output"
 ```
 
 Group by plan, dimension, severity.
 
+**What binds and what does not.** `required_property` (the invariant that must hold),
+`description` (the evidence it does not) and `severity` are binding. `fix_hint` is **one
+example** of a route to that property — an illustration, never an instruction. You address an
+issue by making `required_property` true; the hint's own mechanism is optional.
+
+An older checker may return an issue with no `required_property`. Derive it from `dimension`
++ `description` and state the derived property in your revision summary. Never treat the
+absence of the field as licence to apply `fix_hint` literally.
+
+**Prefer the smallest sufficient mechanism.** If a smaller change than the hint makes
+`required_property` true, take it — that fully addresses the issue and must be reported as
+addressed, naming the property satisfied and the mechanism used.
+
+### Step 2.5: Constraint Re-check (before any edit)
+
+Before editing, re-read the constraints already in force:
+
+- Locked decisions in CONTEXT.md (`## Decisions`) and deferred ideas (`## Deferred Ideas`)
+- Active capability / project guidance (CLAUDE.md, `.claude/skills/`, `.agents/skills/`)
+- Constraints the existing plans already encode (chosen mechanism, scope boundary, must_haves)
+
+A `fix_hint` conflicts when applying it would contradict any of those. Applying it anyway is
+a contract violation, not a judgement call. When a hint conflicts — or when the property is
+unreachable without breaking a constraint — do NOT edit around it and do NOT burn a revision
+iteration on it: emit `## REVISION_CONFLICT` (Step 7) for that issue, apply every
+non-conflicting issue normally, and return.
+
+A hint that merely proposes a *bigger* mechanism than needed is not a conflict. Take the
+smaller route under Step 2 and report it as addressed.
+
 ### Step 3: Revision Strategy
 
 | Dimension | Strategy |
@@ -38,15 +69,25 @@ Group by plan, dimension, severity.
 | scope_sanity | Split into multiple plans |
 | must_haves_derivation | Derive and add must_haves to frontmatter |
 
+Each strategy is the usual route, not the only one. Any change that makes the issue's
+`required_property` true is a valid strategy.
+
 ### Step 4: Make Targeted Updates
 
 **DO:** Edit specific flagged sections, preserve working parts, update waves if dependencies change.
+Choose the smallest mechanism that makes each issue's `required_property` true — explicitly
+including a mechanism smaller than, or different from, the one its `fix_hint` names.
 
-**DO NOT:** Rewrite entire plans for minor issues, add unnecessary tasks, break existing working plans.
+**DO NOT:** Rewrite entire plans for minor issues, add unnecessary tasks, break existing working
+plans, or apply a `fix_hint` that contradicts a constraint from Step 2.5 — that one goes to
+`## REVISION_CONFLICT` instead.
 
 ### Step 5: Validate Changes
 
-- [ ] All flagged issues addressed
+- [ ] Every flagged issue's `required_property` now holds — reached by its `fix_hint` OR by a
+      smaller/different mechanism (both count as addressed), OR raised as `## REVISION_CONFLICT`
+- [ ] No `fix_hint` applied that contradicts a locked decision, capability guidance, or an
+      existing plan constraint (Step 2.5)
 - [ ] No new issues introduced
 - [ ] Wave numbers still valid
 - [ ] Dependencies still correct
@@ -85,3 +126,35 @@ gsd_run query commit "fix($PHASE): revise plans based on checker feedback" --fil
 |-------|--------|
 | {issue} | {why - needs user input, architectural change, etc.} |
 ```
+
+### Step 7b: Return Revision Conflict (when Step 2.5 found one)
+
+Emit this INSTEAD OF `## REVISION COMPLETE` when at least one issue could not be addressed
+without contradicting a constraint. Non-conflicting issues you already fixed stay listed under
+`### Changes Made` so the work is not lost. The orchestrator routes this to the user or to the
+configured plan-review convergence loop; it does not count as a failed revision iteration.
+
+```markdown
+## REVISION_CONFLICT
+
+**Conflicts:** {N}  |  **Issues addressed anyway:** {M}
+
+| Issue | required_property | Conflicts with | Why the hint cannot be applied |
+|-------|-------------------|----------------|-------------------------------|
+| {dimension}/{plan} | {property} | {locked decision D-nn / CLAUDE.md rule / plan constraint} | {one line} |
+
+### Alternatives Considered
+
+| Issue | Alternative | Satisfies required_property? | Cost of adopting |
+|-------|-------------|------------------------------|------------------|
+| {dimension}/{plan} | {smaller or different mechanism} | {yes / partially — how} | {what it changes} |
+
+### Changes Made
+
+{table of the non-conflicting issues you DID address, same shape as REVISION COMPLETE}
+```
+
+**Every field is one line of plain text.** No newlines inside a cell, and never begin a field with
+`#`, `-`, `|` or a code fence. These fields are appended to a shared markdown file that a later
+reader scans by heading; a field that starts a heading truncates that scan and hides conflicts
+below it.

package/gsd-core/references/planning-config.md

@@ -289,6 +289,7 @@ Set via `workflow.*` namespace in config.json (e.g., `"workflow": { "research":
 | `workflow.ui_phase` | boolean | `true` | `true`, `false` | Generate UI-SPEC.md for frontend phases |
 | `workflow.ui_safety_gate` | boolean | `true` | `true`, `false` | Require safety gate approval for UI changes |
 | `workflow.text_mode` | boolean | `false` | `true`, `false` | Use plain-text numbered lists instead of AskUserQuestion menus |
+| `workflow.compact_content` | boolean | `false` | `true`, `false` | Compact content mode (#4139, ADR-4139) — per-project boolean selecting terser payloads. Six workflows branch on it via spine+detail: `plan-phase` (#4402, pilot), `execute-phase`, `docs-update`, `new-project`, `verify-work`, `complete-milestone` (#4405). The rest of the eager-window corpus was reviewed and recorded as not worth splitting (`docs/PARTITION-RULES.md`). Lazily-`Read` workflow fragments and `gsd-core/templates/**` templates use a `.compact.md` sibling instead (#4406, `gsd-core/references/compact-content-gate.md` § "Streams 1b and 4") — wired today for `help --full` and the sequential-execution `SUMMARY.md`/`USER-SETUP.md` reads. Agent-skill payloads (#4407, § "Stream 2") use the same `.compact.md` sibling shape, resolved in code by the `gsd_run query agent-skills` CLI seam rather than prose, for the non-Claude persona fallback only |
 | `workflow.research_before_questions` | boolean | `false` | `true`, `false` | Run research before interactive questions in discuss phase (also honored on the `/gsd:quick` path, #3894). _Alias:_ `research_before_questions` is the flat-key form used in `CONFIG_DEFAULTS`; `workflow.research_before_questions` is the canonical namespaced form. |
 | `workflow.discuss_mode` | string | `"discuss"` | `"discuss"`, `"assumptions"` | Default mode for discuss-phase: `"discuss"` runs interactive questioning; `"assumptions"` analyzes codebase and surfaces assumptions instead |
 | `workflow.skip_discuss` | boolean | `false` | `true`, `false` | Skip discuss phase entirely |
@@ -299,7 +300,7 @@ Set via `workflow.*` namespace in config.json (e.g., `"workflow": { "research":
 | `workflow.build_command` | string\|null | `null` | Any shell command | Build gate command run by the post-merge gate. Unset → build step auto-detected/skipped. |
 | `workflow.mvp_mode` | boolean | `false` | `true`, `false` | Persist the MVP-mode flag in config so every phase defaults to MVP framing without requiring `--mvp` on the CLI. Resolved via the chain: `--mvp` CLI flag → ROADMAP.md `**Mode:** mvp` field → this config value → `false`. When `true`, the planner, executor, verifier, and discovery surfaces (progress, stats, graphify) all treat the phase as an MVP vertical slice (UI → API → DB) of one user-visible capability. |
 | `workflow.context_guard_mode` | string | `"warn"` | `"auto"`, `"warn"`, `"off"` | Context exhaustion guard mode for `execute-phase`. Before each wave, the orchestrator self-assesses context pressure using degradation signals from `context-budget.md`. `"warn"` (default): emit a warning and recommend `/gsd:pause-work` when POOR tier is detected. `"auto"`: automatically invoke `/gsd:pause-work` before the next wave when POOR tier is detected. `"off"`: disable the guard. The guard is heuristic — no programmatic context-% API exists. |
-| `workflow.plan_chunked` | boolean | `false` | `true`, `false` | Enable chunked planning mode. When `true`, the plan-phase orchestrator splits the single long-lived planner Task into a short outline Task followed by N short per-plan Tasks (~3–5 min each). Each plan is committed individually for crash resilience. Particularly useful on Windows where long-lived Tasks may hang on stdio. Also activated by the `--chunked` flag. |
+| `workflow.plan_chunked` | boolean | `false` | `true`, `false` | Enable chunked planning mode. When `true`, the plan-phase orchestrator splits the single long-lived planner Task into a short outline Task followed by N short per-plan Tasks (~3–5 min each). Each plan is committed individually for crash resilience. Particularly useful on Windows where long-lived Tasks may hang on stdio. Also activated by the `--chunked` flag. See `planning.chunked_parallel` below for concurrent per-plan dispatch. |
 | `workflow.specless_probe_fallback` | boolean | `true` | `true`, `false` | Gate the SPEC-less probe fallback in `plan-phase`. When `true` (default), a phase that did not supply a `## Edge Coverage` / `## Prohibitions` SPEC section (header absent or present-but-empty) runs the existing probe protocol — the deterministic `edge-probe.cjs` for edges and an in-planner LLM recall pass for prohibitions — and authors the resulting predicates into PLAN.md `must_haves` (section-level precedence: a SPEC-supplied section is never re-run or overwritten). When `false`, the fallback is skipped but the skip is recorded: plan-phase emits a visible "probe fallback disabled" marker, never a silent skip. |
 | `workflow.code_review_command` | string\|null | `null` | Any shell command | External code-review command integrated into `/gsd:ship`. The diff is piped to the command via stdin; the command must output JSON with a `verdict` field (`"APPROVED"` or `"REVISE"`). Non-zero exit or `"REVISE"` verdict blocks the ship workflow. When unset, the built-in review flow runs. Example: `my-review-tool --review`. |
 | `workflow.inline_plan_threshold` | number | `2` | `0`–`10` | Plans with ≤N tasks execute inline instead of spawning a subagent |
@@ -360,6 +361,8 @@ Set via `hooks.*` namespace (e.g., `"hooks": { "context_warnings": true }`).
 | Key | Type | Default | Allowed Values | Description |
 |-----|------|---------|----------------|-------------|
 | `hooks.context_warnings` | boolean | `true` | `true`, `false` | Show warnings when context budget is exceeded |
+| `hooks.context_warning_threshold` | number | `35` | Greater than 0 and at most 100, and strictly greater than `hooks.context_critical_threshold`. `config-set` refuses 0: nothing is below it, so no critical value could satisfy the pair | Percent of context window REMAINING at or below which the monitor emits CONTEXT WARNING. An out-of-domain value falls back **per key**; both keys revert to their defaults only when the RESOLVED pair violates `critical < warning`. Read from the root project config — a workstream-scoped `config-set` does not reach this hook. Inert on a runtime with no context-monitor hook installed, Codex among them (#2586); see [context-monitor.md](../../docs/context-monitor.md) (#4285) |
+| `hooks.context_critical_threshold` | number | `25` | At least 0 and less than 100, and strictly less than `hooks.context_warning_threshold`. `config-set` refuses 100: nothing is above it, so no warning value could satisfy the pair | Percent of context window REMAINING at or below which the monitor escalates to CONTEXT CRITICAL. Setting only one of the pair is checked against the other's default, so tune both when moving either past the other. Same root-config scope, and the same installed-monitor prerequisite, as the key above (#4285) |
 
 ### Learnings Fields
 
@@ -404,6 +407,7 @@ These can be set at top level or nested under `planning.*` (e.g., `"planning": {
 |-----|------|---------|----------------|-------------|
 | `planning.commit_docs` | boolean | `true` | `true`, `false` | Alias for top-level `commit_docs` |
 | `planning.search_gitignored` | boolean | `false` | `true`, `false` | Alias for top-level `search_gitignored` |
+| `planning.chunked_parallel` | boolean | `false` | `true`, `false` | Opt-in for `workflow.plan_chunked`'s per-plan loop (§8.5.2 of `chunked-planning-mode.md`, #3777). When `true`, the runnable per-plan planners within one outline Wave are dispatched concurrently (one message, `run_in_background=true` each) instead of one at a time, honoring the outline's Wave column as the schedule (`Depends On` is expected to name only an earlier Wave and is not separately parsed — batching strictly by Wave already respects it). Gated on the negotiated `dispatch-capacity` query (#3673): a host that declares no `maxConcurrency` (capacity resolves to `1`) stays serial regardless of this setting. Default `false` is byte-identical to the pre-#3777 serial loop. Trade-off: per-plan commits interleave within a batch instead of strictly one-at-a-time, and a stalled plan's retry no longer blocks sibling plans in the same batch from having already committed. |
 
 ---
 

package/gsd-core/references/response-language-directive.md

@@ -0,0 +1,9 @@
+# Response-Language Directive (#2529)
+
+**If `response_language` is set** (in the init JSON this workflow parses, or in `.planning/config.json`): ALL user-facing output of this workflow MUST be in that language — narration between tool calls, status updates, progress notes, findings, banners, report prose, questions (AskUserQuestion or plain text), and summaries. Technical terms, code, file paths, commands, and identifiers stay in English.
+
+Literal English report/banner templates embedded in a workflow are a structural SOURCE, not literal output to copy verbatim — render their prose translated into `{response_language}` while keeping headings' structural markers, table columns, IDs, commands, and file paths unchanged. Exception: blocks a workflow explicitly requires to be emitted byte-for-byte (e.g. pre-rendered checkpoints) are output exactly as rendered.
+
+Pass `response_language: {value}` into every spawned subagent prompt so any user-facing output they produce stays in the configured language.
+
+Workflows take this contract in one of three forms (REQ-LANG-03): an `@`-reference to this file; their own inline directive naming the same narration class; or, for a fragment loaded by a covered parent, inheritance from that parent. Coverage is enforced by `scripts/lint-response-language-coverage.cjs` — a new workflow cannot ship without one of the three, and the lint checks this file's own wording too, so a weakened directive here uncovers every workflow that imports it rather than passing silently. Workflow-specific directives (e.g. `execute-phase-response-language.md`) take precedence where present.

package/gsd-core/references/revision-loop.md

@@ -16,6 +16,8 @@ This pattern applies whenever:
 ```
 prev_issue_count = Infinity
 iteration = 0
+previous_conflict_property = null
+conflict_return_count = 0
 
 LOOP:
   1. Run checker/validator on current output
@@ -23,15 +25,30 @@ LOOP:
   3. If PASSED or only INFO-level issues:
      -> Accept output, exit loop
   4. If BLOCKER or WARNING issues found:
-     a. iteration += 1
-     b. If iteration > 3:
+     a. If iteration + 1 > 3:
         -> Escalate to user (see "After 3 Iterations" below)
-     c. Parse issue count from checker output
-     d. If issue_count >= prev_issue_count:
+     b. Parse issue count from checker output
+     c. If issue_count >= prev_issue_count:
         -> Escalate to user: "Revision loop stalled (issue count not decreasing)"
-     e. prev_issue_count = issue_count
-     f. Re-spawn the producing agent with checker feedback appended
-     g. After revision completes, go to LOOP
+     d. prev_issue_count = issue_count
+     e. Re-spawn the producing agent with checker feedback appended
+     f. If the agent returns REVISION_CONFLICT:
+        -> conflict_return_count += 1
+        -> If conflict_return_count >= 3:
+             escalate through the iteration-cap gate
+        -> If it names the same required_property as the previous conflict:
+             escalate as a stall (the resolution did not take)
+           Else: previous_conflict_property = current required_property
+             resolve it (see "Conflict Return" below) and go to step e.
+             Do NOT increment iteration -- the conflict was not a failed attempt.
+        Else: previous_conflict_property = null (a normal revision ends the conflict chain --
+             a LATER, unrelated conflict on the same property must not be misread as a repeat)
+     g. iteration += 1
+     h. After revision completes, go to LOOP
+
+The increment is step g, AFTER the producing agent returns. An iteration counted at step a is
+already spent by the time a REVISION_CONFLICT comes back, so it cannot then be withheld, and the
+cap would punish the agent for correctly refusing to apply incompatible advice.
 ```
 
 ### Issue Count Tracking
@@ -45,19 +62,38 @@ Display iteration progress before each revision spawn:
 
 When re-spawning the producing agent for revision, pass the checker's YAML-formatted issues. The checker's output contains a `## Issues` heading followed by a YAML block. Parse this block and pass it verbatim to the revision agent.
 
+The field names are the plan-checker's schema (`agents/gsd-plan-checker.md` → `<issue_structure>`):
+`plan`, `dimension`, `severity`, `required_property`, `description`, `task`, `fix_hint`. There is no
+`suggested_fix` field and no `finding` or `affected_field` field — those names were drift, and every
+producer now emits the schema above.
+
 ```
 <checker_issues>
-The issues below are in YAML format. Each has: dimension, severity, finding,
-affected_field, suggested_fix. Address ALL BLOCKER issues. Address WARNING
-issues where feasible.
+The issues below are in YAML format. Each has: dimension, severity,
+required_property, description, fix_hint.
+
+BINDING: required_property (the invariant that must hold), description (the
+evidence it does not), severity. NON-BINDING: fix_hint -- ONE example route to
+the property, never an instruction.
+
+Satisfy the required_property of ALL BLOCKER issues. Satisfy WARNING issues
+where feasible.
 
 {YAML issues block from checker output -- passed verbatim}
 </checker_issues>
 
 <revision_instructions>
 Address ALL BLOCKER and WARNING issues identified above.
-- For each BLOCKER: make the required change
+- For each BLOCKER: make required_property true. Its fix_hint is one example
+  route; a smaller or different mechanism that makes the same property true
+  addresses the issue in full -- report which mechanism you used.
 - For each WARNING: address or explain why it's acceptable
+- Before editing, re-check locked decisions, active capability guidance, and
+  constraints the existing output already encodes. If a fix_hint would
+  contradict one of those, or the property is unreachable without breaking one,
+  do NOT apply it and do NOT work around it: return REVISION_CONFLICT naming
+  the conflict and the alternatives considered, having addressed every
+  non-conflicting issue.
 - Do NOT introduce new issues while fixing existing ones
 - Preserve all content not flagged by the checker
 This is revision iteration {N} of max 3. Previous iteration had {prev_count}
@@ -65,6 +101,75 @@ issues. You must reduce the count or the loop will terminate.
 </revision_instructions>
 ```
 
+### Conflict Return (REVISION_CONFLICT)
+
+A revision agent that returns `REVISION_CONFLICT` has not failed and has not stalled. Handle it
+BEFORE the iteration counter and the stall check — a conflict is not resolvable by re-running the
+same loop, so spending retry budget on it only exhausts the cap:
+
+**This protocol is shared.** Every revision-bearing workflow follows it — `plan-phase`, `quick`,
+`ui-phase`, and `verify-work`'s gap-plan loop. `plan-phase` @-imports this reference and states
+only its own bindings (counter name, artifact path, next step). The other three do not import it,
+so they restate the operative rules inline; this section is the authority they must agree with.
+
+1. **Do not spend budget.** Do NOT increment the iteration counter and do NOT update
+   `prev_issue_count`. Do NOT re-spawn the checker yet — the conflict is not a revised output.
+2. **Record**, where the host has a channel an arbitration loop reads. `review.md` emits one
+   fixed writer-owned slot immediately after the artifact title, between
+   `<!-- gsd:plan-revision-conflicts:begin -->` and
+   `<!-- gsd:plan-revision-conflicts:end -->`. When `workflow.plan_review_convergence` is enabled
+   and the phase `*-REVIEWS.md` already exists, `plan-phase` appends one line per conflict under
+   `## Plan-Revision Conflicts` inside that slot:
+
+```markdown
+- [ ] REVISION_CONFLICT {dimension}/{plan} — required_property: {property} | conflicts with: {locked decision D-nn / CLAUDE.md rule / plan constraint} | alternatives: {the agent's alternatives}
+```
+
+   A checkbox, not a table row: `- [ ] REVISION_CONFLICT` is open and `- [x] REVISION_CONFLICT`
+   is resolved. The reader counts matching open lines only inside the first fixed slot after the
+   artifact title; an identical marker in reviewer output is not state. An open line in the owned
+   slot blocks convergence even if this run is abandoned.
+   A workflow with no such channel (`quick` has no phase and no REVIEWS.md) skips this step.
+
+   Before appending, reuse the existing open line instead of appending a duplicate when its
+   sanitized fields identify the same conflict. This makes persisted conflict state idempotent.
+
+   **Sanitize before writing — the conflict text is agent-authored.** Every field comes from the
+   producing agent. Before appending, for EACH field: collapse every newline and tab to a single
+   space, and strip any leading `#`, `-`, `|` or backtick-fence run. Otherwise an embedded
+   newline can forge an extra conflict-shaped record inside the owned slot. One conflict is exactly
+   one line beginning `- [ ]`. Never append agent text verbatim, and never append a fenced block.
+3. **Resolve** — present the conflict and its alternatives to the user and ask which to take
+   (pattern: `gsd-core/references/gate-prompts.md`): adopt a named alternative / override the
+   named constraint and apply the hint / amend the constraint itself. Each option resolves the
+   conflict. Accepting the output with the blocker still open is NOT offered here — the blocking
+   `required_property` still fails, and that choice belongs to the cap escalation.
+4. **Close** — the workflow that wrote the line owns flipping it to `- [x]` once the resolution
+   has been applied, appending ` | resolved: {chosen resolution}`. Readers only read. A line left
+   open is a live blocker, never a stale artifact.
+5. **Re-spawn** with the chosen resolution, then re-evaluate the return from the top of this
+   handler — never fall through to the checker spawn. A second conflict is still a conflict, not
+   a revised output, and handing it to the checker would check the conflict message.
+
+**Bounded — two ways, because one is evadable.** Not incrementing must not make this path
+unbounded:
+
+- **Repeat.** A conflict naming the SAME `required_property` twice in a row means the chosen
+  resolution did not take. Stop re-spawning; escalate as a stall.
+- **Total.** Count every conflict return in this revision loop, whatever property each names. On
+  the THIRD, stop and escalate — an agent that alternates property names never trips the repeat
+  rule, so the repeat rule alone leaves the loop unbounded. This total is what actually bounds the
+  path; the repeat rule just catches the common case sooner.
+
+Both escalate through the same gate the iteration cap uses. A conflict still never consumes a
+revision iteration — the cap on conflicts is separate from, and additional to, the cap on
+revisions.
+
+**No workflow hands a conflict to a loop and returns.** Asking the user is the route everywhere;
+recording is in addition to asking, never instead of it. `plan-phase` in particular never invokes
+`/gsd:plan-review-convergence` — it runs *inside* that loop, so invoking it would be a cycle, and
+"was I invoked by convergence?" is not a question the orchestrator can answer at runtime.
+
 ### After 3 Iterations
 
 If issues persist after 3 revision cycles:
@@ -95,3 +200,5 @@ If issues persist after 3 revision cycles:
 - **Each iteration gets a fresh agent spawn** -- don't try to continue in the same context
 - **Checker feedback must be inlined** -- the revision agent needs to see exactly what failed
 - **Don't silently swallow issues** -- always present the final state to the user after exiting the loop
+- **A remediation hint is an example, not an order** -- an issue satisfied through a smaller valid
+  mechanism is addressed, and counts as resolved for the issue-count and stall checks

package/gsd-core/references/tdd.md

@@ -94,9 +94,10 @@ After completion, create SUMMARY.md with:
 **RED - Write failing test:**
 1. Create test file following project conventions
 2. Write test describing expected behavior (from `<behavior>` element)
-3. Run test - it MUST fail
-4. If test passes: feature exists or test is wrong. Investigate.
-5. Commit: `test({phase}-{plan}): add failing test for [feature]`
+3. Run test - it MUST fail **intentionally** (#3770): the TARGET test you named must be the test that fails, on an assertion for the planned behavior. A nonzero exit alone is NOT RED — syntax errors, zero-test discovery, fixture crashes, parser errors, and unrelated assertions are INVALID_RED and must not authorize GREEN.
+4. Persist the RED evidence record (command, exit code, failing test, expected result, actual result) and verify it: `gsd_run check tdd-red-evidence <record.json>`. Only verdict `RED_EVIDENCE_OK` satisfies the RED gate; `INVALID_RED` blocks GREEN until the RED phase is fixed.
+5. If test passes: feature exists or test is wrong. Investigate.
+6. Commit: `test({phase}-{plan}): add failing test for [feature]`
 
 **GREEN - Implement to pass:**
 1. Write minimal code to make test pass
@@ -256,26 +257,33 @@ When `workflow.tdd_mode` is enabled in config, the RED/GREEN/REFACTOR gate seque
 
 | Gate | Required | Commit Pattern | Validation |
 |------|----------|---------------|------------|
-| RED | Yes | `test({phase}-{plan}): ...` | Test exists AND fails before implementation |
+| RED | Yes | `test({phase}-{plan}): ...` | Test exists AND fails before implementation — intentionally: `check tdd-red-evidence` returns `RED_EVIDENCE_OK` (target test failed on an assertion for the behavior; anything else is INVALID_RED) |
 | GREEN | Yes | `feat({phase}-{plan}): ...` | Test passes after implementation |
 | REFACTOR | No | `refactor({phase}-{plan}): ...` | Tests still pass after cleanup |
 
 ### Fail-Fast Rules
 
 1. **Unexpected GREEN in RED phase:** If the test passes before any implementation code is written, STOP. The feature may already exist or the test is wrong. Investigate before proceeding.
-2. **Missing RED commit:** If no `test(...)` commit precedes the `feat(...)` commit, the TDD discipline was violated. Flag in SUMMARY.md.
-3. **REFACTOR breaks tests:** Undo the refactor immediately. Commit was premature — refactor in smaller steps.
+2. **INVALID_RED in RED phase (#3770):** A nonzero exit is not RED by itself. Zero-test discovery, fixture/load crashes, nonzero exits with no failing test, unrelated failing tests, and unexpected greens all classify as INVALID_RED (`gsd_run check tdd-red-evidence`). STOP and fix the RED phase — do NOT proceed to GREEN.
+3. **Missing RED commit:** If no `test(...)` commit precedes the `feat(...)` commit, the TDD discipline was violated. Flag in SUMMARY.md.
+4. **REFACTOR breaks tests:** Undo the refactor immediately. Commit was premature — refactor in smaller steps.
 
 ### Executor Gate Validation
 
 After completing a `type: tdd` plan, the executor validates the git log:
 ```bash
+# The commit protocol promises no zero-padding for ${PHASE}/${PLAN} — strip both and
+# match the commit-scope position anchored (#4003). #4619: PHASE may be decimal/
+# N-segment; zero-strip only the leading integer segment, escape the rest.
+PHASE_INT=${PHASE%%.*}; PHASE_FRAC=${PHASE#"$PHASE_INT"}
+PHASE_N="$((10#$PHASE_INT))${PHASE_FRAC//./\\.}"
+PLAN_N=$((10#${PLAN}))
 # Check for RED gate commit
-git log --oneline --grep="^test(${PHASE}-${PLAN})" | head -1
+git log --oneline -E --grep="^test\((0*${PHASE_N})-(0*${PLAN_N})\):" | head -1
 # Check for GREEN gate commit  
-git log --oneline --grep="^feat(${PHASE}-${PLAN})" | head -1
+git log --oneline -E --grep="^feat\((0*${PHASE_N})-(0*${PLAN_N})\):" | head -1
 # Check for optional REFACTOR gate commit
-git log --oneline --grep="^refactor(${PHASE}-${PLAN})" | head -1
+git log --oneline -E --grep="^refactor\((0*${PHASE_N})-(0*${PLAN_N})\):" | head -1
 ```
 
 If RED or GREEN gate commits are missing, add a `## TDD Gate Compliance` section to SUMMARY.md with the violation details.

package/gsd-core/references/thinking-models-planning.md

@@ -34,13 +34,29 @@ For each significant decision in this plan, ask what undoing it would cost three
 
 This is the reasoning step that produces the rating. The taxonomy itself, the emission rules, and the anti-patterns live in @~/.claude/gsd-core/references/planner-reversibility.md — do not maintain a second classification here.
 
-## 5. Curse of Knowledge Counter
+## 5. Occam's Razor
+
+**Counters:** Plans that prescribe avoidable dependencies, abstractions, files, or speculative flexibility before execution begins.
+
+This check complements the planner's RESEARCH.md `dont_hand_roll` guidance and the plan checker's Dimension 12 (Pattern Compliance): those sources identify capabilities and established patterns, while this check orders otherwise sufficient implementation choices. The executor applies the related check later in `thinking-models-execution.md`, after the plan has already selected an approach.
+
+After preserving locked user decisions and complete requirement coverage, choose the first option that is demonstrably sufficient for the task's `<done>` condition:
+
+1. Existing project behavior, helper, or established pattern
+2. Standard-library capability
+3. Native platform capability
+4. Already-installed dependency
+5. Minimum new implementation
+
+This ordering is a sufficiency check, not permission to make the task smaller. It must never reduce requested scope or override locked user decisions, requirement coverage, security, validation, accessibility, error handling, or verification. The planner uses it when choosing implementation actions; the plan checker flags a new abstraction or dependency only when a higher rung is demonstrably sufficient.
+
+## 6. Curse of Knowledge Counter
 
 **Counters:** Plan-to-executor ambiguity from compressed instructions.
 
 For each `<action>` step, re-read it as if you have NEVER seen this codebase. Is every noun unambiguous (which file? which function? which endpoint?)? Is every verb specific (add WHERE? modify HOW?)? If a step could be interpreted two ways, rewrite it. Include file paths, function names, and expected behavior in every action step.
 
-## 6. Base Rate Neglect Counter
+## 7. Base Rate Neglect Counter
 
 **Counters:** Planners ignoring low-confidence research caveats.
 

package/gsd-core/references/verification-patterns.md

@@ -309,14 +309,17 @@ grep -r "$hook_name()" src/ --include="*.tsx" --include="*.ts" | grep -v "$hook_
 # .env file exists
 [ -f ".env" ] || [ -f ".env.local" ]
 
-# Required variable is defined
-grep -E "^$VAR_NAME=" .env .env.local 2>/dev/null
+# Required variable is defined (in the environment: dotenv/direnv/the framework has loaded it)
+printenv "$VAR_NAME" >/dev/null
 ```
 
 **Substantive check:**
 ```bash
-# Variable has actual value (not placeholder)
-grep -E "^$VAR_NAME=.+" .env .env.local 2>/dev/null | grep -v "your-.*-here|xxx|placeholder|TODO" -i
+# Variable has an actual value (not a placeholder) -- tests the shape, never prints the value;
+# exit 0 = real value, exit 1 = missing or placeholder (case-insensitive)
+v=$(printenv "$VAR_NAME"); case "$(printf %s "$v" | tr '[:upper:]' '[:lower:]')" in
+  ""|*your-*-here*|*xxx*|*placeholder*|*todo*) exit 1;;
+esac
 
 # Value looks valid for type:
 # - URLs should start with http
@@ -324,6 +327,16 @@ grep -E "^$VAR_NAME=.+" .env .env.local 2>/dev/null | grep -v "your-.*-here|xxx|
 # - Booleans should be true/false
 ```
 
+When the variable is not present in the agent's own environment (a framework that loads
+`.env.local` itself at runtime does not export it to the shell that runs these checks),
+ask the user to confirm it is set rather than reading `.env` directly. Variable NAMES can
+still be checked against `.env.example`, which the secret-read guard exempts from its
+protected-file patterns.
+
+One guard-matching note worth knowing when auditing docs for `.env` mentions: the guard
+treats a grep PATTERN whose last path segment is a secret file name as a file operand, so
+`grep -n "\.env" file.md` is denied while `grep -n "\.env\b" file.md` is allowed.
+
 **Stub patterns specific to env:**
 ```bash
 # RED FLAGS - These are stubs: