From 4868dfa352d70a4517091020e1914d8ded0a3719 Mon Sep 17 00:00:00 2001
From: Vito <5780819+Tapanito@users.noreply.github.com>
Date: Wed, 4 Mar 2026 13:51:29 +0100
Subject: [PATCH 1/4] adds copilot review instructions

---
 .github/copilot-instructions.md | 158 ++++++++++++++++++++++++++++++++
 1 file changed, 158 insertions(+)
 create mode 100644 .github/copilot-instructions.md

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 000000000..e65e9fec4
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,158 @@
+# GitHub Copilot Instructions for XRPL-Standards
+
+## Repository Summary
+
+**Documentation-only** repository for XRP Ledger Standards (XLSes) — Markdown specification documents plus Python validation/site-generation scripts and GitHub Actions CI. No application code to compile. Trust these instructions; only search if something here is incomplete or in error.
+
+## Project Layout
+
+| Path                                 | Purpose                                                               |
+| ------------------------------------ | --------------------------------------------------------------------- |
+| `XLS-NNNN-short-title/README.md`     | One specification per standard (74 total)                             |
+| `templates/XLS_TEMPLATE.md`          | Base template for all new XLS specs                                   |
+| `templates/AMENDMENT_TEMPLATE.md`    | Specification section structure for Amendment XLSes                   |
+| `scripts/xls_parser.py`              | Parses and validates preambles of all XLS docs (main CI)              |
+| `scripts/validate_xls_template.py`   | Validates structure of changed files (Beta CI)                        |
+| `scripts/requirements.txt`           | Python deps: markdown, jinja2, beautifulsoup4, pyyaml, markdown-it-py |
+| `.github/workflows/lint.yml`         | prettier@3.6.2 check — **required on every PR**                       |
+| `.github/workflows/validate-xls.yml` | xls_parser + template validator — **required on every PR**            |
+| `.pre-commit-config.yaml`            | prettier@3.6.2 + trailing-whitespace, end-of-file-fixer               |
+
+## XLS Preamble Format
+
+Every `README.md` must open with a `<pre>` block (the `xls_parser.py` CI reads it):
+
+```
+<pre>
+  xls: [number]
+  title: [max 44 chars, no "XLS" prefix or number]
+  description: [one full sentence]
+  author: [Name <email@example.com>, Name2 (@github-handle)]
+  category: [Amendment | System | Ecosystem | Meta]
+  status: [Draft | Final | Living | Deprecated | Stagnant | Withdrawn]
+  proposal-from: [URL to GitHub Discussions thread]
+  created: YYYY-MM-DD
+  updated: YYYY-MM-DD          ← optional
+  implementation: [URL]        ← optional; required for Final Amendment/System
+  requires: XLS-N, XLS-M      ← optional
+  withdrawal-reason: [text]    ← required if status is Withdrawn
+</pre>
+```
+
+Every author **must** have a link — `Name <email>` or `Name (@github-handle)`; a bare name fails CI.
+
+## Template Compliance
+
+> **Always read the actual template files before reviewing or writing any XLS specification.** The structure documented below reflects the templates at the time these instructions were written; the files are the authoritative source and may have been updated since.
+>
+> - `templates/XLS_TEMPLATE.md` — top-level section structure for all XLS types
+> - `templates/AMENDMENT_TEMPLATE.md` — Specification section structure for Amendment XLSes
+
+## XLS_TEMPLATE.md — Required Top-Level Sections
+
+```
+## 1. Abstract                     ← required
+## 2. Motivation                   ← optional
+## 3. Specification                ← required; for Amendment use AMENDMENT_TEMPLATE.md
+## 4. Rationale                    ← required
+## 5. Backwards Compatibility      ← optional (required if incompatibilities exist)
+## 6. Test Plan                    ← optional (required for Amendment/System)
+## 7. Reference Implementation     ← optional
+## 8. Security Considerations      ← required (XLS rejected without it)
+# Appendix                         ← optional
+```
+
+## AMENDMENT_TEMPLATE.md — Specification Section Structure
+
+For Amendment-category XLSes, `## 3. Specification` contains components as `### 3.N. ComponentType: \`Name\``subsections. Each component has numbered sub-subsections`#### 3.N.M.` and deeper.
+
+### Ledger Entry (`### 3.N. Ledger Entry: \`Name\``)
+
+| Sub | Heading             | Notes                                                                                                                                                                                        |
+| --- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| .1  | `Object Identifier` | Optional if entry already on mainnet. **Key Space:** `0x[XXXX]`; **ID Calculation Algorithm:**                                                                                               |
+| .2  | `Fields`            | See table schema below. Standard rows always present: `LedgerEntryType`, `Account`, `OwnerNode`, `PreviousTxnID`, `PreviousTxnLgrSeq`. Field detail sub-subsections at `##### 3.N.2.1.` etc. |
+| .3  | `Flags`             | Optional if none. Flag names use `lsf` prefix. See Flags table schema.                                                                                                                       |
+| .4  | `Ownership`         | Optional if existing. **Owner:**; **Directory Registration:**                                                                                                                                |
+| .5  | `Reserves`          | Optional if existing. **Reserve Requirement:** `[Standard/Custom/None]`                                                                                                                      |
+| .6  | `Deletion`          | Optional if existing. **Deletion Transactions:**; **Deletion Conditions:** bullet list; **Account Deletion Blocker:** `[Yes/No]`                                                             |
+| .7  | `Pseudo-Account`    | Optional. **Uses Pseudo-Account:** `[Yes/No]`; Purpose, AccountID Derivation, Capabilities                                                                                                   |
+| .8  | `Freeze/Lock`       | Optional. **Freeze Support:**; **Lock Support:**                                                                                                                                             |
+| .9  | `Invariants`        | Bullet list. Use `<object>` for before-state, `<object>'` for after-state                                                                                                                    |
+| .10 | `RPC Name`          | Optional if existing. **RPC Type Name:** `snake_case_name`                                                                                                                                   |
+| .11 | `Example JSON`      | ` ```json ` block                                                                                                                                                                            |
+
+**Ledger Entry Fields table columns (exact):**
+
+```
+| Field Name | Constant | Required | Internal Type | Default Value | Description |
+```
+
+### Transaction (`### 3.N. Transaction: \`Name\``)
+
+Naming convention: `<LedgerEntryName><Verb>` (e.g., `VaultCreate`, `VaultDelete`).
+
+| Sub | Heading              | Notes                                                                                                                |
+| --- | -------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| .1  | `Fields`             | See table schema below. Always includes `TransactionType` row. Field detail sub-subsections at `##### 3.N.1.1.` etc. |
+| .2  | `Flags`              | Optional if none. Flag names use `tf` prefix. See Flags table schema.                                                |
+| .3  | `Transaction Fee`    | Optional if existing. **Fee Structure:** `[Standard/Custom]`                                                         |
+| .4  | `Failure Conditions` | **Two mandatory sub-subsections** (see below)                                                                        |
+| .5  | `State Changes`      | **On Success (`tesSUCCESS`):** bold label followed by bullet list                                                    |
+| .6  | `Metadata Fields`    | Optional. See table schema below.                                                                                    |
+| .7  | `Example JSON`       | ` ```json ` block                                                                                                    |
+
+**Transaction Fields table columns (exact):**
+
+```
+| Field Name | Required? | JSON Type | Internal Type | Default Value | Description |
+```
+
+**Failure Conditions structure — always two sub-subsections with numbered lists:**
+
+```markdown
+##### 3.N.4.1. Data Verification
+
+[All Data Verification failures return a `tem` level error.]
+
+1. [condition description] (`[ERROR_CODE]`)
+2. [condition description] (`[ERROR_CODE]`)
+
+##### 3.N.4.2. Protocol-Level Failures
+
+[Protocol-level failures return `tec` codes ...]
+
+1. [condition description] (`[ERROR_CODE]`)
+```
+
+### Permission (`### 3.N. Permission: \`Name\``)
+
+Sub-subsections: `.1. Permission Description`, `.2. Transaction Types Affected`, `.3. Permission Value`
+
+### RPC (`### 3.N. RPC: \`method_name\``)
+
+| Sub | Heading              | Notes                                            |
+| --- | -------------------- | ------------------------------------------------ |
+| .1  | `Request Fields`     | Always includes `command` row. See table schema. |
+| .2  | `Response Fields`    | Always includes `status` row. See table schema.  |
+| .3  | `Failure Conditions` | Single numbered list (no sub-subsections)        |
+| .4  | `Example Request`    | ` ```json ` block                                |
+| .5  | `Example Response`   | ` ```json ` block                                |
+
+### Table Schemas (exact column headings)
+
+| Table                | Columns                                                                                 |
+| -------------------- | --------------------------------------------------------------------------------------- |
+| Ledger Entry Fields  | `Field Name \| Constant \| Required \| Internal Type \| Default Value \| Description`   |
+| Transaction Fields   | `Field Name \| Required? \| JSON Type \| Internal Type \| Default Value \| Description` |
+| Flags (both)         | `Flag Name \| Flag Value \| Description`                                                |
+| RPC Request Fields   | `Field Name \| Required? \| JSON Type \| Description`                                   |
+| RPC Response Fields  | `Field Name \| Always Present? \| JSON Type \| Description`                             |
+| Transaction Metadata | `Field Name \| Validated \| Always Present? \| Type \| Description`                     |
+
+## Key Rules
+
+- **No unfilled placeholders** — `validate_xls_template.py` rejects patterns like `[FieldName]`, `[example value]`, `_[Describe...]`, `0x[XXXX]`, `[r-address]`, `[Yes/No]`, etc.
+- **New draft directories** use `XLS-draft-<short-title>/` — the CI bot assigns the number; editors rename before merge.
+- **`scripts/_site/` is gitignored** — never commit build output.
+- Always run `python scripts/xls_parser.py` after any preamble change; it validates all docs and exits 1 on error.

