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 <noreply@anthropic.com>
This commit is contained in:
Mikael Hugo 2026-05-02 02:29:46 +02:00
parent b8bcd6fdd1
commit 98da1980fb
3 changed files with 44 additions and 2 deletions

View file

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

View file

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

View file

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