# Records Note — 2026-05-01

## What Changed

**commit `a611cd579`** — feat: introduce repo-vcs skill and add JSDoc annotations across core modules

- `src/resources/extensions/sf/repository-vcs-context.ts` — new: detects Git vs Jujutsu, builds VCS guidance block injected into system prompt
- `src/resources/skills/repo-vcs/` — new: bundled skill for commit, push, safe-push workflows
- `src/resources/extensions/sf/bootstrap/system-context.ts` — added `repo-vcs` to bundled skill trigger table; injects `repositoryVcsBlock` into system prompt
- `src/resources/extensions/sf/tests/repository-vcs-context.test.ts` — new: test suite for VCS context detection
- JSDoc `Purpose:` and `Consumer:` annotations added to: `app-paths.ts`, `bundled-extension-paths.ts`, `errors.ts`, `extension-discovery.ts`, `extension-registry.ts`, `headless-types.ts`, `headless.ts`, `traces.ts`
- `flake.nix` — added `just` to devShell
- `justfile` — new: build, test, typecheck, lint, sf recipes

**Notification specs drafted:**
- `docs/design-docs/notification-event-model.md` — design decision: structured source/kind/blocking/dedupe_key on all events
- `docs/product-specs/notification-source-hygiene.md` — product spec: separate user messages from automated notices

**Docs filled (previously placeholder):**
- `docs/design-docs/index.md` — ADR index
- `docs/PLANS.md` — active and upcoming work index
- `docs/exec-plans/active/index.md` — ADR-018, ADR-008, notification model
- `docs/exec-plans/completed/index.md` — repo-vcs, stabilization, JSDoc, ADR-001/003/004/010
- `docs/exec-plans/tech-debt-tracker.md` — 6 known items
- `docs/RELIABILITY.md` — exit codes, failure modes, recovery paths, observability
- `docs/SECURITY.md` — auth model, write gate, protected files, secret scan
- `docs/DESIGN.md` — TUI line-width rule, overlays, theming, IME, performance
- `docs/PRODUCT_SENSE.md` — product thesis, user goals, non-goals, tradeoffs
- `docs/QUALITY_SCORE.md` — thresholds, fast/slow checks, known blind spots
- `docs/records/index.md` — this index

## What Canonical Docs Were Updated

- `docs/design-docs/index.md` — now indexes all 18 ADRs and 2 design docs
- `docs/PLANS.md` — now reflects active initiatives and upcoming work
- All exec-plan index files — now have real content

## Contradictions Found

- ADR-008 (SF tools over MCP) was superseded after the user clarified that SF is the only runtime in use; Claude Code is used as an external dev assistant, not as a provider inside SF. Current guidance rejects SF-as-MCP-server exposure and keeps MCP strictly client-side for external tools.

- `docs/design-docs/` and `docs/dev/ADR-*.md` are split across two directories. The design-docs folder has 2 files; 18 ADRs live in dev/. This split is navigable with the index but worth consolidating eventually.

## What Remains Unresolved

- ADR-008 relevance is resolved by `docs/dev/ADR-008-sf-tools-over-mcp-for-provider-parity.md`: SF must not expose workflow mutations over MCP.
- ADR-018 Phase 1 (repo profiler wired into dispatch) is not yet started
- Notification event model implementation (Phase 2 of the spec) is not yet started
- No ADR template or `just adr` recipe
- `write-gate.ts` BASH_READ_ONLY_RE monolithic regex not yet refactored
