From ef82fbf2c62ef18fdfcef6a84e7ec771620f140e Mon Sep 17 00:00:00 2001 From: Mikael Hugo Date: Sat, 2 May 2026 23:11:16 +0200 Subject: [PATCH] docs(sf): finish ADR-011 disambiguation across remaining .ts files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Final pass over the comment-only ambiguity. Every internal "ADR-011" reference outside test files now reads "gsd-2 ADR-011" so the source-of-truth lookup is unambiguous (SF's local ADR-011 is "Swarm Chat and Debate Mode", which has nothing to do with progressive planning or escalation). Files: workflow-tool-executors.ts, bootstrap/db-tools.ts, unit-context-manifest.ts, commands-escalate.ts, sf-db.ts (full sweep, including remaining function docstrings), tools/plan-milestone.ts, tools/plan-slice.ts. Comment-only diff. The one bare "(ADR-011 P2)" left in commands/catalog.ts:62 (the /sf escalate help text) belongs to the parallel session's WIP edit on that file — leaving it for them. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../extensions/sf/bootstrap/db-tools.ts | 4 +-- .../extensions/sf/commands-escalate.ts | 2 +- src/resources/extensions/sf/sf-db.ts | 28 +++++++++---------- .../extensions/sf/tools/plan-milestone.ts | 18 ++++++------ .../extensions/sf/tools/plan-slice.ts | 2 +- .../sf/tools/workflow-tool-executors.ts | 4 +-- .../extensions/sf/unit-context-manifest.ts | 4 +-- 7 files changed, 31 insertions(+), 31 deletions(-) diff --git a/src/resources/extensions/sf/bootstrap/db-tools.ts b/src/resources/extensions/sf/bootstrap/db-tools.ts index 9bfefb90f..69a03fce8 100644 --- a/src/resources/extensions/sf/bootstrap/db-tools.ts +++ b/src/resources/extensions/sf/bootstrap/db-tools.ts @@ -1497,7 +1497,7 @@ export function registerDbTools(pi: ExtensionAPI): void { description: "Whether a plan-invalidating blocker was discovered", }), ), - // ADR-011 Phase 2: mid-execution escalation — agent flags an ambiguity + // gsd-2 ADR-011 Phase 2: mid-execution escalation — agent flags an ambiguity // for the user. Only honored when phases.mid_execution_escalation=true. escalation: Type.Optional( Type.Object( @@ -1536,7 +1536,7 @@ export function registerDbTools(pi: ExtensionAPI): void { }, { description: - "ADR-011 P2: optional escalation payload. Only honored when phases.mid_execution_escalation is true.", + "gsd-2 ADR-011 P2: optional escalation payload. Only honored when phases.mid_execution_escalation is true.", }, ), ), diff --git a/src/resources/extensions/sf/commands-escalate.ts b/src/resources/extensions/sf/commands-escalate.ts index 6df25ce89..72feedcc0 100644 --- a/src/resources/extensions/sf/commands-escalate.ts +++ b/src/resources/extensions/sf/commands-escalate.ts @@ -1,4 +1,4 @@ -// SF Command — `/sf escalate` (ADR-011 P2) +// SF Command — `/sf escalate` (gsd-2 ADR-011 P2) // // Subcommands: // list — show pending escalations across all active milestones diff --git a/src/resources/extensions/sf/sf-db.ts b/src/resources/extensions/sf/sf-db.ts index aea9b0259..5929b5b7e 100644 --- a/src/resources/extensions/sf/sf-db.ts +++ b/src/resources/extensions/sf/sf-db.ts @@ -2255,7 +2255,7 @@ export function insertSlice(s: { } /** - * ADR-011: clear the is_sketch flag after refine-slice fills in the full plan. + * gsd-2 ADR-011: clear the is_sketch flag after refine-slice fills in the full plan. * Idempotent — safe to call on already-refined slices. */ export function clearSliceSketch(milestoneId: string, sliceId: string): void { @@ -2263,7 +2263,7 @@ export function clearSliceSketch(milestoneId: string, sliceId: string): void { } /** - * ADR-011 (gsd-2 parity): generalized sketch-flag setter — flip true or false. + * gsd-2 ADR-011: generalized sketch-flag setter — flip true or false. * Idempotent. Use this instead of clearSliceSketch when you also need to * mark a slice as a sketch (e.g., a re-plan flow that wants to revert to * sketch-then-refine). @@ -2286,7 +2286,7 @@ export function setSliceSketchFlag( } /** - * ADR-011 auto-heal: reconcile stale is_sketch=1 rows whose PLAN file already + * gsd-2 ADR-011 auto-heal: reconcile stale is_sketch=1 rows whose PLAN file already * exists on disk. The caller passes a predicate that uses the canonical path * resolver so path logic stays in one place. Safe to call repeatedly — only * flips rows that meet the predicate. @@ -2309,7 +2309,7 @@ export function autoHealSketchFlags( } /** - * ADR-011 P2 (gsd-2 parity): list tasks across a milestone that have an + * gsd-2 ADR-011 P2: list tasks across a milestone that have an * escalation artifact path. By default returns only ACTIVE escalations * (pending OR awaiting_review); pass includeResolved=true to also return * resolved-but-still-recorded entries (audit trail). @@ -2481,7 +2481,7 @@ export function updateTaskStatus( }); } -/** ADR-011 P2: set pause-on-escalation state on a task. The two flags are +/** gsd-2 ADR-011 P2: set pause-on-escalation state on a task. The two flags are * mutually exclusive — pending=1 forces awaiting_review=0. */ export function setTaskEscalationPending( milestoneId: string, @@ -2506,7 +2506,7 @@ export function setTaskEscalationPending( }); } -/** ADR-011 P2: continueWithDefault=true marker — artifact exists but no pause. +/** gsd-2 ADR-011 P2: continueWithDefault=true marker — artifact exists but no pause. * Mutually exclusive with escalation_pending. */ export function setTaskEscalationAwaitingReview( milestoneId: string, @@ -2531,7 +2531,7 @@ export function setTaskEscalationAwaitingReview( }); } -/** ADR-011 P2: clear both escalation flags (called when an escalation is +/** gsd-2 ADR-011 P2: clear both escalation flags (called when an escalation is * resolved or its artifact is removed). Leaves escalation_artifact_path so * the resolution audit trail survives. */ export function clearTaskEscalationFlags( @@ -2550,7 +2550,7 @@ export function clearTaskEscalationFlags( .run({ ":mid": milestoneId, ":sid": sliceId, ":tid": taskId }); } -/** ADR-011 P2 carry-forward: find a task in this slice that has a resolved +/** gsd-2 ADR-011 P2 carry-forward: find a task in this slice that has a resolved * escalation override that has NOT yet been injected into a downstream * prompt. Returns the first match by sequence (lowest first), or null when * no carry-forward is pending. @@ -2585,7 +2585,7 @@ export function findUnappliedEscalationOverride( return { taskId: row.id, artifactPath: row.escalation_artifact_path }; } -/** ADR-011 P2 carry-forward: atomically claim the override for injection. +/** gsd-2 ADR-011 P2 carry-forward: atomically claim the override for injection. * Returns true when this caller successfully flipped 0→1 (race winner) or * false when another caller claimed it first (race loser). Use this to * guarantee the override is injected exactly once. */ @@ -2693,7 +2693,7 @@ export interface SliceRow { replan_triggered_at: string | null; /** Optional freeform scope sketch written at plan-slice time. */ sketch_scope?: string | null; - /** ADR-011: 1 = slice is a sketch awaiting refinement, 0 = full plan. Column may be absent on + /** gsd-2 ADR-011: 1 = slice is a sketch awaiting refinement, 0 = full plan. Column may be absent on * pre-migration installs (gated by phases.progressive_planning preference). */ is_sketch?: number; } @@ -2828,14 +2828,14 @@ export interface TaskRow { full_plan_md: string; sequence: number; verification_status?: string; - /** ADR-011 P2: 1 = task is paused waiting for the user to resolve an escalation. */ + /** gsd-2 ADR-011 P2: 1 = task is paused waiting for the user to resolve an escalation. */ escalation_pending?: number; - /** ADR-011 P2: 1 = continueWithDefault=true marker — artifact recorded but loop not paused. */ + /** gsd-2 ADR-011 P2: 1 = continueWithDefault=true marker — artifact recorded but loop not paused. */ escalation_awaiting_review?: number; - /** ADR-011 P2 carry-forward: 1 once the resolved override has been injected + /** gsd-2 ADR-011 P2 carry-forward: 1 once the resolved override has been injected * into a downstream prompt. Race-safe atomic claim via claimEscalationOverride. */ escalation_override_applied?: number; - /** ADR-011 P2: relative path to the T##-ESCALATION.json artifact next to T##-PLAN.md. */ + /** gsd-2 ADR-011 P2: relative path to the T##-ESCALATION.json artifact next to T##-PLAN.md. */ escalation_artifact_path?: string | null; } diff --git a/src/resources/extensions/sf/tools/plan-milestone.ts b/src/resources/extensions/sf/tools/plan-milestone.ts index 62f594e6e..91d960dc0 100644 --- a/src/resources/extensions/sf/tools/plan-milestone.ts +++ b/src/resources/extensions/sf/tools/plan-milestone.ts @@ -34,17 +34,17 @@ export interface PlanMilestoneSliceInput { depends: string[]; demo: string; goal: string; - /** Required when isSketch is false/absent; may be empty for sketch slices (ADR-011). */ + /** Required when isSketch is false/absent; may be empty for sketch slices (gsd-2 ADR-011). */ successCriteria: string; - /** Required when isSketch is false/absent; may be empty for sketch slices (ADR-011). */ + /** Required when isSketch is false/absent; may be empty for sketch slices (gsd-2 ADR-011). */ proofLevel: string; - /** Required when isSketch is false/absent; may be empty for sketch slices (ADR-011). */ + /** Required when isSketch is false/absent; may be empty for sketch slices (gsd-2 ADR-011). */ integrationClosure: string; - /** Required when isSketch is false/absent; may be empty for sketch slices (ADR-011). */ + /** Required when isSketch is false/absent; may be empty for sketch slices (gsd-2 ADR-011). */ observabilityImpact: string; - /** ADR-011: when true, this slice is a sketch awaiting refine-slice expansion. */ + /** gsd-2 ADR-011: when true, this slice is a sketch awaiting refine-slice expansion. */ isSketch?: boolean; - /** ADR-011: 2–3 sentence scope boundary, required when isSketch is true. */ + /** gsd-2 ADR-011: 2–3 sentence scope boundary, required when isSketch is true. */ sketchScope?: string; } @@ -189,7 +189,7 @@ function validateSlices(value: unknown): PlanMilestoneSliceInput[] { const observabilityImpact = obj.observabilityImpact; const isSketchRaw = obj.isSketch; const sketchScopeRaw = obj.sketchScope; - // ADR-011: preserve 3-valued isSketch semantics (true/false/absent). + // gsd-2 ADR-011: preserve 3-valued isSketch semantics (true/false/absent). // Absent must round-trip as undefined so DB upsert ON CONFLICT preserves // any existing is_sketch row state rather than silently overwriting. const isSketch: boolean | undefined = @@ -221,7 +221,7 @@ function validateSlices(value: unknown): PlanMilestoneSliceInput[] { if (!isNonEmptyString(goal)) throw new Error(`slices[${index}].goal must be a non-empty string`); - // ADR-011: sketch slices defer the heavyweight planning fields to + // gsd-2 ADR-011: sketch slices defer the heavyweight planning fields to // refine-slice. Non-sketch slices must populate them up front. if (isSketch === true) { if (!isNonEmptyString(sketchScopeRaw)) { @@ -505,7 +505,7 @@ export async function handlePlanMilestone( isSketch: slice.isSketch, sketchScope: slice.sketchScope, }); - // ADR-011: sketches defer planning fields to refine-slice — only + // gsd-2 ADR-011: sketches defer planning fields to refine-slice — only // upsert when we actually have content to write. if (slice.isSketch !== true) { upsertSlicePlanning(params.milestoneId, slice.sliceId, { diff --git a/src/resources/extensions/sf/tools/plan-slice.ts b/src/resources/extensions/sf/tools/plan-slice.ts index 3d2858c0c..12dab5de5 100644 --- a/src/resources/extensions/sf/tools/plan-slice.ts +++ b/src/resources/extensions/sf/tools/plan-slice.ts @@ -320,7 +320,7 @@ export async function handlePlanSlice( planningMeeting: params.planningMeeting, }); - // ADR-011: when sf_plan_slice runs against a sketch slice (refine-slice + // gsd-2 ADR-011: when sf_plan_slice runs against a sketch slice (refine-slice // produced a full plan from the sketch_scope hint), clear the is_sketch // flag atomically with the plan write so the next dispatch cycle no // longer routes to refine. Idempotent — no-op for non-sketches. diff --git a/src/resources/extensions/sf/tools/workflow-tool-executors.ts b/src/resources/extensions/sf/tools/workflow-tool-executors.ts index f3f489561..920259fdb 100644 --- a/src/resources/extensions/sf/tools/workflow-tool-executors.ts +++ b/src/resources/extensions/sf/tools/workflow-tool-executors.ts @@ -218,7 +218,7 @@ type VerificationEvidenceInput = } | string; -/** ADR-011 Phase 2: optional escalation payload on sf_task_complete. +/** gsd-2 ADR-011 Phase 2: optional escalation payload on sf_task_complete. * When phases.mid_execution_escalation is enabled, the executor calls * buildEscalationArtifact + writeEscalationArtifact after the task is * recorded, flipping the appropriate task escalation flag. */ @@ -307,7 +307,7 @@ export async function executeTaskComplete( }; } - // ADR-011 P2: optional escalation payload. Only honored when the + // gsd-2 ADR-011 P2: optional escalation payload. Only honored when the // phases.mid_execution_escalation preference is true. When false (default), // any escalation field on the params is silently ignored — keeps the // payload backwards-compatible for callers that always send it. diff --git a/src/resources/extensions/sf/unit-context-manifest.ts b/src/resources/extensions/sf/unit-context-manifest.ts index 5de10cacf..12526aca3 100644 --- a/src/resources/extensions/sf/unit-context-manifest.ts +++ b/src/resources/extensions/sf/unit-context-manifest.ts @@ -297,7 +297,7 @@ export const KNOWN_UNIT_TYPES = [ "run-uat", "gate-evaluate", "rewrite-docs", - // ADR-011 deep planning gate (project-scoped, before any milestone work) + // gsd-2 ADR-011 deep planning gate (project-scoped, before any milestone work) "discuss-project", "discuss-requirements", "research-project", @@ -643,7 +643,7 @@ export const UNIT_MANIFESTS: Record = { }, maxSystemPromptChars: COMMON_BUDGET_MEDIUM, }, - // ─── Project-scoped (deep planning gate, ADR-011) ─────────────────── + // ─── Project-scoped (deep planning gate, gsd-2 ADR-011) ─────────────────── "discuss-project": { skills: { mode: "all" }, knowledge: "full",