@tyroneross/build-loop 0.36.0 → 0.43.0

package/scripts/install_memory.py

@@ -306,7 +306,15 @@ def _project_relpath(project: str) -> Path:
 
 
 def ensure_project_scaffold(dest: Path, project: str) -> Path:
-    """Create the per-project raw-source scaffold and return the project dir."""
+    """Create the per-project raw-source scaffold and return the project dir.
+
+    Stable-ID-at-init hook (memory-identity-graph Phase 1): the first time a
+    project folder is scaffolded, freeze ``id == project`` in the v2 project
+    registry (``<dest>/config/projects.yaml``). This is what makes a later
+    repo rename a no-op — the id is registered once and never re-derived; the
+    old dirname becomes an alias instead of orphaning the store. Best-effort:
+    a registry-write failure never blocks scaffolding.
+    """
     project_dir = dest / "projects" / _project_relpath(project)
     raw_dir = project_dir / "raw"
     for subdir in PROJECT_RAW_SUBDIRS:
@@ -315,9 +323,33 @@ def ensure_project_scaffold(dest: Path, project: str) -> Path:
         keep = leaf / KEEP_FILENAME
         if not keep.exists():
             keep.write_text("", encoding="utf-8")
+    _register_stable_id(dest, project)
     return project_dir
 
 
+def _register_stable_id(dest: Path, project: str) -> None:
+    """Freeze ``id == project`` in the v2 registry under ``dest`` (best-effort).
+
+    Skips the ``_unscoped`` sentinel and any sub-component slug (``a/b``) —
+    those are not standalone project identities.
+    """
+    if not project or project == "_unscoped" or "/" in project:
+        return
+    try:
+        scripts_dir = Path(__file__).resolve().parent
+        if str(scripts_dir) not in sys.path:
+            sys.path.insert(0, str(scripts_dir))
+        import project_registry  # type: ignore  # noqa: PLC0415
+
+        project_registry.register_project(
+            project,
+            slug=project,
+            registry_path=dest / "config" / "projects.yaml",
+        )
+    except Exception:  # noqa: BLE001 — init hook must never break scaffolding
+        pass
+
+
 def link_private_repo(dest: Path, repo_url: str) -> tuple[bool, str]:
     """Clone a private repo INTO the dest path. Requires dest to be empty or non-existent.
 

package/scripts/lessons_index/ingest.py

@@ -146,17 +146,24 @@ def _lane_dirs(project: str | None) -> list[tuple[str, Path]]:
         project_decisions_dir,
         project_lessons_dir,
         project_product_dir,
+        project_research_dir,
+        project_root,
         top_level_lessons_dir,
+        memory_store_root,
     )
     if project:
         return [
             ("lessons", project_lessons_dir(project)),
             ("decisions", project_decisions_dir(project)),
             ("product", project_product_dir(project)),
+            ("research", project_research_dir(project)),
+            ("references", project_root(project) / "references"),
         ]
     else:
         return [
             ("lessons", top_level_lessons_dir()),
+            ("research", memory_store_root() / "research"),
+            ("references", memory_store_root() / "references"),
         ]
 
 
@@ -193,8 +200,12 @@ def ingest(
         for lane_name, lane_dir in lanes:
             if not lane_dir.exists():
                 continue
-            for md_path in sorted(lane_dir.glob("*.md")):
-                if md_path.name in {"INDEX.md", "MEMORY.md", "README.md"}:
+            for md_path in sorted(lane_dir.rglob("*.md")):
+                relative_parts = md_path.relative_to(lane_dir).parts[:-1]
+                if md_path.name in {"INDEX.md", "MEMORY.md", "README.md"} or any(
+                    part in {"raw-originals", "archive", "indexes", "raw"}
+                    for part in relative_parts
+                ):
                     continue
                 summary["total_scanned"] += 1
                 try:

package/scripts/lessons_index/query.py

@@ -74,16 +74,22 @@ def _unpack_floats(blob: bytes) -> list[float]:
     return list(struct.unpack(f"{n}f", blob))
 
 
-def _try_embed(text: str) -> list[float] | None:
-    """Return embedding vector or None if backend unavailable."""
+def _try_embed(text: str) -> tuple[list[float] | None, str | None]:
+    """Return (embedding vector, model name), or (None, None) if unavailable.
+
+    The model name is returned so the reranker can refuse to score stored
+    vectors that came from a DIFFERENT embedding model. Two models can share a
+    dimension (bge-m3 and mxbai-embed-large-v1 are both 1024), so a mismatch
+    raises no error — it silently produces meaningless cosine scores.
+    """
     if os.environ.get("EMBED_BACKEND_UNAVAILABLE"):
-        return None
+        return None, None
     try:
         import embed_backend as _eb  # type: ignore  # noqa: PLC0415
         vec = _eb.embed(text)
-        return list(vec)
+        return list(vec), _eb.active_model()
     except Exception:  # noqa: BLE001
-        return None
+        return None, None
 
 
 def query(
@@ -146,9 +152,9 @@ def _run_query(
         return []
 
     # Hybrid rerank if embeddings are available.
-    goal_vec = _try_embed(goal_text)
+    goal_vec, goal_model = _try_embed(goal_text)
     if goal_vec is not None and _embeddings_populated(conn):
-        candidates = _cosine_rerank(conn, candidates, goal_vec)
+        candidates = _cosine_rerank(conn, candidates, goal_vec, goal_model)
 
     # Trim to limit.
     results = candidates[:limit]
@@ -248,18 +254,35 @@ def _embeddings_populated(conn) -> bool:
     return count > 0
 
 
-def _cosine_rerank(conn, candidates: list[dict], goal_vec: list[float]) -> list[dict]:
+def _cosine_rerank(
+    conn,
+    candidates: list[dict],
+    goal_vec: list[float],
+    goal_model: str | None = None,
+) -> list[dict]:
     """Rerank BM25 candidates by cosine similarity of stored embeddings.
 
     Returns candidates sorted by cosine similarity (descending). Candidates
