chore(core/migration): remove legacy src/ duplicates; convert include/gitmind.h to pure umbrella; flatten CLI path to apps/cli/

AGENTS.md

@@ -18,12 +18,16 @@
 - Enable hooks: `pre-commit install` (clang-format + detect-secrets + docs link/TOC checks)
 - Docs linter (all docs): `python3 tools/docs/check_docs.py --mode link` and `--mode toc`
 - Pre-commit (changed files): `pre-commit run --all-files docs-link-check` and `docs-toc-check`
+ - Markdown linter: `make md-lint` (check) and `make md-fix` (autofix) — uses `.markdownlint.jsonc`
+ - Header guards lint: `meson run -C build lint_header_guards`
+ - Public headers compile check: `ninja -C build header-compile`
 
 ## 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`.
+ - Public headers must be umbrella-safe: compile standalone, correct include order, stable header guards, and `extern "C"` when included from C++.
 
 ## Testing Guidelines
 - Unit tests live in `core/tests/unit/` as `test_<module>.c`. Keep deterministic and isolated.
@@ -33,14 +37,17 @@
 ## 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.
+ - Code review (CodeRabbit): Keep `.coderabbit.yml` updated. Prefer summary reviews, limit per-line comments on docs. If rejecting a suggestion, add a note under `docs/code-reviews/rejected-suggestions/{commit}_{branch}_{PR#}_{suggestion}.md` with a link to the original comment and rationale.
 
 ## 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.
+ - E2E safety: some CI E2E steps require `GITMIND_SAFETY=off` in the container environment.
 
 ## 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.
+ - Prefer OID-first APIs for SHA-agnostic correctness. Use `git_oid` (typedef `gm_oid_t`) in new core interfaces, and compare via `git_oid_cmp`.
 
 ## 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).
@@ -50,6 +57,25 @@
 - 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 captured by external 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.
