From aca7dc462602077a46698c9ae80b7660d839aee6 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 25 Jun 2026 19:50:24 +0100 Subject: [PATCH] docs(readme): convert README.adoc -> Markdown README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README must be real Markdown to render in GitHub community-health, the GitHub profile, and external MCP directories (Glama) — AsciiDoc shows as raw markup there. pandoc asciidoc->GFM, badges fixed to clickable, SPDX header kept as an HTML comment, duplicate README.adoc removed. Co-Authored-By: Claude Opus 4.8 --- README.adoc | 111 ---------------------------------------------- README.md | 124 ++++++++++++++++++++++------------------------------ 2 files changed, 52 insertions(+), 183 deletions(-) delete mode 100644 README.adoc diff --git a/README.adoc b/README.adoc deleted file mode 100644 index 745aec1..0000000 --- a/README.adoc +++ /dev/null @@ -1,111 +0,0 @@ -= a2ml-validate-action -:toc: preamble -:icons: font - -== Overview - -**GitHub Action to validate A2ML manifest files in your repository.** - -A2ML (Agnostic Agent Markup Language) is a manifest format used across RSR -(Rhodium Standard Repository) projects to declare machine-readable metadata, -AI agent instructions, and project state. This action scans for `.a2ml` files -and validates their structure and required fields. - -== Checks Performed - -1. **SPDX header** — Verifies `SPDX-License-Identifier` is present in the first 10 lines -2. **Identity fields** — Requires `agent-id`, `name`, or `project` field (relaxed for AI-MANIFEST files) -3. **Version field** — Checks for `version` or `schema_version` -4. **Attestation blocks** — If an `[attestation]` section exists, validates it contains `proof`, `signature`, or `hash` fields -5. **Section syntax** — Warns on malformed `[section]` headings with unclosed brackets - -== Usage - -Add to your workflow: - -[source,yaml] ----- -name: Validate A2ML -on: [push, pull_request] - -permissions: - contents: read - -jobs: - validate: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: hyperpolymath/a2ml-validate-action@v1 - with: - path: '.' # Directory to scan (default: repo root) - strict: 'false' # Promote warnings to errors (default: false) - # paths-ignore: defaults to vendored / fixture patterns; override - # via newline-separated string. Use '' to disable. ----- - -=== Inputs - -[cols="1,1,3"] -|=== -| Input | Default | Description - -| `path` -| `.` -| Directory path to scan for `.a2ml` files - -| `strict` -| `false` -| When `true`, warnings become errors and the action fails on any issue - -| `paths-ignore` -| _vendored & fixture defaults_ -| Newline-separated path fragments to skip. Substring match against each - file path. Default set: `vendor/`, `vendored/`, `verified-container-spec/`, - `.audittraining/`, `integration/fixtures/`, `test/fixtures/`, - `tests/fixtures/`. Pass an empty string (`paths-ignore: ''`) to disable - and scan everything. See https://github.com/hyperpolymath/hypatia/pull/243 - for the architectural rationale (content-pattern validators must - distinguish targets from fixtures / vendored / training-corpus files - that legitimately contain the very pattern being checked). -|=== - -==== Why default-on path exemptions? - -A2ML files inside vendored projects (e.g. `verified-container-spec/`) have -their own identity declarations elsewhere or are themselves training corpora. -Flagging every such file as "missing identity field" is provenance noise, -not signal. The defaults match the canonical RSR vendored-content paths; -override for project-specific carve-outs. - -=== Outputs - -[cols="1,3"] -|=== -| Output | Description - -| `files-scanned` -| Number of `.a2ml` files processed - -| `errors` -| Count of validation errors - -| `warnings` -| Count of validation warnings -|=== - -== Strict Mode - -In strict mode (`strict: 'true'`), all warnings are promoted to errors. This -is useful for repositories that require full A2ML compliance, such as those -following the RSR standard. - -== Author - -Jonathan D.A. Jewell - -== License - -SPDX-License-Identifier: CC-BY-SA-4.0 - -See link:LICENSE[LICENSE] for details. diff --git a/README.md b/README.md index 4f55b16..b54f2bf 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,38 @@ -[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github)](https://github.com/sponsors/hyperpolymath) - -= a2ml-validate-action -:toc: preamble -:icons: font + -== Overview +# Overview **GitHub Action to validate A2ML manifest files in your repository.** -A2ML (Agnostic Agent Markup Language) is a manifest format used across RSR -(Rhodium Standard Repository) projects to declare machine-readable metadata, -AI agent instructions, and project state. This action scans for `.a2ml` files -and validates their structure and required fields. +A2ML (Agnostic Agent Markup Language) is a manifest format used across +RSR (Rhodium Standard Repository) projects to declare machine-readable +metadata, AI agent instructions, and project state. This action scans +for `.a2ml` files and validates their structure and required fields. + +# Checks Performed + +1. **SPDX header** — Verifies `SPDX-License-Identifier` is present in + the first 10 lines + +2. **Identity fields** — Requires `agent-id`, `name`, or `project` + field (relaxed for AI-MANIFEST files) + +3. **Version field** — Checks for `version` or `schema_version` -== Checks Performed +4. **Attestation blocks** — If an `[attestation]` section exists, + validates it contains `proof`, `signature`, or `hash` fields -1. **SPDX header** — Verifies `SPDX-License-Identifier` is present in the first 10 lines -2. **Identity fields** — Requires `agent-id`, `name`, or `project` field (relaxed for AI-MANIFEST files) -3. **Version field** — Checks for `version` or `schema_version` -4. **Attestation blocks** — If an `[attestation]` section exists, validates it contains `proof`, `signature`, or `hash` fields -5. **Section syntax** — Warns on malformed `[section]` headings with unclosed brackets +5. **Section syntax** — Warns on malformed `[section]` headings with + unclosed brackets -== Usage +# Usage Add to your workflow: -[source,yaml] ----- +```yaml name: Validate A2ML on: [push, pull_request] @@ -44,70 +50,44 @@ jobs: strict: 'false' # Promote warnings to errors (default: false) # paths-ignore: defaults to vendored / fixture patterns; override # via newline-separated string. Use '' to disable. ----- - -=== Inputs - -[cols="1,1,3"] -|=== -| Input | Default | Description - -| `path` -| `.` -| Directory path to scan for `.a2ml` files - -| `strict` -| `false` -| When `true`, warnings become errors and the action fails on any issue - -| `paths-ignore` -| _vendored & fixture defaults_ -| Newline-separated path fragments to skip. Substring match against each - file path. Default set: `vendor/`, `vendored/`, `verified-container-spec/`, - `.audittraining/`, `integration/fixtures/`, `test/fixtures/`, - `tests/fixtures/`. Pass an empty string (`paths-ignore: ''`) to disable - and scan everything. See https://github.com/hyperpolymath/hypatia/pull/243 - for the architectural rationale (content-pattern validators must - distinguish targets from fixtures / vendored / training-corpus files - that legitimately contain the very pattern being checked). -|=== - -==== Why default-on path exemptions? +``` -A2ML files inside vendored projects (e.g. `verified-container-spec/`) have -their own identity declarations elsewhere or are themselves training corpora. -Flagging every such file as "missing identity field" is provenance noise, -not signal. The defaults match the canonical RSR vendored-content paths; -override for project-specific carve-outs. +## Inputs -=== Outputs +| Input | Default | Description | +|----|----|----| +| `path` | `.` | Directory path to scan for `.a2ml` files | +| `strict` | `false` | When `true`, warnings become errors and the action fails on any issue | +| `paths-ignore` | *vendored & fixture defaults* | Newline-separated path fragments to skip. Substring match against each file path. Default set: `vendor/`, `vendored/`, `verified-container-spec/`, `.audittraining/`, `integration/fixtures/`, `test/fixtures/`, `tests/fixtures/`. Pass an empty string (`paths-ignore:` `’’`) to disable and scan everything. See for the architectural rationale (content-pattern validators must distinguish targets from fixtures / vendored / training-corpus files that legitimately contain the very pattern being checked). | -[cols="1,3"] -|=== -| Output | Description +### Why default-on path exemptions? -| `files-scanned` -| Number of `.a2ml` files processed +A2ML files inside vendored projects (e.g. `verified-container-spec/`) +have their own identity declarations elsewhere or are themselves +training corpora. Flagging every such file as "missing identity field" +is provenance noise, not signal. The defaults match the canonical RSR +vendored-content paths; override for project-specific carve-outs. -| `errors` -| Count of validation errors +## Outputs -| `warnings` -| Count of validation warnings -|=== +| Output | Description | +|-----------------|-----------------------------------| +| `files-scanned` | Number of `.a2ml` files processed | +| `errors` | Count of validation errors | +| `warnings` | Count of validation warnings | -== Strict Mode +# Strict Mode -In strict mode (`strict: 'true'`), all warnings are promoted to errors. This -is useful for repositories that require full A2ML compliance, such as those -following the RSR standard. +In strict mode (`strict:` `’true’`), all warnings are promoted to +errors. This is useful for repositories that require full A2ML +compliance, such as those following the RSR standard. -== Author +# Author -Jonathan D.A. Jewell +Jonathan D.A. Jewell \<[j.d.a.jewell@open.ac](j.d.a.jewell@open.ac).uk\> -== License +# License SPDX-License-Identifier: CC-BY-SA-4.0 -See link:LICENSE[LICENSE] for details. +See [LICENSE](LICENSE) for details.