@opengsd/gsd-core 1.13.0 → 1.14.0

package/gsd-core/references/compact-content-gate.md

@@ -0,0 +1,66 @@
+# Compact Content Gate
+
+Shared by every workflow spine split under ADR-4139, and by every lazily-read fragment or
+planning-artifact template given a compact variant under Phase 6 (#4406). States the config check
+and both resolution rules once — a spine or fragment references this file; it never restates
+either check inline.
+
+## The check
+
+```bash
+COMPACT_CONTENT=$(gsd_run query config-get workflow.compact_content --raw 2>/dev/null || echo "false")
+```
+
+## Stream 1 — spine + detail (top-level, eagerly `@`-included workflows)
+
+- **`COMPACT_CONTENT` is `"false"` (default):** Read every part under this workflow's own `detail/` directory (a sibling of this spine, e.g. `gsd-core/workflows/<name>/detail/*.md`) now, in full, before continuing past this point. Their content elaborates on the spine you are reading — treat everything they say as part of this document from here on.
+- **`COMPACT_CONTENT` is `"true"`:** Do not read the detail file. Continue directly with the spine's own content — per ADR-4139 Decision 3, it is complete enough to run this workflow correctly on its own.
+
+**The fail-safe this holds (ADR-4139 Decision 4):** A `Read` that does not fire for any reason (tool error, a skipped step, a misread condition) leaves you running on the spine alone. That is the same, correct, terser state an opted-in project runs in on purpose — never a state with no instructions. The spine's own completeness is what makes this safe; this gate is only ever additive.
+
+## Streams 1b and 4 — variant resolution (lazily-read fragments and planning-artifact templates)
+
+For a `workflows/<name>/{modes,steps,templates}/*.md` fragment or a `gsd-core/templates/**`
+planning-artifact template that has a registered `.compact.md` sibling (same directory, same stem,
+`.compact.md` suffix):
+
+- **`COMPACT_CONTENT` is `"false"` (default), or the file has no registered `.compact.md` sibling:** Read the canonical path exactly as named — unchanged from today.
+- **`COMPACT_CONTENT` is `"true"` and a `.compact.md` sibling is registered:** Read the `.compact.md` sibling instead of the canonical path.
+
+Both files are complete, independently — Read exactly one, never both, and never read the compact
+sibling's content as an addendum to the canonical file.
+
+**The fail-safe this holds:** unlike stream 1, a call site this rule actually applies to is already
+reached only by a runtime `Read` — a missed `Read` already means zero overlay content, with or
+without `workflow.compact_content`. Selecting between two independently-complete files at that
+call site does not introduce a new way to end up with nothing; the worst case is identical to
+today's. This is why stream 1b/4 can use variant-swap (two independent files) where stream 1 could
+not: the degradation-direction argument that ruled out converting stream 1's `@`-includes (ADR-4139
+Decision 4) does not apply at a genuine runtime-`Read` call site, because there is no
+host-guaranteed baseline being traded away there.
+
+**This rule is scoped per call site, not per file.** A `gsd-core/templates/**` file can have both
+kinds of reference in the corpus at once — some places name it inside an eager `@`-include or an
+orchestrator build-time embed (the same mechanism as stream 1, just reaching a template path
+instead of a workflow path), others name it in prose instructing a runtime `Read`. Only the latter
+gets rewritten to point at this rule; an eager reference to the canonical file is left exactly as
+it is, for the same reason stream 1's `@`-includes were left alone — converting it would trade a
+host-guaranteed load for a conditional one. Before wiring any call site, confirm by inspection
+which kind it is; do not assume every mention of a `gsd-core/templates/**` path is a runtime `Read`
+just because the directory's typical case is.
+
+## Stream 2 — agent-skill payloads (the `gsd_run query agent-skills` CLI seam)
+
+`agents/<name>.compact.md`, same directory, same stem, `.compact.md` suffix — registered and
+checked the same way as streams 1b/4. The selection is different: this seam already runs through
+a real function call (`cmdAgentSkills`, `src/init.cts`), so the resolution happens **in code**,
+not by a `gsd_run query config-get` prose instruction. There is nothing to state here for a
+workflow author to follow, because no workflow author calls this seam directly — it fires only
+inside the `#2454` persona fallback for non-Claude, AGENTS-native runtimes that cannot dispatch a
+named subagent.
+
+Same two rules as streams 1b/4, enforced in code instead of prose: `workflow.compact_content` off,
+or no registered `.compact.md` sibling for that agent, serves the canonical persona unchanged; on,
+with a sibling registered, serves the compact one. The one addition code gives that prose could
+not: a missing sibling is disclosed in the served payload itself (a leading `<!-- gsd: no compact
+payload registered ... -->` comment) rather than silently serving canonical with no signal at all.

