Move grund.toml to the project roots (#1026)

* Move grund.toml to the project roots

grund probes a bare `grund.toml` before `.agents/grund.toml`. Move all
four configs — the workspace root and the common, native-gradle-plugin,
and native-maven-plugin members — up to the project root each one
configures, so they sit with the other top-level project files and match
the layout grund uses in its own repo.

The spec gate needs two matching edits. Its path filter named
`.agents/grund.toml`, so it would have stopped triggering on config
edits; and GRUND_VERSION was pinned to 0.5.0, which predates root
discovery (grund 0.9.0) — a grund that finds no config exits 0 without
checking anything, so the gate would have gone green while validating
nothing.

Bumping the pin surfaces a pre-existing failure: under 0.9.0 all four
AGENTS.md files fail `grund check` with `outdated grund init block v3`.
`grund init` refreshes them to v7, which spells the config path without
the `.agents/` prefix, adds the BEGIN/END block markers, and adds the
marker and clickable-citation paragraphs.

Verified with grund 0.9.0: `grund check` and
`grund fmt . --marker --cross-refs --check` both exit 0.

Closes #1025

* Name the package when installing grund from git

The grund repository now ships two binary packages, grund and grund-lsp,
so `cargo install --git … --tag v0.9.0` fails with "multiple packages
with binaries found" before it installs anything. Name the package
explicitly.

Author: vjovanov

.github/workflows/check-grund-spec.yml

@@ -6,7 +6,7 @@ on:
   pull_request:
     paths:
       - 'docs/spec/**'
-      - '.agents/grund.toml'
+      - 'grund.toml'
       - '.pre-commit-config.yaml'
       - 'AGENTS.md'
       - 'common/**'
@@ -27,8 +27,8 @@ permissions:
   contents: read
 
 env:
-  # Bump to refresh the cached binary. Validated locally against grund 0.5.0.
-  GRUND_VERSION: "0.5.0"
+  # Bump to refresh the cached binary. Validated locally against grund 0.9.0.
+  GRUND_VERSION: "0.9.0"
 
 jobs:
   check-grund-spec:
@@ -49,10 +49,10 @@ jobs:
         if: steps.cache-grund.outputs.cache-hit != 'true'
         run: |
           rustup toolchain install stable --profile minimal
-          rustup run stable cargo install --git https://github.com/vjovanov/grund --tag "v${GRUND_VERSION}"
+          rustup run stable cargo install --git https://github.com/vjovanov/grund --tag "v${GRUND_VERSION}" grund
       - name: "✅ grund check"
         # Validates that every §<ID> citation in docs, workflows, and source doc-comments resolves,
-        # and that section headings and inline-note limits hold. See AGENTS.md and .agents/grund.toml.
+        # and that section headings and inline-note limits hold. See AGENTS.md and grund.toml.
         # The root workspace validates root, Gradle, and Maven namespaces together.
         run: |
           grund check

AGENTS.md

@@ -1,8 +1,9 @@
 # Native Build Tools — agent instructions
 
-## Grounding with grund (v3)
+<!-- BEGIN GRUND MANAGED BLOCK -->
+## Grounding with grund (v7)
 
-This project uses [`grund`](https://github.com/vjovanov/grund): every spec, goal, decision, and end-to-end test has a stable ID `<KIND>-<slug>[.<section>]` (`KIND ∈ {GRUND, GOAL, NGOAL, REQ, AR, FS, E2E, DEC, GLOSS}`), cited with the marker `§` — e.g. `FS-user-login.3.1` is the shape of a section ID, and a real citation prefixes that shape with `§`. Type `$$` in a grund-aware editor and it becomes `§`. Bare ID-shaped tokens are ignored — `[reference] strict = true` is set in `.agents/grund.toml`, so only `§`-prefixed citations are checked.
+This project uses [`grund`](https://github.com/vjovanov/grund): every spec, goal, decision, and end-to-end test has a stable ID `<KIND>-<slug>[.<section>]` (`KIND ∈ {GRUND, GOAL, NGOAL, REQ, AR, FS, E2E, DEC, GLOSS}`), cited with the marker `§` — e.g. `<§>FS-user-login.3.1` (the `FS-user-login` here is a shape illustration, not a real ID in this repo, hence the `<§>` escape). Type `$$` in a grund-aware editor and it becomes `§`. Bare ID-shaped tokens are ignored — `[reference] strict = true` is set in `grund.toml`, so only `§`-prefixed citations are checked.
 
 ### Grounding from a citation
 
@@ -31,7 +32,7 @@ A `§<ID>` is a pointer to a fact, not a file path. Resolve it with `grund` and
 
 A namespace is a project boundary, not a docs folder. The current project is the local namespace: cite its IDs as `§<ID>`.
 
-Create or use a separate namespace when work introduces an independently checked app, package, service, or subproject. Give that project its own `.agents/grund.toml`, add it to the workspace root's `[workspace] members`, run `grund init` there, and set a stable `project_name`.
+Create or use a separate namespace when work introduces an independently checked app, package, service, or subproject. Give that project its own `grund.toml`, add it to the workspace root's `[workspace] members`, run `grund init` there, and set a stable `project_name`.
 
 Do not create a namespace for a regular module or component that still belongs to this project. Cite across namespaces as `§alias/<ID>` and run `grund check` from the workspace root.
 
@@ -52,6 +53,7 @@ Declarations are heading lines `# FS-user-login: …` in markdown. In a code doc
 
 - **Spec first.** For behavior or design changes, write or update the most-specific spec point before code.
 - **Cite as you write.** Place `§<ID>` at the point a claim or behavior is made — on the doc-comment for a whole behavior, inline beside the clause it enforces.
+- **Marker = live citation.** A `§`-prefixed token resolves and is checked wherever it appears — including inside Markdown backticks. To mention an ID without citing it, write `<§><ID>`, omit the marker, or use a fenced code block.
 - **Inline citation style.** Inline notes: ≤ 1 line preferred, hard cap 12 lines; ≤ 160 columns.
 - **Always cite the most-specific point.**
 
@@ -66,3 +68,8 @@ Declarations are heading lines `# FS-user-login: …` in markdown. In a code doc
 - **DEC** should cite */FS or */AR or */REQ or */GOAL or */NGOAL or */DEC.
 - **code** (any file outside a kind home) should cite */FS or */AR or */E2E.
 Unlisted kinds and pairs are fine.
+
+### Clickable citations
+
+On repository web surfaces, link `§<ID>` to the PR branch in PR bodies, the reviewed commit in reviews, an exact commit for permalinks, and the default branch otherwise; fall back to plain when unsure.
+<!-- END GRUND MANAGED BLOCK -->

common/AGENTS.md

@@ -1,8 +1,9 @@
 # Common Libraries — agent instructions
 
-## Grounding with grund (v3)
+<!-- BEGIN GRUND MANAGED BLOCK -->
+## Grounding with grund (v7)
 
-This project uses [`grund`](https://github.com/vjovanov/grund): every spec, goal, decision, and end-to-end test has a stable ID `<KIND>-<slug>[.<section>]` (`KIND ∈ {GRUND, GOAL, REQ, FS, AR, E2E}`), cited with the marker `§` — e.g. `FS-user-login.3.1` is the shape of a section ID, and a real citation prefixes that shape with `§`. Type `$$` in a grund-aware editor and it becomes `§`. Bare ID-shaped tokens are ignored — `[reference] strict = true` is set in `.agents/grund.toml`, so only `§`-prefixed citations are checked.
+This project uses [`grund`](https://github.com/vjovanov/grund): every spec, goal, decision, and end-to-end test has a stable ID `<KIND>-<slug>[.<section>]` (`KIND ∈ {GRUND, GOAL, REQ, FS, AR, E2E}`), cited with the marker `§` — e.g. `<§>FS-user-login.3.1` (the `FS-user-login` here is a shape illustration, not a real ID in this repo, hence the `<§>` escape). Type `$$` in a grund-aware editor and it becomes `§`. Bare ID-shaped tokens are ignored — `[reference] strict = true` is set in `grund.toml`, so only `§`-prefixed citations are checked.
 
 ### Grounding from a citation
 
@@ -28,7 +29,7 @@ A `§<ID>` is a pointer to a fact, not a file path. Resolve it with `grund` and
 
 A namespace is a project boundary, not a docs folder. The current project is the local namespace: cite its IDs as `§<ID>`.
 
-Create or use a separate namespace when work introduces an independently checked app, package, service, or subproject. Give that project its own `.agents/grund.toml`, add it to the workspace root's `[workspace] members`, run `grund init` there, and set a stable `project_name`.
+Create or use a separate namespace when work introduces an independently checked app, package, service, or subproject. Give that project its own `grund.toml`, add it to the workspace root's `[workspace] members`, run `grund init` there, and set a stable `project_name`.
 
 Do not create a namespace for a regular module or component that still belongs to this project. Cite across namespaces as `§alias/<ID>` and run `grund check` from the workspace root.
 
@@ -49,6 +50,7 @@ Declarations are heading lines `# FS-user-login: …` in markdown. In a code doc
 
 - **Spec first.** For behavior or design changes, write or update the most-specific spec point before code.
 - **Cite as you write.** Place `§<ID>` at the point a claim or behavior is made — on the doc-comment for a whole behavior, inline beside the clause it enforces.
+- **Marker = live citation.** A `§`-prefixed token resolves and is checked wherever it appears — including inside Markdown backticks. To mention an ID without citing it, write `<§><ID>`, omit the marker, or use a fenced code block.
 - **Inline citation style.** Inline notes: ≤ 1 line preferred, hard cap 12 lines; ≤ 160 columns.
 - **Always cite the most-specific point.**
 
@@ -62,6 +64,11 @@ Declarations are heading lines `# FS-user-login: …` in markdown. In a code doc
 - **code** (any file outside a kind home) should cite */FS or */AR or */E2E.
 Unlisted kinds and pairs are fine.
 
+### Clickable citations
+
+On repository web surfaces, link `§<ID>` to the PR branch in PR bodies, the reviewed commit in reviews, an exact commit for permalinks, and the default branch otherwise; fall back to plain when unsure.
+<!-- END GRUND MANAGED BLOCK -->
+
 ## Local Grounding Notes
 
 Repository-wide grounding, non-goals, shared plugin behavior, and CI remain in the `root`

common/.agents/grund.toml common/grund.tomlcommon/.agents/grund.toml renamed to common/grund.toml

@@ -1,8 +1,9 @@
 # Native Gradle Plugin — agent instructions
 
-## Grounding with grund (v3)
+<!-- BEGIN GRUND MANAGED BLOCK -->
+## Grounding with grund (v7)
 
-This project uses [`grund`](https://github.com/vjovanov/grund): every spec, goal, decision, and end-to-end test has a stable ID `<KIND>-<slug>[.<section>]` (`KIND ∈ {GRUND, GOAL, REQ, FS, AR, E2E}`), cited with the marker `§` — e.g. `FS-user-login.3.1` is the shape of a section ID, and a real citation prefixes that shape with `§`. Type `$$` in a grund-aware editor and it becomes `§`. Bare ID-shaped tokens are ignored — `[reference] strict = true` is set in `.agents/grund.toml`, so only `§`-prefixed citations are checked.
+This project uses [`grund`](https://github.com/vjovanov/grund): every spec, goal, decision, and end-to-end test has a stable ID `<KIND>-<slug>[.<section>]` (`KIND ∈ {GRUND, GOAL, REQ, FS, AR, E2E}`), cited with the marker `§` — e.g. `<§>FS-user-login.3.1` (the `FS-user-login` here is a shape illustration, not a real ID in this repo, hence the `<§>` escape). Type `$$` in a grund-aware editor and it becomes `§`. Bare ID-shaped tokens are ignored — `[reference] strict = true` is set in `grund.toml`, so only `§`-prefixed citations are checked.
 
 ### Grounding from a citation
 
@@ -28,7 +29,7 @@ A `§<ID>` is a pointer to a fact, not a file path. Resolve it with `grund` and
 
 A namespace is a project boundary, not a docs folder. The current project is the local namespace: cite its IDs as `§<ID>`.
 
-Create or use a separate namespace when work introduces an independently checked app, package, service, or subproject. Give that project its own `.agents/grund.toml`, add it to the workspace root's `[workspace] members`, run `grund init` there, and set a stable `project_name`.
+Create or use a separate namespace when work introduces an independently checked app, package, service, or subproject. Give that project its own `grund.toml`, add it to the workspace root's `[workspace] members`, run `grund init` there, and set a stable `project_name`.
 
 Do not create a namespace for a regular module or component that still belongs to this project. Cite across namespaces as `§alias/<ID>` and run `grund check` from the workspace root.
 
@@ -49,6 +50,7 @@ Declarations are heading lines `# FS-user-login: …` in markdown. In a code doc
 
 - **Spec first.** For behavior or design changes, write or update the most-specific spec point before code.
 - **Cite as you write.** Place `§<ID>` at the point a claim or behavior is made — on the doc-comment for a whole behavior, inline beside the clause it enforces.
+- **Marker = live citation.** A `§`-prefixed token resolves and is checked wherever it appears — including inside Markdown backticks. To mention an ID without citing it, write `<§><ID>`, omit the marker, or use a fenced code block.
 - **Inline citation style.** Inline notes: ≤ 1 line preferred, hard cap 12 lines; ≤ 160 columns.
 - **Always cite the most-specific point.**
 
@@ -62,6 +64,11 @@ Declarations are heading lines `# FS-user-login: …` in markdown. In a code doc
 - **code** (any file outside a kind home) should cite */FS or */AR or */E2E.
 Unlisted kinds and pairs are fine.
 
+### Clickable citations
+
+On repository web surfaces, link `§<ID>` to the PR branch in PR bodies, the reviewed commit in reviews, an exact commit for permalinks, and the default branch otherwise; fall back to plain when unsure.
+<!-- END GRUND MANAGED BLOCK -->
+
 ## Local Grounding Notes
 
 Repository-wide grounding, non-goals, shared plugin behavior, and CI remain in the `root`

.agents/grund.toml grund.toml.agents/grund.toml renamed to grund.toml

@@ -1,8 +1,9 @@
 # Native Maven Plugin — agent instructions
 
-## Grounding with grund (v3)
+<!-- BEGIN GRUND MANAGED BLOCK -->
+## Grounding with grund (v7)
 
-This project uses [`grund`](https://github.com/vjovanov/grund): every spec, goal, decision, and end-to-end test has a stable ID `<KIND>-<slug>[.<section>]` (`KIND ∈ {GRUND, GOAL, REQ, FS, AR, E2E}`), cited with the marker `§` — e.g. `FS-user-login.3.1` is the shape of a section ID, and a real citation prefixes that shape with `§`. Type `$$` in a grund-aware editor and it becomes `§`. Bare ID-shaped tokens are ignored — `[reference] strict = true` is set in `.agents/grund.toml`, so only `§`-prefixed citations are checked.
+This project uses [`grund`](https://github.com/vjovanov/grund): every spec, goal, decision, and end-to-end test has a stable ID `<KIND>-<slug>[.<section>]` (`KIND ∈ {GRUND, GOAL, REQ, FS, AR, E2E}`), cited with the marker `§` — e.g. `<§>FS-user-login.3.1` (the `FS-user-login` here is a shape illustration, not a real ID in this repo, hence the `<§>` escape). Type `$$` in a grund-aware editor and it becomes `§`. Bare ID-shaped tokens are ignored — `[reference] strict = true` is set in `grund.toml`, so only `§`-prefixed citations are checked.
 
 ### Grounding from a citation
 
@@ -28,7 +29,7 @@ A `§<ID>` is a pointer to a fact, not a file path. Resolve it with `grund` and
 
 A namespace is a project boundary, not a docs folder. The current project is the local namespace: cite its IDs as `§<ID>`.
 
-Create or use a separate namespace when work introduces an independently checked app, package, service, or subproject. Give that project its own `.agents/grund.toml`, add it to the workspace root's `[workspace] members`, run `grund init` there, and set a stable `project_name`.
+Create or use a separate namespace when work introduces an independently checked app, package, service, or subproject. Give that project its own `grund.toml`, add it to the workspace root's `[workspace] members`, run `grund init` there, and set a stable `project_name`.
 
 Do not create a namespace for a regular module or component that still belongs to this project. Cite across namespaces as `§alias/<ID>` and run `grund check` from the workspace root.
 
@@ -49,6 +50,7 @@ Declarations are heading lines `# FS-user-login: …` in markdown. In a code doc
 
 - **Spec first.** For behavior or design changes, write or update the most-specific spec point before code.
 - **Cite as you write.** Place `§<ID>` at the point a claim or behavior is made — on the doc-comment for a whole behavior, inline beside the clause it enforces.
+- **Marker = live citation.** A `§`-prefixed token resolves and is checked wherever it appears — including inside Markdown backticks. To mention an ID without citing it, write `<§><ID>`, omit the marker, or use a fenced code block.
 - **Inline citation style.** Inline notes: ≤ 1 line preferred, hard cap 12 lines; ≤ 160 columns.
 - **Always cite the most-specific point.**
 
@@ -62,6 +64,11 @@ Declarations are heading lines `# FS-user-login: …` in markdown. In a code doc
 - **code** (any file outside a kind home) should cite */FS or */AR or */E2E.
 Unlisted kinds and pairs are fine.
 
+### Clickable citations
+
+On repository web surfaces, link `§<ID>` to the PR branch in PR bodies, the reviewed commit in reviews, an exact commit for permalinks, and the default branch otherwise; fall back to plain when unsure.
+<!-- END GRUND MANAGED BLOCK -->
+
 ## Local Grounding Notes
 
 Repository-wide grounding, non-goals, shared plugin behavior, and CI remain in the `root`