Add hex ports, cache coordinators, and journal adapter robustness

.gitignore

@@ -75,6 +75,15 @@ Review.md
 # Test directories and generated content
 chaos-backup/
 # Test environments are now created in Docker containers
+# GitMind unit tests create temporary Git repositories in the repo root
+.gm_cache_query_tmp/
+.gm_cache_branch_tmp/
+.gm_cache_tree_tmp/
+.gm_cache_meta_tmp/
+.gm_build_tree_repo/
+.gm_build_tree_src/
+.gm_journal_tmp/
+.gm_journal_e2e_repo/
 
 # Build outputs
 dist/

AGENTS.md

@@ -126,6 +126,7 @@ recent_developments:
 
 - 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`.
+- **NEVER** use `NOLINT` or other mechanisms to suppress clang-tidy warnings. All warnings must be fixed.
 - 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++.
@@ -138,9 +139,14 @@ recent_developments:
 
 ## Commit & Pull Request Guidelines
 
-- Conventional commits: `type(scope): description` (e.g., `fix(core/cbor): handle null keys`). Reference issues (`Fixes #123`).
+- Conventional commits: `type(scope): description` (e.g., `fix(core/cbor): handle null keys`).
+- Every PR should reference a corresponding GitHub issue. Commits closing an issue should use the `Fixes #<number>` syntax.
+- For any non-trivial task, briefly outline your plan of attack in the PR description or an associated issue. This includes the files you expect to change and the verification steps you will take.
 - 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.
+- **NEVER** use `git add -A` or `git commit -a`. Always stage changes intentionally and individually (`git add <path>`) to ensure only desired changes are included.
+- **NEVER** alter, disable, or otherwise circumvent git hooks or tests. They are critical for maintaining code quality and repository integrity.
+- After a PR is approved and all checks pass, ask the user if they want you to push the changes and open a pull request.
+- 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
 
@@ -388,6 +394,10 @@ Every outbound port ships with: (a) production adapter, (b) deterministic fake u
 - Guardrails always on: run `make ci-local` (Docker) for every commit; touched files must be clang-tidy clean.
 - Document progress: update `AGENTS.md` and `docs/activity/` as ports or adapters graduate from TODO to done.
 
+#### Integration of Legacy Concerns
+- **Security Primitives:** All new security features must be designed and implemented as ports and adapters within the hexagonal architecture.
+- **Memory Safety:** All module migrations must address memory safety concerns, including bounds checking and null checks.
+
 ### One-Thing Rule (Touched code policy)
 
 - You touch it? You refactor it. If you modify a type or function that clearly bundles multiple concerns in a single file, split out the thing you touched into its own file (1 file = 1 thing):
@@ -415,6 +425,35 @@ Every outbound port ships with: (a) production adapter, (b) deterministic fake u
 
 See archives under `docs/activity/` for older logs.
 
+### 2025-10-08
+- Telemetry & logging
+  - Added internal telemetry config shim (`core/include/gitmind/telemetry/internal/config.h`, `core/src/telemetry/config.c`).
+  - Implemented repo tag hashing flag `GITMIND_METRICS_REPO_HASH_ALGO=sha256|fnv` (default `fnv`); tests cover `sha256` path.
+  - Introduced log formatter DI seam: `gm_log_formatter_fn` in `gm_context_t` (internal) with default renderer (`core/src/telemetry/log_format.c`); services format KV → render (JSON/text) → emit via `gm_logger_port`.
+- Cache
+  - Refactored cache rebuild service to use the formatter DI seam; emits `rebuild_start`/`rebuild_ok`/`rebuild_failed` logs and metrics (`cache.rebuild.duration_ms`, `cache.edges_processed_total`, `cache.tree_size_bytes`).
+  - Added end‑to‑end test using fakes for logger/metrics and a stub repo; metrics exercised by default.
+- Journal
+  - Scaffolded inbound port `gm_cmd_journal_port` (append/append_attributed) with thin coordinator.
+  - Instrumented journal append/read with logs + metrics via the formatter DI seam; unified tags (branch/mode/repo/extras). Removed legacy env branch override from writer; use repo HEAD via port.
+  - Added formatter unit test and a small journal port test using fake repo head.
+- Adapter contract tests
+  - Added libgit2 adapter test for `build_tree_from_directory` (verifies tree ODB object).
+- Docs
+  - Updated `docs/operations/Telemetry_Config.md` with repo hash flag, Quickstart, custom logger adapter guide, and note on advanced formatter DI seam.
+  - Pruned stale CLI links in docs index to keep docs checks green.
+- CI/Status
+  - `make ci-local` (Docker) green across the session; tidy diff‑guard ran. Branch: `feat/hex-ports-ci-green`. Merge‑only; no force pushes.
+- Next actions (paused for feedback)
+  - Journal: consider adding edge‑count metric on read (requires callback plumbing), and enable richer unit tests around the inbound port.
+  - Optional: regenerate concise CLI docs; consider flipping repo hash default to `sha256` after review.
+
+```jsonl
+{"ts":"2025-10-08T23:59:00Z","kind":"note","topic":"logging","msg":"Formatter DI seam added; cache/journal emitting structured logs; adapters remain the extension point."}
+{"ts":"2025-10-08T23:59:00Z","kind":"note","topic":"telemetry","msg":"Repo tag hashing supports sha256|fnv; tests and docs updated."}
+{"ts":"2025-10-08T23:59:00Z","kind":"note","topic":"journal","msg":"Inbound port scaffolded; append/read instrumented; writer env override removed; CI green."}
+```
+
 ### 2025-09-29
 - Merged PR #173 after tightening the remaining safe-string usage and OID helper semantics; rebased on `origin/main` and created `feat/next-hex-task` for the follow-up work.
 - Problems solved today: delivered GM.MVP.T001 (strict equality regressions + OID-first doc sweep), captured a fresh clang-tidy snapshot, and drafted the "State of the Repo" discussion.
