Skip to content

docs(readme): convert README.adoc -> Markdown (renders on Glama/profile/community-health) #46

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hyperpolymath merged 1 commit into from
Jun 25, 2026
+52 −183
Merged

docs(readme): convert README.adoc -> Markdown (renders on Glama/profile/community-health) #46

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 0 additions & 111 deletions README.adoc
View file
Open in desktop

This file was deleted.

124 changes: 52 additions & 72 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
<!--
SPDX-License-Identifier: CC-BY-SA-4.0
SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
-->

== 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]

Expand All @@ -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 <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). |

[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 <j.d.a.jewell@open.ac.uk>
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.
Loading