From f326d17508e69c4f04d7bcbe6bd52c58d4922679 Mon Sep 17 00:00:00 2001
From: Vito <5780819+Tapanito@users.noreply.github.com>
Date: Thu, 30 Apr 2026 10:58:59 +0200
Subject: [PATCH 2/4] adds improved copilot instructions

---
 .github/copilot-instructions.md | 108 ++------------------------------
 1 file changed, 4 insertions(+), 104 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index e65e9fec4..23b5f1c08 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -43,112 +43,12 @@ Every author **must** have a link — `Name <email>` or `Name (@github-handle)`;
 
 ## Template Compliance
 
-> **Always read the actual template files before reviewing or writing any XLS specification.** The structure documented below reflects the templates at the time these instructions were written; the files are the authoritative source and may have been updated since.
+> **Always read the actual template files before reviewing or writing any XLS specification.** The templates are the single source of truth for section structure, sub-section ordering, table column headings, and naming conventions. Do not rely on summaries — open the files directly.
 >
 > - `templates/XLS_TEMPLATE.md` — top-level section structure for all XLS types
-> - `templates/AMENDMENT_TEMPLATE.md` — Specification section structure for Amendment XLSes
-
-## XLS_TEMPLATE.md — Required Top-Level Sections
-
-```
-## 1. Abstract                     ← required
-## 2. Motivation                   ← optional
-## 3. Specification                ← required; for Amendment use AMENDMENT_TEMPLATE.md
-## 4. Rationale                    ← required
-## 5. Backwards Compatibility      ← optional (required if incompatibilities exist)
-## 6. Test Plan                    ← optional (required for Amendment/System)
-## 7. Reference Implementation     ← optional
-## 8. Security Considerations      ← required (XLS rejected without it)
-# Appendix                         ← optional
-```
-
-## AMENDMENT_TEMPLATE.md — Specification Section Structure
-
-For Amendment-category XLSes, `## 3. Specification` contains components as `### 3.N. ComponentType: \`Name\``subsections. Each component has numbered sub-subsections`#### 3.N.M.` and deeper.
-
-### Ledger Entry (`### 3.N. Ledger Entry: \`Name\``)
-
-| Sub | Heading             | Notes                                                                                                                                                                                        |
-| --- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| .1  | `Object Identifier` | Optional if entry already on mainnet. **Key Space:** `0x[XXXX]`; **ID Calculation Algorithm:**                                                                                               |
-| .2  | `Fields`            | See table schema below. Standard rows always present: `LedgerEntryType`, `Account`, `OwnerNode`, `PreviousTxnID`, `PreviousTxnLgrSeq`. Field detail sub-subsections at `##### 3.N.2.1.` etc. |
-| .3  | `Flags`             | Optional if none. Flag names use `lsf` prefix. See Flags table schema.                                                                                                                       |
-| .4  | `Ownership`         | Optional if existing. **Owner:**; **Directory Registration:**                                                                                                                                |
-| .5  | `Reserves`          | Optional if existing. **Reserve Requirement:** `[Standard/Custom/None]`                                                                                                                      |
-| .6  | `Deletion`          | Optional if existing. **Deletion Transactions:**; **Deletion Conditions:** bullet list; **Account Deletion Blocker:** `[Yes/No]`                                                             |
-| .7  | `Pseudo-Account`    | Optional. **Uses Pseudo-Account:** `[Yes/No]`; Purpose, AccountID Derivation, Capabilities                                                                                                   |
-| .8  | `Freeze/Lock`       | Optional. **Freeze Support:**; **Lock Support:**                                                                                                                                             |
-| .9  | `Invariants`        | Bullet list. Use `<object>` for before-state, `<object>'` for after-state                                                                                                                    |
-| .10 | `RPC Name`          | Optional if existing. **RPC Type Name:** `snake_case_name`                                                                                                                                   |
-| .11 | `Example JSON`      | ` ```json ` block                                                                                                                                                                            |
-
-**Ledger Entry Fields table columns (exact):**
-
-```
-| Field Name | Constant | Required | Internal Type | Default Value | Description |
-```
-
-### Transaction (`### 3.N. Transaction: \`Name\``)
-
-Naming convention: `<LedgerEntryName><Verb>` (e.g., `VaultCreate`, `VaultDelete`).
-
-| Sub | Heading              | Notes                                                                                                                |
-| --- | -------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| .1  | `Fields`             | See table schema below. Always includes `TransactionType` row. Field detail sub-subsections at `##### 3.N.1.1.` etc. |
-| .2  | `Flags`              | Optional if none. Flag names use `tf` prefix. See Flags table schema.                                                |
-| .3  | `Transaction Fee`    | Optional if existing. **Fee Structure:** `[Standard/Custom]`                                                         |
-| .4  | `Failure Conditions` | **Two mandatory sub-subsections** (see below)                                                                        |
-| .5  | `State Changes`      | **On Success (`tesSUCCESS`):** bold label followed by bullet list                                                    |
-| .6  | `Metadata Fields`    | Optional. See table schema below.                                                                                    |
-| .7  | `Example JSON`       | ` ```json ` block                                                                                                    |
-
-**Transaction Fields table columns (exact):**
-
-```
-| Field Name | Required? | JSON Type | Internal Type | Default Value | Description |
-```
-
-**Failure Conditions structure — always two sub-subsections with numbered lists:**
-
-```markdown
-##### 3.N.4.1. Data Verification
-
-[All Data Verification failures return a `tem` level error.]
-
-1. [condition description] (`[ERROR_CODE]`)
-2. [condition description] (`[ERROR_CODE]`)
-
-##### 3.N.4.2. Protocol-Level Failures
-
-[Protocol-level failures return `tec` codes ...]
-
-1. [condition description] (`[ERROR_CODE]`)
-```
-
-### Permission (`### 3.N. Permission: \`Name\``)
-
-Sub-subsections: `.1. Permission Description`, `.2. Transaction Types Affected`, `.3. Permission Value`
-
-### RPC (`### 3.N. RPC: \`method_name\``)
-
-| Sub | Heading              | Notes                                            |
-| --- | -------------------- | ------------------------------------------------ |
-| .1  | `Request Fields`     | Always includes `command` row. See table schema. |
-| .2  | `Response Fields`    | Always includes `status` row. See table schema.  |
-| .3  | `Failure Conditions` | Single numbered list (no sub-subsections)        |
-| .4  | `Example Request`    | ` ```json ` block                                |
-| .5  | `Example Response`   | ` ```json ` block                                |
-
-### Table Schemas (exact column headings)
-
-| Table                | Columns                                                                                 |
-| -------------------- | --------------------------------------------------------------------------------------- |
-| Ledger Entry Fields  | `Field Name \| Constant \| Required \| Internal Type \| Default Value \| Description`   |
-| Transaction Fields   | `Field Name \| Required? \| JSON Type \| Internal Type \| Default Value \| Description` |
-| Flags (both)         | `Flag Name \| Flag Value \| Description`                                                |
-| RPC Request Fields   | `Field Name \| Required? \| JSON Type \| Description`                                   |
-| RPC Response Fields  | `Field Name \| Always Present? \| JSON Type \| Description`                             |
-| Transaction Metadata | `Field Name \| Validated \| Always Present? \| Type \| Description`                     |
+> - `templates/AMENDMENT_TEMPLATE.md` — Specification section structure for Amendment XLSes (Ledger Entries, Transactions, Permissions, RPCs, and their required table schemas)
+>
+> When reviewing or authoring a spec, diff the document against the relevant template to catch missing sections, wrong table columns, or incorrect heading numbering.
 
 ## Key Rules
 

