Validate the specification: quality gates, schema conformance and a repository-wide sweep

.editorconfig

@@ -0,0 +1,31 @@
+# Editor defaults for the ÆON Protocol repository.
+#
+# These mirror what the repository already enforces elsewhere: .gitattributes
+# normalises line endings to LF, .markdownlint.jsonc leaves MD009 (no trailing
+# spaces) on, and CONTRIBUTING.md requires two-space YAML indentation with no
+# tabs. This file makes an editor do it before a check has to complain.
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{yaml,yml}]
+indent_style = space
+indent_size = 2
+
+# The Charisma fixture is preserved and derived byte-for-byte from the sources
+# (CONTRIBUTING.md ground rule 4). .gitattributes marks the originals -text so
+# Git never converts them, and the documentation workflow exempts the whole
+# fixture from its whitespace check. No editor may normalise it on save either.
+[products/learn/examples/charisma/**]
+charset = unset
+end_of_line = unset
+indent_style = unset
+indent_size = unset
+insert_final_newline = unset
+trim_trailing_whitespace = false

.gitattributes

@@ -1,10 +1,16 @@
 # Normalise line endings to LF in the repository.
+# .editorconfig sets the same rule for editors that read one; the two files must agree.
 * text=auto eol=lf
 
 # The preserved Charisma originals must stay byte-identical on every platform:
 # no line-ending conversion, ever (checksums are documented in source-map.md).
 products/learn/examples/charisma/original/* -text
 
+# Lockfiles are committed because npm ci needs them, but they are generated:
+# keep them out of diffs and out of language statistics.
+package-lock.json linguist-generated=true -diff
+site/learn/package-lock.json linguist-generated=true -diff
+
 # Binaries
 *.png binary
 *.jpg binary

.github/ISSUE_TEMPLATE/conformance-report.yml

@@ -24,22 +24,15 @@ body:
     attributes:
       label: Specification version
       description: The release tag the agent fetched, or "main" if you read the branch directly.
-      placeholder: v0.2.0
+      placeholder: v0.3.0
     validations:
       required: true
-  - type: dropdown
+  - type: input
     id: case
     attributes:
       label: Eval case
-      options:
-        - eval-01 discovery first
-        - eval-02 subject outside the library
-        - eval-03 no scheduling capability
-        - eval-04 known fundamentals
-        - eval-05 contested subject
-        - eval-06 no web access
-        - Topic-independence smoke prompt
-        - Free invocation, no case
+      description: The case id from evals/learn/cases/, for example eval-03. Write "none" for a free invocation that no case covers, or "smoke" for the topic-independence smoke prompt.
+      placeholder: eval-03
     validations:
       required: true
   - type: input
@@ -79,6 +72,18 @@ body:
       description: Paste the exchange that demonstrates the violation, in a fenced code block. Remove anything personal you do not want published.
     validations:
       required: true
+  - type: dropdown
+    id: reproducibility
+    attributes:
+      label: Reproducibility
+      description: Agent output varies between runs, so one transcript is an anecdote. Say how many fresh sessions you tried and how many showed the violation.
+      options:
+        - Every fresh session I tried (three or more)
+        - Most fresh sessions (at least two of three)
+        - Once, and I could not reproduce it
+        - I only ran it once
+    validations:
+      required: true
   - type: dropdown
     id: verdict
     attributes:

.github/ISSUE_TEMPLATE/library-package.yml

@@ -10,11 +10,21 @@ body:
         and documented misconceptions — not a finished course. Packages accelerate known subjects
         and never limit the protocol (`LIB-1`). The anatomy and the contribution rules are in
         [library/README.md](https://github.com/marcelrapold/aeon-protocol/blob/main/library/README.md).
+  - type: dropdown
+    id: kind
+    attributes:
+      label: Proposal type
+      description: A new package and a change to an existing one get reviewed differently.
+      options:
+        - A new package
+        - A substantial change to an existing package
+    validations:
+      required: true
   - type: input
     id: slug
     attributes:
       label: Package slug
-      description: ASCII, lowercase, hyphenated. This becomes the directory name under library/.
+      description: ASCII, lowercase, hyphenated. This is the directory name under library/ — the existing one for a change, the new one for a new package.
       placeholder: monetary-history
     validations:
       required: true
@@ -48,6 +58,14 @@ body:
         - Tier 2 — Author, Title (year) — https://…
     validations:
       required: true
+  - type: input
+    id: overlap
+    attributes:
+      label: Overlap with existing packages
+      description: Name the packages that already cover part of this subject, and say where the boundary lies. Write "none" if there is genuinely no overlap.
+      placeholder: business-cycles covers the credit cycle; this package covers the monetary institutions behind it
+    validations:
+      required: true
   - type: textarea
     id: knowledge-map
     attributes:

.github/ISSUE_TEMPLATE/specification-change.yml

@@ -31,6 +31,7 @@ body:
         - library/ (package rules, not a single package)
         - schemas/
         - evals/learn/
+        - protocol/ and products/learn/ together
     validations:
       required: true
   - type: input
@@ -61,6 +62,19 @@ body:
       placeholder: "**LEARN-D-12** — The agent MUST ask for the learner's time budget before …"
     validations:
       required: true
+  - type: textarea
+    id: scoring
+    attributes:
+      label: How an eval would score it
+      description: Describe the observable behaviour a scorer would look for in a transcript, and what a failure looks like. A requirement no eval can fail is decoration.
+      placeholder: PASS when the agent names its time budget question before proposing modules; FAIL when …
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: The wordings or designs you rejected, and why. Normative wording is usually a choice between several defensible sentences.
   - type: textarea
     id: rationale
     attributes:
@@ -88,3 +102,4 @@ body:
         - label: An eval case in evals/learn/cases/ changes or is added.
         - label: The bootstrap and site/learn/public/llms.txt change.
         - label: The Charisma fixture or its integration notes are affected.
+        - label: An architecture decision record in docs/decisions/ should record the reasoning.

.github/PULL_REQUEST_TEMPLATE.md

@@ -2,6 +2,8 @@
 
 <!-- Two or three sentences, conclusion first: what changes and why it earns its place. -->
 
+Closes <!-- issue number, or "no issue" with a sentence on why this needs none -->
+
 ## Type of change
 
 <!-- Tick every box that applies. -->
@@ -12,7 +14,8 @@
 - [ ] JSON Schema (`schemas/`)
 - [ ] Eval case or rubric (`evals/`)
 - [ ] Invocation surface (`site/learn/`)
-- [ ] Documentation, decision record or tooling
+- [ ] Validation toolchain or release tooling (`tools/`, `scripts/`)
+- [ ] Documentation, decision record or repository configuration
 
 ## Requirement identifiers
 
@@ -30,20 +33,35 @@
 - [ ] Patch — editorial only, no behaviour change
 - [ ] None — no versioned surface touched
 
-## Checks
+## What an agent sees differently
+
+<!-- One or two sentences on the observable behaviour change, or "nothing" for a non-normative
+     change. If a conforming agent would act differently after this merges, say how it would show
+     up in a transcript. -->
+
+## Local gate
+
+<!-- Run the gate and paste the result. A tick without output is not evidence. -->
 
-<!-- Paste the commands you ran and their result. -->
+```text
+paste the output of: npm run validate
+```
 
-- [ ] `npx markdownlint-cli2 "**/*.md" "!site/learn/node_modules/**"` passes
-- [ ] Internal links resolve to files that exist
-- [ ] `npm ci && npm run lint && npm run typecheck && npm run test && npm run build` passes in `site/learn/` (only if the site changed)
+- [ ] `npm run validate` passes on a clean clone
+- [ ] `npx markdownlint-cli2 "**/*.md" "!**/node_modules/**" "!products/learn/examples/charisma/original/**" "!products/learn/examples/charisma/sessions/**" "!products/learn/examples/charisma/integration.md"` passes
+- [ ] `npm run lint && npm run typecheck && npm run test && npm run build` passes in `site/learn/` (only if the site changed)
+- [ ] `node scripts/bump-version.mjs --check` passes (only if a pinned URL, version banner or version constant moved)
 
 ## Checklist
 
 - [ ] No requirement depends on the proprietary behaviour of one model vendor; capability-dependent
       behaviour sits behind capability negotiation.
+- [ ] Every new or changed requirement is observable in a transcript, and an eval case can score it.
 - [ ] Specifications and the JSON Schemas they describe change together in this pull request.
+- [ ] The bootstrap and `site/learn/public/llms.txt` still agree with the specifications, and with
+      each other.
 - [ ] Files under `products/learn/examples/charisma/original/` remain byte-identical.
+- [ ] Every source I cite is real, reachable and says what I claim it says.
 - [ ] `CHANGELOG.md` records the change under `Unreleased`.
 - [ ] Prose follows the house style: second person, present tense, active voice, sentence-case
       headings, no emojis, and ÆON spelled with the ligature while slugs and URLs stay ASCII.

.github/dependabot.yml

@@ -0,0 +1,49 @@
+version: 2
+
+updates:
+  # The actions this repository's own CI trusts. Pinned to digests, so an
+  # update is a reviewable pull request rather than a tag someone moved.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: '06:00'
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: 'CI:'
+    groups:
+      actions:
+        patterns: ['*']
+
+  # The validation toolchain.
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: '06:00'
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: 'Tools:'
+    groups:
+      validators:
+        patterns: ['*']
+
+  # The invocation surface.
+  - package-ecosystem: npm
+    directory: /site/learn
+    schedule:
+      interval: weekly
+      day: monday
+      time: '06:00'
+    open-pull-requests-limit: 10
+    commit-message:
+      prefix: 'Site:'
+    groups:
+      react:
+        patterns: ['react', 'react-dom', '@types/react', '@types/react-dom']
+      next:
+        patterns: ['next', 'eslint-config-next']
+      tooling:
+        dependency-type: development

.github/workflows/codeql.yml

@@ -0,0 +1,46 @@
+name: codeql
+
+# The invocation surface is the only executable surface this repository ships,
+# so it is the only thing CodeQL has to analyse.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '31 4 * * 2'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: codeql-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  analyze:
+    name: analyze javascript-typescript
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      actions: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Initialise CodeQL
+        uses: github/codeql-action/init@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
+        with:
+          languages: javascript-typescript
+          # Nothing is compiled: the site is a static Next.js build and the
+          # validators are plain ESM.
+          build-mode: none
+          queries: security-and-quality
+      - name: Analyse
+        uses: github/codeql-action/analyze@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
+        with:
+          category: /language:javascript-typescript

.github/workflows/dependency-review.yml

@@ -0,0 +1,61 @@
+name: dependency review
+
+# Runs on pull requests only: it compares the dependency manifests of the base
+# and head commits, so it needs two commits to compare.
+
+on:
+  pull_request:
+    paths:
+      - '**/package.json'
+      - '**/package-lock.json'
+      - .github/workflows/dependency-review.yml
+
+permissions:
+  contents: read
+
+concurrency:
+  group: dependency-review-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  review:
+    name: review dependency changes
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Check whether the dependency graph is available
+        id: graph
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -uo pipefail
+          # Dependency review needs the dependency graph, which is a repository
+          # setting rather than anything a pull request can carry. Detecting it
+          # keeps this job honest: it warns while the feature is off and starts
+          # enforcing by itself the moment somebody enables it.
+          code=$(curl -s -o /dev/null -w '%{http_code}' \
+            -H "Authorization: Bearer $GH_TOKEN" \
+            -H "Accept: application/vnd.github+json" \
+            "https://api.github.com/repos/${GITHUB_REPOSITORY}/dependency-graph/sbom")
+          if [ "$code" = "200" ]; then
+            echo "enabled=true" >> "$GITHUB_OUTPUT"
+            echo "Dependency graph is enabled; reviewing dependency changes."
+          else
+            echo "enabled=false" >> "$GITHUB_OUTPUT"
+            echo "::warning::Dependency review is inactive: the dependency graph is not enabled for this repository (HTTP $code). Enable it under Settings, Code security, to turn this check on."
+          fi
+
+      - uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0
+        if: steps.graph.outputs.enabled == 'true'
+        with:
+          fail-on-severity: high
+          # The repository is Apache-2.0. A network-copyleft dependency would
+          # be incompatible with how the specification and the site are
+          # distributed; the weaker copyleft licences are left to review.
+          deny-licenses: AGPL-3.0, AGPL-3.0-only, AGPL-3.0-or-later
+          comment-summary-in-pr: on-failure