Upgrade to docs-spec-template 5a3a96e (fixes home/index.html 404s)

.gitignore

@@ -4,6 +4,9 @@
 **/.DS_Store
 # Local Antora preview tooling (see package.json / ANTORA.md Phase 5)
 /node_modules/
+# Vale style packages, downloaded into StylesPath by `vale sync` at lint time
+# (see .vale.ini). Fetched on every run, never committed.
+/.github/styles/
 /.cache/
 # Generated diagram/math artifacts (kroki fetch + asciidoctor-mathematical);
 # regenerated every build, never committed.

.template-version

@@ -4,9 +4,10 @@
 # v* git tags created by the version-bot.yml workflow.
 #
 # Baseline is template main rather than a release tag: doc mode (the posture
-# this repo runs in, see .docmode) landed in template PR #150 and is not in any
-# tagged release yet. The template's tag namespace also mixes real releases with
-# version-bot test tags, so the SHA is the authoritative record.
+# this repo runs in, see .docmode) landed in template PR #150, and the fixes for
+# the issues this repo raised (#151, #152) landed in PRs #153 and #154. None of
+# that is in a tagged release yet. The template's tag namespace also mixes real
+# releases with version-bot test tags, so the SHA is the authoritative record.
 template_ref: main
-template_sha: 74566374080a11fd7abe482b1246a87a12158f8b
-upgraded_on: 2026-09-09
+template_sha: 5a3a96eb1d9bab1332c74ebdda046a3d0b80030f
+upgraded_on: 2026-09-10

.vale.ini

@@ -1,34 +1,44 @@
+# Vale configuration for this specification repository.
+#
+# Vale runs on every pull request via .github/workflows/vale-linting.yml, which
+# calls the reusable workflow in riscv-admin/riscv-vale. That action reads THIS
+# file from the repository under test -- it does not supply a config of its own,
+# so an empty or missing .vale.ini means Vale runs and lints nothing.
+#
+# Ownership (see UPGRADING.md, "Shared files"): `StylesPath` and `Packages` are
+# template-owned -- they point at the shared RISC-V style package and should be
+# taken from the template on every upgrade. `BasedOnStyles`, `Vocab`, and the
+# rule disables at the bottom are YOURS: a task group that has agreed on its own
+# vocabulary or has switched a rule off should keep those lines across upgrades.
+#
+# `Packages` are downloaded into `StylesPath` by `vale sync` at lint time and are
+# never committed -- .gitignore excludes .github/styles/ for that reason.
+
 StylesPath = .github/styles
-minAlertLevel = suggestion
+MinAlertLevel = suggestion
 
 IgnoredScopes = code, tt, img, url, a, body.id
 
 SkippedScopes = script, style, pre, figure, code, tt, blockquote, listingblock, literalblock
 
-Packages = RedHat, AsciiDoc, https://github.com/riscv-admin/riscv-vale/releases/latest/download/riscv.zip, https://github.com/riscv-admin/riscv-vale/releases/latest/download/config.zip
+Packages = AsciiDoc, https://github.com/riscv-admin/riscv-vale/releases/latest/download/riscv.zip, https://github.com/riscv-admin/riscv-vale/releases/latest/download/config.zip
 Vocab = riscv-vocab
 
 [*.adoc]
-BasedOnStyles = Vale, RedHat, riscv, AsciiDoc
-
-#[*.md]
-#BasedOnStyles = Vale, RISCV-Vale, AsciiDoc
-
-# Ignore code surrounded by backticks or plus sign, parameters defaults, URLs.
-TokenIgnores = (\x60[^\n\x60]+\x60), ([^\n]+=[^\n]*), (\+[^\n]+\+), (http[^\n]+\[)
-
-# Match INI files. See: https://docs.errata.ai/vale/scoping
-#[*.ini]
-#BasedOnStyles = Vale, RISCV-Vale
-
-# Disabling rules (NO)
-#RedHat.CaseSensitiveTerms = NO
-#RedHat.ConfigMap = NO
-#RedHat.Definitions = NO
-#RedHat.Slash = NO
-#RedHat.Spacing = NO
-#RedHat.Spelling = NO
-#RedHat.TermsSuggestions = NO
-
-#with:
-#      files: src/*.adoc
+# `riscv` is the RISC-V house style; `AsciiDoc` checks AsciiDoc structure. The
+# generic `Vale` style (Vale.Spelling, Vale.Repetition) is deliberately NOT
+# enabled: specification prose is dense with mnemonics, CSR names and extension
+# names that its dictionary does not carry, and it reports 401 errors on this
+# template's own sample content. To opt in, add `Vale` to the list below and
+# expect to grow `Vocab` alongside it.
+BasedOnStyles = riscv, AsciiDoc
+
+# Ignore code surrounded by backticks or plus signs, parameter defaults, URLs,
+# and AsciiDoc macro patterns like csr:mseccfg[mlpe].
+TokenIgnores = (\x60[^\n\x60]+\x60), ([^\n]+=[^\n]*), (\+[^\n]+\+), (http[^\n]+\[), (\w+:\w+\[[^\]]*\])
+
+# Disabled rules. riscv.Slash flags "and/or" style constructions and
+# riscv.SentenceLength flags long sentences; both are advisory and produce heavy
+# noise on specification prose.
+riscv.Slash = NO
+riscv.SentenceLength = NO

MIGRATION.md

@@ -69,11 +69,12 @@ preface, the phase/milestone attributes, and `SPEC_STATE.md` tracking.
       `phase-floor-version` all resolve to `""` in doc mode automatically.
 - [ ] In Step 3/4's `build-pdf.yml`/`version-bot.yml`, the `target_phase`
       enum and milestone gating stay as-is (they're pure version arithmetic,
-      not ratification), but a doc-mode `version-bot.yml`'s `milestone-pr`
-      job (which regenerates `SPEC_STATE.md`) should be gated the same way
-      upstream's is: add `&& needs.tag-version.outputs.mode == 'spec'` to its
-      `if:` (and add a `mode` output to `tag-version`, from
-      `release-info.sh mode`).
+      not ratification). No doc-mode edit is needed on top of that: upstream's
+      `version-bot.yml` already exports a `mode` output from `tag-version`
+      (`release-info.sh mode`) and already gates the `milestone-pr` job --
+      the one that regenerates `SPEC_STATE.md` -- on
+      `needs.tag-version.outputs.mode == 'spec'`. Take the upstream file as
+      written and the gate comes with it. Do not re-apply that edit by hand.
 - [ ] Skip Step 5's Document State preface and phase-attribute defaults
       entirely — a doc-mode top-level `.adoc` needs neither; the upstream
       file already guards them behind `ifndef::doc-mode[]`.