From bd55d1129470cc88e9a9309e30edda84264342a5 Mon Sep 17 00:00:00 2001
From: Vito Tumas <5780819+Tapanito@users.noreply.github.com>
Date: Mon, 4 May 2026 16:26:33 +0200
Subject: [PATCH 3/4] Revise Copilot instructions for XRPL-Standards

Updated instructions for Copilot Cloud Agent in XRPL-Standards repository, including repository purpose, layout, and key rules.

Co-authored-by: mvadari <mvadari@gmail.com>
---
 .github/copilot-instructions.md | 159 ++++++++++++++++++++++++--------
 1 file changed, 121 insertions(+), 38 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 23b5f1c08..87975e407 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,58 +1,141 @@
-# GitHub Copilot Instructions for XRPL-Standards
+# Copilot Cloud Agent Instructions — XRPL-Standards
 
-## Repository Summary
+## Repository Purpose
 
-**Documentation-only** repository for XRP Ledger Standards (XLSes) — Markdown specification documents plus Python validation/site-generation scripts and GitHub Actions CI. No application code to compile. Trust these instructions; only search if something here is incomplete or in error.
+This repository is the canonical home for **XRP Ledger Standards (XLSes)** — specifications and standards that govern the XRP Ledger ecosystem. Each XLS is a living document covering protocol amendments, system-level changes, or community/off-chain conventions. The full process is defined in [XLS-0001](../XLS-0001-xls-process/README.md) and summarized in [CONTRIBUTING.md](../CONTRIBUTING.md).
 