@@ -538,3 +577,9 @@ References
 - Code review seeding script: `tools/review/seed_feedback_from_github.py` (uses `GITHUB_TOKEN`).
 - CodeRabbit config: `.coderabbit.yml` (summary-first, caps, doc filters).
 - PR template: `.github/pull_request_template.md` (guidance for reviewers).
+
+
+---
+
+{"date":"2025-10-07","time":"15:30","summary":"Conducted a comprehensive repository analysis and cleanup, reconciled legacy documentation into a single source of truth (`AGENTS.md`), and formulated a detailed, actionable plan for the hexagonal architecture migration.","topics":[{"topic":"`CLAUDE.md` vs `AGENTS.md` Reconciliation","what":"Compared the two files to identify outdated information.","why":"To consolidate agent instructions into a single source of truth.","context":"`CLAUDE.md` was the old, conversational guide, while `AGENTS.md` is the new, technical guide.","issue":"Discrepancies and outdated information in `CLAUDE.md`.","resolution":"Created `FACTS.md` to compare the files, then updated `AGENTS.md` with the relevant information from `CLAUDE.md`.","future_work":"None.","time_percent":25},{"topic":"`TASKLIST.md` Analysis","what":"Analyzed `TASKLIST.md` to determine the relevance of its tasks.","why":"To understand the project's historical context and current priorities.","context":"`TASKLIST.md` was a historical document from mid-2022.","issue":"The file was largely outdated and did not reflect the current focus on the hexagonal architecture.","resolution":"Appended an analysis to `TASKLIST.md`, then deleted the file and integrated the relevant parts into `AGENTS.md`.","future_work":"None.","time_percent":25},{"topic":"Repository Cleanup","what":"Identified and deleted obsolete files and directories.","why":"To improve the repository's hygiene.","context":"The repository contained several build artifacts and legacy files.","issue":"The presence of unnecessary files cluttered the repository.","resolution":"Created `file-matrix.md` to analyze the file hierarchy, then deleted the unnecessary files and updated `.gitignore`.","future_work":"None.","time_percent":25},{"topic":"Hexagonal Architecture Migration Planning","what":"Created a detailed prompt for completing the hexagonal architecture migration.","why":"To provide a clear and actionable plan for the next phase of development.","context":"The hexagonal architecture is the top priority for the project.","issue":"The need for a detailed, step-by-step plan to guide the migration.","resolution":"Created a comprehensive prompt that includes progress tracking, testing, and documentation requirements.","future_work":"Execute the prompt to complete the migration.","time_percent":25}],"key_decisions":["`AGENTS.md` is the single source of truth for agent instructions.","`TASKLIST.md` is obsolete and has been deleted.","The hexagonal architecture migration is the top priority."],"action_items":[{"task":"Execute the hexagonal architecture migration prompt.","owner":"AI agent"}]}
+{"date":"2025-10-07","time":"16:08","summary":"Conducted a comprehensive documentation cleanup, consolidating and archiving outdated files to improve clarity and maintainability.","topics":[{"topic":"Documentation Cleanup","what":"Analyzed the docs/ directory, identified redundant and outdated files, and consolidated them into a more coherent structure.","why":"The documentation was disorganized and contained conflicting information, making it difficult for newcomers to understand the project.","context":"The docs/ directory had a large number of historical and overlapping documents.","issue":"The documentation was a mess.","resolution":"Created a cleanup plan, archived obsolete files, and consolidated related documents into single, comprehensive guides.","future_work":"Continue the cleanup by reviewing and updating the remaining core documents and implementing the new directory structure.","time_percent":100}],"key_decisions":["Consolidated attribution, cache, and CLI documentation into single, authoritative files.","Archived a significant number of outdated and redundant documents.","Adopted a Map of Content (MoC) approach for the documentation."],"action_items":[{"task":"Continue the documentation cleanup by reviewing and updating the remaining core documents.","owner":"AI agent"}]}

