feat(vault): Obsidian vault V2 — janitor, archival, weekly report, KB ingest, Bases + sync runbook (#482)

* feat(vault): V2 — create-seam + drift janitor, archival, weekly org-report, KB ingest, Bases views + sync runbook

Implements the vault V2 canonical spec end to end (the splice guard shipped
separately and is reused at KB-ingest time):

- materialize-on-create: TaskService.create writes each task's note best-effort
  from the moment it exists; the transition-touch stops no-oping on live work
- drift janitor (services/vault_janitor.py + hourly _vault_janitor_loop): daily
  changed-task re-projection, random drift sample, archival pass — restart-proof
  via RoboCo/_meta/.janitor_state.json, 200/cycle caps, per-item isolation,
  processed-only resume markers, self-repairing state file
- archival: vault_archive_days (30, 0=off) moves old terminal tasks' notes to
  RoboCo/Archive/<year>/Tasks/<project>/ — one write_task code path for janitor
  and rebuild, id8 lookup across Tasks/+Archive/, alias links keep moves safe
- weekly org-report: VaultWriter.write_org_report renders Reports/<ISO-week>.md
  from MetricsService/UsageService (numbers duplicated into frontmatter for
  trend queries), once per ISO week, with a best-effort CEO notification
- KB ingest: IndexType.VAULT_NOTES + VaultNotesIndexPlugin + _vault_kb_loop
  embed the CEO's RoboCo/Notes into the RAG corpus — injection guard as a hard
  gate (flagged notes quarantined with an idempotent callout), traversal- and
  symlink-contained at both config and engine layers, content-hash dedup,
  50-ingest/cycle cap, frontmatter stripped; reaches roboco_kb_search, the
  mentor default domain, claim-time briefings (kind vault_note), and the panel
  KB browser; no migration (chunks table auto-creates; migration 030's
  CHUNK_TABLES tuple appended per the chunks_playbooks precedent)
- Bases views (Task Board.base, Reports.base — schema verified against the
  Obsidian docs) + the Mac sync runbook vault asset
- config/flags/compose: vault_archive_days, vault_report_enabled (flags card),
  vault_kb_enabled (flags card; NAS compose arms it, registry ships it off),
  vault_kb_dirs (+ overlap/traversal validator), vault_kb_interval_seconds
- e2e smoke (tests/e2e_smoke/test_vault_v2.py): real create-seam, real janitor
  cycle incl. archival + state, real KB engine + real guard

* docs: vault V2 sweep — map, RAG corpus, CLAUDE.md

- docs/map/vault.md: V1+V2 — janitor/archival/report/KB data flows, new files,
  config, health posture
- docs/map/orchestrator.md + task-service.md: the two new loops, the create
  seam, the three janitor queries
- docs/rag/architecture/obsidian-vault.md: agent-facing what-changed (notes
  from creation, archive link-safety, CEO notes retrievable, weekly report)
- docs/rag/architecture/config-reference.md: the five new settings
- CLAUDE.md: vault paragraph covers V1+V2; flags-card list mentions the vault
  report/KB flags

---------

Co-authored-by: Renn F <rennf93@users.noreply.github.com>

tests/unit/config/test_vault_janitor_flags.py

@@ -0,0 +1,41 @@
+"""Vault janitor knobs — archival window + weekly-report flag (mirrors the
+vault-intake flag test idiom)."""
+
+from __future__ import annotations
+
+import os
+from unittest import mock
+
+import pytest
+from pydantic import ValidationError
+from roboco.config import Settings
+from roboco.services.settings import FEATURE_FLAGS, validate_setting
+
+_DEFAULT_ARCHIVE_DAYS = 30
+
+
+def test_vault_janitor_defaults() -> None:
+    s = Settings()
+    assert s.vault_archive_days == _DEFAULT_ARCHIVE_DAYS
+    assert s.vault_report_enabled is True
+
+
+def test_vault_archive_days_reads_env_var() -> None:
+    with mock.patch.dict(os.environ, {"ROBOCO_VAULT_ARCHIVE_DAYS": "0"}):
+        assert Settings().vault_archive_days == 0
+
+
+def test_vault_archive_days_rejects_negative() -> None:
+    with (
+        mock.patch.dict(os.environ, {"ROBOCO_VAULT_ARCHIVE_DAYS": "-1"}),
+        pytest.raises(ValidationError),
+    ):
+        Settings()
+
+
+def test_vault_report_flag_registered_in_feature_flags() -> None:
+    assert "vault_report_enabled" in [key for key, _ in FEATURE_FLAGS]
+
+
+def test_vault_report_flag_validates_as_bool() -> None:
+    validate_setting("vault_report_enabled", "false")

tests/unit/config/test_vault_kb_flags.py

@@ -0,0 +1,141 @@
+"""Vault KB ingest knobs — dirs/interval defaults + the reserved-dir overlap
+guard (mirrors the vault-janitor flag test idiom)."""
+
+from __future__ import annotations
+
+import os
+from unittest import mock
+
+import pytest
+from pydantic import ValidationError
+from roboco.config import Settings
+from roboco.services.settings import FEATURE_FLAGS, validate_setting
+
+_DEFAULT_INTERVAL = 900
+
+
+def test_vault_kb_defaults() -> None:
+    s = Settings()
+    assert s.vault_kb_enabled is False
+    assert s.vault_kb_dirs == "RoboCo/Notes"
+    assert s.vault_kb_interval_seconds == _DEFAULT_INTERVAL
+
+
+def test_vault_kb_interval_rejects_below_minimum() -> None:
+    with (
+        mock.patch.dict(os.environ, {"ROBOCO_VAULT_KB_INTERVAL_SECONDS": "30"}),
+        pytest.raises(ValidationError),
+    ):
+        Settings()
+
+
+def test_vault_kb_flag_registered_in_feature_flags() -> None:
+    assert "vault_kb_enabled" in [key for key, _ in FEATURE_FLAGS]
+
+
+def test_vault_kb_flag_validates_as_bool() -> None:
+    validate_setting("vault_kb_enabled", "true")
+
+
+def test_vault_kb_dirs_clean_config_passes() -> None:
+    with mock.patch.dict(
+        os.environ,
+        {"ROBOCO_VAULT_KB_ENABLED": "true", "ROBOCO_VAULT_KB_DIRS": "RoboCo/Notes"},
+    ):
+        assert Settings().vault_kb_dirs == "RoboCo/Notes"
+
+
+def test_vault_kb_dirs_overlap_with_intake_dir_rejected() -> None:
+    with (
+        mock.patch.dict(
+            os.environ,
+            {
+                "ROBOCO_VAULT_KB_ENABLED": "true",
+                "ROBOCO_VAULT_KB_DIRS": "RoboCo/Inbox",
+            },
+        ),
+        pytest.raises(ValidationError),
+    ):
+        Settings()
+
+
+@pytest.mark.parametrize(
+    "kb_dirs",
+    [
+        "RoboCo/Tasks",
+        "RoboCo/Tasks/Sub",  # nests under a reserved dir
+        "RoboCo",  # nests OVER every reserved dir (reverse direction)
+        ".obsidian",
+        "RoboCo/Notes,RoboCo/Journals",  # one clean entry, one reserved
+    ],
+)
+def test_vault_kb_dirs_reserved_overlap_rejected(kb_dirs: str) -> None:
+    with (
+        mock.patch.dict(
+            os.environ,
+            {"ROBOCO_VAULT_KB_ENABLED": "true", "ROBOCO_VAULT_KB_DIRS": kb_dirs},
+        ),
+        pytest.raises(ValidationError),
+    ):
+        Settings()
+
+
+@pytest.mark.parametrize(
+    "kb_dirs",
+    [
+        "/etc",  # absolute path
+        "/etc/passwd",
+        "../sibling_secret_dir",  # leading traversal
+        "RoboCo/Notes/..",  # trailing traversal
+        "RoboCo/../../outside",  # embedded traversal
+        "RoboCo/Notes,../outside",  # one clean entry, one traversal
+        ".",  # vault root itself — would rglob every projection dir
+        "./",  # vault root, trailing-slash spelling
+        "./RoboCo/Tasks",  # dot-prefixed reserved dir must not evade overlap
+    ],
+)
+def test_vault_kb_dirs_traversal_rejected(kb_dirs: str) -> None:
+    """Absolute paths and '..' segments would let KB ingest read files
+    entirely outside the vault into the fleet-retrievable corpus."""
+    with (
+        mock.patch.dict(
+            os.environ,
+            {"ROBOCO_VAULT_KB_ENABLED": "true", "ROBOCO_VAULT_KB_DIRS": kb_dirs},
+        ),
+        pytest.raises(ValidationError),
+    ):
+        Settings()
+
+
+def test_vault_kb_dirs_dot_prefixed_clean_entry_passes() -> None:
+    """'./RoboCo/Notes' normalizes to a clean, non-reserved subfolder."""
+    with mock.patch.dict(
+        os.environ,
+        {
+            "ROBOCO_VAULT_KB_ENABLED": "true",
+            "ROBOCO_VAULT_KB_DIRS": "./RoboCo/Notes",
+        },
+    ):
+        assert Settings().vault_kb_dirs == "./RoboCo/Notes"
+
+
+def test_vault_kb_dirs_dotted_name_is_not_traversal() -> None:
+    """A '..' inside a segment name (not a whole segment) is a legal dir name."""
+    with mock.patch.dict(
+        os.environ,
+        {
+            "ROBOCO_VAULT_KB_ENABLED": "true",
+            "ROBOCO_VAULT_KB_DIRS": "RoboCo/my..notes",
+        },
+    ):
+        assert Settings().vault_kb_dirs == "RoboCo/my..notes"
+
+
+def test_vault_kb_disabled_skips_dir_validation() -> None:
+    """An invalid vault_kb_dirs is only enforced when vault_kb_enabled — off
+    by default, so a stale/misconfigured env value never blocks startup."""
+    with mock.patch.dict(
+        os.environ,
+        {"ROBOCO_VAULT_KB_ENABLED": "false", "ROBOCO_VAULT_KB_DIRS": "RoboCo/Tasks"},
+    ):
+        assert Settings().vault_kb_dirs == "RoboCo/Tasks"