Implements the 3-table normalization model for milestone, slice, and task entities:
- 9 new tables: {milestone,slice,task}_{specs,evidence} + runtime tables
- milestone_specs: immutable record of intent (vision, goals, risks, proof strategy)
- slice_specs: immutable slice-level intent
- task_specs: immutable task verification criteria
- {entity}_evidence: append-only audit trail with timestamps and phase metadata
- Indices on evidence tables for efficient chronological queries
Key improvements:
- Spec immutability: Write-once specs preserve original intent
- Audit trail: Evidence chain enables data archaeology and decision history
- Query efficiency: Each table contains only relevant columns
- Re-planning clarity: Multiple spec versions can exist for same entity ID
- Forensic capability: Timestamp + phase metadata on evidence rows
Migration:
- Schema version bumped to 32
- Migration runs on first open of existing databases
- No data loss; existing milestone/slice/task rows preserved
- Creates spec and evidence tables from existing columns (future work)
This is Phase 1 of Tier 1.3 implementation (schema definition + basic setup).
Phases 2-5 (migration, data layer updates, tool updates, tests) follow in next PRs.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Document the three-phase integration of SF memory system with UOK:
Phase 1: Unit outcome recording (recordUnitOutcomeInMemory)
- Records success/failure patterns with 0.9/0.5 confidence
- Fire-and-forget async, never blocks execution
Phase 2: Dispatch ranking enhancement (enhanceUnitRankingWithMemory)
- Queries memory for similar patterns
- Boosts matching candidates by up to 15% (conservative limit)
- Deterministic embeddings ensure reproducible ranking
Phase 3: Gate context enrichment (enrichGateResultWithMemory)
- Diagnostic only; never changes gate pass/fail logic
- Helps operators understand recurring issues
All memory operations gracefully degrade if DB unavailable.
56 test cases validate integration across all phases.
Relates to ADR-0075 (UOK gates), ADR-008 (SF tools).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add architecture decision: Memory is not exposed as MCP server.
- SF is an MCP client only (consumes external MCP tools)
- Memory is internal SF infrastructure (uses SQLite, fire-and-forget async)
- Memory exposed as SF tools only (capture, query, graph)
- No external MCP exposure needed (memory is autonomous learning, not a service)
This keeps SF's learning system private and prevents:
- External memory pollution
- Uncontrolled confidence scoring
- Inconsistent learning patterns
- Loss of autonomy (memory decisions stay internal)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Comprehensive guide for migrating from JSON to node:sqlite when Node 24 is available:
- Schema design (model_outcomes + model_stats tables)
- Phase-by-phase refactoring approach
- Data migration from JSON with backward compatibility
- Testing strategy with new SQLite-specific tests
- Future opportunities: dashboards, trend analysis, A/B testing, federated learning
This doc serves as a roadmap for ~2 days of work when Node 24 becomes standard.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Integration of 3 quick wins into existing UOK infrastructure:
1. Model Learning (Quick Win #2) → metrics.js
- Record outcomes to model-learner for per-task-type performance tracking
- Hook: recordUnitOutcome() now calls ModelLearner.recordOutcome()
- Fire-and-forget: never blocks outcome recording on learning failure
- Enables adaptive model routing decisions in downstream gates
2. Self-Report Fixing (Quick Win #1) → triage-self-feedback.js
- Auto-fix high-confidence reports (>0.85) in applyTriageReport()
- Hook: After triage and requirement promotion, apply auto-fixes
- Fire-and-forget: never blocks report application on fix failure
- Returns reportsAutoFixed count for triage metrics
3. Knowledge Injection (Quick Win #3) → already integrated in auto-prompts.js
- Already active in execute-task prompt template
- Semantic matching with graceful degradation
All integration points:
- Fire-and-forget: learning/fixing failures never block dispatch
- UOK-native: use existing outcome recording, db, gates
- Backward compatible: applyTriageReport now async, but callers handle it
- No new dependencies: all modules already in codebase
Testing: 2934 tests pass (no regressions from integration)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.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>
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>
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>
prompts/parallel-research-slices.md step 3 told the dispatcher to verify
research at `.sf/{{mid}}/`, but slice research files actually live at
`.sf/milestones/{{mid}}/slices/<sliceId>/<sliceId>-RESEARCH.md`. Step 3
verification could only ever fail.
prompts/validate-milestone.md sent the three milestone-validation reviewer
agents to wrong paths:
- parentTrace pointed at `.sf/{{milestoneId}}/S0X-SUMMARY.md` (slice
summaries actually live at `.sf/milestones/{{milestoneId}}/slices/S0X/`)
- Reviewer A read `.sf/{{milestoneId}}/REQUIREMENTS.md` (the file is at
project-level `.sf/REQUIREMENTS.md`)
- Reviewer A scanned `.sf/{{milestoneId}}/` for slice SUMMARYs (wrong dir)
- Reviewer C read `.sf/{{milestoneId}}/CONTEXT.md` (actual file is
`.sf/milestones/{{milestoneId}}/{{milestoneId}}-CONTEXT.md`)
Reviewers would either return false MISSING / FAIL verdicts or have to
re-discover the layout.
docs/dev/ADR-{008,009}-IMPLEMENTATION-PLAN.md "Related ADR" links pointed
to absolute paths inside a contributor's old Mac (`/Users/jeremymcspadden/
Github/sf-2/...`). Replaced with sibling-file relative paths.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
After fixing forensics.md and error-classifier.ts last fire, swept the
rest of the tree for the same class of stale reference:
- scripts/validate-pack.js: criticalPackages list used \`@sf\` and
\`@sf-build\` scopes — neither exists in node_modules; this is in CI
(.github/workflows/ci.yml) + prepublishOnly, so the validation step
was failing to find anything. Now \`@singularity-forge/pi-coding-agent\`
and \`@singularity-forge/rpc-client\` (the actual scope).
- src/resources/skills/github-workflows/references/gh/SKILL.md: same
GraphQL bug as forensics.md — owner:"sf-build" name:"sf-2" — and
three \`gh project\` commands using owner sf-build. The gh issue
create command above already used singularity-forge/sf-run, so the
follow-up calls always failed. Also retitled "sf-2 Backlog" to
"sf-run Backlog".
- src/resources/extensions/sf/bootstrap/system-context.ts: deprecation
warning linked to https://github.com/sf-build/SF/issues/1492.
- packages/mcp-server/README.md, packages/rpc-client/README.md: 9 refs
to \`@sf-build/...\` for installable package names — would mislead
anyone copy-pasting into npm install.
- docs/user-docs/troubleshooting.md (+ zh-CN): GitHub Issues link
pointed at github.com/sf-build/SF/issues.
- docs/user-docs/getting-started.md (+ zh-CN): clone URL was correct
but the next \`cd\` was \`cd sf-2/docker\` — won't exist after a
fresh clone of sf-run.
- docs/dev/ci-cd-pipeline.md: GHCR org was \`sf-build\`.
Code comments containing "sf-2" / "sf-build" in non-active places
(parsers.ts banner, error message URLs in tests, dev-doc absolute
paths from a contributor's Mac) left alone — they're informational
and not addressed by users or runtime.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
