docs: de-template RSR metadata, complete 6a2 + contractiles, add PROOF-NEEDS

.github/workflows/casket-pages.yml

@@ -18,6 +18,7 @@ concurrency:
 jobs:
   build:
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     steps:
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4
@@ -36,6 +37,7 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     needs: build
+    timeout-minutes: 10
     steps:
       - name: Deploy to GitHub Pages
         id: deployment

.github/workflows/mirror.yml

@@ -0,0 +1,15 @@
+# SPDX-License-Identifier: MPL-2.0
+name: Mirror to Git Forges
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  mirror:
+    uses: hyperpolymath/standards/.github/workflows/mirror-reusable.yml@e6b2884722350515934d443daf23442f2195796f
+    secrets: inherit

.github/workflows/scorecard.yml

@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: MPL-2.0
+name: Scorecards supply-chain security
+
+on:
+  branch_protection_rule:
+  schedule:
+    - cron: '23 4 * * 1'
+  push:
+    branches: [main]
+
+# Workflow-level permissions are read-only. The job that calls the reusable
+# upgrades to the writes `ossf/scorecard-action` requires. Job-level
+# permissions REPLACE workflow-level for that job, so `contents: read` here
+# plus the writes below yields the correct effective set and avoids the
+# `read-all` startup_failure seen estate-wide. Matches the canonical caller in
+# hyperpolymath/standards/.github/workflows/scorecard-reusable.yml.
+permissions:
+  contents: read
+
+jobs:
+  analysis:
+    permissions:
+      security-events: write
+      id-token: write
+    uses: hyperpolymath/standards/.github/workflows/scorecard-reusable.yml@e03686486e11b662834d7090dffae54c3e96fd59
+    secrets: inherit

.github/workflows/secret-scanner.yml

@@ -0,0 +1,19 @@
+# SPDX-License-Identifier: MPL-2.0
+name: Secret Scanner
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  scan:
+    uses: hyperpolymath/standards/.github/workflows/secret-scanner-reusable.yml@3e4bd4c93911750727e2e4c66dff859e00079da0
+    secrets: inherit

.machine_readable/6a2/AGENTIC.a2ml

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# AGENTIC.a2ml — AI agent interaction patterns for git-reticulator.
+
+[metadata]
+version = "0.2.0"
+last-updated = "2026-06-03"
+
+[agent-permissions]
+can-edit-source = true
+can-edit-tests = true
+can-edit-docs = true
+can-edit-config = true
+can-create-files = true
+
+[agent-constraints]
+rules = [
+  "HONESTY FIRST: never document a SKELETON/println stub as a working feature. Use the NEUROSYM status legend (IMPLEMENTED|SKELETON|ASPIRATIONAL).",
+  "Do not assert 'lattice' algebra (meet/join) anywhere unless PROOF-NEEDS.md P1 is discharged — otherwise say 'typed graph/DAG'.",
+  "Never reintroduce template placeholders ({{...}}, [YOUR-REPO-NAME]).",
+  "Never commit secrets; SPDX header on every file; MPL-2.0 only.",
+  "State files live in .machine_readable/6a2/ ONLY (not repo root, not .machine_readable/ root).",
+  "Banned languages per estate policy (TypeScript, Python (non-Salt), Go, Node/npm/Bun).",
+]
+
+# ════════════════════════════════════════════════════════════════════════════
+# THE AGENT-FACING ROLE OF THIS REPO
+# ════════════════════════════════════════════════════════════════════════════
+# git-reticulator exists largely TO SERVE AI agents: it is a RAG context
+# provider. Agents are both maintainers of, and consumers of, this repo.
+
+[agent-as-consumer]
+primary-call = "zoom_to_node(node, level) -> token-bounded sub-lattice for the prompt"
+token-discipline = "request the SMALLEST level that answers the question; widen only on miss"
+trust-model = "when layers 3-4 are present, prefer context that carries FRESHNESS/PROVENANCE proofs; drop context that fails them rather than showing it"
+
+[maintenance-integrity]
+fail-closed = true
+require-evidence-per-step = true
+allow-silent-skip = false
+require-rerun-after-fix = true
+release-claim-requires-hard-pass = true
+
+[automation-hooks]
+on-enter = "Read 0-AI-MANIFEST.a2ml, then .machine_readable/6a2/STATE.a2ml, then PROOF-NEEDS.md"
+on-exit = "Update 6a2/STATE.a2ml [honest-status] + [critical-next-actions] with session outcomes"
+on-commit = "just must-check && just trust-verify"

.machine_readable/6a2/ECOSYSTEM.a2ml