-## Project Layout
+---
 
-| Path                                 | Purpose                                                               |
-| ------------------------------------ | --------------------------------------------------------------------- |
-| `XLS-NNNN-short-title/README.md`     | One specification per standard (74 total)                             |
-| `templates/XLS_TEMPLATE.md`          | Base template for all new XLS specs                                   |
-| `templates/AMENDMENT_TEMPLATE.md`    | Specification section structure for Amendment XLSes                   |
-| `scripts/xls_parser.py`              | Parses and validates preambles of all XLS docs (main CI)              |
-| `scripts/validate_xls_template.py`   | Validates structure of changed files (Beta CI)                        |
-| `scripts/requirements.txt`           | Python deps: markdown, jinja2, beautifulsoup4, pyyaml, markdown-it-py |
-| `.github/workflows/lint.yml`         | prettier@3.6.2 check — **required on every PR**                       |
-| `.github/workflows/validate-xls.yml` | xls_parser + template validator — **required on every PR**            |
-| `.pre-commit-config.yaml`            | prettier@3.6.2 + trailing-whitespace, end-of-file-fixer               |
+## Repository Layout
 
-## XLS Preamble Format
+```
+/
+├── XLS-NNNN-slug/          # One folder per XLS spec (4-digit zero-padded number + hyphenated title)
+│   └── README.md           # The XLS document itself (required)
+├── templates/
+│   ├── XLS_TEMPLATE.md     # Preamble + section scaffold for all new XLSes
+│   └── AMENDMENT_TEMPLATE.md  # Extra scaffold for Amendment-category XLSes (Section 3 onward)
+├── scripts/
+│   ├── requirements.txt    # Python deps (install with: pip install -r scripts/requirements.txt)
+│   ├── xls_parser.py       # Parses XLS README.md files and validates preamble metadata
+│   ├── validate_xls_template.py  # Validates XLS structure against templates (Beta CI)
+│   └── build_site.py       # Builds the GitHub Pages static site from XLS docs
+├── CONTRIBUTING.md         # How to contribute (summarises XLS-1)
+└── .github/
+    ├── pull_request_template.md
+    ├── workflows/           # CI workflows (see below)
+    └── scripts/             # Scripts used by CI (assign_xls_number.py, etc.)
+```
+
+---
+
+## XLS Document Format
 
