Add observe-only monitor milestone for issue #4

.claude/hooks/session-start.sh

@@ -2,23 +2,35 @@
 # SPDX-License-Identifier: MPL-2.0
 # SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
 #
-# SessionStart hook for Claude Code on the web. Best-effort and idempotent:
-# ensures the lint/compliance tools this repo's checks rely on are present so
-# a fresh session can run scripts/check-*.sh and `reuse lint` without manual
-# setup.
-#
-# Installs ONLY via standard package managers (pip / apt / gem) — there is
-# deliberately no piped remote script (no `curl ... | bash`). Never blocks a
-# session: each step is guarded by a `command -v` probe and trails `|| true`.
+# Read-only SessionStart preflight. Never installs tools, changes repo state,
+# or blocks the assistant from starting; missing requirements are reported.
 set -u
 
 note() { printf '[session-start] %s\n' "$*"; }
+have() { command -v "$1" >/dev/null 2>&1; }
 
-command -v reuse       >/dev/null 2>&1 || { note "installing reuse (pip)";       pip install --quiet reuse        >/dev/null 2>&1 || true; }
-command -v shellcheck  >/dev/null 2>&1 || { note "installing shellcheck (apt)";  apt-get install -y shellcheck    >/dev/null 2>&1 || true; }
-command -v asciidoctor >/dev/null 2>&1 || { note "installing asciidoctor (gem)"; gem install --silent asciidoctor >/dev/null 2>&1 || true; }
-
-have() { command -v "$1" >/dev/null 2>&1 && echo y || echo n; }
-note "tooling present: reuse=$(have reuse) shellcheck=$(have shellcheck) asciidoctor=$(have asciidoctor)"
-note "(the 'just' task runner is not auto-installed here; add it manually if you want recipe shortcuts)"
+note "llm-grace is development scaffolding; no monitor daemon or enforcement hooks are installed."
+for tool in git bash; do
+    if have "$tool"; then
+        note "available: $tool ($(command -v "$tool"))"
+    else
+        note "missing optional/preflight tool: $tool"
+    fi
+done
+if have zig; then
+    version="$(zig version 2>/dev/null || true)"
+    if [[ "$version" == 0.15.2 ]]; then
+        note "available: Zig $version"
+    else
+        note "Zig version mismatch: expected 0.15.2, found ${version:-unavailable}"
+    fi
+else
+    note "Zig 0.15.2 is required to run core tests; no installation attempted."
+fi
+if have just; then
+    note "available: $(just --version)"
+else
+    note "just is optional; scripts/run.sh provides the shell entrypoint."
+fi
+note "Read CLAUDE.md and docs/practice/AI-CONVENTIONS.adoc before editing."
 exit 0

.github/copilot-instructions.md

@@ -1,13 +1,15 @@
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
 <!-- Copyright (c) 2026 Jonathan Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk> -->
-<!-- Authoritative source: docs/AI-CONVENTIONS.md -->
+<!-- Authoritative source: docs/practice/AI-CONVENTIONS.adoc -->
 
 # Copilot Instructions
 
 ## Before Writing Code
 
-- Read `.machine_readable/STATE.a2ml` for canonical file locations.
-- State files (.a2ml) live in `.machine_readable/` ONLY, never the root.
+- Read `0-AI-MANIFEST.a2ml`, `.machine_readable/STATE.a2ml`, and `docs/practice/AI-CONVENTIONS.adoc` before making changes.
+- State and policy files (.a2ml) live in `.machine_readable/` ONLY, never the root.
+
+The authoritative conventions live in `docs/practice/AI-CONVENTIONS.adoc`.
 
 ## License
 

.gitignore

@@ -126,6 +126,7 @@ sync_report*.txt
 # Hypatia scan cache (local-only)
 .hypatia/
 .zig-cache/
+zig-out/
 target/
 node_modules/
 _build/

.machine_readable/root-allow.txt

@@ -34,6 +34,8 @@ Justfile                   # delegates phases to build/just/*.just
 coordination.k9            # repo-local session binding (template-mandated)
 
 # ─── Conventional dotfiles (tool-required at root) ───────────────────────────
+CLAUDE.md                   # Provider-specific pointer to the canonical AI conventions.
+GEMINI.md                   # Provider-specific pointer to CLAUDE.md; avoids rule duplication.
 .editorconfig
 .envrc
 .gitattributes
@@ -81,3 +83,4 @@ tools/                     # TODO: consolidate with scripts/ or document the spl
 
 # Local Zig test/build cache; ignored by Git, created by `just test`.
 .zig-cache/
+zig-out/                      # Explicitly generated monitor binary output; ignored by Git.

0-AI-MANIFEST.a2ml

@@ -41,5 +41,5 @@ status = "Local guardrail repairs; full RSR and release compliance not certified
 [core-implementation]
 issue = "https://github.com/hyperpolymath/llm-grace/issues/4"
 decision = "docs/decisions/0006-ledger-and-proof-boundaries.adoc"
-status = "Tested primitives; no live monitor, session autoconnection, or global deployment"
+status = "Observe-only monitor API and fixtures tested; no session autoconnection, resident daemon, hook integration, or global deployment"
 proofs = "Finite policy tests only; no new formal proofs claimed"

CLAUDE.md

@@ -0,0 +1,37 @@
+<!--
+SPDX-License-Identifier: MPL-2.0
+SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+-->
+
+# Claude Code instructions for llm-grace
+
+Read these repository sources before acting:
+
+1. `0-AI-MANIFEST.a2ml` and `.machine_readable/STATE.a2ml`.
+2. `docs/practice/AI-CONVENTIONS.adoc` and `.machine_readable/6a2/AGENTIC.a2ml`.
+3. For issue #4, ADR-0003, ADR-0004, ADR-0006, and
+   `docs/governance/COMPLIANCE-REVIEW.adoc`.
+
+## Safety and evidence
+
+- Issue #2 is owner-only. Do not edit existing SPDX/license declarations or
+  claim legal clearance.
+- The monitor is observe-only. Do not install global hooks, signal user
+  processes, create memory pressure, or connect this work to enforcement.
+- Treat fixture tests, a live one-epoch read, and production acceptance as
+  different evidence. Never call issue #4 closed or claim the repository is
+  security/quality issue-free without the remaining ADR-0006 criteria.
+- Do not silently skip a missing tool or turn an unsupported operation into a
+  green result. State which checks ran and which did not.
+
+## Local entrypoints
+
+- `scripts/run.sh help` is the stable shell entrypoint.
+- `scripts/dev.sh check` runs implemented local structural, syntax, and format
+  checks; `scripts/dev.sh test [Debug|ReleaseSafe]` runs core tests.
+- `just --list` shows the task interface. Just recipes must delegate to real
+  commands or fail explicitly; no placeholder success messages.
+
+This checkout has no runnable monitor daemon or installable application yet.
+Do not represent the developer entrypoint as a desktop/service launcher or
+install it into user/system locations.

GEMINI.md

@@ -0,0 +1,7 @@
+<!-- SPDX-License-Identifier: MPL-2.0 -->
+
+# Gemini entrypoint
+
+Read [`CLAUDE.md`](./CLAUDE.md) for the shared repository and task instructions;
+ignore any provider-specific tooling details that do not apply to Gemini. The
+canonical AI conventions are in `docs/practice/AI-CONVENTIONS.adoc`.