@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# ECOSYSTEM.a2ml — git-reticulator's position and relationships.
+
+[metadata]
+version = "0.2.0"
+last-updated = "2026-06-03"
+
+[project]
+name = "git-reticulator"
+purpose = "Symbolic-lattice + embedding extractor for git repos; layer 1 of the neuro-symbolic retrieval stack."
+role = "library + cli (structure extractor / RAG context provider)"
+
+[position-in-ecosystem]
+tier = "2"               # 1 = foundational language/proof; 2 = tooling/application; infrastructure = scaffolding
+neuro-symbolic-layer = 1
+
+# relationship types: dependency, dependent, sibling, substrate, proof-layer,
+#                     potential-consumer, inspiration
+[[related-projects.project]]
+name = "affinescript"
+relationship = "core-language + sibling"
+contract = "intended implementation language of the lattice core (src/lattice/affine/*.affine); compiles to Wasm. NOTE: not yet a working compiler, and the current .affine calls Rust crates it cannot bind."
+
+[[related-projects.project]]
+name = "verisimdb"
+relationship = "substrate (downstream)"
+contract = "the octad (8 modalities) is a superset of reticulator's needs: Graph<-lattice, Vector<-embeddings, Document<-source, Temporal<-history, Provenance<-authorship, Semantic<-type tags. reticulator is, in effect, a specialised ingester producing verisim octads."
+
+[[related-projects.project]]
+name = "vcl-ut"
+relationship = "proof-layer (downstream)"
+contract = "typed, proof-carrying query language over verisim. Turns reticulator retrieval into PROPOSITIONS carrying PROVENANCE/FRESHNESS/EXISTENCE certificates — the basis of proof-carrying retrieval (NEUROSYM stack layer 4)."
+
+[[related-projects.project]]
+name = "k9"
+relationship = "dependency (metadata tooling)"
+contract = "k9iser.toml is consumed here; K9 contracts machine-check MUST constraints."
+
+[[related-projects.project]]
+name = "hypatia / panic-attack"
+relationship = "potential-consumer"
+contract = "security/quality scanners; PB-4 feeds them a reachable-set (blast radius) from the lattice. Hypatia also scans this repo (hypatia-scan.yml)."
+
+[[related-projects.project]]
+name = "standards"
+relationship = "sibling-standard"
+contract = "estate standards, CRG grading, changelog-reusable.yml, contractile/RSR conventions."
+
+[[related-projects.project]]
+name = "LLM / RAG agents"
+relationship = "primary-consumer"
+contract = "consume zoom_to_node sub-lattices as token-bounded, (eventually) proof-carrying context."
+
+[integration-points]
+# system, direction, protocol
+points = [
+  { system = "verisimdb-data", direction = "outbound", protocol = "git-backed flat-file / repository_dispatch (PB-5)" },
+  { system = "postgres+pgRouting", direction = "outbound", protocol = "SQL (ASPIRATIONAL, feature-gated)" },
+  { system = "REST consumers", direction = "inbound", protocol = "actix-web /build /zoom /health (stub responses today)" },
+]

.machine_readable/6a2/META.a2ml