-Every `README.md` must open with a `<pre>` block (the `xls_parser.py` CI reads it):
+Every XLS lives at `XLS-NNNN-slug/README.md` and **must** start with an RFC-822-style `<pre>` preamble block:
 
 ```
 <pre>
   xls: [number]
-  title: [max 44 chars, no "XLS" prefix or number]
-  description: [one full sentence]
-  author: [Name <email@example.com>, Name2 (@github-handle)]
+  title: [max 44 chars, no "XLS" prefix]
+  description: [max 140 chars, one sentence]
+  author: Name (@github-handle), Other Name <email@example.com>
   category: [Amendment | System | Ecosystem | Meta]
   status: [Draft | Final | Living | Deprecated | Stagnant | Withdrawn]
-  proposal-from: [URL to GitHub Discussions thread]
+  proposal-from: https://github.com/XRPLF/XRPL-Standards/discussions/NNN
   created: YYYY-MM-DD
-  updated: YYYY-MM-DD          ← optional
-  implementation: [URL]        ← optional; required for Final Amendment/System
-  requires: XLS-N, XLS-M      ← optional
-  withdrawal-reason: [text]    ← required if status is Withdrawn
+  updated: YYYY-MM-DD          # optional
+  implementation: [url]        # optional, for Amendment/System XLSes
+  requires: [xls numbers]      # optional
+  withdrawal-reason: [reason]  # required only when status is Withdrawn
 </pre>
 ```
 
