chore(rsr): standards compliance — adoc-first cleanup + licence invariant (#10)

## Summary

Brings arghda-core to the hyperpolymath **standards / RSR** baseline,
clears root cruft, and makes the **MPL-2.0 / CC-BY-SA-4.0 licence split
a formal, enforced invariant**. Two commits:

### 1 — adoc-first cleanup + RSR baseline (`5b7aff4`)
- `README.md` → **`README.adoc`** (adoc-first), refreshed to
feature-complete v0.1. New **`EXPLAINME.adoc`**, **`LICENSE`** (full
MPL-2.0), **`CODE_OF_CONDUCT.md`**. Refreshed
`STATE`/`META`/`0-AI-MANIFEST`. Removed `dist-newstyle/`. No duplicate
doc formats; `just validate-rsr` passes.

### 2 — licence invariant (`af5fa44`, owner-directed)
- Applied SPDX headers per file: **`MPL-2.0`** to all
code/config/scripts/state (25 `.rs`, `Cargo.toml`, `.gitignore`),
**`CC-BY-SA-4.0`** to prose. Fixed drift: prose docs that were `MPL-2.0`
or `CC-BY-4.0` → `CC-BY-SA-4.0`.
- New **`scripts/check-spdx.sh`** enforces the split; wired into `just
check` + Rust CI. New **`.machine_readable/licensing-policy.toml`**
declares it machine-readably.
- **Third-party protection:** `Cargo.lock` (generated), `LICENSE` (the
licence text), and `tests/fixtures/` (Agda test data) are excluded and
never relicensed. No vendored third-party source exists in-tree; if any
is added, the checker fails until it's listed as excluded **with its
original SPDX preserved** — the guard against silent relicensing.

## Deliberately NOT done
- The maximalist rsr-template tree (`build/just`, `verification/proofs`,
`container/`, hundreds of placeholder dirs) — vestigial for a small Rust
CLI. A formal *capability-gated* rule for this ("carry a template module
iff the repo has the capability it serves") is the proposed follow-up
(recorded in `STATE.a2ml`).

## Verification
`bash scripts/check-spdx.sh` ✓ · `cargo fmt --check` ✓ · `cargo clippy
-D warnings` ✓ · `cargo test` ✓ (7 groups) · `just validate-rsr` ✓.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_019GiSiEfgZCte35dyykgBHs

Author: hyperpolymath

.github/workflows/rust-ci.yml

@@ -49,6 +49,9 @@ jobs:
           cargo --version
           rustup component add clippy rustfmt
 
+      - name: SPDX licence invariant
+        run: bash scripts/check-spdx.sh
+
       - name: cargo fmt --check
         run: cargo fmt --all -- --check
 

.gitignore

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+
 # Rust build artefacts
 target/
 

.machine_readable/6a2/META.a2ml

@@ -6,7 +6,7 @@
 
 [metadata]
 version = "0.1.0"
-last-updated = "2026-06-18"
+last-updated = "2026-06-20"
 
 [project-info]
 type = "library"  # library | binary | monorepo | service | website
@@ -20,6 +20,9 @@ author = "Jonathan D.A. Jewell (hyperpolymath)"
 # - { id = "ADR-002", title = "Triage transitions are file moves; ground truth is the filesystem", status = "accepted", date = "2026-05-30" }
 # - { id = "ADR-003", title = "Dependency-free RFC 3339 timestamps (hermetic build, no chrono)", status = "accepted", date = "2026-06-18" }
 # - { id = "ADR-004", title = "Orphan reachability is the union of discovered CI roots (All.agda/Smoke.agda)", status = "accepted", date = "2026-06-18" }
+# - { id = "ADR-005", title = "unused-import is an agda.rs-style external shell-out (per-file, local mode, LC_ALL=C.UTF-8), not a per-file LintRule", status = "accepted", date = "2026-06-20" }
+# - { id = "ADR-006", title = "Headline pattern is operator-configurable; precedence default < .arghda/config.toml < CLI flag (on the rule instance, not LintContext)", status = "accepted", date = "2026-06-20" }
+# - { id = "ADR-007", title = "DAG node `headlines` reuses the unpinned-headline extractor with the configured pattern", status = "accepted", date = "2026-06-20" }
 
 [development-practices]
 build-tool = "just"

.machine_readable/6a2/STATE.a2ml

@@ -6,13 +6,13 @@
 [metadata]
 project = "arghda-core"
 version = "0.1.0"
-last-updated = "2026-06-18"
+last-updated = "2026-06-20"
 status = "active"  # active | paused | archived
 
 [project-context]
 name = "arghda-core"
 purpose = "Lightweight proof-workspace manager for Agda — the language-agnostic engine half of arghda. A four-state triage workspace (inbox/working/proven/rejected) as file moves, a lint pack targeting the silent-failure class, a first-class import-graph DAG, and a JSON + event-stream contract a visual layer (arghda-studio) consumes. It never proves anything; Agda does."
-completion-percentage = 55
+completion-percentage = 85
 
 [position]
 phase = "implementation"   # design | implementation | testing | maintenance | archived
@@ -21,37 +21,44 @@ maturity = "alpha"         # experimental | alpha | beta | production | lts
 [route-to-mvp]
 milestones = [
   { name = "Workspace scaffold + filesystem watcher", completion = 100 },
-  { name = "Lint pack (missing-safe-pragma, orphan-module, unjustified-postulate, escape-hatch, tab-mix)", completion = 100 },
-  { name = "First-class import graph + `dag` JSON command", completion = 100 },
+  { name = "Hard-block lint pack (missing-safe-pragma, orphan-module, unjustified-postulate)", completion = 100 },
+  { name = "Warn lint pack (escape-hatch, tab-mix, unpinned-headline, unused-import)", completion = 100 },
+  { name = "First-class import graph + `dag` JSON command (nodes incl. headlines, edges, blocked)", completion = 100 },
   { name = "State machine (claim/promote/reject/requeue/invalidate) + events.jsonl", completion = 100 },
   { name = "`check` command (Agda typecheck + lint verdict)", completion = 100 },
   { name = "Multi-root reachability (union of discovered CI roots)", completion = 100 },
-  { name = "Content-hash invalidation of proven (file-level; +imports deferred)", completion = 75 },
-  { name = "Remaining lint rules (unpinned-headline, unused-import)", completion = 0 },
-  { name = "Groove service manifest (/.well-known/groove)", completion = 0 },
-  { name = "RSR retrofit (.machine_readable, Justfile, .well-known)", completion = 60 },
+  { name = "Content-hash invalidation of proven (file-level; transitive imports deferred)", completion = 75 },
+  { name = "Operator config (.arghda/config.toml + --headline-pattern + --config)", completion = 100 },
+  { name = "RSR / standards alignment (.machine_readable, README.adoc, EXPLAINME, LICENSE, .well-known)", completion = 100 },
+  { name = "Groove service manifest (/.well-known/groove) for PanLL discovery", completion = 0 },
 ]
 
 [blockers-and-issues]
-# No active blockers. `unpinned-headline` needs Smoke.agda parsing + a
-# configurable headline regex; `unused-import` shells out to `agda-unused`.
+# No active blockers. v0.1 lint set + DAG schema (arghda-spec.adoc) are
+# complete. The SPDX licence invariant is applied and enforced
+# (scripts/check-spdx.sh; .machine_readable/licensing-policy.toml).
 
 [critical-next-actions]
 actions = [
-  "Add unpinned-headline (needs config + headline regex) + unused-import (agda-unused) lint rules",
-  "Extend content-hash to cover transitive imports (needs include-root tracking)",
-  "Serve /.well-known/groove for PanLL discovery",
+  "Formalise template-applicability rules (capability-gated RSR profile: carry a template module iff the repo declares the capability it serves) — estate-wide, candidate for hyperpolymath/standards",
+  "Extend content-hash invalidation to cover transitive imports (needs include-root tracking)",
+  "Serve /.well-known/groove for PanLL discovery (Groove protocol)",
   "Scaffold arghda-studio (AffineScript visual layer consuming the dag JSON)",
 ]
 
 [maintenance-status]
-last-run-utc = "never"
-last-result = "unknown"  # unknown | pass | warn | fail
+last-run-utc = "2026-06-20"
+last-result = "pass"  # unknown | pass | warn | fail
 open-warnings = 0
 open-failures = 0
+# `just check` (fmt-check + clippy -D warnings + build + test) green; ~50 lib
+# tests + integration suites pass. Dogfooded against echo-types + a live
+# agda-unused build.
 
 [ecosystem]
 part-of = ["arghda"]
 depends-on = []
+# Build deps: anyhow, clap, notify, regex, serde, serde_json, toml, walkdir.
+# Optional external tools: agda, agda-unused (both degrade gracefully).
 # Downstream consumers: arghda-studio (planned), arghda-panll (planned).
 # Dogfood workspaces: echo-types, absolute-zero.

.machine_readable/licensing-policy.toml

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# Licence invariant for arghda-core — machine-readable declaration of the rule
+# enforced by scripts/check-spdx.sh (run in `just check` + Rust CI). The split
+# itself comes from hyperpolymath/standards LICENCE-POLICY.adoc Rule 1.
+
+[invariant]
+enforced = true
+checker = "scripts/check-spdx.sh"
+wired-into = ["Justfile (just check / just license-check)", ".github/workflows/rust-ci.yml"]
+
+[licences]
+# By content type, not by directory.
+code = "MPL-2.0"        # *.rs, *.toml, *.a2ml, *.yml, *.sh, Justfile, .gitignore, .well-known/*
+prose = "CC-BY-SA-4.0"  # *.adoc, *.md narrative
+# Canonical texts: MPL-2.0 -> ./LICENSE ; CC-BY-SA-4.0 -> standards/LICENSES/CC-BY-SA-4.0.txt
+
+[excluded]
+# NOT ours, generated, or test-input data. These never carry the repo's
+# licence choices; the checker skips them.
+paths = [
+  "Cargo.lock",      # generated by cargo; enumerates third-party dependencies
+  "LICENSE",         # the MPL-2.0 licence text itself
+  "target/",         # cargo build output (gitignored)
+  "tests/fixtures/", # Agda test-input data (some deliberately malformed)
+]
+
+[third-party]
+# arghda-core vendors NO third-party source in-tree: every dependency is
+# fetched by cargo (declared in Cargo.toml, pinned in Cargo.lock) and is never
+# relicensed. If third-party source is ever vendored in-tree, add its path to
+# [excluded] above and preserve its ORIGINAL SPDX header verbatim. The checker
+# fails on any unrecognised in-tree file until it is excluded — that failure is
+# the intended guard against silently relicensing others' code.
+vendored-in-tree = []

0-AI-MANIFEST.a2ml

@@ -5,17 +5,18 @@
 
 [metadata]
 version = "0.1.0"
-last-updated = "2026-06-18"
+last-updated = "2026-06-20"
 
 [project]
 name = "arghda-core"
 purpose = "Language-agnostic proof-workspace engine for the arghda visual proof-wiring tool (Agda first). Emits the DAG / events.jsonl JSON contract a visual layer consumes; never proves anything itself."
 
 [entry]
 read-order = [
+  "EXPLAINME.adoc",
   ".machine_readable/6a2/STATE.a2ml",
   ".machine_readable/6a2/META.a2ml",
-  "README.md",
+  "README.adoc",
   "docs/arghda-spec.adoc",
   "docs/arghda-vision.adoc",
 ]

CHANGELOG.md

@@ -1,4 +1,4 @@
-<!-- SPDX-License-Identifier: MPL-2.0 -->
+<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
 # Changelog
 
 All notable changes to arghda-core are documented here. The format follows
@@ -7,6 +7,25 @@ All notable changes to arghda-core are documented here. The format follows
 
 ## [Unreleased]
 
+### Changed
+
+- Standards / RSR alignment and root cleanup: `README.md` → `README.adoc`
+  (adoc-first; refreshed to the feature-complete v0.1 status), no duplicate
+  doc formats. Added `EXPLAINME.adoc` (orientation pointer), `LICENSE` (full
+  MPL-2.0 text), and `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1). Prose
+  docs carry `CC-BY-SA-4.0`; code/config/state stay `MPL-2.0` (per the estate
+  licence policy). Refreshed `.machine_readable/6a2/STATE.a2ml` + `META.a2ml`
+  and the `0-AI-MANIFEST.a2ml` read-order; removed local `dist-newstyle/`
+  build cruft.
+- Formal SPDX licence invariant (owner-directed): every tracked file carries
+  the correct header — `MPL-2.0` for code/config/scripts/state, `CC-BY-SA-4.0`
+  for prose — applied per file (incl. all `src/*.rs`) and enforced by
+  `scripts/check-spdx.sh`, wired into `just check` and Rust CI. Third-party,
+  generated (`Cargo.lock`), and test-data (`tests/fixtures/`) files are
+  explicitly excluded and never relicensed; `docs/*.adoc` normalised from
+  `CC-BY-4.0` to `CC-BY-SA-4.0`. Declared in
+  `.machine_readable/licensing-policy.toml`.
+
 ### Added
 
 - `dag` command emitting the dependency-DAG JSON contract (nodes with

CODE_OF_CONDUCT.md

@@ -0,0 +1,7 @@
+<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
+<!-- SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk> -->
+# Code of Conduct
+
+This project follows the [Contributor Covenant 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+Reports go to `j.d.a.jewell@open.ac.uk`. Reports are confidential by default.

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-<!-- SPDX-License-Identifier: MPL-2.0 -->
+<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
 # Contributing to arghda-core
 
 arghda-core is the Rust engine for the arghda proof-workspace tool.

Cargo.toml

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+
 [package]
 name = "arghda-core"
 version = "0.1.0"