Type-level + DB scaffolding for the escalation feature gsd-2 has but
SF lacks. Pure additive — no behavior change yet. Mirrors the same
incremental pattern that worked for progressive planning (types +
DDL first, state derivation + dispatch + module port in subsequent
fires).
PDD spec:
Purpose: lay the foundation so a task agent can write
tasks.escalation_pending=1 + escalation_artifact_path=<file> when
it hits a decision the user must make. Future fires will: (1) add
detectPendingEscalation() to state.ts, (2) add a dispatch rule that
returns 'stop' on phase='escalating-task', (3) port the escalation
helper module from gsd-2.
Consumer: task agents (execute-task) when they hit ambiguity that
shouldn't be silently resolved. Operators running future
/sf escalate list/resolve commands.
Contract:
- types.ts:23 Phase union now includes 'escalating-task'.
- sf-db.ts:370-371 fresh CREATE TABLE for tasks gains
escalation_pending + escalation_artifact_path.
- sf-db.ts:1430+ schema_version 23 migration adds the columns +
an opportunistic index for fast pending-escalation lookups.
- TaskRow type gains escalation_pending?: number and
escalation_artifact_path?: string | null. rowToTask returns
them with safe defaults (0 and null).
Failure boundary: index creation is wrapped in try/catch — backends
without index support fall through silently. Pre-migration installs
treat the column as 0 default (no escalation pending) on first
read, matching post-migration default.
Evidence: typecheck passes; smoke test deferred to next fire when the
state derivation rule lands and we have something observable to
test.
Non-goals:
- state.ts emission of phase='escalating-task' (next fire)
- auto-dispatch.ts pause rule (next fire)
- escalation.ts helper module port (next fire — 367 LOC in gsd-2)
- /sf escalate user command (later fire)
- Escalation artifact format/validation (later fire)
Invariants:
- Safety: ALTER TABLE adds nullable/defaulted columns; existing
rows behave identically (escalation_pending defaults to 0).
- Liveness: migration runs in same atomic transaction block as
other version 23 work — never half-applied.
Assumptions verified:
- SF already has EscalationOption + EscalationArtifact types
(types.ts:692-704) — they were stubs with no producers; this
commit is the producer-side scaffolding.
- schema_version 22 already exists and is the current latest;
23 is the next available.
ADR-011 reference: gsd-2's docs/dev/ADR-011-progressive-planning-
escalation.md covers both progressive planning (already ported in
this session) and mid-execution escalation (in progress). SF's own
ADR-011 file (docs/dev/ADR-011-swarm-chat-and-debate-mode.md) is
unrelated to gsd-2's ADR-011 — same number, different topic.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
62dacb6270