package/gsd-core/references/loop-hook-dispatch.md

@@ -57,6 +57,24 @@ Dispatch the referenced unit. Exactly one of `ref.skill`, `ref.agent`, or `ref.c
 
 Wait for the result before continuing to the next hook or the next step.
 
+**`supportsReviewerLanes` (optional, boolean).** A `step` entry may carry
+`supportsReviewerLanes: true` alongside `ref` (#4209). A workflow opts a step into external
+reviewer-lane dispatch by calling `gsd_run review-lane dispatch-step --cap-id <capId> --point
+<point> --explicit <slugs> ...` — `dispatch-step` resolves its OWN active hook for `<point>` (via
+`resolveActiveHooksForPoint`, the same in-process resolver `loop render-hooks` itself calls) and
+checks whether `<capId>`'s hook carries this field before proceeding; the workflow does not
+resolve or gate on the trait itself, only passes the two flags naming which step it is. When the
+trait reads exactly `true`, `dispatch-step` routes through `dispatchReviewerLanes`, the one
+interpreter in `src/reviewer-step-dispatch.cts` that reuses the existing reviewer-lane selection,
+planning, and invocation machinery, so any explicitly selected reviewer lane also reviews the
+same scope. Absent or `false` is inert: `dispatch-step` itself is a no-op (a non-boolean value is
+rejected by `capability-validator.cjs` at load time, so it never reaches `dispatch-step` at all).
+This is the only place a step opts into reviewer-lane support: a capability beyond `code-review`
+reuses it by declaring the same trait on its own step and calling `dispatch-step` with
+`--cap-id`/`--point`, with zero bespoke TRAIT-RESOLUTION code of its own. The workflow still owns
+matching its own CLI flags against the reviewer-lane roster and assembling the evidence block
+handed to its consolidator — those are NOT part of what this trait makes reusable.
+
 A `step` is **advisory by construction**: it never blocks or redirects the host workflow —
 that is what a `gate` is for. Each dispatch is best-effort; on error record a warning and
 continue, honoring `onError`.

package/gsd-core/references/model-profiles.md

@@ -58,6 +58,10 @@ Model profiles control which Claude model each GSD agent uses. This allows balan
 3. **Profile table** — the per-agent column from the active `model_profile`
 4. **Runtime default** — when nothing else applies
 
+Steps 2–4 select the *tier*; a `model_profile_overrides.<runtime>.<tier>` entry then
+maps that tier to a concrete model (#4192 — honored on the claude runtime as well, so
+pinning composes with tiering instead of replacing it).
+
 ### Why two layers above the profile?
 
 - **Profile** is a global tier strategy (everyone runs balanced).
@@ -215,8 +219,11 @@ is (highest → lowest):
    (see §Dynamic Routing — escalation steps tier up per attempt counter)
 4. If no dynamic_routing match, check models[phase_type] for a phase-type tier
    (see §Per-Phase-Type Model Map for the agent → phase-type mapping)
-5. If no phase-type slot, look up agent in profile table
-6. Pass model parameter to Task call
+5. Check model_profile_overrides.<runtime>.<tier> for a per-tier model override
+   (honored on the claude runtime too — #4192; verbatim unless it maps to the
+   current tier alias)
+6. If no phase-type slot, look up agent in profile table
+7. Pass model parameter to Task call
 ```
 
 `model` and `effort` resolve through different mechanisms at different
