chore(agent): phase roadmap from TODO.md — 3 phases (document modal, global tuning, git-based sources)

2026-08-25 10:15:42 -04:00
parent 025f57beb5
commit 476aa0e066
4 changed files with 149 additions and 1 deletions
@@ -0,0 +1,40 @@
+# Story: Git-Based Sources (No Hardcoded Directories)
+
+**Phase:** `28_git_based_sources.md` · **E2E:** none (no UI/API change; unit + integration cover the git flow)
+
+## Narrative
+
+As **the admin (owner)**, I don't want the import sources hard-coded to
+`~/Homelab` and `~/Deployments`. I want to **specify a list of git
+repository URLs** and have `import_docs` **clone or pull** each one into a
+dedicated local location and then **index all the code** in them.
+
+- **Given** a list of git URLs and a destination directory
+- **When** I run `import_docs`
+- **Then** each repo is cloned (first run) or pulled to `ff` (subsequent
+  runs) into the dedicated directory, and the resulting files are indexed
+  exactly like any other A9-format directory.
+
+## Acceptance criteria
+1. `BOR_GIT_SOURCES` (comma-separated git URLs) + `BOR_SOURCES_DIR`
+   (default `~/bor-sources`) settings; `git_source_list` parses the CSV.
+2. `scripts/git_sync.py::clone_or_pull(url, dest)` — shallow clone when the
+   dest has no `.git`, `--ff-only` pull otherwise; raises `GitSyncError`
+   (with stderr) on failure and on missing `git`.
+3. `scripts.import_docs` resolves `BOR_GIT_SOURCES` → cloned/pulled local
+   dirs and passes them to `import_sources`; `--source <path>` overrides
+   (manual mode wins); a failed sync aborts the run (non-zero exit, no
+   partial import).
+4. The A9 format filter / hidden-dir skip / exclusion list still apply to
+   the cloned content (the importer's walk is unchanged).
+5. `documents.source` = the repo directory name (e.g. `homelab`).
+6. `.env.example` + README document both source modes.
+7. Unit (git_sync dispatch/errors) + integration (import_docs resolution
+   with mocked git + import) green; `app/` coverage >90%; one
+   `--no-gpg-sign` commit.
+
+## Playwright Mapping Rule
+No story E2E suite (no `app/` UI/API change). The git flow is covered by
+unit tests (`tests/unit/test_git_sync.py`) and an integration test
+(`tests/integration/test_import_docs_git.py`) with `clone_or_pull` and
+`import_sources` mocked — no network, no `git`, no real embed endpoint.