UPGRADING.md

@@ -215,7 +215,7 @@ history required:
 git checkout $TARGET -- \
   scripts/ tests/ \
   .github/workflows/ .github/dependabot.yml \
-  .pre-commit-config.yaml .vale.ini docker-compose.yml \
+  .pre-commit-config.yaml docker-compose.yml \
   ANTORA.md MIGRATION.md ARC_SUBMISSION.md
 ```
 
@@ -590,7 +590,6 @@ tests/release-info-test.sh
 .github/workflows/vale-linting.yml
 .github/dependabot.yml
 .pre-commit-config.yaml
-.vale.ini
 docker-compose.yml
 ANTORA.md
 MIGRATION.md
@@ -629,6 +628,7 @@ keeping your own values from this table.
 | `CHANGELOG.md` | Yours; see section 6 for how to log the upgrade itself |
 | `.gitignore` | Usually identical; the template adds entries as new generated artifacts appear |
 | `.gitmodules` | Usually identical — check rather than assume |
+| `.vale.ini` | `BasedOnStyles`, `Vocab`, and any rule you have switched off; `StylesPath` and `Packages` are template-owned |
 | `src/<your-spec>.adoc` | Your `include::` lines only; see below |
 
 #### The one file that is both

scripts/build-pages-site.sh

@@ -176,4 +176,35 @@ antora_bin="$repo_root/node_modules/.bin/antora"
 [ -x "$antora_bin" ] || antora_bin="npx antora"
 $antora_bin --fetch "$generated_playbook"
 
+# The shared RISC-V UI bundle links to `home/index.html` from every page: the
+# header logo, the "RISC-V Specifications" breadcrumb, and the nav-tree root.
+# That path is the `home` component on the central docs.riscv.org site, which a
+# single-repo build does not have -- so without this file every page here 404s
+# on the logo and the breadcrumb.
+#
+# This CANNOT be fixed in the generated playbook. Of the three references, only
+# partials/nav.hbs is configurable (via site.keys.toc_home_link_path);
+# partials/header-content.hbs and partials/breadcrumbs.hbs hardcode the path.
+# Emitting the file is the only lever a standalone build has.
+#
+# Antora has already written the site-root index.html -- a redirect to
+# `start_page` -- so one hop from here lands the reader on the component start
+# page, which is where the central site's `home` component would have taken
+# them. Guarded so a repo that genuinely ships its own `home` component keeps it.
+if [ -e "$output_dir/home/index.html" ]; then
+  echo "==> Keeping existing home/index.html (this build has a 'home' component)"
+else
+  echo "==> Emitting home/index.html redirect for the shared UI's fixed links"
+  mkdir -p "$output_dir/home"
+  cat > "$output_dir/home/index.html" <<'HTML'
+<!DOCTYPE html>
+<meta charset="utf-8">
+<script>location="../index.html"</script>
+<meta http-equiv="refresh" content="0; url=../index.html">
+<meta name="robots" content="noindex">
+<title>Redirect Notice</title>
+<p>This documentation is <a href="../index.html">here</a>.</p>
+HTML
+fi
+
 echo "==> Done: $output_dir"

tests/release-info-test.sh

@@ -9,7 +9,26 @@
 set -uo pipefail
 
 here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-RI="$here/../scripts/release-info.sh"
+
+# These assertions describe SPEC-mode behaviour, and release-info.sh resolves
+# .docmode relative to its OWN location (repo_root = script dir/..), not the
+# caller's cwd. Running the script in place would therefore inherit whatever
+# mode THIS repository is in -- in a doc-mode repo every phase/display/floor
+# assertion below would compare against the empty string that doc mode is
+# supposed to return, and the suite would report failures for correct behaviour
+# (see issue #152).
+#
+# So drive a copy of the script from a scratch repo with no .docmode: mode is
+# pinned to spec no matter where the suite runs. The doc-mode assertions at the
+# bottom keep their own scratch repo and opt IN to doc mode explicitly, which is
+# the same pattern -- this just applies it to the whole suite. Nothing here
+# needs the template's git history: the two blocks that DO need a repo (the
+# untagged-build and .docmode sections) build their own.
+specrepo="$(mktemp -d)"
+mkdir -p "$specrepo/scripts"
+cp "$here/../scripts/release-info.sh" "$specrepo/scripts/release-info.sh"
+RI="$specrepo/scripts/release-info.sh"
+trap 'rm -rf "$specrepo"' EXIT
 
 pass=0
 fail=0