structured-address-fix 0.1.0__tar.gz

structured_address_fix-0.1.0/LICENSE

@@ -0,0 +1,189 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work.
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to the Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by the Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding any notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2023-2026 Sebastien Rousseau
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

structured_address_fix-0.1.0/PKG-INFO

@@ -0,0 +1,404 @@
+Metadata-Version: 2.4
+Name: structured-address-fix
+Version: 0.1.0
+Summary: ISO 20022 structured-address remediation and payment-rejection prevention for the November 2026 cliff.
+License: Apache-2.0
+License-File: LICENSE
+Keywords: iso20022,cbpr,postal-address,pacs008,payments,remediation
+Author: Sebastien Rousseau
+Author-email: sebastian.rousseau@gmail.com
+Requires-Python: >=3.12,<4.0
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: defusedxml (>=0.7,<0.8)
+Requires-Dist: pydantic (>=2.9,<3)
+Requires-Dist: xmlschema (>=3.4,<5)
+Project-URL: Homepage, https://sebastienrousseau.github.io/structured-address-fix/
+Project-URL: Repository, https://github.com/sebastienrousseau/structured-address-fix
+Description-Content-Type: text/markdown
+
+# structured-address-fix: ISO 20022 Structured-Address Remediation
+
+[![PyPI Version][pypi-badge]][pypi-url]
+[![Python Versions][python-versions-badge]][pypi-url]
+[![License][license-badge]][01]
+[![Tests][tests-badge]][tests-url]
+[![Quality][quality-badge]][quality-url]
+[![OpenSSF Scorecard][scorecard-badge]][scorecard-url]
+[![Documentation][docs-badge]][docs-url]
+
+**A vendor-neutral core library that detects, scores, and remediates
+non-compliant postal addresses in [ISO 20022][iso] payment messages** —
+ahead of the **14 November 2026** cliff, when fully unstructured addresses
+are rejected across SWIFT CBPR+, HVPS+, T2 RTGS, CHAPS, Fedwire, and Lynx.
+Point it at a `pacs.008` or `pain.001` document, get back an explainable
+list of findings, and turn an `AdrLine`-only address into a structured one
+with reversible, auditable patches.
+
+> **The cliff, in one line.** From **14 November 2026** an ISO 20022 postal
+> address that is `AdrLine`-only (unstructured) is non-compliant and liable
+> to be rejected by the major cross-border and high-value schemes. A
+> *hybrid* address (town + country plus at most two residual `AdrLine`
+> lines) is the minimum bar; *structured* is the target. This library exists
+> to move addresses across that line before it bites.
+
+## Contents
+
+- [Overview](#overview)
+- [The ISO 20022 Suite](#the-iso-20022-suite)
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [Architecture](#architecture)
+- [Policies](#policies)
+- [Premium rule packs](#premium-rule-packs)
+- [Writing a rule pack](#writing-a-rule-pack)
+- [When not to use structured-address-fix](#when-not-to-use-structured-address-fix)
+- [Development](#development)
+- [Security](#security)
+- [Documentation](#documentation)
+- [License](#license)
+- [Contributing](#contributing)
+- [Acknowledgements](#acknowledgements)
+
+## Overview
+
+`structured-address-fix` is the shared core of a small ISO 20022 address
+toolchain. It reads the postal addresses carried by the parties of a payment
+message (debtor, creditor, agents, ultimate parties), classifies each one as
+**structured**, **hybrid**, or **unstructured** per CBPR+ UG2026, scores the
+compliance risk against a chosen policy, and — where it can — proposes a
+remediation that promotes the address toward the structured target.
+
+Two properties are non-negotiable:
+
+- **Explainable.** Every remediation is a set of RFC 6902-shaped
+  `PatchOperation`s. Each records *why* it exists (the `FindingCode` it
+  resolves), *where its value came from* (the originating `AdrLine` token,
+  when applicable), and *how confident* the deriving heuristic was. Anything
+  it cannot resolve is reported as a **residual finding**, so the gap to full
+  compliance is always visible.
+- **Safe by default.** Untrusted XML is parsed with `defusedxml` (no XXE,
+  no billion-laughs). The canonical address model is frozen, closed to extra
+  fields, and enforces the ISO 20022 element-length maxima as construction
+  invariants. Errors raise a typed [`StructuredAddressError`](docs/error-taxonomy.md)
+  with a stable `code` and safe `context`.
+
+- **Website / docs:** <https://sebastienrousseau.github.io/structured-address-fix/>
+- **Source code:** <https://github.com/sebastienrousseau/structured-address-fix>
+- **Bug reports:** <https://github.com/sebastienrousseau/structured-address-fix/issues>
+
+The public surface is the `structured_address_fix.services` facade; the
+domain models are re-exported from the package root for convenience.
+
+## The ISO 20022 Suite
+
+`structured-address-fix` is the **postal-address remediation core** of the
+sebastienrousseau ISO 20022 suite. It supersedes and generalises the bespoke
+`pacs008.standards.address` module, and it is the shared engine that a thin
+Model Context Protocol server wraps for AI agents — so the classification and
+remediation logic lives in exactly one place and every surface behaves
+identically.
+
+| Package | Role |
+| :--- | :--- |
+| **`structured-address-fix`** | **The core library (this package): domain model, policies, adapters, services facade, plugin SDK** |
+| [`structured-address-fix-mcp`](https://github.com/sebastienrousseau/structured-address-fix-mcp) | Thin Model Context Protocol server wrapping the services facade for AI agents |
+| [`pacs008`](https://github.com/sebastienrousseau/pacs008) | FI-to-FI credit-transfer library; delegates its address linting + Nov-2026 readiness here |
+
+```mermaid
+flowchart LR
+    A["MCP / REST / LSP wrapper"] -->|delegates to| B["structured_address_fix.services"]
+    B -->|classify + score + remediate| C["ISO 20022 pacs.008 / pain.001 XML"]
+```
+
+## Install
+
+`structured-address-fix` runs on macOS, Linux, and Windows and requires
+**Python 3.12+** and **pip**. Its only runtime dependencies are `pydantic`,
+`defusedxml`, and `xmlschema`.
+
+```sh
+python -m pip install structured-address-fix
+```
+
+<details>
+<summary>Using an isolated virtual environment (recommended)</summary>
+
+```sh
+python -m venv venv
+source venv/bin/activate        # macOS/Linux
+venv\Scripts\activate           # Windows
+python -m pip install -U structured-address-fix
+```
+</details>
+
+## Quick Start
+
+For the guided tour, see [`docs/quickstart.md`](docs/quickstart.md).
+
+### Classify an address
+
+The domain model is re-exported from the package root and works standalone.
+`CanonicalAddress` models the ISO 20022 `PostalAddress27` type and classifies
+itself per CBPR+ UG2026:
+
+```python
+from structured_address_fix import CanonicalAddress
+
+# Unstructured: AdrLine only, no town / country -> rejected from the cliff.
+unstructured = CanonicalAddress(
+    address_lines=("221B Baker Street", "London NW1 6XE", "United Kingdom"),
+)
+print(unstructured.classification)   # AddressClassification.UNSTRUCTURED
+
+# Structured: town + country + structured detail, no residual AdrLine.
+structured = CanonicalAddress(
+    building_number="221B",
+    street_name="Baker Street",
+    post_code="NW1 6XE",
+    town_name="London",
+    country="GB",
+)
+print(structured.classification)     # AddressClassification.STRUCTURED
+
+# Serialise back to ISO 20022 element names for the wire.
+structured.model_dump(by_alias=True, exclude_none=True)
+# {'BldgNb': '221B', 'StrtNm': 'Baker Street', 'PstCd': 'NW1 6XE',
+#  'TwnNm': 'London', 'Ctry': 'GB', ...}
+```
+
+### Assess and remediate a message
+
+The top-level entry point is the `structured_address_fix.services` facade:
+`assess` returns a read-only [`ValidationReport`](docs/remediation-model.md);
+`remediate` adds the proposed fixes (and, optionally, the patched XML):
+
+```python
+from structured_address_fix.services import assess, remediate
+
+pacs008_xml = ...  # an ISO 20022 pacs.008 document, as text
+
+# 1. Score every party's address against a policy.
+report = assess(pacs008_xml, policy="cbpr-2026")
+print(report.is_compliant)                       # False
+for finding in report.findings:
+    print(finding.code, finding.party_role, finding.message)
+# SAF001 Dbtr  Address is AdrLine-only; rejected from 2026-11-14
+
+# 2. Propose reversible, explainable patches for what can be fixed.
+result = remediate(pacs008_xml, policy="cbpr-2026")
+for suggestion in result.suggestions:
+    print(suggestion.before.classification, "->",
+          suggestion.after.classification)       # unstructured -> hybrid
+    for op in suggestion.operations:
+        print(op.op, op.path, op.reason_code, op.confidence)
+    # Anything no heuristic could resolve is reported, never hidden:
+    for residual in suggestion.residual_findings:
+        print("residual:", residual.code)
+```
+
+> The built-in policies, XML adapters, per-country heuristics, and the
+> `assess` / `remediate` facade land in the v0.1.x series; see
+> [`ROADMAP.md`](ROADMAP.md). The domain model and error taxonomy shipped in
+> v0.1.0 and are stable.
+
+## Architecture
+
+The library is layered so that each concern is testable in isolation and the
+public surface stays small. Dependencies point downward only.
+
+| Layer | Module | Responsibility |
+| :--- | :--- | :--- |
+| **Domain** | `structured_address_fix.domain` | Pure Pydantic v2 entities and their invariants, with zero I/O: `CanonicalAddress`, `AddressedParty`, `RiskFinding`, `PatchOperation`, the result envelopes, and the wire-facing enums. |
+| **Policies** | `structured_address_fix.policies` | Rulebooks that inspect a `CanonicalAddress` and raise `RiskFinding`s: the four built-ins (see below), each citing a rulebook clause. |
+| **Adapters** | `structured_address_fix.adapters` | `defusedxml` parsing of pacs.008 / pain.001, party discovery, and the per-country `AdrLine` → structured heuristics that populate the canonical model with recorded confidence + source tokens. |
+| **Services** | `structured_address_fix.services` | The `assess` / `remediate` facade — the single public entry point wrappers (MCP / REST / LSP) call. |
+| **Plugins** | `structured_address_fix.plugins` | The premium rule-pack SDK: entry-point discovery of third-party `PolicyPack`s, gated by entitlement + integrity checks. |
+
+## Policies
+
+A **policy** is a rulebook: it names the finding codes that apply and the
+severity each carries. Four are built in and open-source:
+
+| Policy id | Scope | Use it when |
+| :--- | :--- | :--- |
+| `cbpr-2026` | SWIFT CBPR+ UG2026 cross-border requirements — the Nov-2026 cliff rules. **The default.** | You send or receive cross-border SWIFT payments |
+| `sepa` | SEPA credit-transfer address expectations | You operate in the euro retail-payment area |
+| `hvps-plus` | HVPS+ high-value / RTGS market-practice (T2, CHAPS, Fedwire, Lynx) | You settle over a high-value system |
+| `generic-structured` | Scheme-agnostic structured-vs-unstructured hygiene | You want the baseline structural checks with no scheme assumptions |
+
+The default policy is `cbpr-2026`, overridable per call or via the
+`SAF_DEFAULT_POLICY` environment variable. Finding codes (`SAF001`–`SAF008`)
+are a stable public API: a code's meaning is fixed once released. See
+[`docs/policies.md`](docs/policies.md) for the full rule-to-code mapping and
+[`docs/error-taxonomy.md`](docs/error-taxonomy.md) for the exception codes.
+
+## Premium rule packs
+
+The four built-in policies cover the open, published scheme rules. Some
+requirements — proprietary market-practice profiles, correspondent-specific
+overlays, jurisdiction-specific address validation — are better shipped as
+**premium rule packs**: separately installable Python distributions that
+register additional policies through an entry point.
+
+A pack is discovered automatically once installed, contributes its own policy
+ids and finding codes (with their own prefixes, so they never collide with the
+core `SAF` codes), and is gated at load time by the entitlement + integrity
+checks in the [error taxonomy](docs/error-taxonomy.md)
+(`PackNotLicensedError`, `PackIntegrityError`). The core never bundles a pack;
+you opt in by installing one.
+
+```python
+from structured_address_fix.services import assess
+
+# A premium pack's policy id, resolved through the plugin registry.
+report = assess(message_xml, policy="acme-correspondent-2026")
+```
+
+## Writing a rule pack
+
+Publishing a rule pack means shipping a `PolicyPack` and advertising it under
+the `structured_address_fix.policies` entry-point group:
+
+```toml
+# pyproject.toml of your pack distribution
+[project.entry-points."structured_address_fix.policies"]
+acme-correspondent-2026 = "acme_saf_pack:PACK"
+```
+
+```python
+# acme_saf_pack/__init__.py
+from structured_address_fix.domain import (
+    FindingCode, RiskFinding, Severity, CanonicalAddress,
+)
+
+def check(address: CanonicalAddress, *, location: str) -> list[RiskFinding]:
+    """Raise the pack's findings against a single address."""
+    findings: list[RiskFinding] = []
+    if address.post_code is None:
+        findings.append(RiskFinding(
+            code=FindingCode.MISSING_TOWN,  # or a pack-specific code
+            severity=Severity.ERROR,
+            message="Correspondent profile requires a post code.",
+            policy_id="acme-correspondent-2026",
+            location=location,
+        ))
+    return findings
+
+PACK = ...  # a PolicyPack binding the id "acme-correspondent-2026" to check()
+```
+
+The full contract — the `PolicyPack` shape, custom finding-code prefixes,
+entitlement, and integrity signing — is in
+[`docs/writing-a-rule-pack.md`](docs/writing-a-rule-pack.md).
+
+## When not to use structured-address-fix
+
+- **Your addresses are already fully structured.** If every message you send
+  already carries `TwnNm` + `Ctry` + structured detail and no `AdrLine`,
+  there is nothing to remediate; a one-off `assess` to confirm compliance is
+  all you need.
+- **You need to *generate* whole payment messages.** This library remediates
+  the postal-address portion of an existing message; it does not build a
+  pacs.008 or pain.001 from scratch. Use the message-family libraries for
+  that (e.g. `pacs008`, `pain001`).
+- **You want an agent tool, not a library import.** Use the thin
+  [`structured-address-fix-mcp`](https://github.com/sebastienrousseau/structured-address-fix-mcp)
+  server, which wraps this facade for MCP clients.
+- **You need authoritative address verification against a postal database.**
+  The `AdrLine` → structured heuristics are deterministic, explainable
+  best-effort splits with recorded confidence; they do not consult a national
+  address file. Low-confidence or unresolvable fragments are reported as
+  residual findings for a human to resolve, never silently guessed.
+- **You need a schema validator.** For pure XSD validation of a whole
+  document, use `xmlschema` directly; this library focuses on address
+  compliance, not full-message schema conformance.
+
+## Development
+
+`structured-address-fix` uses [Poetry](https://python-poetry.org/) and
+[mise](https://mise.jdx.dev/).
+
+```bash
+git clone https://github.com/sebastienrousseau/structured-address-fix.git && cd structured-address-fix
+mise install
+poetry install
+poetry shell
+```
+
+A `Makefile` orchestrates the quality gates (kept in lockstep with CI):
+
+```bash
+make check        # lint + type-check + test (REQUIRED before commit)
+make test         # pytest at 100% line + branch coverage
+make lint         # ruff + black --check
+make type-check   # mypy --strict
+make security     # bandit
+make examples     # run each examples/*.py
+make pip-compile  # regenerate hash-pinned requirements/*.txt from *.in
+```
+
+## Security
+
+Untrusted ISO 20022 XML is parsed with `defusedxml`, never the standard-library
+parser, so XXE / billion-laughs / external-DTD attacks are structurally
+prevented. The canonical model is frozen and `extra="forbid"`, and every error
+is a typed `StructuredAddressError` with a stable `code` and safe `context`, so
+a wrapping transport can serialise `{"error": ...}` payloads rather than leaking
+tracebacks. Premium rule packs are opt-in and gated by entitlement + integrity
+checks. Reporting practice, supported versions, the NIST SSDF practice mapping,
+and the accepted OpenSSF Scorecard findings are documented in
+[`SECURITY.md`](SECURITY.md). Vulnerabilities go via GitHub Private
+Vulnerability Reporting, not public issues.
+
+## Documentation
+
+- [`README.md`](README.md) — this file
+- [`docs/index.md`](docs/index.md) — documentation index
+- [`docs/quickstart.md`](docs/quickstart.md) — guided tour
+- [`docs/policies.md`](docs/policies.md) — the built-in policies and their rules
+- [`docs/writing-a-rule-pack.md`](docs/writing-a-rule-pack.md) — the premium rule-pack contract
+- [`docs/remediation-model.md`](docs/remediation-model.md) — findings, patches, and results
+- [`docs/error-taxonomy.md`](docs/error-taxonomy.md) — the exception codes
+- [`docs/nov-2026-cutover.md`](docs/nov-2026-cutover.md) — the Nov-2026 cliff, scheme by scheme
+- [`CHANGELOG.md`](CHANGELOG.md) — release notes
+- [`SECURITY.md`](SECURITY.md) — disclosure + supported versions
+- [`ROADMAP.md`](ROADMAP.md) — where the project is going
+
+## License
+
+Licensed under the [Apache License, Version 2.0][01]. Any contribution submitted
+for inclusion shall be licensed as above, without additional terms.
+
+## Contributing
+
+Contributions are welcome — see the [contributing instructions][04]. Thanks to
+all [contributors][05].
+
+## Acknowledgements
+
+Built on [Pydantic](https://docs.pydantic.dev/), [defusedxml][defusedxml], and
+[xmlschema](https://github.com/sissaschool/xmlschema), and grounded in the
+ISO 20022 CBPR+ / HVPS+ structured-address requirements.
+
+[01]: https://opensource.org/license/apache-2-0/
+[04]: https://github.com/sebastienrousseau/structured-address-fix/blob/main/CONTRIBUTING.md
+[05]: https://github.com/sebastienrousseau/structured-address-fix/graphs/contributors
+[iso]: https://www.iso20022.org
+[defusedxml]: https://github.com/tiran/defusedxml
+[docs-badge]: https://img.shields.io/badge/Docs-structured--address--fix-blue?style=for-the-badge
+[docs-url]: https://sebastienrousseau.github.io/structured-address-fix/
+[license-badge]: https://img.shields.io/pypi/l/structured-address-fix?style=for-the-badge
+[pypi-badge]: https://img.shields.io/pypi/v/structured-address-fix?style=for-the-badge
+[pypi-url]: https://pypi.org/project/structured-address-fix/
+[python-versions-badge]: https://img.shields.io/pypi/pyversions/structured-address-fix.svg?style=for-the-badge
+[quality-badge]: https://img.shields.io/github/actions/workflow/status/sebastienrousseau/structured-address-fix/ci.yml?branch=main&label=Quality&style=for-the-badge
+[quality-url]: https://github.com/sebastienrousseau/structured-address-fix/actions/workflows/ci.yml
+[scorecard-badge]: https://api.scorecard.dev/projects/github.com/sebastienrousseau/structured-address-fix/badge?style=for-the-badge
+[scorecard-url]: https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/structured-address-fix
+[tests-badge]: https://img.shields.io/github/actions/workflow/status/sebastienrousseau/structured-address-fix/ci.yml?branch=main&label=Tests&style=for-the-badge
+[tests-url]: https://github.com/sebastienrousseau/structured-address-fix/actions/workflows/ci.yml
+