singularity/singularity-forge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

docs(sf): finish ADR-011 disambiguation across remaining .ts files

Browse source 
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) <noreply@anthropic.com>
This commit is contained in:
Mikael Hugo 2026-05-02 23:11:16 +02:00
parent f5dabf1857
commit ef82fbf2c6
7 changed files with 31 additions and 31 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
src/resources/extensions/sf/bootstrap/db-tools.ts
View file

@ -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.",
},
),
),

2
src/resources/extensions/sf/commands-escalate.ts
View file

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

28
src/resources/extensions/sf/sf-db.ts
View file

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

18
src/resources/extensions/sf/tools/plan-milestone.ts
View file

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

2
src/resources/extensions/sf/tools/plan-slice.ts
View file

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

4
src/resources/extensions/sf/tools/workflow-tool-executors.ts
View file

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

4
src/resources/extensions/sf/unit-context-manifest.ts
View file

@ -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<UnitType, UnitContextManifest> = {
},
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",