README.md

@@ -95,20 +95,38 @@ Install/build instructions: see `docs/install.md`.
 > - `meson setup build -Dforce_local_builds=true` — explicit Meson override
 > - `GITMIND_ALLOW_HOST_BUILD=1` — legacy env override (discouraged)
 
-CLI examples (subset implemented today):
+### CLI Quickstart (implemented today)
+
+Human output (stdout) + text logs (stderr):
 
 ```bash
-# Start linking
-git mind link README.md core/src/main.c --type documents
-git mind link core/src/auth.c tests/auth.test.c --type "tested-by"
+git mind link README.md core/src/main.c --type references
+git mind list
+git mind cache-rebuild
+```
 
-# Explore connections
-git mind list --from core/src/auth.c
+Porcelain output (stdout) + JSON logs (stderr):
 
-# Rebuild cache when needed
-git mind cache-rebuild
+```bash
+git mind --json --porcelain list 2>logs.json | tee list.txt
+
+# list.txt (stdout)
+# type=IMPLEMENTS src=src/a.c tgt=include/a.h
+# ...
+
+# logs.json (stderr, one JSON per line)
+# {"event":"journal_read_start","branch":"main","mode":"read"}
+```
+
+Diagnostics breadcrumbs for debugging:
+
+```bash
+export GITMIND_DEBUG_EVENTS=1
+git mind cache-rebuild 2>diag.txt
 ```
 
+More: see apps/cli/README.md.
+
 > [!NOTE]
 > Branch shorthands that touch git-mind (for example when you pass `--branch` to the CLI) are validated. Empty names, leading/trailing slashes, `refs/...` prefixes, `..`, `@{`, or characters such as `~ ^ : ? [ * \\` will be rejected with `GM_ERR_INVALID_ARGUMENT`. Trim to `feature/x` style if you hit the guardrail—the command leaves refs untouched on failure.
 
@@ -183,6 +201,12 @@ $ git mind list --from core/src/cache.c --format json
 - `docs/tutorial.md` — Hands‑on walkthrough
 - `docs/philosophy.md` — Why we built this
 - `docs/TECHNICAL.md` — How it works under the hood
+- `docs/operations/Observability.md` — Logs, metrics, diagnostics overview
+- `docs/operations/Telemetry_Config.md` — Telemetry knobs (env), JSON logs
+- `docs/operations/Diagnostics_Events.md` — Dev/test diagnostics events
+- `apps/cli/README.md` — CLI quickstart (flags, output channels, recipes)
+- `apps/cli/Scripting_Patterns.md` — Porcelain parsing and JSON log pipelines
+- `docs/architecture/hexagonal/Journal.md` — Journal hex split (domain vs app)
 - `CONTRIBUTING.md` — PRs welcome!
 
 ---

apps/cli/README.md

@@ -0,0 +1,58 @@
+---
+title: CLI Quickstart
+description: Flags, output channels, and common recipes for using the git-mind CLI.
+audience: [developers]
+domain: [operations]
+tags: [cli, logging, porcelain]
+status: draft
+last_updated: 2025-10-08
+---
+
+# CLI Quickstart
+
+## Flags
+
+- `--verbose` — increase CLI stderr logger to DEBUG.
+- `--porcelain` — print stable key=value lines to stdout (friendly to scripts).
+- `--json` — format service logs as compact JSON strings (to stderr).
+
+## Output Channels
+
+- Stdout — command results (human or porcelain). Use this in scripts.
+- Stderr — logs produced by services (text or JSON). Use for diagnostics.
+
+## Recipes
+
+Human output (stdout) + text logs (stderr):
+
+```
+git-mind link src.c tgt.c --type references
+```
+
+Porcelain output (stdout) + JSON logs (stderr):
+
+```
+git-mind --json --porcelain list 2>logs.json | tee list.txt
+```
+
+Debugging with diagnostics events:
+
+```
+export GITMIND_DEBUG_EVENTS=1
+git-mind cache-rebuild 2>diag.txt
+```
+
+Piping JSON logs to jq:
+
+```
+git-mind --json cache-rebuild 2> >(jq -c .)
+```
+
+## Safety
+
+The CLI prevents running in the git-mind development repository by default. To override for CI/E2E:
+
+```
+export GITMIND_SAFETY=off
+```
+