@tyroneross/build-loop 0.30.3 → 0.35.0

package/scripts/_paths.py

@@ -11,7 +11,14 @@ Environment variable contract:
 - ``$BUILD_LOOP_MEMORY_STORE_ROOT``: override the build-loop-memory root.
 - ``$BUILD_LOOP_MEMORY_ROOT``: compatibility override for the same root.
 - ``$AGENT_MEMORY_ROOT``     : compatibility override for the same root.
-                                Defaults to ``~/dev/git-folder/build-loop-memory``.
+
+Default resolution (when no env override is set), in order:
+  1. If the legacy personal root ``~/dev/git-folder/build-loop-memory``
+     EXISTS on disk, keep using it. This makes machines that predate the
+     neutral default keep working with zero configuration.
+  2. Otherwise use the neutral per-user default ``~/.build-loop-memory``
+     (``.<toolname>`` storage convention). Fresh installs land here — no
+     author-specific directory layout is ever encoded.
 - ``$AGENT_MEMORY_SCHEMA``   : override the default Postgres schema.
                                 Defaults to ``personal_memory``.
 - ``$AGENT_MEMORY_DUAL_WRITE``: when set to ``"1"``, writers must produce
@@ -42,14 +49,27 @@ from pathlib import Path
 LEGACY_SCHEMA = "build_loop_memory"
 LEGACY_DECISIONS_REL = ".episodic/decisions"
 
-DEFAULT_MEMORY_STORE_ROOT = "~/dev/git-folder/build-loop-memory"
+# Neutral per-user default for fresh installs. Matches the `.<toolname>`
+# storage convention. NOTE: this is the HYPHENATED `~/.build-loop-memory`,
+# deliberately NOT the retired `~/.build-loop/memory` (see the legacy-root
+# note further down — that exact path has migration tooling that would fight
+# a new write there).
+NEUTRAL_MEMORY_STORE_ROOT = "~/.build-loop-memory"
+# Legacy personal default. Predates the neutral default; kept as the resolved
+# root when it already exists on disk so existing machines need zero config.
+LEGACY_PERSONAL_MEMORY_STORE_ROOT = "~/dev/git-folder/build-loop-memory"
+# Back-compat constant name. `DEFAULT_MEMORY_STORE_ROOT` now names the NEUTRAL
+# default (what a fresh install gets). Resolution at call time still prefers an
+# existing legacy root — see `memory_store_root()`.
+DEFAULT_MEMORY_STORE_ROOT = NEUTRAL_MEMORY_STORE_ROOT
 DEFAULT_AGENT_MEMORY_ROOT = DEFAULT_MEMORY_STORE_ROOT
 DEFAULT_SCHEMA = "personal_memory"
 
 CUTOVER_LOCK_PATH = "/tmp/agent-memory-cutover.lock"
 
 # Historical name retained as a compatibility alias. The active root is now
-# the sibling `build-loop-memory` repository, not `~/.build-loop/memory`.
+# the sibling `build-loop-memory` repository (or the neutral fresh-install
+# default), not `~/.build-loop/memory`.
 DEFAULT_BUILD_LOOP_MEMORY_ROOT = DEFAULT_MEMORY_STORE_ROOT
 
 # Sub-component patterns: paths under a project that count as a distinct
@@ -61,18 +81,31 @@ SUBCOMPONENT_PATTERNS: tuple[str, ...] = ("workers",)
 def memory_store_root() -> Path:
     """Return the canonical build-loop-memory root.
 
-    Reads, in order, ``$BUILD_LOOP_MEMORY_STORE_ROOT``,
-    ``$BUILD_LOOP_MEMORY_ROOT``, and ``$AGENT_MEMORY_ROOT`` (expanded for
-    ``~``). Falls back to ``~/dev/git-folder/build-loop-memory``. Path is
-    not required to exist; callers that need the directory should create it.
+    Resolution order:
+      1. ``$BUILD_LOOP_MEMORY_STORE_ROOT`` / ``$BUILD_LOOP_MEMORY_ROOT`` /
+         ``$AGENT_MEMORY_ROOT`` env override (first set wins, ``~`` expanded).
+      2. The legacy personal default ``~/dev/git-folder/build-loop-memory``
+         when it EXISTS on disk — keeps pre-neutral-default machines working
+         with zero config.
+      3. The neutral per-user default ``~/.build-loop-memory`` for fresh
+         installs.
+
+    The returned path is not required to exist (only the legacy branch checks
+    existence); callers that need the directory should create it.
     """