-    without an embedding retain their BM25 rank at the end.
+    without a *same-model* embedding retain their BM25 rank at the end.
+
+    Vectors from a different embedding model are excluded rather than scored.
+    Cross-model cosine is meaningless, and because models can share a dimension
+    the mismatch is silent — excluding degrades to BM25 instead of ranking on
+    noise. `goal_model=None` (backend didn't report one) keeps the legacy
+    unfiltered behavior.
     """
     ids = [r["id"] for r in candidates]
     placeholders = ",".join("?" * len(ids))
-    emb_rows = conn.execute(
-        f"SELECT fact_id, vec FROM embeddings WHERE fact_id IN ({placeholders})",  # nosec: only ?-placeholders / constant fragments interpolated; values bound as params
-        ids,
-    ).fetchall()
+    if goal_model:
+        emb_rows = conn.execute(
+            f"SELECT fact_id, vec FROM embeddings WHERE fact_id IN ({placeholders}) AND model = ?",  # nosec: only ?-placeholders / constant fragments interpolated; values bound as params
+            [*ids, goal_model],
+        ).fetchall()
+    else:
+        emb_rows = conn.execute(
+            f"SELECT fact_id, vec FROM embeddings WHERE fact_id IN ({placeholders})",  # nosec: only ?-placeholders / constant fragments interpolated; values bound as params
+            ids,
+        ).fetchall()
     emb_map = {row["fact_id"]: _unpack_floats(row["vec"]) for row in emb_rows}
 
     scored = []

package/scripts/memory_context/__init__.py

@@ -29,6 +29,7 @@ from _paths import (  # type: ignore  # noqa: E402
     memory_store_root,
     project_decisions_dir,
     project_lessons_dir,
+    project_research_dir,
     project_root,
     top_level_lessons_dir,
 )
@@ -41,6 +42,7 @@ KIND_STATUS = "build-loop-memory-status"
 VALID_MODES = {"fast", "expand"}
 DEFAULT_LIMIT = 5
 DEFAULT_MAX_CHARS = 900
+CAPSULE_MAX_AGE_DAYS = 7
 
 
 def utc_now() -> str:
@@ -147,11 +149,29 @@ def _recent_markdown(
     prefix: str,
     limit: int,
     max_chars: int,
+    query: str = "",
 ) -> list[dict[str, Any]]:
     if not directory.is_dir():
         return []
-    candidates = [p for p in directory.glob("*.md") if p.name not in {"INDEX.md", "README.md", "MEMORY.md"}]
-    candidates.sort(key=lambda p: p.stat().st_mtime if p.exists() else 0, reverse=True)
+    excluded_dirs = {"raw-originals", "archive", "indexes", "raw"}
+    candidates = [
+        p for p in directory.rglob("*.md")
+        if p.name not in {"INDEX.md", "README.md", "MEMORY.md"}
+        and not any(part in excluded_dirs for part in p.relative_to(directory).parts[:-1])
+    ]
+    query_tokens = {token.lower() for token in re.findall(r"[A-Za-z][A-Za-z0-9_-]{2,}", query)}
+
+    def rank(path: Path) -> tuple[int, float]:
+        if not query_tokens:
+            return (0, path.stat().st_mtime if path.exists() else 0)
+        try:
+            text = path.read_text(encoding="utf-8", errors="ignore").lower()
+        except OSError:
+            text = ""
+        score = sum(1 for token in query_tokens if token in text)
+        return (score, path.stat().st_mtime if path.exists() else 0)
+
+    candidates.sort(key=rank, reverse=True)
     rows: list[dict[str, Any]] = []
     for path in candidates[:limit]:
         text, reason = _read_text(path, max_chars=max_chars * 2)
@@ -233,6 +253,33 @@ def _freshness(workdir: Path, project: str, project_dir: Path, warnings: list[st
             validity = "stale"
     if not project_dir.exists():
         validity = "unknown"
+    capsule_reasons: list[str] = []
+    capsule_path = project_dir / "context" / "freshness.json"
+    capsule: dict[str, Any] = {}
+    try:
+        if capsule_path.is_file():
+            capsule = json.loads(capsule_path.read_text(encoding="utf-8"))
+            stored_source = str(capsule.get("source_commit") or "")
+            stored_memory = str(capsule.get("memory_commit") or "")
+            if stored_source and source_git.get("commit") and stored_source != source_git.get("commit"):
+                capsule_reasons.append("source_commit_changed")
+            if stored_memory and memory_git.get("commit") and stored_memory != memory_git.get("commit"):
+                capsule_reasons.append("memory_commit_changed")
+            generated_at = str(capsule.get("generated_at") or "")
+            if generated_at:
+                try:
+                    age_seconds = (datetime.now(timezone.utc) - datetime.fromisoformat(generated_at.replace("Z", "+00:00"))).total_seconds()
+                    if age_seconds > CAPSULE_MAX_AGE_DAYS * 86400:
+                        capsule_reasons.append("capsule_older_than_7_days")
+                except ValueError:
+                    capsule_reasons.append("capsule_timestamp_invalid")
+        elif project_dir.exists():
+            capsule_reasons.append("capsule_missing")
+    except (OSError, json.JSONDecodeError):
+        capsule_reasons.append("capsule_unreadable")
+    if capsule_reasons:
+        validity = "stale" if validity == "clean" else validity
+        warnings.extend(f"memory_capsule_{reason}" for reason in capsule_reasons)
     return {
         "validity": validity,
         "generated_at": utc_now(),
@@ -246,6 +293,10 @@ def _freshness(workdir: Path, project: str, project_dir: Path, warnings: list[st
         "memory_branch": memory_git.get("branch", ""),
         "memory_commit": memory_git.get("commit", ""),
         "memory_dirty_count": memory_git.get("dirty_count"),
+        "capsule_generated_at": capsule.get("generated_at"),
+        "capsule_source_commit": capsule.get("source_commit"),
+        "capsule_memory_commit": capsule.get("memory_commit"),
+        "capsule_stale_reasons": capsule_reasons,
         "index": _index_state(),
     }
 
@@ -255,10 +306,16 @@ def _evidence_from_current(current: dict[str, Any]) -> list[dict[str, str]]:
     ctx = current.get("context") or {}
     if ctx.get("exists") and ctx.get("path"):
         evidence.append({"id": ctx.get("id", "context:CONTEXT"), "path": ctx["path"], "type": "context"})
-    for lane in ("decisions", "lessons"):
+    lane_types = {
+        "decisions": "decision",
+        "lessons": "lesson",
+        "research": "research",
+        "references": "reference",
+    }
+    for lane, evidence_type in lane_types.items():
         for item in current.get(lane, []):
             if item.get("id") and item.get("path"):
-                evidence.append({"id": str(item["id"]), "path": str(item["path"]), "type": lane[:-1]})
+                evidence.append({"id": str(item["id"]), "path": str(item["path"]), "type": evidence_type})
     return evidence
 
 
@@ -287,21 +344,53 @@ def build_current(
         prefix="decision",
         limit=limit,
         max_chars=max_chars,
+        query=query,
     )
     project_lessons = _recent_markdown(
         project_lessons_dir(project_tag),
         prefix="lesson",
         limit=limit,
         max_chars=max_chars,
+        query=query,
     )
     global_lessons = _recent_markdown(
         top_level_lessons_dir(),
         prefix="lesson",
         limit=max(0, limit - len(project_lessons)),
         max_chars=max_chars,
+        query=query,
     )
     lessons = project_lessons + global_lessons
 
+    project_research = _recent_markdown(
+        project_research_dir(project_tag),
+        prefix="research",
+        limit=limit,
+        max_chars=max_chars,
+        query=query,
+    )
+    project_references = _recent_markdown(
+        proj_dir / "references",
+        prefix="reference",
+        limit=limit,
+        max_chars=max_chars,
+        query=query,
+    )
+    global_research = _recent_markdown(
+        memory_store_root() / "research",
+        prefix="research",
+        limit=max(0, limit - len(project_research)),
+        max_chars=max_chars,
+        query=query,
+    )
+    global_references = _recent_markdown(
+        memory_store_root() / "references",
+        prefix="reference",
+        limit=max(0, limit - len(project_references)),
+        max_chars=max_chars,
+        query=query,
+    )
+
     current: dict[str, Any] = {
         "schema_version": SCHEMA_VERSION,
         "kind": KIND_CURRENT,
@@ -312,6 +401,8 @@ def build_current(
         "context": context,
         "decisions": project_decisions,
         "lessons": lessons[:limit],
+        "research": (project_research + global_research)[:limit],
+        "references": (project_references + global_references)[:limit],
         "next_commands": [
             'blm context --workdir "$PWD" --mode fast --json',
             'blm context --workdir "$PWD" --mode expand --json',
@@ -354,11 +445,12 @@ def render_current_markdown(current: dict[str, Any]) -> str:
         for item in current["decisions"]:
             lines.append(f"- {item.get('title') or item.get('id')} ({item.get('id')})")
         lines.append("")
-    if current.get("lessons"):
-        lines.extend(["## Relevant Lessons", ""])
-        for item in current["lessons"]:
-            lines.append(f"- {item.get('title') or item.get('id')} ({item.get('id')})")
-        lines.append("")
+    for lane, heading in (("lessons", "Relevant Lessons"), ("research", "Relevant Research"), ("references", "Relevant References")):
+        if current.get(lane):
+            lines.extend([f"## {heading}", ""])
+            for item in current[lane]:
+                lines.append(f"- {item.get('title') or item.get('id')} ({item.get('id')})")
+            lines.append("")
     if current.get("warnings"):
         lines.extend(["## Warnings", ""])
         for warning in current["warnings"]:
@@ -469,11 +561,13 @@ def _expand_with_lessons(query: str, project: str, limit: int) -> dict[str, Any]
 def _expand_with_graph(current: dict[str, Any], limit: int) -> dict[str, Any]:
     project = str(current.get("project") or "")
     seeds = [f"project:{project}"] if project else []
-    if not seeds:
-        for item in current.get("evidence", []):
-            item_id = str(item.get("id") or "")
-            if item_id and not item_id.startswith("context:"):
-                seeds.append(item_id)
+    # Seed with hot evidence as well as the project node. This makes research
+    # and reference lanes reachable instead of relying on a project-only
+    # traversal whose bounded result can be dominated by lessons/decisions.
+    for item in current.get("evidence", []):
+        item_id = str(item.get("id") or "")
+        if item_id and item.get("type") in {"research", "reference"}:
+            seeds.append(item_id)
     # Preserve order while deduping.
     seeds = list(dict.fromkeys(seeds))
     if not seeds:

package/scripts/memory_graph/__init__.py

@@ -120,8 +120,11 @@ class SQLiteEdgesStore:
         self.index_dir = root / "indexes"
         self.nodes_path = self.index_dir / "graph-nodes.jsonl"
         self.edges_path = self.index_dir / "graph-edges.jsonl"
-        self.db_path = db_path or self.index_dir / "graph.sqlite"
+        # SQLite is a rebuildable runtime cache. Keep it out of the tracked
+        # ``indexes/`` surface so expand-mode reads never dirty memory git.
+        self.db_path = db_path or root / "db" / "runtime" / "graph.sqlite"
         self.reasons = list(reasons)
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
         self._conn = sqlite3.connect(str(self.db_path))
         self._conn.row_factory = sqlite3.Row
         self._sync_if_needed()
@@ -160,6 +163,7 @@ class SQLiteEdgesStore:
 
     def _sync_if_needed(self) -> None:
         self.index_dir.mkdir(parents=True, exist_ok=True)
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
         self._ensure_schema()
         signature = _source_signature(self.nodes_path, self.edges_path)
         current = self._conn.execute(

package/scripts/project_resolver.py

@@ -28,6 +28,7 @@ import sys
 if str(HERE) not in sys.path:
     sys.path.insert(0, str(HERE))
 from _paths import derive_slug_from_cwd, memory_store_root  # type: ignore  # noqa: E402
+import project_registry  # type: ignore  # noqa: E402
 
 DEFAULT_PROJECT_TAG = "_unscoped"
 
@@ -126,44 +127,49 @@ def _normalize(p: str | Path) -> str:
 
 
 def resolve_project(cwd: Path | str) -> str:
-    """Return the project tag for ``cwd``.
-
-    Resolution order (post memory-consolidation PR 1):
-      1. ``derive_slug_from_cwd(cwd)`` — filesystem-driven slug from git
-         toplevel + ``_safe_project_tag`` normalization. The PRIMARY path.
-         Returns ``_unscoped`` when ``cwd`` is outside any git repo.
-      2. ``projects.yaml`` lookup (exact then longest-prefix) — used ONLY
-         when (a) the filesystem rule returned ``_unscoped`` AND (b) the
-         operator has registered an explicit alias for this cwd. This
-         covers the rare case where the working directory isn't a git
-         repo but should still map to a known project tag.
-      3. ``projects.yaml`` ``default:`` key, else ``_unscoped``.
-
+    """Return the canonical project id for ``cwd``.
+
+    Resolution contract (memory-identity-graph Phase 1 — stable-ID + alias
+    walking; supersedes the single-value ``memoryProjectSlug`` pin, which
+    is now one alias case):
+
+      1. ``candidate = derive_slug_from_cwd(cwd)`` — unchanged deriver:
+           1a. A durable ``memoryProjectSlug`` PIN in the enclosing repo's
+               ``.build-loop/config.json`` (``_paths._read_pinned_slug``),
+               used verbatim when present; the pin still SETS the candidate
+               and the registry can still map it further.
+           1b. Filesystem derivation: ``basename(git toplevel)`` normalized.
+           Returns ``_unscoped`` outside any git repo and unpinned.
+      2. Registry lookup (``project_registry.resolve``): find the project
+         where ``candidate`` ∈ {id, canonical_slug, *aliases} OR ``cwd``
+         matches one of ``paths``, then a BOUNDED, CYCLE-GUARDED alias walk
+         returns that project's terminal canonical id. A hit wins.
+      3. Else, if ``candidate != _unscoped`` → return ``candidate`` verbatim.
+         An unregistered / new / unmigrated repo IS its own id and keeps
+         working with zero registry entry.
+      4. Else (``_unscoped``, no registry hit) → the registry ``default:``
+         (else ``_unscoped``). The registry's ``paths`` seed IS the old
+         ``projects.yaml`` path-fallback, consulted inside step 2.
+
+    Deterministic, no LLM, never raises (degrades to the candidate/_unscoped).
     Aligns by construction with Postgres ``semantic_facts.project`` —
-    ``derive_slug_from_cwd`` routes through ``_safe_project_tag``, which
-    is the same validator used by ``decisions_dir_for_project``.
+    ``derive_slug_from_cwd`` routes through ``_safe_project_tag``.
     """
-    # Step 1 — filesystem-driven derivation (the new primary path).
-    slug = derive_slug_from_cwd(cwd)
-    if slug != DEFAULT_PROJECT_TAG:
-        return slug
-
-    # Step 2 — fall back to projects.yaml only when filesystem returned
-    # _unscoped. This preserves backward-compat for explicit aliases.
-    data = load_projects_yaml()
-    cwd_norm = _normalize(cwd)
-    best_match: tuple[int, str] | None = None
-    for entry in data["projects"]:
-        path_norm = _normalize(entry["path"])
-        if path_norm == cwd_norm:
-            return entry["project"]
-        if cwd_norm.startswith(path_norm + os.sep):
-            length = len(path_norm)
-            if best_match is None or length > best_match[0]:
-                best_match = (length, entry["project"])
-    if best_match is not None:
-        return best_match[1]
-    return data["default"]
+    # Step 1 — pinned-or-derived candidate slug.
+    candidate = derive_slug_from_cwd(cwd)
+
+    # Step 2 — registry lookup + alias walk (returns terminal canonical id).
+    registry = project_registry.load_registry()
+    hit = project_registry.resolve(candidate, cwd, registry)
+    if hit is not None:
+        return hit
+
+    # Step 3 — an unregistered git repo is its own id.
+    if candidate != DEFAULT_PROJECT_TAG:
+        return candidate
+
+    # Step 4 — _unscoped with no registry hit → default.
+    return registry.get("default", DEFAULT_PROJECT_TAG)
 
 
 if __name__ == "__main__":  # pragma: no cover - manual smoke tool

package/scripts/sync_plugin_cache.py

@@ -33,7 +33,20 @@ if str(HERE) not in sys.path:
 import check_cache_sync as cache_sync  # type: ignore  # noqa: E402
 
 
-EXCLUDE_DIRS = {".git", "node_modules", "__pycache__", ".venv", ".build-loop", ".rally"}
+EXCLUDE_DIRS = {
+    ".git", "node_modules", "__pycache__", ".venv", ".build-loop", ".rally",
+    # Per-tool runtime state (the `.<toolname>/` convention). All gitignored, so
+    # none of it belongs in a plugin cache. Named, observed failure (2026-08-11):
+    # `.ibr/browser-profile/` held a stopped Chrome's SingletonSocket /
+    # SingletonLock / SingletonCookie / RunningChromeVersion. shutil.copytree
+    # raised on those four dangling entries, so EVERY `build-loop-install
+    # --host claude` failed while the installer still printed
+    # "claude: OK build-loop@<version>". The Claude cache sat on 0.37.0 for
+    # multiple bumps.
+    ".ibr", ".navgator", ".spectra", ".bookmark", ".episodic", ".procedural",
+    ".in_use", ".pytest_cache", ".claude-code-debugger", ".localsmartz",
+    ".ci-rally-apps",
+}
 HOOK_NAMES = ("post-commit", "post-merge", "post-checkout", "post-rewrite")
 HOOK_MARKER = "# --- BEGIN build-loop plugin-cache-sync ---"
 HOOK_MARKER_END = "# --- END build-loop plugin-cache-sync ---"
@@ -101,7 +114,29 @@ def materialize_head(source: Path) -> tempfile.TemporaryDirectory[str]:
 
 
 def ignore_dirty_tree(_dir: str, names: list[str]) -> set[str]:
-    return {name for name in names if name in EXCLUDE_DIRS}
+    """Skip excluded dirs, and anything copytree cannot copy.
+
+    The exclude list handles the runtime dirs we know about. This second clause
+    handles the ones we don't: a socket, a FIFO, or a symlink whose target has
+    gone away raises inside shutil.copytree and aborts the whole sync. A plugin
+    cache should skip an unreadable runtime artifact, not fail the install.
+    """
+    skip = {name for name in names if name in EXCLUDE_DIRS}
+    base = Path(_dir)
+    for name in names:
+        if name in skip:
+            continue
+        p = base / name
+        try:
+            if p.is_symlink() and not p.exists():
+                skip.add(name)          # dangling symlink
+                continue
+            st = p.lstat()
+            if stat.S_ISSOCK(st.st_mode) or stat.S_ISFIFO(st.st_mode):
+                skip.add(name)          # socket / named pipe
+        except OSError:
+            skip.add(name)              # vanished mid-walk
+    return skip
 
 
 def copy_tree_to_temp(source: Path, target_parent: Path) -> Path:

package/skills/agent-rally-point/SKILL.md

@@ -50,12 +50,22 @@ surfaced on Rally Point records as top-level `build_loop_id` and
   `scripts/agent_rally.py where`; do not hardcode legacy channel roots.
 - Write cross-session events through `scripts/rally_point/post.py::post()`;
   do not append directly to `changes.jsonl`.
+- Correct a wrong fact by appending a retraction (`agent_rally.py retract`),
+  never by editing the log. See "Retracting a wrong fact" below.
 - Keep `build_loop_id` separate from `producer_metadata`.
 - Keep substrate files independent from build-loop memory/orchestration
   internals. If a build-loop-specific integration is needed, put it in a thin
   adapter named in `plugin_boundary.json`.
 - Use stable tool ids: `claude_code`, `codex`, `cursor`, `gemini`, or another
   lowercase id agreed by the adapter.
+- When the work produces a handoff or retrospective **document**, post its
+  **absolute** path (`rally say handoff ... --evidence "file:/abs/path"`) and
+  state that same path in the terminal reply. A receiver runs in a different
+  working directory, so a relative path resolves to nothing or to the wrong
+  file, and a retrospective written to the memory store is unreachable from the
+  repo unless its path is said out loud. Post first, then go on writing; the
+  post needs no reading and nothing should delay it. The common failure is not
+  a thin handoff, it is a thorough one nobody located.
 
 ## Commands
 
@@ -74,6 +84,42 @@ session-ack aware; read `inbox/<tool>.jsonl` or `inbox/all.jsonl` before acting
 on a full message, then run `ack-inbox` after handling it. Ack cursors live
 under `inbox/.acks/` and never rewrite the append-only inbox payloads.
 
+## Retracting a wrong fact
+
+The ledger is append-only, so a posted fact is never edited or deleted. Withdraw
+one by appending a **retraction** that names its `event_id` — the `[fact_...]`
+id shown in `rally room`:
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/agent_rally.py retract \
+  --workdir "$PWD" --session-id "$SESSION_ID" --tool "$TOOL_ID" \
+  --fact fact_f4c9_18c99988bcb40648 \
+  --reason "wrong sha — read from a stale worktree" \
+  --superseded-by fact_a1b2_0f3e4d5c6b7a8901   # optional: the corrected fact
+```
+
+From then on every build-loop read path drops the withdrawn fact and keeps the
+retraction, so peers see the correction instead of the bad claim. `--superseded-by`
+is optional: use it when a corrected fact replaces the retracted one, omit it when
+the fact was simply wrong.
+
+Guardrails: an unknown `--fact` id exits 1 rather than posting a retraction that
+neutralizes nothing (`--force` overrides, for a fact in a store build-loop cannot
+read back); a second retraction of the same fact exits 1 as `retract-noop`; and
+retracting a retraction is refused, because that would erase the correction trail
+— post a new corrective fact instead.
+
+Limits worth knowing before you rely on it:
+
+- **Resolution is build-loop-side.** `rally room` is the Rust binary and does not
+  yet honor retractions, so a retracted fact still appears there (as does the
+  retraction next to it). Native `rally retract` is filed against the
+  `agent-rally-point` repo.
+- **A fact a peer already read cannot be un-read.** A retraction arriving in a
+  later poll surfaces as its own record; it cannot reach back into context a peer
+  already consumed.
+- **Pre-`fact.v1` records carry no `event_id`** and therefore cannot be targeted.
+
 ## Task Heartbeat — still on the claimed task
 
 Presence is process liveness: it tells peers this session can still write to

package/skills/api-registry-bridge/SKILL.md

@@ -48,7 +48,7 @@ When Assess detects a newly added third-party package:
 2. If `cooldown.install_blocked: true` (latest version released < 7 days ago, service not `author_owned`):
    - Surface the `cooldown.reason` to the user.
    - The `pre_bash_dependency_cooldown.sh` PreToolUse hook is the enforcement point — it already rewrites/denies fresh installs at the Bash boundary. The registry verdict is the *advisory* signal that explains *why* a hook rewrite happened; it does not replace the hook.
-   - `author_owned: true` services (`@tyroneross/*` scope + the user's own projects) are exempt — `cooldown.install_blocked` is always `false` for them, matching the hook's allowlist.
+   - `author_owned: true` services (the scope(s)/repos configured in `dependencyCooldown.allowlist`, plus the user's own projects) are exempt — `cooldown.install_blocked` is always `false` for them, matching the hook's allowlist. The default allowlist ships pinned to the maintainer's own npm scope; set `dependencyCooldown.allowlist` to your own scope(s) so this exemption applies to packages you own rather than the maintainer's.
 3. The 7-day registry cooldown window and the hook's 7-day install cooldown are deliberately the same number (supply-chain dwell time). If they ever diverge, the hook is authoritative for *enforcement*; the registry is authoritative for *explanation*.
 
 ## What this does NOT do

package/skills/architecture/dead/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: build-loop:architecture-dead
-description: Use when the user asks to "find dead code", "scan for orphaned components", or "clean up unused files", or during Phase 4 Review before a release. Scans for unreachable components and dead code; build-loop's native scan from NavGator's CLI.
+description: Find code/components with zero remaining callers — dead, unreachable, or orphaned files to delete. Use when the user asks to "find dead code", "clean up unused files", or "scan for orphaned components". Not for code that's still called but breaks a layer boundary or forms a cycle (use `architecture-rules`).
 version: 0.1.0
 user-invocable: false
 source: NavGator/commands/dead.md

package/skills/architecture/impact/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: build-loop:architecture-impact
-description: Use when Phase 1 Assess evaluates top-risk components, Phase 5 Iterate precedes a cross-layer fix, or the user asks "what does changing X break". Blast-radius analysis tracing upstream/downstream dependencies for a component or file before refactor.
+description: Blast-radius analysis — trace upstream/downstream dependencies for one component or file before changing it. Use when the user asks "what does changing X break" or before a cross-layer fix.
 version: 0.1.0
 user-invocable: false
 source: NavGator/skills/impact-analysis/SKILL.md