-Every author **must** have a link — `Name <email>` or `Name (@github-handle)`; a bare name fails CI.
+**Required sections** (all XLSes): Abstract, Rationale, Security Considerations.
+**Amendment XLSes** additionally require the sub-structure from `AMENDMENT_TEMPLATE.md` covering STypes, Ledger Entries, Transactions, Permissions, and RPCs as applicable.
+
+### Categories
+
+| Category | Description |
+|----------|-------------|
+| `Amendment` | Requires an XRP Ledger amendment (on-chain protocol change via rippled) |
+| `System` | Affects XRPL protocol behavior (RPCs, P2P) but no amendment needed |
+| `Ecosystem` | Off-chain/community standards (metadata, registries, etc.) |
+| `Meta` | Standards about the XLS process itself |
+
+### Statuses
+
+`Idea` → `Proposal` → `Draft` → `Final` or `Living`
+
+Also: `Deprecated` (Final XLS no longer recommended), `Stagnant` (Draft inactive ≥6 months), `Withdrawn` (removed by author — number cannot be reused).
+
+---
+
+## How to Add a New XLS
+
+1. Start in GitHub Discussions (Idea or Proposal stage) — do **not** open a PR until there is community feedback.
+2. Create a directory named `XLS-draft-<short-title>/` (agents/authors must NOT self-assign numbers for XLS numbers > 95).
+3. Copy `templates/XLS_TEMPLATE.md` to `XLS-draft-<short-title>/README.md` and fill it in.
+4. Open a PR. CI will assign the official XLS number automatically after a maintainer with write access approves; the `assign-xls-number.yml` workflow renames the directory and updates the preamble.
+
+---
+
+## CI Workflows
+
+| Workflow | Trigger | What it does |
+|----------|---------|--------------|
+| `validate-xls.yml` | PRs, push to master | Runs `python scripts/xls_parser.py` — validates preamble of **all** XLS docs |
+| `validate-xls.yml` (beta job) | PRs | Runs `python scripts/validate_xls_template.py <changed files>` — checks section structure |
+| `assign-xls-number.yml` | PRs | Detects `XLS-draft-*` directories and assigns the next available XLS number after write-access approval |
+| `pre-commit.yml` | PRs, push to master | Runs pre-commit hooks (trailing whitespace, end-of-file, prettier) |
+| `deploy.yml` | Push to master | Builds and deploys the GitHub Pages site |
+| `discussions.yml` | Daily schedule | Closes/warns on stale GitHub Discussions (inactive ≥1 year) |
+| `close-xls-discussions.yml` | Push to master | Closes the GitHub Discussion linked in `proposal-from` when an XLS is merged |
+
+### Running Validation Locally
+
+```bash
+pip install -r scripts/requirements.txt
+
+# Validate all XLS preambles
+python scripts/xls_parser.py
+
+# Validate structure of changed files
+python scripts/validate_xls_template.py XLS-NNNN-slug/README.md
+
+# Build the static site
+python scripts/build_site.py
+```
+
+---
+
+## Code Style and Conventions
+
+- **Markdown formatting**: enforced by `prettier` via pre-commit. Run `pre-commit run --all-files` or let CI flag issues.
+- **No trailing whitespace**, files must end with a newline (`end-of-file-fixer` hook).
+- **Folder naming**: `XLS-NNNN-slug` with a 4-digit zero-padded number and lowercase hyphenated slug.
+- **Author format**: either `Name (@github-handle)` or `Name <email@example.com>` — both forms are parsed by `xls_parser.py`. Each author must have a name **and** a link; otherwise validation fails.
+- **Dates**: always `YYYY-MM-DD`.
+- **Section numbering**: XLS documents use numeric section headings (`## 1. Abstract`, `## 2. Motivation`, etc.).
+- **Python scripts** in `scripts/` use Python 3.11 and are run directly (no build step needed beyond `pip install -r scripts/requirements.txt`).
+- **Templates are normative**: sections from `XLS_TEMPLATE.md` and `AMENDMENT_TEMPLATE.md` are checked by `validate_xls_template.py`. Do not skip required sections or leave template placeholders (bracketed instructions) in merged XLS documents.
+
+---
+
+## PR Checklist (from `pull_request_template.md`)
 
