From df095b406ae72d003bbd0cf91e1f4e856fb82dc5 Mon Sep 17 00:00:00 2001 From: Mikael Hugo Date: Sat, 2 May 2026 23:06:34 +0200 Subject: [PATCH] =?UTF-8?q?docs(sf):=20disambiguate=20"ADR-011"=20?= =?UTF-8?q?=E2=80=94=20comments=20now=20say=20"gsd-2=20ADR-011"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A future maintainer reading "ADR-011 Phase 2" in escalation.ts would look up SF's local docs/dev/ADR-011 and find "Swarm Chat and Debate Mode" — totally unrelated. The escalation + progressive-planning work ports gsd-2's ADR-011 (Progressive Planning + Escalation), which happens to share the number with our local ADR-011. Prefixed every internal comment that referenced the gsd-2 ADR with "gsd-2 ADR-011" so the source-of-truth lookup is unambiguous. Comment- only diff — no compilation, runtime, or test surface affected. Files: types.ts, auto-prompts.ts, auto-dispatch.ts, escalation.ts. Co-Authored-By: Claude Opus 4.7 (1M context) --- src/resources/extensions/sf/auto-dispatch.ts | 2 +- src/resources/extensions/sf/auto-prompts.ts | 8 ++++---- src/resources/extensions/sf/escalation.ts | 2 +- src/resources/extensions/sf/types.ts | 11 ++++++----- 4 files changed, 12 insertions(+), 11 deletions(-) diff --git a/src/resources/extensions/sf/auto-dispatch.ts b/src/resources/extensions/sf/auto-dispatch.ts index 16cfdb88a..a2d9a2e0c 100644 --- a/src/resources/extensions/sf/auto-dispatch.ts +++ b/src/resources/extensions/sf/auto-dispatch.ts @@ -1101,7 +1101,7 @@ export const DISPATCH_RULES: DispatchRule[] = [ }, }, { - // ADR-011 progressive planning: when a slice was created as a sketch + // gsd-2 ADR-011 progressive planning: when a slice was created as a sketch // (slices.is_sketch=1) and the phases.progressive_planning preference is // enabled, dispatch refine-slice instead of plan-slice. The refine unit // expands the stored sketch_scope into a full plan using prior slice diff --git a/src/resources/extensions/sf/auto-prompts.ts b/src/resources/extensions/sf/auto-prompts.ts index c2946cf68..b83d410d3 100644 --- a/src/resources/extensions/sf/auto-prompts.ts +++ b/src/resources/extensions/sf/auto-prompts.ts @@ -2185,7 +2185,7 @@ export async function buildPlanSlicePrompt( }, ): Promise { const prependBlocks: string[] = []; - // ADR-011: when the refining-phase dispatch rule gracefully downgrades to + // gsd-2 ADR-011 (progressive planning): when the refining-phase dispatch rule gracefully downgrades to // plan-slice (progressive_planning was toggled off mid-milestone), it // forwards the stored sketch_scope as a SOFT hint — context, not a hard // constraint. The planner is free to expand beyond it. @@ -2226,7 +2226,7 @@ export async function buildPlanSlicePrompt( } /** - * ADR-011 refine-slice: expand a sketch into a full plan using the current + * gsd-2 ADR-011 refine-slice: expand a sketch into a full plan using the current * codebase state and prior slice summary. Mechanically similar to plan-slice * but framed as a *transformation* (sketch → full plan) rather than a * blank-sheet planning pass. Reuses inlineDependencySummaries for prior @@ -2445,7 +2445,7 @@ export async function buildExecuteTaskPrompt( let phaseAnchorSection = planAnchor ? formatAnchorForPrompt(planAnchor) : ""; - // ADR-011 Phase 2: inject any resolved-but-unapplied escalation override + // gsd-2 ADR-011 Phase 2: inject any resolved-but-unapplied escalation override // into this task's prompt. Claim is atomic via DB UPDATE WHERE IS NULL, so // if a parallel build already injected it, we skip. Feature-gated by // phases.mid_execution_escalation. Prepended to phaseAnchorSection so it @@ -2498,7 +2498,7 @@ export async function buildExecuteTaskPrompt( } })(); - // ADR-011 P2: when the feature is enabled, teach the executor that it can + // gsd-2 ADR-011 P2: when the feature is enabled, teach the executor that it can // surface non-obvious choices via the `escalation` field on sf_task_complete // rather than silently picking. Auto-mode auto-accepts the recommendation // (see phases.escalation_auto_accept), so this is low-cost overhead — but diff --git a/src/resources/extensions/sf/escalation.ts b/src/resources/extensions/sf/escalation.ts index 753a4c450..963ed007b 100644 --- a/src/resources/extensions/sf/escalation.ts +++ b/src/resources/extensions/sf/escalation.ts @@ -212,7 +212,7 @@ export function detectPendingEscalation( return null; } -/** ADR-011 P2 carry-forward injection: when a previous task in this slice +/** gsd-2 ADR-011 P2 carry-forward injection: when a previous task in this slice * had an escalation that the user resolved, atomically claim the override * (race-safe via DB UPDATE) and return the markdown block to prepend to * the next executor's prompt. Returns null when no unapplied override diff --git a/src/resources/extensions/sf/types.ts b/src/resources/extensions/sf/types.ts index 1c3aab42d..ead7589bd 100644 --- a/src/resources/extensions/sf/types.ts +++ b/src/resources/extensions/sf/types.ts @@ -349,11 +349,12 @@ export interface PhaseSkipPreferences { reassess_after_slice?: boolean; /** When true, auto-mode pauses before each slice for discussion (#789). */ require_slice_discussion?: boolean; - /** ADR-011 Phase 2: when true, mid-execution escalation overrides are injected into the execute-task prompt. */ + /** gsd-2 ADR-011 Phase 2: when true, mid-execution escalation overrides are injected into the execute-task prompt. + * Note: SF's local ADR-011 is "Swarm Chat and Debate Mode" — unrelated. */ mid_execution_escalation?: boolean; - /** ADR-011: when true, sketch slices (slices.is_sketch=1) enter the "refining" phase - * and dispatch through refine-slice instead of plan-slice. When false (default), sketches - * are indistinguishable from missing plans and fall through to the normal "planning" phase. */ + /** gsd-2 ADR-011 Phase 1 (progressive planning): when true, sketch slices (slices.is_sketch=1) enter the "refining" + * phase and dispatch through refine-slice instead of plan-slice. When false (default), sketches are + * indistinguishable from missing plans and fall through to the normal "planning" phase. */ progressive_planning?: boolean; /** Auto-mode is autonomous: when true (default), an escalation in auto-mode auto-accepts * the agent's recommendation and continues. The user can review/override later via @@ -692,7 +693,7 @@ export interface GateEvaluationConfig { task_gates?: boolean; } -// ─── ADR-011 Phase 2 Escalation ────────────────────────────────────────── +// ─── gsd-2 ADR-011 Phase 2 — Mid-Execution Escalation ──────────────────── export interface EscalationOption { id: string;