planning: roadmap DAG styling + SVG; issue sweep; ISSUES.md

.github/CODEOWNERS

@@ -0,0 +1,4 @@
+# Default code owner for the repo
+# CODEOWNERS only supports GitHub handles; email added as a note.
+* @flyingrobots  # james@flyingrobots.dev
+

.github/pull_request_template.md

@@ -1,25 +1,22 @@
-# Summary
+## Summary
 
-<!-- Briefly describe the change. Link the primary issue and milestone. -->
+Describe the change and why it’s needed. Include links to related issues.
 
-## Testing
+## Checklist
 
-- [ ] `cmake --build` (debug)
-- [ ] `cmake --build` (release)
-- [ ] `ctest`
-- [ ] `meson compile` (debug)
-- [ ] `meson compile` (release)
-- [ ] `meson test`
-- [ ] Additional checks (lint, docs, etc.):
+- [ ] Tests added/updated
+- [ ] Docs updated (README/docs/ISSUES/ROADMAP)
+- [ ] ACTIVITY.log.jsonl entry added (`make log`) and `make activity-validate` passes
+- [ ] Roadmap/DAG updated if dependencies changed (`make roadmap-validate`)
+- [ ] Containerized targets used (no host builds), per AGENTS.md
 
-## Deployment / Release Impact
+## Acceptance Criteria
 
-- [ ] No migration needed
-- [ ] Docs updated
-- [ ] Follow-up issues filed
+- [ ] Builds green in CI matrix
+- [ ] Lint/format passes (`make format-check`)
+- [ ] Analyzer (optional) passes (`make analyze`)
 
-## Reviewer Checklist
+## Screenshots/Artifacts (if applicable)
+
+## Notes
 
-- [ ] Includes issue link (e.g., `Closes #123`)
-- [ ] Tests cover new/changed behavior
-- [ ] Dual-build CI expectations satisfied

.github/workflows/ci.yml

@@ -39,6 +39,9 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          # The main CI build/tests do not require submodules; make this explicit.
+          submodules: false
 
       - name: Install dependencies
         run: |
@@ -101,6 +104,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          submodules: false
 
       - name: Install dependencies
         run: |
@@ -115,6 +120,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          submodules: false
 
       - name: Install dependencies
         run: |

.github/workflows/compliance.yml

@@ -0,0 +1,29 @@
+name: Compliance (artifact)
+
+on:
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  compliance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+      - name: Build (meson)
+        run: |
+          sudo apt-get update && sudo apt-get install -y ninja-build meson
+          meson setup meson-debug --buildtype debugoptimized
+          meson compile -C meson-debug
+      - name: Emit placeholder compliance report
+        run: |
+          cat > compliance.json <<'JSON'
+          {"implementation":"libgitledger","version":"0.0.0","date":"1970-01-01T00:00:00Z","results":[],"summary":{"core":"PARTIAL","policy":"N/A","wasm":"N/A"}}
+          JSON
+      - uses: actions/upload-artifact@v4
+        with:
+          name: compliance.json
+          path: compliance.json

.gitignore

@@ -67,3 +67,6 @@ compile_commands.json
 
 # Project-specific
 .obsidian/
+website/.docusaurus/
+website/node_modules/
+FEEDBACK.md

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "external/ledger-kernel"]
+	path = external/ledger-kernel
+	url = https://github.com/flyingrobots/ledger-kernel

CONTRIBUTING.md

@@ -14,6 +14,14 @@ Thanks for helping build `libgitledger`! This document complements the roadmap a
 - Maintain both build systems. Preferred: run the containerised make targets (`make cmake`, `make meson`, `make test-both`) so you exercise the same matrix CI runs. These jobs copy the repo into isolated workspaces, prepare sandbox Git fixtures, and remove all remotes before mutating anything.
 - If you must run directly on the host checkout, export `I_KNOW_WHAT_I_AM_DOING=1` before invoking host targets. The makefile will otherwise abort unless it detects the container guard. Manual command sequences for CMake/Meson live in the README if you need to craft bespoke invocations.
 - Align tooling: warning flags, optional dependencies, and targets must stay consistent across CMake and Meson.