+ - CI path filters: Core build/test workflows are restricted to code paths; doc-only changes do not trigger core builds. Markdown lint runs separately with reduced noise via `.markdownlint.jsonc`.
+
+## Agent Activity Log
+
+2025-09-14
+- CI/CD: Added Markdown linting with repo-aligned rules (`.markdownlint.jsonc`), `make md-lint`/`md-fix` targets, and path filters limiting core workflows to code paths. Enabled docker pull retry and set `GITMIND_SAFETY=off` for E2E in the core workflow.
+- Header hygiene: Standardized header guards to `GITMIND_*`, added umbrella viability check (public headers compile standalone), and a header guard linter (`tools/quality/check_header_guards.py`) wired via Meson run target.
+- OID-first migration: Introduced `typedef git_oid gm_oid_t` and `GM_OID_RAWSZ`. Migrated edges, cache queries, and hooks APIs to OID-first and switched equality to `git_oid_cmp`. Maintained compatibility where needed; CBOR decode backfills OIDs from legacy fields temporarily.
+- Journal safety: Base64-encoded CBOR commit messages on write and decoded on read; added strict `gm_snprintf` overflow checks and security-conscious includes.
+- CLI fixes: Adjusted `apps/cli` commands for include hygiene, error handling, and consistent porcelain output; freed libgit2 arrays correctly.
+- Reviews/PRs: Pushed branches, resolved merge conflicts, and responded to CodeRabbit with summary feedback. Opened a PR for CodeRabbit + markdownlint config changes and updated PRs addressing invalid path errors and core cleanup.
+
+## Next Steps (handoff checklist)
+- Complete on-disk cache migration to OID-only storage and naming; ensure rebuild and fallback readers handle both formats or gate with a one-time migration.
+- Extend journal CBOR schema to store OIDs explicitly (not only derivable from legacy fields); update reader/writer and consumers.
+- Sweep any remaining headers for guard/extern "C" issues and fix items flagged by `lint_header_guards`.
+- Expand attributed edge CBOR to include OIDs alongside legacy fields; update cache/journal consumers accordingly.
+- Stabilize and merge open PRs (#164, #165, #166, #167) after CI green; incorporate CodeRabbit actionable feedback and document any rejections under `docs/code-reviews/rejected-suggestions/`.
+- Add focused tests: journal base64 encode/decode roundtrip, `gm_snprintf` truncation behavior, and OID-based equality/lookup paths in cache and hooks.
 
 
 ## Vision Snapshot

core/include/gitmind/cache.h

@@ -9,9 +9,9 @@
 #include <stdint.h>
 
 #include <git2/types.h>
+#include <git2/oid.h>
 
 #include "gitmind/context.h"
-#include "gitmind/result.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -30,7 +30,7 @@ extern "C" {
 #define GM_CACHE_SHARD_BITS 8 /* 2 hex chars = 256 shards */
 #define GM_CACHE_REF_PREFIX "refs/gitmind/cache/"
 #define GM_CACHE_BRANCH_NAME_SIZE 64  /* Maximum branch name length */
-#define GM_CACHE_OID_STRING_SIZE 41   /* Git OID as string + null terminator */
+#define GM_CACHE_OID_STRING_SIZE (GIT_OID_HEXSZ + 1) /* OID hex + NUL */
 
 /* Cache result containing edge IDs matching a query */
 typedef struct {
@@ -65,24 +65,24 @@ int gm_cache_init(void);
 int gm_cache_rebuild(gm_context_t *ctx, const char *branch, bool force_full);
 
 /**
- * Query edges by source SHA (forward traversal)
+ * Query edges by source OID (forward traversal)
  * @param ctx Git-mind context containing repository
- * @param src_sha Source SHA bytes (20 bytes)
+ * @param src_oid Source object ID
  * @param result Output result structure
  * @return GM_OK on success, error code on failure
  */
-int gm_cache_query_fanout(gm_context_t *ctx, const char *branch, const uint8_t *src_sha, 
+int gm_cache_query_fanout(gm_context_t *ctx, const char *branch, const gm_oid_t *src_oid,
                           gm_cache_result_t *result);
 
 /**
- * Query edges by target SHA (reverse traversal)
+ * Query edges by target OID (reverse traversal)
  * @param ctx Git-mind context containing repository
  * @param branch Branch name to query
- * @param tgt_sha Target SHA bytes (20 bytes)
+ * @param tgt_oid Target object ID
  * @param result Output result structure
  * @return GM_OK on success, error code on failure
  */
-int gm_cache_query_fanin(gm_context_t *ctx, const char *branch, const uint8_t *tgt_sha,
+int gm_cache_query_fanin(gm_context_t *ctx, const char *branch, const gm_oid_t *tgt_oid,
                          gm_cache_result_t *result);
 
 /**

core/include/gitmind/cache/cache.h

@@ -1,8 +1,8 @@
 /* SPDX-License-Identifier: LicenseRef-MIND-UCAL-1.0 */
 /* © 2025 J. Kirby Ross / Neuroglyph Collective */
 
-#ifndef GM_CACHE_H
-#define GM_CACHE_H
+#ifndef GITMIND_CACHE_CACHE_H
+#define GITMIND_CACHE_CACHE_H
 
 #include <git2/types.h>
 
@@ -75,4 +75,4 @@ void gm_cache_result_free(gm_cache_result_t *result);
 int gm_cache_stats(git_repository *repo, const char *branch,
                    uint64_t *edge_count, uint64_t *cache_size_bytes);
 
-#endif /* GM_CACHE_H */
+#endif /* GITMIND_CACHE_CACHE_H */

core/include/gitmind/cbor/keys.h

@@ -0,0 +1,35 @@
+/* SPDX-License-Identifier: LicenseRef-MIND-UCAL-1.0 */
+/* © 2025 J. Kirby Ross / Neuroglyph Collective */
+
+#ifndef GITMIND_CBOR_KEYS_H
+#define GITMIND_CBOR_KEYS_H
+
+/* Common CBOR keys for edge encodings */
+
+/* Legacy/basic edge fields */
+#define GM_CBOR_KEY_SRC_SHA      0
+#define GM_CBOR_KEY_TGT_SHA      1
+#define GM_CBOR_KEY_REL_TYPE     2
+#define GM_CBOR_KEY_CONFIDENCE   3
+#define GM_CBOR_KEY_TIMESTAMP    4
+#define GM_CBOR_KEY_SRC_PATH     5
+#define GM_CBOR_KEY_TGT_PATH     6
+#define GM_CBOR_KEY_ULID         7
+
+/* OID-first additions (raw bytes of length GM_OID_RAWSZ) */
+#define GM_CBOR_KEY_SRC_OID      8
+#define GM_CBOR_KEY_TGT_OID      9
+
+/* Attributed extras */
+#define GM_CBOR_KEY_SOURCE_TYPE  10
+#define GM_CBOR_KEY_AUTHOR       11
+#define GM_CBOR_KEY_SESSION      12
+#define GM_CBOR_KEY_FLAGS        13
+#define GM_CBOR_KEY_LANE         14
+
+/* Field counts for writers */
+#define GM_CBOR_EDGE_FIELDS_TOTAL       10  /* legacy 8 + 2 OID fields */
+#define GM_CBOR_ATTR_EDGE_FIELDS_TOTAL  15  /* edge total + 5 attribution fields */
+
+#endif /* GITMIND_CBOR_KEYS_H */
+

core/include/gitmind/constants.h

@@ -32,7 +32,7 @@
 /* Cache system constants */
 #define BITS_PER_HEX_CHAR 4
 #define HEX_CHARS_PER_BYTE 2
-#define SHA_HEX_SIZE (GM_SHA1_SIZE * HEX_CHARS_PER_BYTE + 1)
+#define SHA_HEX_SIZE (GM_OID_RAWSZ * HEX_CHARS_PER_BYTE + 1)
 #define ZERO_SHA_STRING "0000000000000000000000000000000000000000"
 #define EDGE_MAP_BUCKETS 1024
 #define DIR_PERMS_NORMAL 0755

core/include/gitmind/edge.h

@@ -30,8 +30,10 @@ typedef struct gm_context gm_context_t;
  * Edge structure representing a directed relationship between two git objects
  */
 typedef struct gm_edge {
-    uint8_t src_sha[GM_SHA1_SIZE];      /**< Source object SHA-1 */
-    uint8_t tgt_sha[GM_SHA1_SIZE];      /**< Target object SHA-1 */
+    uint8_t src_sha[GM_SHA1_SIZE];      /**< Source object SHA-1 (legacy) */
+    uint8_t tgt_sha[GM_SHA1_SIZE];      /**< Target object SHA-1 (legacy) */
+    gm_oid_t src_oid;                   /**< Source object OID (preferred) */
+    gm_oid_t tgt_oid;                   /**< Target object OID (preferred) */
     uint16_t rel_type;                  /**< Relationship type */
     uint16_t confidence;                /**< Confidence (IEEE-754 half float) */
     uint64_t timestamp;                 /**< Creation time (Unix millis) */

core/include/gitmind/edge_attributed.h

@@ -38,8 +38,10 @@ typedef enum {
  */
 typedef struct gm_edge_attributed {
     /* Base edge fields */
-    uint8_t src_sha[GM_SHA1_SIZE];      /**< Source object SHA-1 */
-    uint8_t tgt_sha[GM_SHA1_SIZE];      /**< Target object SHA-1 */
+    uint8_t src_sha[GM_SHA1_SIZE];      /**< Source object SHA-1 (legacy) */
+    uint8_t tgt_sha[GM_SHA1_SIZE];      /**< Target object SHA-1 (legacy) */
+    gm_oid_t src_oid;                   /**< Source object OID (preferred) */
+    gm_oid_t tgt_oid;                   /**< Target object OID (preferred) */
     uint16_t rel_type;                  /**< Relationship type */
     uint16_t confidence;                /**< Confidence (IEEE-754 half float) */
     uint64_t timestamp;                 /**< Creation time (Unix millis) */
@@ -119,6 +121,40 @@ gm_result_void_t gm_edge_attributed_format(const gm_edge_attributed_t *edge,
 gm_result_void_t gm_edge_attributed_format_with_attribution(
     const gm_edge_attributed_t *edge, char *buffer, size_t len);
 
+/**
+ * Encode attributed edge to CBOR (OID-first; includes legacy fields for compat).
+ *
+ * @param edge   Edge to encode
+ * @param buffer Output buffer
+ * @param len    In: buffer size, Out: bytes written
+ * @return       Result indicating success or error
+ */
+gm_result_void_t gm_edge_attributed_encode_cbor(const gm_edge_attributed_t *edge,
+                                                uint8_t *buffer, size_t *len);
+
+/**
+ * Decode attributed edge from CBOR.
+ *
+ * @param buffer CBOR data
+ * @param len    Buffer length
+ * @return       Result with decoded edge on success
+ */
+gm_result_edge_attributed_t gm_edge_attributed_decode_cbor(const uint8_t *buffer,
+                                                           size_t len);
+
+/**
+ * Decode attributed edge from CBOR and return bytes consumed.
+ *
+ * @param buffer   CBOR data
+ * @param len      Buffer length
+ * @param edge_out Output edge
+ * @param consumed Bytes consumed
+ * @return         GM_OK on success or error code
+ */
+int gm_edge_attributed_decode_cbor_ex(const uint8_t *buffer, size_t len,
+                                      gm_edge_attributed_t *edge_out,
+                                      size_t *consumed);
+
 #ifdef __cplusplus
 }
 #endif

core/include/gitmind/hooks/augment.h

@@ -1,21 +1,33 @@
 /* SPDX-License-Identifier: LicenseRef-MIND-UCAL-1.0 */
 /* © 2025 J. Kirby Ross / Neuroglyph Collective */
 
-#ifndef GM_AUGMENT_H
-#define GM_AUGMENT_H
+#ifndef GITMIND_AUGMENT_H
+#define GITMIND_AUGMENT_H
 
-#include "gitmind.h"
+#include "gitmind/context.h"
+#include "gitmind/edge.h"
 
 #include <stdbool.h>
 #include <stddef.h>
 #include <stdint.h>
 #include <git2/types.h>
+#ifdef __cplusplus
+extern "C" {
+// keep C linkage open until end
+#endif
 
-/* Constants */
-#define MAX_CHANGED_FILES 50 /* Skip if more files changed */
-#define LOOKBACK_LIMIT 200   /* Max edges to scan */
-#define HOOK_TIMEOUT_MS 500  /* Abort if taking too long */
-#define MAX_PATH_LENGTH 4096 /* Maximum file path length */
+/* Constants (public, prefixed) */
+
+#define GM_AUGMENT_MAX_CHANGED_FILES 50 /* Skip if more files changed */
+#define GM_AUGMENT_LOOKBACK_LIMIT 200   /* Max edges to scan */
+#define GM_AUGMENT_HOOK_TIMEOUT_MS 500  /* Abort if taking too long */
+#define GM_AUGMENT_MAX_PATH_LENGTH 4096 /* Maximum file path length */
+
+/* Backward-compat (deprecated): old macro names */
+#define MAX_CHANGED_FILES GM_AUGMENT_MAX_CHANGED_FILES
+#define LOOKBACK_LIMIT GM_AUGMENT_LOOKBACK_LIMIT
+#define HOOK_TIMEOUT_MS GM_AUGMENT_HOOK_TIMEOUT_MS
+#define MAX_PATH_LENGTH GM_AUGMENT_MAX_PATH_LENGTH
 
 /* Get blob SHA for a file at a specific commit
  *
@@ -25,19 +37,19 @@
  * @param sha_out   Output buffer for 20-byte SHA-1
  * @return          0 on success, error code otherwise
  */
-int get_blob_sha(git_repository *repo, const char *commit_ref,
-                 const char *file_path, uint8_t *sha_out);
+int gm_hook_get_blob_sha(git_repository *repo, const char *commit_ref,
+                         const char *file_path, gm_oid_t *sha_out);
 
 /* Find recent edges with given source blob
  *
  * @param ctx       git-mind context
  * @param src_sha   Source blob SHA to search for
- * @param edges_out Output array of matching edges (caller must free)
+ * @param edges_out Output array of matching edges (caller must free with free())
  * @param count_out Number of edges found
  * @return          0 on success, error code otherwise
  */
-int find_edges_by_source(gm_context_t *ctx, const uint8_t *src_sha,
-                         gm_edge_t **edges_out, size_t *count_out);
+int gm_hook_find_edges_by_source(gm_context_t *ctx, const gm_oid_t *src_oid,
+                                 gm_edge_t **edges_out, size_t *count_out);
 
 /* Create AUGMENTS edge between two blob versions
  *
@@ -47,8 +59,8 @@ int find_edges_by_source(gm_context_t *ctx, const uint8_t *src_sha,
  * @param file_path Path to file (for human readability)
  * @return          0 on success, error code otherwise
  */
-int create_augments_edge(gm_context_t *ctx, const uint8_t *old_sha,
-                         const uint8_t *new_sha, const char *file_path);
+int gm_hook_create_augments_edge(gm_context_t *ctx, const gm_oid_t *old_oid,
+                                 const gm_oid_t *new_oid, const char *file_path);
 
 /* Process a single changed file
  *
@@ -57,15 +69,33 @@ int create_augments_edge(gm_context_t *ctx, const uint8_t *old_sha,
  * @param file_path Path to changed file
  * @return          0 on success, error code otherwise
  */
-int process_changed_file(gm_context_t *ctx, git_repository *repo,
-                         const char *file_path);
+int gm_hook_process_changed_file(gm_context_t *ctx, git_repository *repo,
+                                 const char *file_path);
 
 /* Check if this is a merge commit
  *
  * @param repo      Git repository
  * @param is_merge  Output: true if merge commit
  * @return          0 on success, error code otherwise
  */
-int is_merge_commit(git_repository *repo, bool *is_merge);
+int gm_hook_is_merge_commit(git_repository *repo, bool *is_merge);
+
+/* Backward-compatibility macros (deprecated) */
+#define get_blob_sha gm_hook_get_blob_sha
+#define find_edges_by_source gm_hook_find_edges_by_source
+#define create_augments_edge gm_hook_create_augments_edge
+#define process_changed_file gm_hook_process_changed_file
+#define is_merge_commit gm_hook_is_merge_commit
+
+/* Preferred names (aliases) */
+#define gm_augment_get_blob_sha gm_hook_get_blob_sha
+#define gm_augment_find_edges_by_source gm_hook_find_edges_by_source
+#define gm_augment_create_augments_edge gm_hook_create_augments_edge
+#define gm_augment_process_changed_file gm_hook_process_changed_file
+#define gm_augment_is_merge_commit gm_hook_is_merge_commit
+
+#ifdef __cplusplus
+}
+#endif
 
-#endif /* GM_AUGMENT_H */
+#endif /* GITMIND_AUGMENT_H */

core/include/gitmind/types.h

@@ -6,6 +6,7 @@
 
 #include <stddef.h>
 #include <stdint.h>
+#include <git2/oid.h>
 
 #ifdef __cplusplus
 extern "C" {
@@ -19,6 +20,10 @@ extern "C" {
 /* Size constants */
 #define GM_SHA1_SIZE 20
 #define GM_SHA256_SIZE 32
+#ifndef GIT_OID_RAWSZ
+#define GIT_OID_RAWSZ 20
+#endif
+#define GM_OID_RAWSZ GIT_OID_RAWSZ
 #define GM_PATH_MAX 256
 #define GM_ULID_SIZE 26
 #define GM_FORMAT_BUFFER_SIZE 512
@@ -37,6 +42,10 @@ typedef enum {
 } gm_rel_type_t;
 
 /* Include sub-types */
+/**
+ * OID type (SHA-agnostic). Use instead of raw byte arrays in new code.
+ */
+typedef git_oid gm_oid_t;
 
 #ifdef __cplusplus
 }