-## Template Compliance
+- Summarize the change and link any associated GitHub Discussion.
+- Check the type of change: New XLS Draft / XLS Update / XLS Status Change / Process/Meta / Infrastructure / Documentation.
+- Ensure the preamble is correct and complete.
+- Do not self-assign XLS numbers (for numbers > 95); use `XLS-draft-<slug>` naming.
 
-> **Always read the actual template files before reviewing or writing any XLS specification.** The templates are the single source of truth for section structure, sub-section ordering, table column headings, and naming conventions. Do not rely on summaries — open the files directly.
->
-> - `templates/XLS_TEMPLATE.md` — top-level section structure for all XLS types
-> - `templates/AMENDMENT_TEMPLATE.md` — Specification section structure for Amendment XLSes (Ledger Entries, Transactions, Permissions, RPCs, and their required table schemas)
->
-> When reviewing or authoring a spec, diff the document against the relevant template to catch missing sections, wrong table columns, or incorrect heading numbering.
+---
 
-## Key Rules
+## Known Gotchas
 
-- **No unfilled placeholders** — `validate_xls_template.py` rejects patterns like `[FieldName]`, `[example value]`, `_[Describe...]`, `0x[XXXX]`, `[r-address]`, `[Yes/No]`, etc.
-- **New draft directories** use `XLS-draft-<short-title>/` — the CI bot assigns the number; editors rename before merge.
-- **`scripts/_site/` is gitignored** — never commit build output.
-- Always run `python scripts/xls_parser.py` after any preamble change; it validates all docs and exits 1 on error.
+- **Duplicate XLS numbers**: `xls_parser.py` fails if two folders resolve to the same number. Always use the `XLS-draft-*` naming convention and let CI assign the number.
+- **Self-assigned numbers > 95**: the `assign-xls-number.yml` workflow posts a warning comment and blocks the CI if a PR adds a numbered directory (> XLS-0095) without the `has-xls-number` label.
+- **Withdrawn XLSes** must include a `withdrawal-reason` field in the preamble or validation fails.
+- **Amendment XLSes cannot reach `Final`** until the corresponding rippled PR is merged; `System` XLSes require a merged implementation too.
+- **`proposal-from` is required** for all XLSes in the preamble. Missing it causes `validate_xls_preamble` to fail.
+- The `build_site.py` script outputs to `scripts/_site/` — this directory is ephemeral and not committed.
+- Pre-commit uses pinned SHAs (not tags) for hook repos — update them in `.pre-commit-config.yaml` if upgrading.

