**Status:** Draft — no active consumer. Parked here for when ACE Coder maintainers pull on convergence; SF's own priorities take precedence until then.
**Purpose:** Document six proven SF patterns that ACE Coder can adopt to stay conceptually compatible without collapsing the Forge/ACE split. Each pattern includes its SF implementation, the value it protects, and a concrete adoption path for ACE.
**Consumer:** ACE Coder maintainers and SF architects evaluating convergence points.
A layered, mergeable preference system that combines global user settings, project-level overrides, profile defaults, and mode defaults into a single effective configuration. SF preferences are stored as pure YAML (`preferences.yaml`) — no frontmatter markers — and support worktree-aware resolution so that linked worktrees read from the main worktree's project prefs.
- Global (`~/.sf/preferences.yaml`) + project (`.sf/preferences.yaml`) merge with project winning.
- Token profiles (`budget`, `speed`, `quality`) inject low-priority defaults for models and phase skips.
- Mode defaults (`solo` vs `team`) set context thresholds, timeouts, and parallel agent limits.
- Worktree-aware `projectPrefsRoot()` resolves the main worktree when running inside a git worktree.
- **Validation:** `preferences-validation.js` enforces schema and emits warnings for deprecated fields.
### ACE Adoption Path
1. Adopt a two-layer (global + workspace) YAML preference file with explicit merge semantics.
2. Introduce mode profiles (`solo`/`team`) that set safe defaults for context limits, timeouts, and parallelism.
3. Add validation at load time so bad prefs fail fast with a clear warning rather than silent misbehavior.
4. Keep preferences as pure data; avoid embedding logic (e.g., callback hooks) inside the preference file itself.
### Cross-References
-`docs/SPEC_FIRST_TDD.md` — Iron Law on preference-driven run control.
-`docs/adr/0000-purpose-to-software-compiler.md` — Run-control policy derived from confidence, risk, and reversibility.
---
## 2. PDD (Purpose-Driven Development)
### What It Is
Before any non-trivial implementation, SF requires eight structured fields — the PDD — that answer *why* the behavior exists, *who* uses it, and *what breaks* if it is wrong. PDD is the gate that blocks implementation until purpose is clear.
### SF Implementation
- **Spec:** `docs/SPEC_FIRST_TDD.md` and `docs/adr/0000-purpose-to-software-compiler.md`
- **Key fields:**
1.**Purpose** — why this behavior exists.
2.**Consumer** — who calls it in production.
3.**Contract** — observable behavior boundary.
4.**Failure Boundary** — failures that must be contained or surfaced.
5.**Evidence** — proof gathered so far.
6.**Non-Goals** — what is intentionally not solved here.
7.**Invariants** — rules that remain true across iterations.
8.**Assumptions** — uncertain facts and how to falsify them.
- **Enforcement:** Doctor checks reject malformed planning artifacts. Exported symbols must carry a JSDoc `Purpose:` line.
### ACE Adoption Path
1. Add a PDD gate to the planning phase (before coding starts) that requires at least Purpose, Consumer, Contract, and Evidence.
2. Require every exported function to open with a JSDoc block containing `Purpose:` and `Consumer:`.
3. Treat tests as the spec — write the failing test for the *correct* behavior before fixing a bug.
4. Use the PDD fields as the schema for autonomous checkpoints so the solver can verify intent was preserved.
-`docs/adr/0077-spec-runtime-evidence-schema-separation.md` — Separating spec (immutable intent) from runtime (mutable state) and evidence (audit trail).
---
## 3. UOK Gates
### What It Is
A structured, extensible post-unit verification pipeline. Every gate implements a uniform execution contract, emits durable audit events, and respects a per-failure-class retry matrix. Gates run in parallel where possible and are protected by circuit breakers.
1. Replace ad-hoc post-task checks with a gate registry that accepts new gates as single files + a registration line.
2. Standardize gate output to `outcome` + `failureClass` + `rationale` so downstream automation can act on it.
3. Add a retry matrix per failure class rather than hard-coding retries per check.
4. Introduce circuit breakers on expensive or flaky gates so one bad gate does not stall the entire pipeline.
### Cross-References
-`docs/adr/0075-uok-gate-architecture.md` — Full gate contract, retry matrix, and circuit-breaker design.
-`docs/adr/0076-uok-memory-integration.md` — Gate failures enriched with historical memory context.
---
## 4. Notifications
### What It Is
A durable, classified notification store that survives context resets and session restarts. Notifications carry `noticeKind` metadata (`system_notice`, `tool_notice`, `blocking_notice`, `user_visible`) so renderers can group and style them without parsing message text. Deduplication uses `dedupe_key` with a time window, and noisy status patterns are suppressed.
### SF Implementation
- **Source:** `src/resources/extensions/sf/notification-store.js` and `notification-overlay.js`
- **Key behaviors:**
- Persisted to `.sf/notifications.jsonl` with a schema version and a max-entry rotation cap (500).
-`NOTICE_KIND` classification separates automated workflow notices from user-visible messages.
- Deduplication: rows with the same `dedupe_key` within `DURABLE_DEDUP_WINDOW_MS` merge into one row with `repeatCount`.
- Actionable kinds (`action_required`, `approval_request`, `blocker`, `error`, `terminal`) never merge.
- Overlay: scrollable history panel with severity filtering, toggled via `Ctrl+Alt+N`.
### ACE Adoption Path
1. Add a `noticeKind` field to all notification events so the UI can distinguish system chatter from user-facing messages.
2. Persist notifications to disk (JSONL or SQLite) so they survive restarts and can be reviewed later.
3. Implement deduplication with `dedupe_key` rather than string matching to avoid spam.
4. Never render automated notices as if the user typed them.
### Cross-References
-`docs/product-specs/notification-source-hygiene.md` — Source classification and trust preservation.
-`docs/adr/0002-sf-schedule-pull-based.md` — Why SF avoids background notification daemons.
---
## 5. Skills-as-Contracts
### What It Is
SF skills are markdown files with YAML frontmatter that act as invocation contracts. The frontmatter declares permission profiles, side-effect awareness, and invocation policy so the loader can enforce safety without loading the full skill body into model context.
Every durable write path in SF is designed to be safe to call multiple times. DB operations use upserts, runtime record writes are versioned, and crash recovery assumes the last operation may have partially succeeded.
-`writeUnitRuntimeRecord` merges with previous state on disk rather than blindly overwriting; `recoveryAttempts`/`retryCount` are coalesced safely.
-`reconcileDurableCompleteUnitRuntimeRecords` and `reconcileStaleCompleteSliceRecords` clear runtime records only when durable artifacts (DB + SUMMARY.md) prove completion, preventing double-recovery.
- DB writer uses `upsertRequirement`, `upsertDecision`, `upsertTaskPlanning` — safe to retry.
-`clearRunawayRecoveredRuntimeRecords` is idempotent: clearing an already-cleared record is a no-op.
*This document is a convergence artifact. It does not mandate ACE adoption; it documents proven patterns so both systems can share vocabulary and reduce integration friction.*