-    raw = (
+    env_raw = (
         os.environ.get("BUILD_LOOP_MEMORY_STORE_ROOT")
         or os.environ.get("BUILD_LOOP_MEMORY_ROOT")
         or os.environ.get("AGENT_MEMORY_ROOT")
-        or DEFAULT_MEMORY_STORE_ROOT
     )
-    return Path(os.path.expanduser(raw))
+    if env_raw:
+        return Path(os.path.expanduser(env_raw))
+
+    legacy = Path(os.path.expanduser(LEGACY_PERSONAL_MEMORY_STORE_ROOT))
+    if legacy.exists():
+        return legacy
+
+    return Path(os.path.expanduser(NEUTRAL_MEMORY_STORE_ROOT))
 
 
 def agent_memory_root() -> Path:
@@ -149,6 +182,11 @@ def project_lessons_dir(project: str) -> Path:
     return project_root(project) / "lessons"
 
 
+def project_research_dir(project: str) -> Path:
+    """Return ``<project_root(project)>/research`` for pre-decision research packets."""
+    return project_root(project) / "research"
+
+
 def project_raw_dir(project: str) -> Path:
     """Return ``<project_root(project)>/raw`` for verbatim source material."""
     return project_root(project) / "raw"
@@ -263,9 +301,11 @@ def cutover_lock_active() -> bool:
 # ---------------------------------------------------------------------------
 # Build-loop memory paths (global + per-project segmentation).
 #
-# Per the memory-consolidation PR series (2026-05-13):
-#   - ~/.build-loop/memory/                   global root (existing)
-#   - ~/.build-loop/memory/projects/<slug>/   project-scoped lessons (NEW)
+# HISTORICAL (the `~/.build-loop/memory/` paths below are RETIRED — do not
+# reintroduce them as a default). The memory-consolidation PR series
+# (2026-05-13) originally rooted the store at `~/.build-loop/memory/`:
+#   - ~/.build-loop/memory/                   global root
+#   - ~/.build-loop/memory/projects/<slug>/   project-scoped lessons
 #   - ~/.build-loop/memory/projects/_archive/<slug>/   retired projects
 #
 # PR 1 (read-path tolerance, 2026-05-13) added the projects/<slug>/ tier
@@ -274,6 +314,12 @@ def cutover_lock_active() -> bool:
 # is now the only path read. Slug derivation reuses _safe_project_tag so
 # the same normalization applies to filesystem dirs AND the Postgres
 # semantic_facts.project column (no split-brain by construction).
+#
+# The ACTIVE root is whatever `memory_store_root()` returns: an env override,
+# else the legacy personal `~/dev/git-folder/build-loop-memory` if present,
+# else the neutral fresh-install default `~/.build-loop-memory` (hyphenated,
+# distinct from the retired `~/.build-loop/memory`). All helpers below build
+# on `memory_store_root()`, so they follow that resolution automatically.
 # ---------------------------------------------------------------------------
 
 

package/scripts/build_codex_plugin_artifact.py

@@ -0,0 +1,314 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com>
+# SPDX-License-Identifier: Apache-2.0
+"""Build the slim Codex plugin artifact.
+
+The source repo keeps Claude's full internal skill tree at ``skills/``. Codex
+auto-discovers root ``skills/*/SKILL.md`` entries, so the Codex marketplace must
+install from an artifact that exposes exactly one public skill.
+"""
+from __future__ import annotations
+
+import argparse
+import filecmp
+import json
+import os
+import re
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Iterable
+
+
+DEFAULT_TARGET = Path("plugin-artifacts/codex")
+IGNORED_NAMES = {".DS_Store", "__pycache__", ".pytest_cache"}
+IGNORED_SUFFIXES = {".pyc"}
+TOP_LEVEL_FILES = ("AGENTS.md", "README.md", "LICENSE")
+
+# Bundle markdown points readers at ``references/<file>.md`` (root-relative).
+# The Claude source resolves that logical namespace across the repo's top-level
+# ``references/`` plus each skill's own ``references/``. The slim Codex bundle
+# ships only the ``build-loop`` skill, so those pointers dangle unless we mirror
+# every cited reference into ONE top-level ``references/`` dir at the bundle
+# root — the natural resolution point for both AGENTS.md (at root) and any
+# deeper file an LLM reads. Search order resolves drift deterministically: the
+# skill's own copy wins (it's the one already shipped in the skill tree), then
+# the repo root, then the ui-design skill.
+REFERENCE_SOURCE_DIRS = (
+    Path("skills") / "build-loop" / "references",
+    Path("references"),
+    Path("skills") / "ui-design" / "references",
+)
+# A bare ``references/X.md`` pointer. Anchored to a path boundary so we don't
+# match foreign-skill prose like ``build-loop:deepagents`` references — those
+# are always written with the skill name in front (``The skill's
+# `references/anti-patterns.md```) and resolve inside that other skill, which
+# the slim bundle does not ship.
+_REFERENCE_POINTER_RE = re.compile(r"(?:^|[\s`(\[])references/([A-Za-z0-9_.-]+\.md)")
+# Pointers that name another skill's references dir in prose, not a build-loop
+# bundle file. They have no build-loop source and must not fail the check.
+FOREIGN_SKILL_REFERENCES = frozenset(
+    {
+        "anti-patterns.md",  # build-loop:building-with-deepagents
+        "stack-templates.md",  # build-loop:logging-tracer
+        "ios-notification-alarm-playbook.md",  # build-loop:debugging-memory
+    }
+)
+# Pre-existing, deliberate forward-reference placeholders in the source tree
+# (marked TBD in prose). They have no file anywhere — in the Claude tree either.
+# Not codex-introduced; fixing them is out of scope for the artifact builder, so
+# they are tolerated rather than blocking every bundle build. Keep this list
+# tight: a NEW unresolvable pointer on the primary surface must still fail.
+KNOWN_TBD_REFERENCES = frozenset(
+    {
+        "brief-filters.md",  # references/implementer-envelope-schema.md: "(TBD)"
+    }
+)
+
+
+def cited_reference_basenames(*roots: Path) -> set[str]:
+    """Every bare ``references/<file>.md`` pointer across the given markdown roots."""
+    cited: set[str] = set()
+    for root in roots:
+        for md in root.rglob("*.md"):
+            cited.update(
+                _REFERENCE_POINTER_RE.findall(
+                    md.read_text(encoding="utf-8", errors="ignore")
+                )
+            )
+    return cited
+
+
+def resolve_reference_source(source: Path, basename: str) -> Path | None:
+    """Locate a cited reference file in the build-loop source search paths."""
+    for rel_dir in REFERENCE_SOURCE_DIRS:
+        candidate = source / rel_dir / basename
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def mirror_references(source: Path, bundle_root: Path) -> None:
+    """Copy the transitive closure of cited references into ``<bundle>/references/``.
+
+    Iterates to a fixpoint: a mirrored reference file may itself cite further
+    ``references/X.md``, so re-scan after each copy until no new resolvable
+    pointer appears. Makes every root-relative ``references/X.md`` pointer in the
+    bundle resolve at the bundle root. Foreign-skill and known-TBD pointers are
+    skipped (no build-loop source); a genuinely unexpected unresolvable pointer
+    is left for ``check_reference_pointers`` to adjudicate by surface.
+    """
+    out_dir = bundle_root / "references"
+    copied: set[str] = set()
+    while True:
+        cited = cited_reference_basenames(bundle_root)
+        new_resolvable = False
+        for basename in sorted(cited - copied):
+            copied.add(basename)
+            if basename in FOREIGN_SKILL_REFERENCES or basename in KNOWN_TBD_REFERENCES:
+                continue
+            src_file = resolve_reference_source(source, basename)
+            if src_file is not None:
+                copy_file(src_file, out_dir / basename)
+                new_resolvable = True
+        if not new_resolvable:
+            break
+
+
+def check_reference_pointers(bundle_root: Path) -> None:
+    """Assert every ``references/X.md`` pointer on the bundle's PRIMARY surface resolves.
+
+    Primary surface = the files a Codex user actually lands on: top-level
+    AGENTS.md / README.md and the whole ``skills/build-loop`` tree. Resolution
+    target is the mirrored top-level ``<bundle>/references/``. Foreign-skill and
+    known-TBD pointers are allowlisted. A dangling primary-surface pointer is a
+    real regression and fails the build. Pointers that appear ONLY inside
+    transitively-mirrored reference files (often forward TBDs) are tolerated —
+    fixing unrelated source dead-links is not the artifact builder's job.
+    """
+    refs_dir = bundle_root / "references"
+    surface_roots = [bundle_root / "skills" / "build-loop"]
+    surface_roots += [
+        bundle_root / name for name in ("AGENTS.md", "README.md") if (bundle_root / name).is_file()
+    ]
+    # rglob on a file path yields nothing; scan top-level files explicitly.
+    cited: set[str] = set()
+    for root in surface_roots:
+        if root.is_dir():
+            cited |= cited_reference_basenames(root)
+        elif root.is_file():
+            cited |= set(
+                _REFERENCE_POINTER_RE.findall(root.read_text(encoding="utf-8", errors="ignore"))
+            )
+    dangling = sorted(
+        b
+        for b in cited
+        if b not in FOREIGN_SKILL_REFERENCES
+        and b not in KNOWN_TBD_REFERENCES
+        and not (refs_dir / b).is_file()
+    )
+    if dangling:
+        raise ArtifactError(
+            "dangling reference pointers on the primary surface (no file at "
+            "bundle references/): " + ", ".join(dangling)
+        )
+
+
+class ArtifactError(RuntimeError):
+    pass
+
+
+def ignore_generated(_dir: str, names: list[str]) -> set[str]:
+    ignored = set()
+    for name in names:
+        if name in IGNORED_NAMES:
+            ignored.add(name)
+            continue
+        if any(name.endswith(suffix) for suffix in IGNORED_SUFFIXES):
+            ignored.add(name)
+    return ignored
+
+
+def copy_file(source: Path, target: Path) -> None:
+    if not source.is_file():
+        raise ArtifactError(f"missing required file: {source}")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(source, target)
+
+
+def copy_tree(source: Path, target: Path) -> None:
+    if not source.is_dir():
+        raise ArtifactError(f"missing required directory: {source}")
+    shutil.copytree(source, target, ignore=ignore_generated)
+
+
+def write_codex_manifest(source: Path, target: Path) -> None:
+    manifest_path = source / ".codex-plugin" / "plugin.json"
+    if not manifest_path.is_file():
+        raise ArtifactError(f"missing required file: {manifest_path}")
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    manifest["skills"] = "./skills"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+
+
+def write_notice(target: Path) -> None:
+    target.write_text(
+        "\n".join(
+            [
+                "# Codex Build Loop Artifact",
+                "",
+                "Generated by `python3 scripts/build_codex_plugin_artifact.py`.",
+                "This artifact is the Codex marketplace install surface.",
+                "It exposes exactly one public skill: `build-loop`.",
+                "",
+            ]
+        ),
+        encoding="utf-8",
+    )
+
+
+def skill_files(root: Path) -> list[Path]:
+    return sorted(root.rglob("SKILL.md"))
+
+
+def validate_artifact(target: Path) -> None:
+    manifest_path = target / ".codex-plugin" / "plugin.json"
+    skills_root = target / "skills"
+    if not manifest_path.is_file():
+        raise ArtifactError(f"artifact missing {manifest_path}")
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    if manifest.get("skills") != "./skills":
+        raise ArtifactError("artifact Codex manifest must use skills=./skills")
+
+    files = skill_files(skills_root)
+    rel_files = [str(path.relative_to(target)) for path in files]
+    if rel_files != ["skills/build-loop/SKILL.md"]:
+        raise ArtifactError(f"artifact must expose exactly one SKILL.md, got {rel_files}")
+
+    check_reference_pointers(target)
+
+
+def build_artifact(source: Path, target: Path) -> None:
+    source = source.resolve()
+    target = target.resolve()
+    if source == target or target in source.parents:
+        raise ArtifactError(f"refusing to write artifact above source: {target}")
+
+    parent = target.parent
+    parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix=".codex-artifact-", dir=str(parent)) as tmp_raw:
+        tmp = Path(tmp_raw)
+        write_codex_manifest(source, tmp / ".codex-plugin" / "plugin.json")
+        for name in TOP_LEVEL_FILES:
+            copy_file(source / name, tmp / name)
+        copy_tree(source / "skills" / "build-loop", tmp / "skills" / "build-loop")
+        copy_file(source / "docs" / "agent-surface-policy.md", tmp / "docs" / "agent-surface-policy.md")
+        write_notice(tmp / "BUILD-ARTIFACT.md")
+        # Mirror cited references AFTER the skill tree + top-level files exist so
+        # the pointer scan sees every citing file.
+        mirror_references(source, tmp)
+        validate_artifact(tmp)
+
+        if target.exists():
+            shutil.rmtree(target)
+        os.replace(tmp, target)
+
+
+def iter_files(root: Path) -> Iterable[Path]:
+    for path in sorted(root.rglob("*")):
+        if path.is_file():
+            yield path
+
+
+def assert_same_tree(expected: Path, actual: Path) -> None:
+    expected_files = {path.relative_to(expected) for path in iter_files(expected)}
+    actual_files = {path.relative_to(actual) for path in iter_files(actual)}
+    if expected_files != actual_files:
+        missing = sorted(str(path) for path in expected_files - actual_files)
+        extra = sorted(str(path) for path in actual_files - expected_files)
+        raise ArtifactError(f"artifact file set differs; missing={missing}, extra={extra}")
+    for rel in sorted(expected_files):
+        if not filecmp.cmp(expected / rel, actual / rel, shallow=False):
+            raise ArtifactError(f"artifact file differs: {rel}")
+
+
+def check_artifact(source: Path, target: Path) -> None:
+    parent = target.resolve().parent
+    parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix=".codex-artifact-check-", dir=str(parent)) as tmp_raw:
+        tmp = Path(tmp_raw) / "codex"
+        build_artifact(source, tmp)
+        assert_same_tree(tmp, target.resolve())
+    validate_artifact(target.resolve())
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--source", default=".", help="Build Loop source repo root.")
+    parser.add_argument("--target", default=str(DEFAULT_TARGET), help="Codex artifact output directory.")
+    parser.add_argument("--check", action="store_true", help="Fail if the artifact is missing or stale.")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    source = Path(args.source).expanduser().resolve()
+    target = Path(args.target).expanduser()
+    if not target.is_absolute():
+        target = source / target
+    try:
+        if args.check:
+            check_artifact(source, target)
+            print(f"codex artifact up to date: {target}")
+        else:
+            build_artifact(source, target)
+            print(f"codex artifact written: {target}")
+        return 0
+    except ArtifactError as exc:
+        print(f"error: {exc}")
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/check_cache_sync.py