From c89cbb66c957ca826672c69fd7bd3c3de220e364 Mon Sep 17 00:00:00 2001
From: Vito Tumas <5780819+Tapanito@users.noreply.github.com>
Date: Tue, 12 May 2026 17:14:50 +0200
Subject: [PATCH 4/4] Update .github/copilot-instructions.md

Co-authored-by: Mayukha Vadari <mvadari@ripple.com>
---
 .github/copilot-instructions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 87975e407..5f94de260 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -75,7 +75,7 @@ Also: `Deprecated` (Final XLS no longer recommended), `Stagnant` (Draft inactive
 1. Start in GitHub Discussions (Idea or Proposal stage) — do **not** open a PR until there is community feedback.
 2. Create a directory named `XLS-draft-<short-title>/` (agents/authors must NOT self-assign numbers for XLS numbers > 95).
 3. Copy `templates/XLS_TEMPLATE.md` to `XLS-draft-<short-title>/README.md` and fill it in.
-4. Open a PR. CI will assign the official XLS number automatically after a maintainer with write access approves; the `assign-xls-number.yml` workflow renames the directory and updates the preamble.
+4. Open a PR. CI will assign the official XLS number automatically after a maintainer with write access approves; the `assign-xls-number.yml` workflow renames the directory and updates the preamble. Authors should not assign their own XLS number.
 
 ---