@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# META.a2ml — Architecture decisions and design rationale for git-reticulator.
+
+[metadata]
+version = "0.2.0"
+last-updated = "2026-06-03"
+
+[project-info]
+type = "library + cli"        # library (git_reticulator) + binary (reticulate)
+languages = ["rust", "affinescript"]
+license = "MPL-2.0"
+author = "Jonathan D.A. Jewell (hyperpolymath)"
+
+[development-practices]
+build-tool = "just"
+container-runtime = "podman"
+ci-platform = "github-actions"
+package-manager = "cargo"     # guix.scm / flake.nix also present for reproducible shells
+
+# ════════════════════════════════════════════════════════════════════════════
+# ARCHITECTURE DECISIONS (ADRs) — status: proposed | accepted | superseded | rejected
+# ════════════════════════════════════════════════════════════════════════════
+
+[[adr]]
+id = "ADR-001"
+title = "Rust host, AffineScript core"
+status = "accepted-but-under-review"
+date = "2026-04"
+decision = "CLI/REST/IO in Rust; lattice algorithms in AffineScript (.affine) for affine-typed safe traversal."
+consequence = "Today the core cannot compile (no AffineScript compiler) and is written against Rust crates AffineScript cannot bind. STATE.honest-status flags this; ADR may be superseded by a Rust-native core."
+
+[[adr]]
+id = "ADR-002"
+title = "Level-of-Detail (LOD) lattice over four semantic levels"
+status = "accepted"
+date = "2026-04"
+decision = "Nodes carry a SemanticLevel (Module>File>Definition>Block) and a parent_id, so zoom_to_node can return a token-bounded sub-lattice."
+rationale = "The product is a RETRIEVAL GEOMETRY for LLMs — minimal relevant context, not a full dump. This is the feature that justifies the project over `git log`."
+
+[[adr]]
+id = "ADR-003"
+title = "Per-node embedding (neuro-symbolic fusion at the data model)"
+status = "accepted"
+date = "2026-04"
+decision = "Keyword carries an optional embedding vector alongside its order position."
+rationale = "One identity = one lattice element + one vector. This is the seam where symbolic and neural meet (see NEUROSYM.a2ml)."
+
+[[adr]]
+id = "ADR-004"
+title = "PostgreSQL + pgRouting for persistence and pathfinding"
+status = "accepted"
+date = "2026-04"
+decision = "Store nodes/edges in Postgres; use pgRouting (Dijkstra/A*) for reachability and blast-radius queries."
+rationale = "Weighted reachability is a first-class query (refactoring impact, security blast-radius — PLAYBOOK PB-4). pgRouting gives it for free."
+caveat = "feature-gated off; not yet wired."
+
+[[adr]]
+id = "ADR-005"
+title = "'Lattice' must be earned, not asserted"
+status = "accepted"
+date = "2026-06-03"
+decision = "The structure is currently a typed weighted DAG/digraph (TOPOLOGY even notes cycle detection). To call it a lattice we must (a) SCC-condense to a DAG, (b) define a partial order, (c) prove meet/join exist + the lattice laws."
+rationale = "Honesty + the formal-methods estate norm (cf. vcl-ut). Tracked in PROOF-NEEDS.md."
+
+[design-rationale]
+why-this-exists = "Existing git tools work at raw commit/blob level; git-reticulator lifts analysis to a semantic, navigable, embeddable structure suited to feeding LLMs cheaply and provably."
+positioning = "layer 1 of a four-layer neuro-symbolic stack (reticulator -> RAG -> verisim octad -> vcl-ut proofs); see NEUROSYM.a2ml"
+
+[maintenance-axes]
+scoping-first = true
+axis-1 = "must > intend > like"
+axis-2 = "corrective > adaptive > perfective"
+axis-3 = "systems > compliance > effects"

.machine_readable/6a2/NEUROSYM.a2ml