@@ -44,7 +44,7 @@ CODEX_DEFAULT_MARKETPLACE = os.environ.get(
     "local-marketplace",
 )
 COORDINATION_EXACT_REFS = (
-    "commands/agent-rally-point.md",
+    "commands/rally-point.md",
     "references/rally-point-protocol.md",
     "references/coordination-rules.md",
     "references/multi-session-coordination.md",

package/scripts/install_memory.py

@@ -3,11 +3,16 @@
 # SPDX-License-Identifier: Apache-2.0
 """install_memory.py — bootstrap the build-loop memory directory.
 
-Creates the canonical build-loop-memory root (default:
-`~/dev/git-folder/build-loop-memory`) and seeds it with template
+Creates the canonical build-loop-memory root and seeds it with template
 `constitution.md` + `MEMORY.md` if either is missing. Idempotent — never
 overwrites existing files.
 
+The root is resolved by `_paths.memory_store_root()`: an env override
+(`$BUILD_LOOP_MEMORY_STORE_ROOT` / `$BUILD_LOOP_MEMORY_ROOT` /
+`$AGENT_MEMORY_ROOT`), else a pre-existing legacy
+`~/dev/git-folder/build-loop-memory` on disk, else the neutral fresh-install
+default `~/.build-loop-memory`.
+
 Optional: link the directory to a private git repo so user-specific memory
 content is versioned. The build-loop public repo ships ONLY the templates;
 the user's actual lessons / patterns / decisions belong in a separate private
@@ -47,7 +52,10 @@ except Exception:  # noqa: BLE001
     memory_store_root = None  # type: ignore[assignment]
     _safe_project_relpath = None  # type: ignore[assignment]
 
-DEFAULT_DEST = memory_store_root() if memory_store_root is not None else Path.home() / "dev" / "git-folder" / "build-loop-memory"
+# Resolve via memory_store_root() (env → legacy-if-present → neutral default).
+# The import-failure fallback uses the neutral fresh-install default so a
+# degraded run never re-encodes a personal directory layout.
+DEFAULT_DEST = memory_store_root() if memory_store_root is not None else Path.home() / ".build-loop-memory"
 TEMPLATE_DIR_RELATIVE = "templates/memory"
 SEED_MANIFEST_FILENAME = "manifest.json"
 TEMPLATES = [