@@ -246,7 +253,9 @@ Override specific agents without changing the entire profile:
 }
 ```
 
-Overrides take precedence over the profile. Valid values: `opus`, `sonnet`, `haiku`, `inherit`, or any fully-qualified model ID (e.g., `"o3"`, `"openai/o3"`, `"google/gemini-2.5-pro"`).
+Overrides take precedence over the profile. Valid values: `opus`, `sonnet`, `haiku`, `fable`, `inherit`, or any fully-qualified model ID (e.g., `"o3"`, `"openai/o3"`, `"google/gemini-2.5-pro"`). `fable` is a Claude Code Agent-tool alias, not a GSD profile tier — it has no column in the profile table above.
+
+On the Claude runtime, fully-qualified Claude model IDs are honored as explicit generation pins (#4192): an ID that names the current tier default (e.g. `"claude-sonnet-5"`) resolves to its tier alias — the same model in the form the Agent tool always accepts — while any other ID (e.g. `"claude-opus-4-7"`) resolves verbatim, with a warn-once stderr note that setups accepting only tier aliases will not honor a full ID. To pin a generation for a whole tier rather than one agent, set `model_profile_overrides.claude.<tier>` (see docs/CONFIGURATION.md — Runtime-Aware Profiles).
 
 ## Switching Profiles
 

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 |
@@ -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
 

package/gsd-core/references/tdd.md

@@ -273,8 +273,11 @@ When `workflow.tdd_mode` is enabled in config, the RED/GREEN/REFACTOR gate seque
 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).
-PHASE_N=$((10#${PHASE})); PLAN_N=$((10#${PLAN}))
+# 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 -E --grep="^test\((0*${PHASE_N})-(0*${PLAN_N})\):" | head -1
 # Check for GREEN gate commit  

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:

package/gsd-core/references/worktree-path-safety.md

@@ -1,7 +1,117 @@
 # Worktree Path Safety
 
-Guards for executor agents running inside Claude Code worktrees. Three checks
-must run before any staging, Edit, or Write operation in worktree mode.
+Guards for executor agents running inside Claude Code worktrees. The
+supplied-root pin (step 0p) runs in EVERY mode; the remaining checks run before
+any staging, Edit, or Write operation in worktree mode.
+
+---
+
+## Supplied-root pin — step 0p (#4254, EVERY mode)
+
+Sequential-mode dispatch (no `isolation="worktree"`) gives the executor no
+spawn-time cwd guarantee, and the worktree-only guards below do not apply — so
+a sequential executor whose process cwd resolved to a different checkout of
+the same repo would self-derive that checkout as its root and commit there,
+silently. Step 0p closes that hole by comparing the executor's actual root
+against a root the ORCHESTRATOR already validated — never against anything the
+executor derives itself.
+
+**Runtime contract (executor):** if your prompt contains a `<project_root_pin>`
+block, run its guard script verbatim before your first Edit/Write and again
+before every commit, in the same cwd as that write or commit. On FATAL, halt
+and report — recovery (moving commits between checkouts) is an
+orchestrator/human decision, never agent self-repair. If your prompt contains
+NO `<project_root_pin>` block (worktree/isolated dispatch, or a legacy
+orchestrator), emit one warning line and continue with steps 0a/0b below — do
+not fail closed on dispatches that never carried a pin. **Never bind
+`{PINNED_ROOT}` yourself**: if this template reaches you unbound it is
+reference prose, not your pin — only the orchestrator's build-time
+substitution produces a valid guard.
+
+**Composition contract (orchestrator — build time, NOT a sub-agent runtime
+step):** copy the guard below into the dispatched prompt inside a
+`<project_root_pin>` block, substituting `{PINNED_ROOT}` with the literal value
+of `$ORCHESTRATOR_WT` captured at execute_waves entry, shell-single-quoted:
+wrap the path in `'…'` and escape any embedded `'` as `'\''`. A path that
+cannot be quoted this way must halt the phase (surface a blocker) rather than
+ship a pin that could mis-parse. The comparison is git-vs-git on BOTH sides —
+`git -C` resolves the pinned path to its repo's canonical toplevel in git's
+own path representation, so symlink aliases, trailing slashes, `/var` vs
+`/private/var` spellings, and Windows drive-letter forms — forward- or
+backslash-separated, `RUNNER~1`-style short names included — compare equal by
+construction (shell `pwd -P` normalization does NOT match git's emission on
+Windows — do not re-introduce it).
+
+Two portability rules baked into the guard below, learned from the #4254 CI
+Windows legs: (1) a backslash comparator must be GENERATED at runtime
+(`printf '\134'`), because a backslash written twice in the script text does
+not survive the Windows command-line round-trip into bash — the doubled form
+arrives halved, which silently rewrites any escape pattern that relies on it;
+(2) every FATAL names its `Guard stage` and, where a git capture failed,
+git's own stderr in a `Diagnostic` line, so a platform failure self-describes
+instead of surfacing as a bare `Actual root: <none>`.
+
+```bash
+# gsd:guard=supplied-root-pin (#4254) — run before the first Edit/Write and before every commit.
+PINNED_ROOT='{PINNED_ROOT}'  # orchestrator build-time substitution — the only valid source of this value
+PIN_STAGE=''
+PIN_DIAG=''
+gsd_pin_fail() {
+  echo "FATAL: executor root does not match the orchestrator-supplied PROJECT_ROOT pin (#4254)." >&2
+  echo "  Pinned root: ${PINNED_ROOT:-<empty or unexpanded>}" >&2
+  echo "  Actual root: ${ACTUAL_ROOT:-<none>}" >&2
+  echo "  Guard stage: ${PIN_STAGE:-<unset>}" >&2
+  if [ -n "$PIN_DIAG" ]; then echo "  Diagnostic: $PIN_DIAG" >&2; fi
+  echo "  No writes or commits are permitted from this checkout. HALT and report; recovery is an" >&2
+  echo "  orchestrator/human decision. Only the IMMEDIATE submodule of the pinned checkout is a" >&2
+  echo "  legitimate other cwd — nested submodules must surface as a blocker, not self-route." >&2
+  exit 1
+}
+# Backslash comparator, generated at runtime: a backslash written twice in this
+# script does not survive the Windows spawn path into bash (the command-line
+# round-trip halves the doubled form), which rejected every C:\ pin at the form
+# gate on the #4254 CI Windows legs. printf's octal escape is a lone backslash,
+# which does survive; the quoted expansion below is literal in a case pattern.
+BS=$(printf '\134')
+# Fail closed if the comparator could not be generated: an empty BS would widen
+# the drive-form arm below to drive-RELATIVE pins (C:foo) — the one fail-open
+# seam in this construction, closed loudly rather than trusted to the shell.
+if [ -z "$BS" ]; then
+  PIN_STAGE=form-gate
+  PIN_DIAG='backslash comparator generation failed (printf octal escape returned empty)'
+  gsd_pin_fail
+fi
+case "$PINNED_ROOT" in
+  ''|'{PINNED_ROOT}') PIN_STAGE=pin-unbound; gsd_pin_fail ;;  # empty or unexpanded pin — fail closed, never warn-and-proceed
+  /*) ;;                                                     # absolute POSIX form
+  [A-Za-z]:/*|[A-Za-z]:"$BS"*) ;;                            # Windows drive form, forward- or backslash-separated
+  *) PIN_STAGE=form-gate; gsd_pin_fail ;;                    # relative pin — never trustworthy across cwds
+esac
+ACTUAL_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+if [ -z "$ACTUAL_ROOT" ]; then
+  PIN_STAGE=actual-capture
+  PIN_DIAG="git rev-parse --show-toplevel from the cwd failed: $(git rev-parse --show-toplevel 2>&1 1>/dev/null)"
+  gsd_pin_fail
+fi
+PINNED_TL=$(git -C "$PINNED_ROOT" rev-parse --show-toplevel 2>/dev/null)
+if [ -z "$PINNED_TL" ]; then
+  PIN_STAGE=pinned-capture
+  PIN_DIAG="git -C <pinned root> rev-parse --show-toplevel failed: $(git -C "$PINNED_ROOT" rev-parse --show-toplevel 2>&1 1>/dev/null)"
+  gsd_pin_fail
+fi
+if [ "$ACTUAL_ROOT" != "$PINNED_TL" ]; then
+  # Registered-submodule allowance: sub_repos plans legitimately commit inside an
+  # immediate submodule of the pinned checkout. The superproject working tree is
+  # git-emitted in the same representation as PINNED_TL, so the equality is
+  # representation-safe on every platform.
+  SUPER_TL=$(git rev-parse --show-superproject-working-tree 2>/dev/null)
+  if [ "$SUPER_TL" != "$PINNED_TL" ]; then
+    PIN_STAGE=root-mismatch
+    PIN_DIAG="actual=${ACTUAL_ROOT} pinned=${PINNED_TL} superproject=${SUPER_TL:-<none>}"
+    gsd_pin_fail
+  fi
+fi
+```
 
 ---
 

package/gsd-core/templates/README.md

@@ -21,8 +21,14 @@ These files live directly at `.planning/` — not inside phase subdirectories.
 | `LEARNINGS.md` | *(inline)* | `/gsd:extract-learnings`, `/gsd:execute-phase` (gated: `features.global_learnings`) | Phase retrospective learnings for future plans |
 | `THREADS.md` | *(inline)* | `/gsd:thread` | Persistent discussion threads |
 | `config.json` | `config.json` | `/gsd:new-project`, `/gsd:health --repair` | Project-specific GSD configuration |
-| `CLAUDE.md` | `claude-md.md` | `/gsd-profile` | Auto-assembled Claude Code context file |
+| `CLAUDE.md` | *(inline)* | `/gsd-profile` | Auto-assembled Claude Code context file |
 | `RETROSPECTIVE.md` | *(inline)* | `/gsd:complete-milestone` | Living milestone retrospective updated at each milestone close |
+| `WINDOWS.md` | *(none)* | broken-windows ledger (`src/broken-windows.cts`) | Tracked known-broken items pending resolution (#3224) |
+| `STATE-ARCHIVE.md` | *(none)* | `state.cts`'s `cmdStatePrune` | Pruned historical STATE.md entries |
+| `milestone.lock` | *(none)* | `src/milestone-lock.cts` | Persistent milestone (phase + session) claim, unlike the transient `STATE.md.lock`/`WAITING.json` (#3311) |
+| `state.json` | *(none)* | `src/state-contract.cts` | Machine-readable state contract published at step boundaries (#3227) |
+| `skill-manifest.json` | *(none)* | `init.cts`'s `cmdSkillManifest --write` | Project-scoped skill manifest (#3964) |
+| `PATTERNS.md` | *(inline)* | `/gsd:extract-learnings` (graduation, `workflows/graduation.md`, `patterns` target) | Graduated cross-phase patterns -- distinct from the per-phase `NN-PATTERNS.md` below (#4282) |
 
 ### Version-stamped artifacts (pattern: `vX.Y-*.md`)
 

package/gsd-core/templates/state.md

@@ -172,9 +172,12 @@ Updated after each plan completion.
 **Decisions:** Reference to PROJECT.md Key Decisions table, plus recent decisions summary for quick access. Full decision log lives in PROJECT.md.
 
 **Pending Todos:** Ideas captured via /gsd-add-todo
-- Count of pending todos
-- Reference to .planning/todos/pending/
-- Brief list if few, count if many (e.g., "5 pending todos — see /gsd:capture --list")
+- One bullet per pending todo, rendered by `init.todos`'s `pending_todos_markdown`
+  (each bullet capped at 240 characters: `- [date] [area] title — [todo file](path) — Needs ...`;
+  the todo-file link is repo-relative, so the cap does not depend on checkout path length)
+- `None yet.` when there are no pending todos
+- No collapse-by-count fallback — every pending todo gets its own line, always
+  (see #2618 design doc for why a "count if many" fallback was rejected)
 
 **Blockers/Concerns:** From "Next Phase Readiness" sections
 - Issues that affect future work

package/gsd-core/templates/summary.compact.md

@@ -0,0 +1,212 @@
+# Summary Template
+
+Template for `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md` - phase completion documentation.
+
+---
+
+## File Template
+
+```markdown
+---
+phase: XX-name
+plan: YY
+subsystem: [primary category: auth, payments, ui, api, database, infra, testing, etc.]
+tags: [searchable tech: jwt, stripe, react, postgres, prisma]
+
+# Dependency graph
+requires:
+  - phase: [prior phase this depends on]
+    provides: [what that phase built that this uses]
+provides:
+  - [bullet list of what this phase built/delivered]
+affects: [list of phase names or keywords that will need this context]
+
+# Actuals (#2632) — pairs with the plan's `estimate` to calibrate future estimates.
+# Same estimateTokens scale (chars/4 over the realized diff), never a harness token count.
+actuals:
+  tokens: [chars/4 over files actually changed]
+  tasks: [tasks completed]
+  commits: [commits made]
+
+# Tech tracking
+tech-stack:
+  added: [libraries/tools added in this phase]
+  patterns: [architectural/code patterns established]
+
+key-files:
+  created: [important files created]
+  modified: [important files modified]
+
+key-decisions:
+  - "Decision 1"
+  - "Decision 2"
+
+patterns-established:
+  - "Pattern 1: description"
+  - "Pattern 2: description"
+
+requirements-completed: []  # REQUIRED — Copy ALL requirement IDs from this plan's `requirements` frontmatter field.
+
+# Coverage metadata (#1602) — one entry per shipped deliverable. Drives DETERMINISTIC UAT routing in verify-work.
+# OMIT this whole block for legacy/prose-only SUMMARYs — verify-work then falls back to the ## Accomplishments bullets
+# (byte-identical behavior for un-migrated phases). See <coverage_guidance> below for the contract.
+coverage:
+  - id: D1
+    description: "[deliverable in human-readable form — what would have been a prose ## Accomplishments bullet]"
+    requirement: "[REQ-ID from this plan's `requirements`, or omit if none]"
+    verification:
+      - kind: unit            # unit | integration | e2e | automated_ui | manual_procedural | other
+        ref: "[tests/path.test.ts#test name | playwright:shot.png | command invocation]"
+        status: pass          # pass | fail | unknown — from the latest run
+    human_judgment: false     # REQUIRED boolean. false => may auto-pass IF every verification status is `pass`.
+  - id: D2
+    description: "[a deliverable that needs a human to sign off]"
+    verification: []
+    human_judgment: true
+    rationale: "[REQUIRED when human_judgment: true — why automation is insufficient]"
+
+# Metrics
+duration: Xmin
+completed: YYYY-MM-DD
+status: complete
+---
+
+# Phase [X]: [Name] Summary
+
+**[Substantive one-liner describing outcome - NOT "phase complete" or "implementation finished"]**
+
+## Performance
+
+- **Duration:** [time] (e.g., 23 min, 1h 15m)
+- **Started:** [ISO timestamp]
+- **Completed:** [ISO timestamp]
+- **Tasks:** [count completed]
+- **Files modified:** [count]
+
+## Accomplishments
+- [Most important outcome]
+- [Second key accomplishment]
+- [Third if applicable]
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: [task name]** - `abc123f` (feat/fix/test/refactor)
+2. **Task 2: [task name]** - `def456g` (feat/fix/test/refactor)
+3. **Task 3: [task name]** - `hij789k` (feat/fix/test/refactor)
+
+**Plan metadata:** `lmn012o` (docs: complete plan)
+
+_Note: TDD tasks may have multiple commits (test → feat → refactor)_
+
+## Files Created/Modified
+- `path/to/file.ts` - What it does
+- `path/to/another.ts` - What it does
+
+## Decisions Made
+[Key decisions with brief rationale, or "None - followed plan as specified"]
+
+## Deviations from Plan
+
+[If no deviations: "None - plan executed exactly as written"]
+
+[If deviations occurred:]
+
+### Auto-fixed Issues
+
+**1. [Rule X - Category] Brief description**
+- **Found during:** Task [N] ([task name])
+- **Issue:** [What was wrong]
+- **Fix:** [What was done]
+- **Files modified:** [file paths]
+- **Verification:** [How it was verified]
+- **Committed in:** [hash] (part of task commit)
+
+[... repeat for each auto-fix ...]
+
+---
+
+**Total deviations:** [N] auto-fixed ([breakdown by rule])
+**Impact on plan:** [Brief assessment - e.g., "All auto-fixes necessary for correctness/security. No scope creep."]
+
+## Issues Encountered
+[Problems and how they were resolved, or "None"]
+
+[Note: "Deviations from Plan" documents unplanned work that was handled automatically via deviation rules. "Issues Encountered" documents problems during planned work that required problem-solving.]
+
+## User Setup Required
+
+[If USER-SETUP.md was generated:]
+**External services require manual configuration.** See [{phase}-USER-SETUP.md](./{phase}-USER-SETUP.md) for:
+- Environment variables to add
+- Dashboard configuration steps
+- Verification commands
+
+[If no USER-SETUP.md:]
+None - no external service configuration required.
+
+## Next Phase Readiness
+[What's ready for next phase]
+[Any blockers or concerns]
+
+---
+*Phase: XX-name*
+*Completed: [date]*
+```
+
+<frontmatter_guidance>
+**Purpose:** Enable automatic context assembly via dependency graph. Frontmatter makes summary metadata machine-readable so plan-phase can scan all summaries quickly and select relevant ones based on dependencies (`requires`/`provides`/`affects` create the explicit links; transitive closure follows from them).
+
+**Subsystem/Tags:** Primary categorization + searchable technical keywords, for detecting related phases and tech-stack awareness. **Key-files:** important files for @context references in PLAN.md. **Patterns:** established conventions future phases should maintain.
+
+**Population:** Frontmatter is populated during summary creation in execute-plan.md. See `<step name="create_summary">` for field-by-field guidance.
+
+**Status (#2830):** `status: complete` is the default — the plan finished. Use `status: halted` instead when the plan reached a designed stop (a gate failure, a spike concluding without expanding into the full build, or any other intentional non-completion) and intentionally left tasks unfinished. `halted` is machine-read: any plan whose `depends_on` (directly or transitively) names a halted plan is reported as blocked, not offered to the executor, until the halt is resolved and re-summarized as `complete`.
+</frontmatter_guidance>
+
+<coverage_guidance>
+**Purpose (#1602):** The `coverage:` block is a per-deliverable Requirements Traceability Matrix. It lets `verify-work`'s `extract_tests` step route deliverables DETERMINISTICALLY — auto-passing those proven by passing tests and reserving human UAT for genuine judgment — instead of re-deriving coverage from prose. Consumed via `gsd-tools uat classify-coverage --summary <SUMMARY>`.
+
+**Field semantics:**
+
+| Field | Purpose |
+|---|---|
+| `id` | Stable identifier (`D1`, `D2`…) for cross-referencing from UAT.md and audit reports. Must be unique within the SUMMARY. |
+| `description` | The deliverable in human-readable form — what would have been a prose bullet. |
+| `requirement` | Links back to a REQUIREMENTS.md REQ-ID (joins `requirements-completed`). Optional. |
+| `verification[].kind` | Enum: `unit \| integration \| e2e \| automated_ui \| manual_procedural \| other`. |
+| `verification[].ref` | Test path + descriptor (`file#test name`), Playwright screenshot ref, or command invocation. Required per entry. |
+| `verification[].status` | `pass \| fail \| unknown` — populated from the latest test run. |
+| `human_judgment` | Explicit boolean; REQUIRED. `true` always routes to a human. |
+| `rationale` | REQUIRED when `human_judgment: true`. The audit trail for why automation is insufficient. |
+
+**Deterministic contract (what the classifier does):**
+- A deliverable auto-passes (no human prompt) **only** when `human_judgment: false` AND `verification` is non-empty AND every `verification[].status` is `pass`. This is the narrow, fully-proven case.
+- **Everything else is presented to a human** — `human_judgment: true`, an empty `verification:`, any non-`pass`/`unknown` status, or any schema error. A false-negative is a redundant prompt (the status quo); a false-positive ships a bug UAT existed to catch.
+- **Fail-safe default:** if you cannot determine coverage for a deliverable, you MUST set `human_judgment: true` with `rationale: "Coverage not determined at authoring time — verifier must classify"`. Never leave a deliverable's `human_judgment` empty, and never set it `false` just to skip the prompt — auto-pass additionally requires a passing `verification` entry, so the flag alone cannot skip the human.
+- `coverage: []` means "no deliverables to classify" (the single-confirmation path). OMITTING the block entirely means "legacy" — `verify-work` falls back to prose `## Accomplishments` extraction unchanged.
+</coverage_guidance>
+
+<one_liner_rules>
+The one-liner MUST be substantive:
+
+**Good:** "JWT auth with refresh rotation using jose library" · "Prisma schema with User, Session, and Product models" · "Dashboard with real-time metrics via Server-Sent Events"
+
+**Bad:** "Phase complete" · "Authentication implemented" · "Foundation finished" · "All tasks done"
+
+The one-liner should tell someone what actually shipped.
+</one_liner_rules>
+
+<guidelines>
+**Frontmatter:** MANDATORY - complete all fields. Enables automatic context assembly for future planning.
+
+**One-liner:** Must be substantive. "JWT auth with refresh rotation using jose library" not "Authentication implemented".
+
+**Decisions section:**
+- Key decisions made during execution with rationale
+- Extracted to STATE.md accumulated context
+- Use "None - followed plan as specified" if no deviations
+
+**After creation:** STATE.md updated with position, decisions, issues.
+</guidelines>