cc-os/docs/adr/0017-project-graph-onboarding-assesses-the-repo-and-writes-graphifyignore-before-extracting.md

id	date	status	supersedes	superseded-by	affected-paths	affected-components	migration_confidence	migration_source
0017	2026-06-17	Accepted					medium	docs/memory-system/03-architecture-decisions.md### ADR-017 — Project graph onboarding assesses the repo and writes `.graphifyignore` before extracting

0017 — Project graph onboarding assesses the repo and writes .graphifyignore before extracting

Context

The /os-vault:onboard-project skill's onboarding flow ran graphify extract . --backend ollama --model qwen2.5-coder:7b directly. graphify does NOT honor .gitignore; it uses a separate .graphifyignore file (same syntax — see docs/graphify/02-installation-setup.md). With no .graphifyignore, onboarding viking-warrior-training-log (135 tracked files) walked node_modules/ (5,858 files / 161MB) and routed every non-code file there through the Ollama doc pass. The run was killed after ~1 hour with no graph.json produced. Cost driver: only non-code files hit the Ollama LLM; code uses the free tree-sitter AST pass.

Decision

Onboarding is now assessment-first. Before running graphify extract, the skill surveys the repo, classifies directories and file types into include/exclude (weighing non-code file count since only non-code files cost LLM time), confirms the proposed ignore list with the user, writes .graphifyignore at the repo root, ensures graphify-out/ is in the project's .gitignore, then runs extract. The ignore list is generated per-project — what counts as noise varies by stack — not from a static template.

• Rationale: graphify's .gitignore blindness is by design; the correct lever is .graphifyignore, not a workaround. Assessment before extraction surfaces borderline dirs (migrations, seeds, fixtures, sample data) that need a human call. Per-project generation avoids the false safety of a shared template that silently mismatches a new stack.

Consequences

Project onboarding now surveys the repo and writes a per-project .graphifyignore before running graphify extract, since graphify does not honor .gitignore and previously walked huge directories like node_modules, routing every non-code file through the costly Ollama LLM pass and causing a run to be killed after an hour with no output. Borderline directories require human confirmation rather than being auto-excluded, and onboarding now also uses a 16k-context model build to reduce chunk counts.

Alternatives rejected

Static .graphifyignore template — rejected; dependency/build/cache dirs vary by project stack; a template would both over-exclude (suppressing wanted source) and under-exclude (missing stack-specific dirs) for any given project. Auto-write without user confirmation — rejected; borderline directories (e.g. migrations, seeds, fixtures) require human judgment; mechanical exclusion would silently drop legitimate content. AST-only mode (skip doc pass entirely) — deferred; the --backend ollama flag stays; the ignore list is the correct cost lever, not backend switching.