+- Submodules: initialise them before building tools that read the external spec.
+
+  ```bash
+  git submodule update --init --recursive
+  # or
+  make bootstrap
+  ```
+
 - Install prerequisites (at minimum `libgit2` and `pkg-config`) before running host builds. Examples: `sudo apt-get install libgit2-dev pkg-config` or `brew install libgit2 pkg-config`.
 - When adding dependencies, update both build descriptions and mention the change in the relevant issue.
 - Run `make lint` (containerised clang-format + clang-tidy) before submitting a PR. CI enforces the same suite on GCC, Clang, and MSVC.

Makefile

@@ -1,7 +1,8 @@
 .PHONY: all test cmake meson both test-cmake test-meson test-both clean format format-check tidy lint tidy-build \
         host-cmake host-meson host-both host-test-cmake host-test-meson host-test-both \
         host-format-check host-tidy host-lint sanitizers host-sanitizers analyze host-analyze \
-	activity-validate log hooks-install hooks-uninstall trophy symbols-check
+	activity-validate log hooks-install hooks-uninstall trophy symbols-check \
+	roadmap-render roadmap-sweep roadmap-validate roadmap-refresh
 
 all: both
 
@@ -197,3 +198,38 @@ hooks-install:
 hooks-uninstall:
 	@git config --unset core.hooksPath || true
 	@echo "hooks: unset core.hooksPath"
+
+# Initialize submodules for fresh clones
+bootstrap:
+	@git submodule update --init --recursive
+# Roadmap helpers
+PYTHON ?= python3
+
+.PHONY: roadmap-render roadmap-sweep roadmap-validate roadmap-refresh
+
+roadmap-render:
+	@if ! command -v docker >/dev/null 2>&1; then \
+		echo "docker is required for roadmap-render" >&2; exit 1; \
+	fi
+	@docker run --rm -v "$(PWD)/docs:/data" minlag/mermaid-cli -i /data/ROADMAP-DAG.mmd -o /data/ROADMAP-DAG.svg
+
+roadmap-sweep:
+	@if ! command -v $(PYTHON) >/dev/null 2>&1; then \
+		echo "$(PYTHON) not found; cannot run roadmap-sweep" >&2; exit 1; \
+	fi
+	@if [ ! -f tools/roadmap/sweep_issues.py ]; then \
+		echo "tools/roadmap/sweep_issues.py not found" >&2; exit 1; \
+	fi
+	@$(PYTHON) tools/roadmap/sweep_issues.py
+
+roadmap-validate:
+	@if ! command -v $(PYTHON) >/dev/null 2>&1; then \
+		echo "$(PYTHON) not found; cannot run roadmap-validate" >&2; exit 1; \
+	fi
+	@if [ ! -f tools/roadmap/validate_dag.py ]; then \
+		echo "tools/roadmap/validate_dag.py not found" >&2; exit 1; \
+	fi
+	@$(PYTHON) tools/roadmap/validate_dag.py
+
+roadmap-refresh:
+	@$(MAKE) roadmap-validate && $(MAKE) roadmap-render

README.md

@@ -18,6 +18,21 @@ Early scaffolding for a Git-native ledger library built on top of `libgit2`.
 - Issue drafts can be copied from `docs/ISSUE-DRAFTS.md`; regenerate with `python3 tools/automation/generate_issue_drafts.py` after editing the breakdown.
 - Pull requests must follow `.github/pull_request_template.md` and exercise both build systems (CMake + Meson).
 - See `CONTRIBUTING.md` for detailed workflow expectations.
