Mikael Hugo 16ff608d80 feat: implement ADR-001 gitignore split and fill placeholder docs

Gitignore (core change):
- Remove stale blanket .sf/ entries from .gitignore (migrated to
  .git/info/exclude on 2026-04-29, never cleaned up)
- gitignore.ts: split SF_RUNTIME_EXCLUSION_PATTERNS into two modes —
  SF_SYMLINK_EXCLUSION_PATTERNS (blanket .sf for symlink repos where
  git cannot traverse the symlink) and SF_RUNTIME_EXCLUSION_PATTERNS
  (granular runtime-only patterns for directory repos, enabling
  .sf/milestones/ and other durable planning artifacts to be tracked)
- ensureGitInfoExclude() now detects symlink vs directory and writes
  the correct patterns, handling transitions between modes cleanly
- ADR-001 status: Proposed → Accepted

Docs:
- Fill 11 placeholder scaffold docs with real SF-specific content:
  PLANS, DESIGN, PRODUCT_SENSE, QUALITY_SCORE, RELIABILITY, SECURITY,
  design-docs/index.md, exec-plans/active, exec-plans/completed,
  exec-plans/tech-debt-tracker, records/index
- Add records note: docs/records/2026-05-01-repo-vcs-and-notifications.md
- ADR-008 status: Accepted → Proposed (deferred — not applicable to
  current usage model where Claude Code assists externally, not as a
  Pi provider inside SF's dispatch loop)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-01 22:32:28 +02:00

2.7 KiB

Raw Blame History

Security

Auth Model and Trust Boundaries

SF never manages Anthropic OAuth directly. The safe paths are:

API key — user sets ANTHROPIC_API_KEY or configures it in auth.json. SF reads it; never generates or exchanges it.
Claude Code CLI (claude-code provider) — SF shells out to the real claude CLI and lets it handle its own credential selection. SF does not reuse Claude subscription tokens.
Cloud providers — Bedrock, Vertex, Azure via their own credential chains.

Prohibited patterns (from docs/user-docs/claude-code-auth-compliance.md):

SF-managed Anthropic OAuth flow for subscription accounts
Reusing user Claude subscription credentials inside SF's own API client
Making Anthropic believe requests come from Claude Code when they come from SF infrastructure

Write Gate

src/resources/extensions/sf/bootstrap/write-gate.ts enforces a phase-aware write boundary:

During queue mode (pre-dispatch planning): only .sf/ writes and read-only tool calls are permitted. All other file writes are blocked.
QUEUE_SAFE_TOOLS allowlist: read, grep, find, ls, ask_user_questions, planning tools, web research tools.
BASH_READ_ONLY_RE: regex allowlist of commands safe to run during write-restricted phases (cat, git log, npm run test|lint|typecheck, jq, etc.).
Write-gate violations are logged and surfaced to the user; they do not crash the session.

Protected Files

The following files require human review before any automated modification (per docs/SPEC_FIRST_TDD.md):

ADR-*.md — architecture decision records
SPEC.md, ARCHITECTURE.md, AGENTS.md
docs/SECURITY.md, docs/RELIABILITY.md

SF will not autonomously overwrite these. Any proposed change to a protected file is surfaced as a diff for human acceptance.

Secret Scanning

Pre-commit hook via npm run secret-scan:install-hook. Blocks commits containing patterns matching API keys, tokens, and credentials. Install with:

npm run secret-scan:install-hook

Dependency Risk

npm audit runs in CI on every push.
No --ignore-scripts bypass: postinstall scripts are reviewed before adding new dependencies.
Rust N-API bindings (packages/native/) undergo separate native-build review for ABI safety.

Sandbox Model

SF agents execute inside the Pi RPC child process. The write gate and tool allowlist are the primary sandbox. There is no OS-level sandbox (no container or seccomp) in the default local deployment.

Headless unsupervised mode (--no-supervised): SF exits with code 10 (blocked) rather than auto-responding to any interactive tool call. This is the safe default for CI pipelines where no human is available to respond.

2.7 KiB Raw Blame History