ADR-025: SYN-220 ambient git capture: scope and filtering

Date: 2026-06-08 Status: Accepted (owner, 2026-06-08) Author: Rômulo Febasi

Context

SYN-220 (behavioural lens) attacks the category’s fatal trait: capture cost is paid up front, retrieval value arrives later, so the corpus never fills and the habit never forms. The fix is to invert the value-timing: let the graph seed itself from artefacts the developer already produces (git), so a fresh workspace is populated before any manual capture is asked for.

The issue proposed harvesting “authors → people, repos/dirs → projects, merge commits / commit conventions → decision notes”. The risk, flagged at design time, is the opposite of the goal: a harvester that floods the pending queue with noise makes the propose/accept review worse, not better. The scope and the filtering are therefore the load-bearing decisions, not the git plumbing.

Decision

syn capture --from-git [PATH] harvests people + project only in v1, as proposals (never silent writes: BR-12.3):

• People = commit authors, deduplicated by email, bot-filtered ([bot], noreply, dependabot, github-actions, renovate), ranked by commit count, capped by --max (default 20). Each becomes a person proposal carrying a contributor membership to the project, so the graph link is durable (materialised from frontmatter on reindex), not an index-only edge.
• Project = the repo’s working-directory name → one project proposal, queued first so syn pending accept --all (ascending, SYN-185) creates it before the people that reference it.
• Idempotent: anything already in the index or already queued as a pending capture_fact is skipped, so re-runs never duplicate.
• Uses gix (bounded to ~5000 commits); never shells out to git (CLAUDE.md). Everything lands in the pending queue for one batch review with syn pending accept --all.

Decision notes from commit messages are deferred. They are the noisy part (merge commits, conventional-commit prefixes: high false-positive rate), and the cold-start value is in seeding the who/what. A future opt-in --decisions can add them once a precise, low-noise heuristic exists.

Consequences

• Improves: a fresh syn init in (or pointed at) a real repo yields a populated graph: the retrieval-before-capture moment the behavioural analysis says creates the habit: without weakening BR-12.3 (all queued) and composing with SYN-185 (accept --all to apply the lot).
• Limits (recorded scope): no decision notes, no per-directory sub-projects, no commit-message mining in v1. People are only as good as git author metadata (shared/again-bot emails slip through if not in the filter list: extend the list, not a parser).
• Open: --decisions (opt-in, needs a vetted heuristic); a git hook for continuous ambient capture; mapping monorepo sub-dirs to projects. Revisit on demand.

Alternatives considered

• Harvest decisions from commits now. Rejected: high noise; would make the queue review worse, defeating the purpose. Deferred behind a future opt-in flag.
• Write the entities directly (skip the queue). Rejected: violates BR-12.3 and removes the human’s chance to prune bot/duplicate authors.
• One atomic propose_batch for project + all people + links. Rejected: one bad author slug would block the whole seed; independent proposals let the human batch-approve and let partial failures be re-tried (SYN-185 semantics). propose_batch stays the tool when cross-write atomicity is actually wanted.