+- Submodules: this repo uses Git submodules (e.g., `external/ledger-kernel`). Clone with submodules or
+  initialise them after cloning:
+
+  ```bash
+  git clone --recursive https://github.com/flyingrobots/libgitledger.git
+  # or, for an existing checkout
+  git submodule update --init --recursive
+  ```
+  Skipping `--recursive` leaves `external/ledger-kernel/` empty and may break tools that read the spec.
+
+- Quick bootstrap after cloning:
+
+  ```bash
+  make bootstrap  # runs: git submodule update --init --recursive
+  ```
 - Quickstart for contributors:
   - Install repo hooks once: `make hooks-install` (pre-commit runs `make format-check` in containers like CI).
   - Temporarily bypass the format gate for a commit: `SKIP_FORMAT_CHECK=1 git commit -m "..."`.

docs/DRIFT_REPORT.md

@@ -0,0 +1,58 @@
+# Drift Report: libgitledger vs. Ledger‑Kernel Spec
+
+Date: 2025-11-03T22:48:13Z
+
+This report compares our current roadmap (issues + DAG) to the Ledger‑Kernel specification in `external/ledger-kernel`.
+
+## Inputs
+
+- Spec repository (submodule): `external/ledger-kernel`
+  - Schemas: `schemas/`
+  - Compliance: `docs/spec/compliance.md` (C‑1…C‑5 ↔ FS/M)
+  - Formal spec: `docs/spec/*.md` (FS‑1…FS‑14, M‑1…M‑9)
+- Roadmap DAG: `docs/ROADMAP-DAG.mmd` (grouped by milestones)
+
+## Mapping Summary
+
+- FS‑10 (Canonical wire format + ID): PARTIAL
+  - Roadmap: No explicit issue yet; closest: [M4] libgit2 adapter (I/O), [M3] API docs.
+  - Gap: Add issue “Wire format canonicalization + BLAKE3 id (FS‑10)” under M3/M4.
+
+- FS‑7/FS‑8 (Append-only + ref fast‑forward): PARTIAL
+  - Roadmap: Append path (#13), Append enforcement (#19), Policy enforcement tests (#20).
+  - Gap: Add explicit non‑FF ref rejection test issue.
+
+- FS‑11 (Temporal ordering): PARTIAL
+  - Roadmap: Ledger lifecycle (#12) + Append/read integration tests (#15).
+  - Gap: Add validation test “reject child timestamp < parent”.
+
+- FS‑3/FS‑9 (Deterministic policy evaluation): N/A (engine not yet present)
+  - Roadmap: Policy parser (#17), Policy storage (#16).
+  - Gap: Add “Deterministic policy eval harness” issue and seed vectors.
+
+- FS‑6 (Offline verify end‑to‑end): PARTIAL
+  - Roadmap: End‑to‑end tests (#39).
+  - Gap: Add small offline replay vector + verifier entrypoint.
+
+## Risks / Assumptions
+
+- BLAKE3 dependency: We will vendor or link a minimal BLAKE3 for FS‑10.
+- WASM policy runtime: Not required for core, mark as N/A until available.
+
+## Recommendations
+
+1. Create the following issues and link under milestones:
+   - [M3] FS‑10 Canonicalization + BLAKE3 id (core)
+   - [M2] Non‑FF ref rejection tests (FS‑7/FS‑8)
+   - [M2] Timestamp monotonicity validation (FS‑11)
+   - [M4] Deterministic policy evaluation harness (FS‑3/FS‑9)
+   - [M3] Offline verify minimal replay (FS‑6)
+2. Add a compliance harness skeleton (report writer + CLI flag) and wire C‑1…C‑3 quickly; mark others N/A.
+3. Add CI workflow `compliance.yml` in soft mode (artifact only); enable gating on core once C‑1…C‑3 are green.
+
+## Next Steps (Implementation Plan)
+
+- Include headers + source stubs under `include/ledger/` and `src/compliance/`.
+- Add CLI flag `--compliance` (or a small utility) without impacting library ABI.
+- Seed vectors in `tests/vectors/core/`.
+