PRD: First-class, time-travel-safe semantics; Neo4j proto; Docker naming

.ci/.dockerignore

@@ -0,0 +1,2 @@
+*
+!Dockerfile

.ci/Dockerfile

@@ -1,12 +1,31 @@
 FROM ubuntu:22.04
+LABEL com.gitmind.project="git-mind" \
+      org.opencontainers.image.title="git-mind-ci"
 ENV DEBIAN_FRONTEND=noninteractive
 ENV TZ=UTC
 RUN apt-get update && \
-    apt-get install -y wget gnupg lsb-release python3-pip pkg-config software-properties-common && \
+    apt-get install -y --no-install-recommends wget gnupg lsb-release python3-pip pkg-config software-properties-common ca-certificates && \
+    rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/* && \
     wget -O - https://apt.llvm.org/llvm.sh | bash -s -- 20 && \
-    apt-get install -y clang-20 clang-tidy-20 cppcheck libsodium-dev git ninja-build && \
+    apt-get clean && rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/* && \
+    apt-get update && \
+    apt-get install -y --no-install-recommends clang-20 clang-tidy-20 cppcheck \
+        libsodium-dev libgit2-dev git ninja-build pkg-config build-essential cmake ca-certificates && \
+    apt-get clean && rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/* && \
     ln -sf /usr/bin/clang-tidy-20 /usr/local/bin/clang-tidy && \
     ln -sf /usr/bin/clang++-20    /usr/local/bin/clang++ && \
     ln -sf /usr/bin/clang-20      /usr/local/bin/clang && \
-    pip3 install meson ninja
+    pip3 install --no-cache-dir meson ninja && \
+    # Install CRoaring from apt if available, otherwise build from source
+    apt-get update && (apt-get install -y --no-install-recommends libroaring-dev || true) && \
+    if ! pkg-config --exists roaring; then \
+      echo "Building CRoaring from source..." && \
+      rm -rf /tmp/croaring && \
+      git clone --depth 1 https://github.com/RoaringBitmap/CRoaring.git /tmp/croaring && \
+      cmake -S /tmp/croaring -B /tmp/croaring/build -DCMAKE_BUILD_TYPE=Release -DENABLE_POPCNT=ON -DENABLE_AVX=OFF -DENABLE_NEON=ON && \
+      cmake --build /tmp/croaring/build -j"$(nproc)" && \
+      cmake --install /tmp/croaring/build && \
+      rm -rf /tmp/croaring && \
+      echo "/usr/local/lib" > /etc/ld.so.conf.d/croaring.conf && ldconfig; \
+    fi
 WORKDIR /workspace

.dockerignore

@@ -0,0 +1,18 @@
+# Reduce Docker build context size when building images from repo root
+.git
+build
+build-*
+build_* 
+compile_commands.json
+ci_logs.zip
+*.o
+*.a
+*.so
+*.dylib
+*.obj
+*.exe
+*.log
+*.tmp
+__pycache__/
+*.pyc
+node_modules/

.github/workflows/c_core.yml

@@ -12,7 +12,7 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y wget gnupg lsb-release python3-pip
           wget -O - https://apt.llvm.org/llvm.sh | sudo bash -s -- 20
-          sudo apt-get install -y clang-20 clang-tidy-20 cppcheck libsodium-dev libgit2-dev
+          sudo apt-get install -y clang-20 clang-tidy-20 cppcheck libsodium-dev libgit2-dev libroaring-dev
           sudo ln -sf /usr/bin/clang-tidy-20 /usr/local/bin/clang-tidy
           sudo ln -sf /usr/bin/clang++-20    /usr/local/bin/clang++
           sudo ln -sf /usr/bin/clang-20      /usr/local/bin/clang

.github/workflows/core-quality.yml

@@ -19,7 +19,7 @@ jobs:
     - name: Install dependencies
       run: |
         sudo apt-get update
-        sudo apt-get install -y clang clang-tidy libsodium-dev libgit2-dev build-essential python3-pip
+        sudo apt-get install -y clang clang-tidy libsodium-dev libgit2-dev libroaring-dev build-essential python3-pip
         pip3 install --break-system-packages meson ninja
 
     - name: Check for TODOs/FIXMEs

AGENTS.md

@@ -0,0 +1,88 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `core/` — C23 library: `include/` (public headers), `src/` (impl), `tests/` (unit). Add new code here.
+- `include/` — Umbrella API (`gitmind.h`) and namespaced headers under `include/gitmind/`.
+- `src/` — Legacy code under migration. Avoid adding new modules here.
+- `apps/` — Future CLI/hooks/apps. Until announced, prefer `core/` additions.
+- `tests/` — E2E/integration/legacy tests and fixtures.
+- `tools/`, `quality/`, `.githooks/` — Dev tooling (clang-tidy, formatting, gauntlet, secret scanning).
+- `docs/` — Architecture, dev setup, and operational notes.
+
+## Build, Test, and Development Commands
+- Configure + build: `meson setup build && ninja -C build`
+- Run unit tests: `ninja -C build test` (or `meson test -C build`)
+- Make shims: `make`, `make test`, `make clean`
+- Lint (CI parity): `./tools/docker-clang-tidy.sh` → produces `clang-tidy-report.txt`
+- Strict multi-compiler build: `./tools/gauntlet/run-gauntlet.sh` (recommended before PRs)
+- Enable hooks: `pre-commit install` (clang-format + detect-secrets)
+
+## Coding Style & Naming Conventions
+- Language: C23 with warnings-as-errors; no VLAs or shadowing; explicit prototypes.
+- Formatting: `.clang-format` (LLVM-based, 4 spaces, 80 cols, pointer alignment right). Pre-commit runs `clang-format`.
+- Naming: functions/vars `lower_snake_case` (prefix `gm_`), macros `UPPER_SNAKE`, types end in `_t`, header guards `GITMIND_*`.
+- Includes: prefer specific headers; order/regroup per `.clang-format`.
+
+## Testing Guidelines
+- Unit tests live in `core/tests/unit/` as `test_<module>.c`. Keep deterministic and isolated.
+- Meson wires test backends as needed—just build and run tests via Meson/Ninja.
+- E2E/integration under `tests/` for CLI/flow checks. Keep fixtures minimal.
+
+## Commit & Pull Request Guidelines
+- Conventional commits: `type(scope): description` (e.g., `fix(core/cbor): handle null keys`). Reference issues (`Fixes #123`).
+- PRs must describe changes, link issues, include a short test plan, pass CI, and introduce no new clang-tidy warnings (`./tools/docker-clang-tidy.sh`). Update docs when applicable.
+
+## Security & Configuration
+- Do not commit secrets. Pre-commit runs `detect-secrets` with `.secrets.baseline`.
+- Use `.env.example` as a template; never check in real credentials.
+
+## Agent-Specific Notes
+- Make minimal, focused diffs; avoid drive-by refactors. Match existing patterns in `core/` and headers under `include/`.
+- Run build, tests, and lint locally before proposing changes. Keep changes zero-warnings and formatted.
+
+## Working Knowledge (for agents)
+- Journal-first graph: Edges are CBOR commits under `refs/gitmind/edges/<branch>`; cache lives in `refs/gitmind/cache/<branch>` and is rebuildable (never merged).
+- Semantics as names: Store `type_name` and `lane_name` as UTF-8 strings on edges; do not collapse into a generic/custom type. Derive 64-bit IDs from names (NFC + stable hash) only for cache/filters.
+- Time-travel correctness: All semantics (and optional advice) are in-history; queries evaluate against the chosen commit and branch.
+- Merge/conflict model: Append-only journal; edge ULIDs form an OR-Set; “Semantics Advice” (optional) merges with hybrid CRDT (LWW scalars, OR-Set collections).
+- Link vs code authors: Edge attribution `author` is the link creator (from `git config` unless provided); code authorship at the chosen commit is recorded separately (per-file last commit author/time) when using Neo4j upsert tooling.
+- Docker hygiene: Images are namespaced/labeled (`gitmind/ci:clang-20`, `gitmind/gauntlet:<compiler>`; label `com.gitmind.project=git-mind`). Use `make docker-clean` to reclaim space safely.
+- CI/Tidy nuance: Local builds and tests pass. Clang-tidy in Docker depends on CRoaring headers in the CI image; add a source build step for deterministic results on aarch64 if CI flags it.
+
+
+## Neo4j Codex Log (Memory Graph)
+- Purpose: record tasks, touched files, and relationships to enable impact/risk queries for this repo.
+- Project tagging: all nodes carry label `:GM` and `repo:'git-mind'`.
+- Setup env:
+  - `export NEO4J_HTTP_URL=http://localhost:7474`
+  - `export NEO4J_USER=neo4j`
+  - `export NEO4J_PASSWORD=password123` (use real local creds; don’t commit)
+- One‑time constraints (HTTP):
+  - Use `scripts/neo4j-constraints.json` which creates GM-scoped constraints (Task:GM.id unique, File:GM.path unique, repo existence).
+- Helper script: `scripts/neo4j-curl.sh`
+  - Pipe JSON or use `-f payload.json`. Posts to `NEO4J_HTTP_URL/db/neo4j/tx/commit` with basic auth.
+- Quick start examples:
+  - Start task: `echo '{"statements":[{"statement":"MERGE (t:Task:GM {id:$id}) ON CREATE SET t.title=$title, t.status=\"in_progress\", t.started_at:datetime(), t.repo=\"git-mind\" ON MATCH SET t.status=\"in_progress\", t.repo=\"git-mind\"","parameters":{"id":"gm-docker-namespacing","title":"Docker image names + cleanup"}}]}' | bash scripts/neo4j-curl.sh`
+  - Link touched file: `echo '{"statements":[{"statement":"MERGE (t:Task:GM {id:$id}) MERGE (f:File:GM {path:$p}) ON CREATE SET f.repo=\"git-mind\" ON MATCH SET f.repo=\"git-mind\" MERGE (t)-[:TOUCHES]->(f)","parameters":{"id":"gm-docker-namespacing","p":"tools/docker-clean.sh"}}]}' | bash scripts/neo4j-curl.sh`
+  - Record dependency: `echo '{"statements":[{"statement":"MERGE (a:File:GM {path:$a}) ON CREATE SET a.repo=\"git-mind\" ON MATCH SET a.repo=\"git-mind\" MERGE (b:File:GM {path:$b}) ON CREATE SET b.repo=\"git-mind\" ON MATCH SET b.repo=\"git-mind\" MERGE (a)-[:DEPENDS_ON]->(b)","parameters":{"a":"tools/docker-clang-tidy.sh","b":".ci/Dockerfile"}}]}' | bash scripts/neo4j-curl.sh`
+
+### Ready-to-run payloads in this repo
+- Initialize constraints (once): `bash scripts/neo4j-curl.sh -f scripts/neo4j-constraints.json`
+- Log this task (files touched): `bash scripts/neo4j-curl.sh -f scripts/neo4j-task-gm-docker-neo4j-2025-09-12.json`
+- Verify touched files for a task: `scripts/neo4j-show-task.sh gm-docker-namespacing-neo4j-2025-09-12`
+
+## Neo4j Proto Edge Schema (git-mind semantics)
+- Relationship: `(a:File:GM {repo:'git-mind'})-[:EDGE {ulid, type, lane, confidence, ts, commit, src_path, tgt_path, src_sha, tgt_sha, author, source_type, session_id, repo:'git-mind'}]->(b:File:GM {repo:'git-mind'})`
+- Properties map 1:1 to libgitmind edge fields (ulid, attribution, lane, SHAs, etc.).
+- Upsert example (script):
+  - `scripts/gm-neo4j-upsert-edge.sh --commit HEAD --src core/src/io/io.c --tgt core/include/gitmind/io/io.h --type IMPLEMENTS --lane verified --author user@local --source human --confidence 90`
+- Export edges to JSON/NDJSON:
+  - `scripts/neo4j-export-edges.sh` (uses jq if available)
+
+### Importer plan (proto → journal)
+- Extract edges: `scripts/neo4j-export-edges.sh > edges.json`
+- For each edge row:
+  - Resolve paths to blob OIDs at `edge.commit` (already present as `src_sha`/`tgt_sha`)
+  - Write journal entry under `refs/gitmind/edges/<lane>` with full properties (ulid, attribution, type)
+  - Rebuild cache: `gm_cache_rebuild()` (Meson test harness covers core APIs)
+- Validate parity: compare fanout/fanin against Neo4j MATCH results on the same commit.

CLAUDE.md

@@ -16,6 +16,8 @@ For workflows that apply to ALL contributors (human and AI):
 - __NEVER__ alter, disable, or otherwise circumvent git hooks or tests
 - __NEVER__ use `git add -A`, __ALWAYS__ stage changes intentionally
 
+> [!DANGER] __NEVER__ use `NOLINT` to suppress clang tidy warnings. __ALWAYS__ fix them problem in your code. Suppressions lead to real bugs. Static analysis is part of the CI gate. Silencing it violates the repo’s “no warnings” contract and kills developer trust. No excuses, push clean builds. End of story.
+
 ## ENCOURAGED ACTIONS
 
 - __USE SEQUENTIAL THINKING__ if you’re planning, doing __RECON__, or find yourself thrashing on an issue