The acquiring-skills skill was a personal developer workflow with
hardcoded paths that did not apply to general sf users.
Rationale for removal rather than generalization:
- SF bundled skills are already generic and installed for all users.
- External skills are consumed via the Anthropic marketplace.
- Per-project custom skills are covered by the creating-skills skill.
Resolves self-feedback sf-mookqlyr-snco79.
Replace the developer-specific acquiring-skills skill with a generic
version that any SF user can follow.
Changes:
- Removed all personal references (/home/mhugo/code/, mikki-bunker,
ace-coder, letta-workspace, dr-repo, singularity-package-intelligence)
- Replaced Method 2 (rsync from local repos) and Method 3 (rsync from
bunker) with a generic local-project porting workflow
- Replaced Trusted Sources table with only public, universally
accessible repositories (anthropics/skills, singularity-forge)
- Kept all safety rules (inspect scripts, no curl|bash, untrusted
sources require approval)
- Kept the Adaptation Checklist for porting foreign skills to sf
- References the Anthropic skills marketplace as the primary source
Resolves self-feedback sf-mookqlyr-snco79.
Prevents pi runtime flow-audit from emitting false-positive stale-dispatch
warnings for slices that completed successfully on retry.
Problem: when a complete-slice unit is cancelled (e.g. provider quota error)
and then retried successfully, the prior cancelled journal/runtime state can
still trigger a flow-audit warning on the next session start. The detector
reads the cancelled unit-end event but does not check for later successful
retries or existing artifact files (#sf-moqv5o7h-vaabu6).
Fix: at auto-mode bootstrap, after cleanStaleRuntimeUnits, run a new
reconcileStaleCompleteSliceRecords() pass that:
- Lists all unit runtime records for complete-slice units
- Filters for terminal non-completed states (cancelled, failed, stale,
runaway-recovered)
- Checks DB slice status === 'complete'
- Checks SUMMARY.md exists with valid completed_at frontmatter
- Clears stale runtime records that pass both checks
Files changed:
- src/resources/extensions/sf/unit-runtime.js: add reconcileStaleCompleteSliceRecords
- src/resources/extensions/sf/auto-start.js: call it after cleanStaleRuntimeUnits
- src/tests/unit-runtime-reconcile.test.ts: unit tests for the new function
When offset or limit are specified, use Node.js readline streaming instead of
loading the entire file into memory. This fixes the truncation issue for large
files (>50KB) where the read tool would return truncated content even when
requesting a small slice.
- Add readLinesStreamed() for memory-efficient line reading
- Add countLines() for total line count without full read
- Use streaming path when offset !== undefined || limit !== undefined
- Keep existing full-file read path when no offset/limit specified
- Add tests for streaming behavior with large files
Fixes the long-standing issue where reading large files like src/headless.ts
(~50KB) with offset/limit would still hit truncation limits.
Adds three layers of defense against the M008/S03 failure mode where
bug-hunt findings referenced .ts files that had been deleted in a prior
corrupted snapshot commit (f712c339b), but .js versions with fixes survived.
1. Prompt-level safeguards:
- research-slice.md: researchers must verify file existence before listing
paths in findings
- plan-slice.md: planners must confirm files exist before including them
in task plans
- execute-task.md: executors must verify files exist before editing;
escalate as blocker if missing
2. Runtime pre-flight validation:
- system-context.js: validateTaskPlanFiles() extracts backtick-wrapped
paths from task plans and checks existence before dispatch
- Missing files trigger a warning injected into the execute-task prompt
- Logs warning for observability
This prevents the research→plan→execute pipeline from propagating stale
file paths that cause phantom work, runaway guard intervention, and
flow-audit failures.
Fixes: sf-moqgvdi7-mxc1sr (flow-audit:repeated-milestone-failure)
Related: M008/S03 bug-hunt cluster
Token count now only triggers a warning when accompanied by a primary
signal (high tool calls, long elapsed time, or many changed files).
This prevents false positives on units doing real work with large
context models, where 25+ tool calls can legitimately burn 1M+ tokens.
Also renames 'session tokens' to 'unit tokens' in guard messages to
clarify that the metric is delta-from-unit-start, not cumulative.
Fixes sf-moqewawp-ijwjjt
Pure-function tests for applyRelationBoost (55b14c3f7) cover the
math, but the wired-through path (createMemoryRelation → boost picked
up by getRelevantMemoriesRanked → reordered output) had no
end-to-end test.
New test:
1. Creates memories a, b, c with orthogonal embeddings
2. Mocks gateway to return a query vector aligned only with a
3. Wires a→b with related_to (confidence 1.0)
4. Asserts ranking: a (cosine top) > b (boost from a) > c (unrelated)
Locks the contract that the boost actually fires through the full
pipeline, not just the pure helper. 16 → 17 tests in the file.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The header listed "artifact I/O, detection, flag flips, resolution" but
not the carry-forward injection (claimOverrideForInjection /
formatOverrideBlock) or the memory persistence calls now embedded in
both writeEscalationArtifact (continueWithDefault path, b9bff3762
sibling) and resolveEscalation (00c13bc5a). These are load-bearing
behaviors a contributor should know up front.
Also folded the "SF's local ADR-011 is 'Swarm Chat'" disambiguation
note into the header (matches the convention the rest of the
disambiguation sweep set).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
memory-sleeper.ts had no file header and the "memory" prefix is
misleading — it's a runtime tool-output watchdog (detects repeated
bash failures, too-large tool results) that emits steers, completely
unrelated to memory-store / memory-relations / memory-embeddings.
A contributor reading directory listing top-down would reasonably
assume this file participates in the same pipeline as the other
memory-*.ts modules. Header now states the historical naming and
points readers in the right direction.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The previous header had two stale references:
- "buildMemoryLLMCall pattern, prefers a dedicated embedding-capable
model" — describes a hook that actually returns null on every call
(the Pi SDK has no provider-neutral embedding API yet).
- "queryMemoriesRanked falls back to keyword-only scoring" —
function doesn't exist; the real consumer is
getRelevantMemoriesRanked, and the fallback is static (confidence
× hit_count), not keyword.
Updated to describe the actual three-stage read pipeline (cosine →
relation-boost → optional rerank) and the soft-degrade fallback to
static ranking when the gateway is offline.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The file header described an aspirational design ("LINK actions
emitted by the memory extractor, or future /sf memory link CLI") that
never matched code reality. As of this session:
Writers shipped:
(a) applyMemoryActions auto-links co-extracted memories with
related_to (b9bff3762)
(b) /sf memory import loads explicit edges from JSON
Read consumers shipped:
(1) getRelevantMemoriesRanked graph-boost (55b14c3f7)
(2) sf_graph MCP tool (pre-existing)
Updated the header so a contributor reading top-down sees the
current data flow, not the original plan.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Updates 23c5de38b (which flagged the table as storage-only) to reflect
that 55b14c3f7 wired the ranker consumer (graph-boost in
getRelevantMemoriesRanked) and b9bff3762 wired the writer
(co-extraction linkage in applyMemoryActions). The graph-aware
pipeline is now end-to-end live, with named relation types,
auto-linking confidence (0.5), intra-pool boost, and damping (0.4).
Honest description for contributors reading top-down.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Previous commit (55b14c3f7) wired memory_relations into ranking, but
the table was empty — no writer added edges.
applyMemoryActions now links memories created in the same batch
pairwise with `related_to` edges (confidence 0.5 reflects "from same
extraction context" being weaker evidence than an explicit
human-authored relation). Pairwise O(n²) is fine for typical
extractor batches of 1–5 memories.
Combined with 55b14c3f7's relation-boost ranker, the effect is:
extracting memories A, B, C from one slice transcript ⇒ when later a
query hits A, B and C get a small score bump (and vice versa). The
cohort surfaces together rather than fragmenting across categories.
UPDATE / REINFORCE / SUPERSEDE actions don't trigger linkage —
linkage is for new co-extracted context, not modifications of
existing memories.
Best-effort: relation creation failures don't roll back the memory
batch. 14 → 16 tests in memory-store.test.ts; new tests verify the
3-memory batch yields C(3,2)=3 edges and a single-CREATE batch yields 0.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
memory_relations was storage-only since 56ee89a94 / 23c5de38b. Now
getRelevantMemoriesRanked walks edges of cosine top-N memories and
applies a one-pass score-boost to neighbors:
combined += parent_score × edge_confidence × damping
where damping=0.4 by default. Both endpoints of an edge get the boost
symmetrically (memory A pulling B is equally evidence that B is
relevant to A's context).
Pure helper `applyRelationBoost(ranked, edges, options)` lives in
memory-embeddings.ts so memory-store.ts doesn't take a direct
dependency on memory-relations.ts; the call site composes the two
modules. When memory_relations is empty (the case until a writer
adds edges — a future agent or hook), applyRelationBoost returns the
input unchanged → no behavior change today.
Intra-pool only: cross-pool edges (where one endpoint is outside the
50–200 cosine pool) are skipped to avoid pulling in low-static
memories on a hot edge alone. Pool expansion via relations would be
a separate, more invasive feature.
4 new tests cover empty edges, empty ranked, cross-pool edge skip,
and the canonical "low-but-related promoted above lone" case.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Audit of all FROM/INTO/UPDATE clauses in the codebase against
CREATE TABLE statements found one missing index. memory_relations
PK is (from_id, to_id, rel) — covers from_id as leading column. But
memory-relations.ts:233 queries `WHERE to_id = :id` which would
full-scan once the relation count grows.
Added idx_memory_relations_to. Cheap insertion cost; avoids the
worst-case query as soon as a ranker consumer starts traversing
edges (the natural next-step from 23c5de38b).
Schema-gap audit (option 3 in the redirect): no other ghost-table
references found. unit_claims has its own .sf/unit-claims.db and
self-contained schema in unit-ownership.ts. active_decisions /
active_requirements / active_memories are CREATE VIEW IF NOT EXISTS,
properly created. "INTO worktree" was a JSDoc false positive.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Real semantic bug: getRelevantMemoriesRanked returns memories in
score-descending order (cosine + optional rerank), but
formatMemoriesForPrompt then re-grouped them by CATEGORY_PRIORITY
(gotcha=0 first, convention=1, ...). A high-relevance "convention"
memory got buried under low-relevance "gotcha" entries purely because
gotcha has higher category priority. The agent never saw the most
relevant items at the top.
formatMemoriesForPrompt gains a `preserveRankOrder` parameter (default
false for backward compat). When true:
- Renders bullets in input order
- Tags each line with [category] so the agent can still tell
gotchas from conventions
Wired auto-prompts.ts execute-task injection: when memoryQuery is
non-empty (i.e. query-aware ranker was used), pass true. Static-ranked
input keeps the historical category-grouped layout.
Tests verify both modes side-by-side using identical input — the
ordering flip is the load-bearing assertion.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Same disambiguation as 45b669ac3 but for the source-file header
comment (a contributor reading commands-escalate.ts top-down sees the
same surface as `/sf escalate help`).
Comment-only.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Commit 0f0aee5bf added the --all flag to /sf escalate list (showing
resolved entries in addition to active ones), but the usage() text
never advertised it. Operators discovered the flag only by reading
source. Adding it to the help line.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The architecture.md entry implied memory-relations.ts contributes to
ranking ("knowledge-graph edges between memories"). The read consumer
doesn't exist yet — getRelevantMemoriesRanked uses cosine + static
score, not graph traversal. Relations are written via /sf memory
import / createMemoryRelation but never read for ranking.
Updated the description so a contributor reading this file knows the
graph-traversal pipeline is the next logical extension, not something
that currently runs.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Pool was Math.min(50, limit * 5). For default limit=10 this gives 50
(intended 5× oversample for rerank). But for limit=100 it gives 50 —
caller asking for 100 results would silently get at most 50.
Now: max(limit, limit * 5), capped at 200 to bound rerank latency on
huge requests. Default behavior unchanged for limit ≤ 10; large
requests now work correctly.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two new tests covering the symmetric write shipped in 7a5b12540:
1. writeEscalationArtifact with continueWithDefault=true → memory
created with "[escalation:T##]" prefix, "auto-applied default:"
rationale marker, and Fail option label (the recommendation).
2. writeEscalationArtifact with continueWithDefault=false → NO memory
at write time (pending entries defer persistence to resolveEscalation
per existing behavior).
Together with the resolve-time tests in 3b5e6588e, all three
escalation flows (resolved, auto-accepted, default-applied) have
locked memory-persistence contracts. 23 → 25 tests in the file.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
When an agent escalates with continueWithDefault=true, it has already
proceeded with the recommendation — the artifact JSON captures the
audit trail but no other surface carries the rationale forward.
Downstream tasks running after this one would query memories and find
nothing about the choice.
resolveEscalation already writes a memory on the continueWithDefault=
false path (after operator resolves). This is the symmetric write for
the continueWithDefault=true path: same category="architecture",
same "[escalation:T##]" prefix, with the rationale prefixed
"auto-applied default: ..." so a journal scan can tell apart
continueWithDefault entries from operator-resolved ones.
Now a slice's full decision history (operator-resolved + auto-accepted
+ default-applied escalations) lives uniformly in the memory store and
flows into the cosine ranking for downstream prompts.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The execute-task escalation guidance claimed the user "can review or
override later via /sf escalate". Commit c1ce9aac1 already made the
already-resolved message explicit that auto-accepted decisions can't
be retroactively undone — the carry-forward into downstream tasks
happens before any operator could intervene.
Updated the agent-facing guidance to match: auto-mode accepts +
persists as memory + carries forward; the operator gets the audit
trail via /sf escalate list --all but the executed work stands. This
shifts the agent's incentive toward thorough rationale capture (since
that's what survives) rather than the false comfort of "the user can
fix it later".
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
After aa60821ec wired the rerank pass, the search header still said
"(embedding-ranked)" even when SF_LLM_GATEWAY_RERANK_MODEL was set
and the worker was online. The user couldn't tell whether they were
seeing cosine-only or rerank-enhanced results.
Now the header has three states:
- "(embedding+rerank-ranked)" — both env vars set
- "(embedding-ranked)" — only SF_LLM_GATEWAY_KEY set
- "(static rank — set SF_LLM_GATEWAY_KEY for embeddings)" — neither
Header-only diff. The rerank can still soft-degrade silently if the
worker is offline (caller throttles the warning to once/min) — header
reports the configured state, not the realized state.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three new tests covering the embedding-cleanup paths shipped in
7bec2dc2d / 1b71ddd17 / 05a326a29:
1. updateMemoryContent → drops the existing memory_embeddings row
(next backfill re-embeds the new content).
2. supersedeMemory → drops the superseded memory's embedding while
preserving the live one's.
3. enforceMemoryCap → sweeps embeddings of newly-superseded memories
so memory_embeddings stays aligned with active memories after a
batch cap.
Without these, a regression in the cleanup paths would silently leave
orphaned vectors that loadAllEmbeddings's superseded_by filter masks
at query time but bloats the table forever.
11 → 14 tests in memory-store.test.ts.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Commit 00c13bc5a added "createMemory on resolveEscalation" but the
behavior was untested — a regression that broke it would silently
disable the cross-session learning surface (the [escalation:T##]
memories are what carry agent rationales forward via getRelevantMemories
ranking).
Two new tests:
1. resolveEscalation with explicit user rationale → memory contains
the question, choice, and user rationale, category=architecture.
2. resolveEscalation with empty rationale → falls back to the
artifact's recommendationRationale (the formatEscalationMemoryContent
contract).
23 tests in the file now (was 21).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The "already-resolved" branch returned a bare timestamp with no
guidance. Auto-accepted escalations especially leave the user wondering
what to do — the carry-forward was already injected into the next
task, so this command can't retroactively undo the choice.
Now the message distinguishes auto-accepted vs user-resolved and, for
the auto-accepted case, points to `/sf memory note "..."` as the
forward-looking corrective surface (it lands in memory_embeddings on
next backfill and influences future ranking).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The repo's architecture file listed only `memory-extractor.ts` and
`memory-store.ts` — the rest of the memory subsystem
(`memory-embeddings.ts`, `memory-embeddings-llm-gateway.ts`,
`memory-relations.ts`, `memory-source-store.ts`) had no entry, so a
new contributor reading the file would miss them entirely.
Added one-line descriptions for each, including the gateway adapter's
opt-in env-var contract (`SF_LLM_GATEWAY_KEY`).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
When SF_LLM_GATEWAY_RERANK_MODEL is set but no rerank worker is online,
every memory query (per execute-task prompt assembly) would log
"[sf:memory-embeddings] WARN: llm-gateway /rerank unavailable (503)" —
several lines per turn, all redundant. The soft-degrade is expected in
this state.
Now the message logs at most once per 60s. Symmetric with the
runEmbeddingBackfill unavailable-throttle pattern. Both sad-path
loggers stay informative (the operator sees one line and knows the
worker is down) without drowning the journal.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
runEmbeddingBackfill fires on every agent_end (per-turn). When the
gateway is online and a project produces memories, every turn would
write a "[sf:memory-embeddings] WARN: backfill: embedded N memories"
line — successes labeled as warnings, repeating on every cycle. That
both inflates the stderr stream and misleads grep-for-WARN diagnostics.
Successes are routine; the function's return value carries the count
when a caller cares. Failures still log (throttled to 60s) via the
existing path. Net effect: the embedding pipeline runs silently in the
happy path.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Same orphan-cleanup as 1b71ddd17 but for the batch path. enforceMemoryCap
calls supersedeLowestRankedMemories, which marks N lowest memories
superseded in one UPDATE — bypassing the per-memory supersede embedding
cleanup. The result was that capping a project at 50 memories left dead
embedding rows for everything that got demoted.
Now: a single DELETE-IN-SUBQUERY removes embedding rows for any memory
that no longer has superseded_by IS NULL — covers both the cap path
and any historical orphans from before the per-row cleanup landed.
Best-effort; cap enforcement is load-bearing, embedding cleanup is not.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
supersedeMemory soft-deleted via superseded_by but left the
memory_embeddings row in place. loadAllEmbeddings already filters
by superseded_by IS NULL, so the orphaned row is harmless functionally
— but it wastes storage, complicates manual SQL audits, and is
inconsistent with updateMemoryContent (which already invalidates the
embedding via 7bec2dc2d).
Best-effort delete; supersede still succeeds even if the embedding
delete raises. Symmetric with the update path.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The gateway rerank surface was shipped dormant in 56ee89a94 — the
function existed but no consumer called it, so setting
SF_LLM_GATEWAY_RERANK_MODEL did nothing functional.
Now: after the cosine-rank top-K is computed, optionally call
rerankCandidates(query, top-K) when a rerank model is configured. Re-
sort by relevance_score; gracefully fall back to cosine order in every
sad path (no model, no worker, network error, malformed response).
Strictly additive precision boost — the cosine-only ranking path is
unchanged when rerank isn't enabled OR returns null.
Two new tests: rerank actively reorders the top-K when scores are
returned, and the no-worker-online soft-degrade path preserves cosine
order. 12 tests in the file passing.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Same UX refinement as e104f17ad applied to /sf escalate show <slice>/<task>.
Auto-mode resolutions now display "Auto-accepted <ts> → choice=..." instead
of the generic "Resolved <ts>". The userRationale prefix "auto-mode:"
already disambiguates the source; surfacing the verb makes the show view
match the list view's status semantics.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Auto-mode resolutions stamp the artifact with userRationale prefix
"auto-mode: ..." (set by auto-dispatch.ts when it auto-resolves an
escalation). The list view now shows "auto-accepted (accept)" for
those entries vs "resolved (option-id)" for user-resolved ones, so an
operator scanning `/sf escalate list --all` can tell at a glance which
decisions were autonomous and which had explicit human input.
The artifact JSON is unchanged — this is purely a list-formatter
refinement that surfaces information already recorded.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Last bare "ADR-011 P2" reference was in the user-facing /sf escalate
help description in commands/catalog.ts. The parallel session's
c481ede33 touched this file (added /sf reload) but left this line
untouched — fixing it now closes the disambiguation sweep across the
entire codebase outside test files.
Comment / string-literal only diff.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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>
Same fix as df095b406 / f1fc8cc86, applied to the schema-comment
references in sf-db.ts (column comments + migration comments). Future
maintainers reading SQL definitions like:
is_sketch INTEGER NOT NULL DEFAULT 0, -- ADR-011: 1 = slice is a sketch
would otherwise look up SF's local ADR-011 ("Swarm Chat") and find
nothing about sketches. Now reads "gsd-2 ADR-011" so the source-of-
truth is unambiguous.
Comment-only diff. The 5 remaining "(gsd-2)" parenthetical references
already disambiguate clearly enough; left intact to avoid churn.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Same fix as df095b406 but for the user-facing PREFERENCES.md template
that ships in /sf init projects. Reading "ADR-011 P2: mid-execution
escalation" without the gsd-2 prefix sends operators to SF's local
ADR-011 ("Swarm Chat and Debate Mode") which has nothing to do with
escalation.
Markdown-only.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