@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# NEUROSYM.a2ml — Neurosymbolic integration metadata for git-reticulator
+#
+# This file is NOT a generic template. It records the specific role
+# git-reticulator plays in a neurosymbolic (neuro-symbolic) system and the
+# invariants that make that role trustworthy. Status markers are honest:
+#   IMPLEMENTED | SKELETON | ASPIRATIONAL.
+
+[metadata]
+version = "0.2.0"
+last-updated = "2026-06-03"
+status-legend = "IMPLEMENTED = working in Rust on main; SKELETON = stub/println; ASPIRATIONAL = designed in .affine, not yet compilable"
+
+# ════════════════════════════════════════════════════════════════════════════
+# THESIS
+# ════════════════════════════════════════════════════════════════════════════
+# git-reticulator is the SYMBOLIC half of a neuro-symbolic retrieval system.
+# It turns an unstructured git repository into a typed, hierarchical, navigable
+# structure (the "lattice"): nodes are semantic keywords at four levels of
+# detail (Module > File > Definition > Block); edges are typed relationships
+# (calls/contains/inherits/depends_on) with weights. The NEURAL half is an
+# embedding attached to each node (models.affine: `Keyword.embedding`).
+#
+# The two halves are fused at the data-model level — every node is
+# simultaneously a lattice element (symbolic, ordered, provable) and a vector
+# (neural, similarity-searchable). That fusion is the whole point.
+
+[thesis]
+symbolic-substrate = "typed keyword lattice + weighted relationship graph (src/lattice/affine/models.affine)"
+neural-layer = "per-node embedding vector (Keyword.embedding: Option<Vec<f64>>)"
+fusion-point = "the Keyword node — one identity carries both an order position and an embedding"
+headline-capability = "proof-carrying retrieval: neural search PROPOSES context, the symbolic lattice + proofs DISPOSE"
+
+# ════════════════════════════════════════════════════════════════════════════
+# THE FOUR-LAYER NEURO-SYMBOLIC STACK
+# ════════════════════════════════════════════════════════════════════════════
+# git-reticulator is layer 1. It is designed to feed layers 2-4. Layers 2-4 are
+# OPTIONAL — git-reticulator + a plain vector store is already a useful
+# Graph-RAG. The verisim/vcl-ut layers are what make retrieval *provable*.
+
+[stack.layer-1-reticulator]
+role = "structure extractor + retrieval geometry"
+status = "SKELETON (Rust host 237 LOC of println stubs) + ASPIRATIONAL (.affine core)"
+produces = "lattice nodes (keywords w/ embeddings) + typed weighted edges"
+key-operation = "zoom_to_node(node, level) — level-of-detail subgraph for token-bounded LLM context"
+
+[stack.layer-2-rag]
+role = "neural retrieval over the lattice"
+status = "ASPIRATIONAL (embeddings feature-gated: Cargo.toml `embeddings`/tch off by default)"
+mechanism = "vector similarity finds candidate nodes; lattice edges expand/constrain/explain them (Graph-RAG)"
+token-discipline = "LOD zoom returns the minimal relevant sub-lattice, not the whole repo — bounds prompt size"
+
+[stack.layer-3-verisim]
+role = "the substrate at scale — the octad IS a superset of what reticulator needs"
+status = "EXTERNAL (hyperpolymath/verisimdb); integration ASPIRATIONAL"
+modality-mapping = [
+  "Graph modality      <- the reticulator lattice",
+  "Vector modality     <- the node embeddings",
+  "Document modality   <- source text of each unit",
+  "Temporal modality   <- commit history (when a concept entered the codebase)",
+  "Provenance modality <- authorship attribution at semantic-unit granularity",
+  "Semantic modality   <- type/category tags",
+]
+drift-payoff = "verisim drift detection becomes 'has the symbolic lattice drifted from the embedding space / from HEAD?' — i.e. stale-index detection for RAG, for free"
+
+[stack.layer-4-vcl-ut]
+role = "typed, proof-carrying query layer over verisim"
+status = "EXTERNAL (hyperpolymath/vcl-ut — REAL: machine-checked Idris2 corpus, %default total, zero proof-escape)"
+mechanism = "retrieval is a PROPOSITION to a consonance engine with up to 10 levels of type safety + optional PROOF clause"
+differentiator = "ordinary RAG retrieves text and hopes; here a retrieved context item can CARRY a machine-checked certificate"
+proofs-that-matter-for-rag = [
+  "PROVENANCE  -> 'this snippet was authored by X at commit Y' (auditable citation)",
+  "FRESHNESS   -> 'this line still exists at HEAD' (kills stale-context bugs)",
+  "EXISTENCE   -> 'this entity is real, not hallucinated' (kills fabricated citations)",
+  "INTEGRITY   -> 'the retrieved text matches the stored hash'",
+]
+
+# ════════════════════════════════════════════════════════════════════════════
+# CONSISTENCY INVARIANT (the neuro-symbolic seam — the genuinely novel proof target)
+# ════════════════════════════════════════════════════════════════════════════
+# When neural similarity and symbolic proximity disagree, ONE of them is stale.
+# We do not assume they agree; we make the disagreement observable and either
+# repair it (re-reticulate) or DISCLOSE it. See PROOF-NEEDS.md obligation P6.
+
+[consistency-invariant]
+statement = "for nodes a,b: high embedding-cosine(a,b) without a short lattice path is a DRIFT SIGNAL, not an error"
+action-on-drift = "re-extract (re-reticulate) the affected sub-lattice; or surface as verisim drift event"
+honest-position = "neural and symbolic layers are INDEPENDENT by default; any claimed correlation must be proven or disclosed, never assumed"
+
+# ════════════════════════════════════════════════════════════════════════════
+# HYPATIA SCANNER CONFIG (estate neurosym CI)
+# ════════════════════════════════════════════════════════════════════════════
+[hypatia-config]
+scan-enabled = true
+scan-depth = "standard"          # quick | standard | deep
+report-format = "logtalk"
+
+[symbolic-rules]
+# Project-specific symbolic rules Hypatia should enforce here.
+rules = [
+  { name = "no-lattice-claim-without-proof", pattern = "lattice", note = "if a module asserts lattice algebra (meet/join), PROOF-NEEDS.md P1 must cover it", severity = "info" },
+  { name = "no-stub-passed-as-done", pattern = "println!\\(\"", note = "build_lattice/query_lattice are SKELETON; do not document them as working", severity = "warning" },
+]
+
+[neural-config]
+# Embedding model selection is deferred until the `embeddings` feature is wired.
+# candidate-model = "code-embedding (local, deno/rust-hosted) — NOT a cloud call"
+# confidence-threshold = 0.85
+embedding-source = "ASPIRATIONAL (Cargo feature `embeddings` = tch/PyTorch, off by default)"