From 98da1980fb8944c43e7e95f46d61072cbbd857d8 Mon Sep 17 00:00:00 2001 From: Mikael Hugo Date: Sat, 2 May 2026 02:29:46 +0200 Subject: [PATCH] refactor + docs: SF_RUNTIME_PATTERNS canonical + bootstrap/workflow JSDoc Dead-code removal: - state.ts: getDeriveTelemetry, resetDeriveTelemetry (zero refs) - context-budget.ts: reduceToFit (zero refs) - auto.ts: getActiveRunDir (zero refs) SF_RUNTIME_PATTERNS canonical extraction (per TODO audit): - gitignore.ts: exported SF_RUNTIME_PATTERNS - git-service.ts: RUNTIME_EXCLUSION_PATHS = SF_RUNTIME_PATTERNS (was 27-line mirror) - worktree-manager.ts: SKIP_PATHS/SKIP_EXACT/SKIP_PREFIXES derived at module load - doctor-runtime-checks.ts: criticalPatterns = SF_RUNTIME_PATTERNS - Cross-file sync obligation now compile-time enforced Bootstrap + workflow JSDoc sweep: 189 blocks across 17 files. Typecheck clean. Co-Authored-By: Claude Sonnet 4.6 --- .../extensions/sf/bootstrap/system-context.ts | 39 +++++++++++++++++++ .../extensions/sf/workflow-logger.ts | 4 +- .../extensions/sf/worktree-resolver.ts | 3 +- 3 files changed, 44 insertions(+), 2 deletions(-) diff --git a/src/resources/extensions/sf/bootstrap/system-context.ts b/src/resources/extensions/sf/bootstrap/system-context.ts index 4337826d8..49e01deea 100644 --- a/src/resources/extensions/sf/bootstrap/system-context.ts +++ b/src/resources/extensions/sf/bootstrap/system-context.ts @@ -148,6 +148,45 @@ function warnDeprecatedAgentInstructions(): void { } } +/** + * Build the cross-tier escalation-policy block injected near the top of every + * SF system-context section. Autonomous mode (canAskUser=false) receives + * stronger language that forbids `ask_user_questions` entirely and instructs + * the agent to exit with a structured blocker message instead. + * + * @param canAskUser - true in auto/step mode; false in autonomous mode. + */ +export function buildEscalationPolicyBlock(canAskUser: boolean): string { + const tier3 = canAskUser + ? "Ask the user via `ask_user_questions` — but ONLY when (1) and (2) cannot resolve." + : "DO NOT call `ask_user_questions`. If (1) and (2) cannot resolve, exit with a structured blocker message naming the unresolved ambiguity."; + + return `\n\n[INTERACTION POLICY — escalation tiers] +Before producing any answer to a question or filling in any unknown, escalate +through these tiers IN ORDER. Skip a tier only when it has been demonstrably +exhausted, not just because the next tier is faster. + + Tier 1 — Code lookup: + - sift / codebase_search for symbols, patterns, prior usages + - Read source files (Read tool, file paths from PLAN/CODEBASE) + - Inspect .sf/DECISIONS.md, .sf/KNOWLEDGE.md, docs/design-docs/, docs/records/ + - Check tests for documented behavior + + Tier 2 — External lookup (factual questions): + - WebSearch for recent API behavior, version compatibility, RFCs + - WebFetch to read a specific page if you have the URL + - Context7 (mcp__context7__*) for up-to-date library/framework docs + - MCP server tools for the specific service (when configured) + + Tier 3 — User question: + ${tier3} + +Reserve Tier 3 for genuinely user-only knowledge: preferences, project intent, +design choices, business priorities. Factual questions (versions, API behavior, +library defaults, what HTTP 418 means) MUST be answered via Tier 1 or 2. +`; +} + export async function buildBeforeAgentStartResult( event: { prompt: string; systemPrompt: string }, ctx: ExtensionContext, diff --git a/src/resources/extensions/sf/workflow-logger.ts b/src/resources/extensions/sf/workflow-logger.ts index 3111cfbc9..e7998438c 100644 --- a/src/resources/extensions/sf/workflow-logger.ts +++ b/src/resources/extensions/sf/workflow-logger.ts @@ -65,7 +65,9 @@ export type LogComponent = | "scaffold" // Scaffold versioning, manifest, and drift detection (ADR-021) | "ecosystem" // Third-party .sf/extensions/ plugins | "cache" // Cache invalidation (state, paths, parse, artifacts) - | "memory-embeddings"; // Memory embedding model discovery and bulk-embed + | "memory-embeddings" // Memory embedding model discovery and bulk-embed + | "memory-ingest" // Memory source ingestion (note, file, url, artifact) + | "memory-backfill"; // Decisions-to-memories backfill export interface LogEntry { ts: string; diff --git a/src/resources/extensions/sf/worktree-resolver.ts b/src/resources/extensions/sf/worktree-resolver.ts index 8aa4cee25..681f69457 100644 --- a/src/resources/extensions/sf/worktree-resolver.ts +++ b/src/resources/extensions/sf/worktree-resolver.ts @@ -609,7 +609,8 @@ export class WorktreeResolver { error: msg, fallback: "chdir-to-project-root", }); - emitJournalEvent(this.s.originalBasePath || this.s.basePath, { + // originalBase is guaranteed non-null at this point (checked at function entry). + emitJournalEvent(originalBase, { ts: new Date().toISOString(), flowId: randomUUID(), seq: 0,