feat: add UNESCO Ethical Impact Assessment (EIA) module

[felipelago17]

Summary

This PR adds a self-contained UNESCO Ethical Impact Assessment (EIA) module to the documentation site, aligned with the UNESCO Recommendation on the Ethics of Artificial Intelligence (2021). It implements all three EIA parts, all six stages as GitHub Issue Forms, machine-readable templates, a regulatory crosswalk, and CI linting/link-checking jobs.

---

Deliverables Checklist

A. MkDocs Documentation Pages (docs/eia/)

• docs/eia/index.md — Overview: definition, who it's for, when to run, why, summary table of 3 parts + 6 stages, Quick Start admonition, attribution
• docs/eia/how-to-run.md — Mermaid flowchart LR of 6 stages; one ## Stage N section per stage with purpose, participants, key activities, outputs, and links to GitHub Issue templates; "Tracking as GitHub Issues" guidance
• docs/eia/scoping.md — Part 1: 6 scoping sections (system description, data sources, affected stakeholders, decision-making context, jurisdiction/regulatory context, prior assessments); TODO(source) placeholders for verbatim EIA workbook text; !!! note "Part 1 of 3" admonition
• docs/eia/principles.md — Part 2: all 10 UNESCO principles, each with === "Safeguards" / === "Mitigation" content tabs; TODO(source) placeholders for verbatim EIA workbook question wording
• docs/eia/impact-mapping.md — Part 3: scoring guide (Likelihood × Severity), instructions, impact tables for all 10 principles, aggregation guidance, !!! warning admonition for critical risks
• docs/eia/principles-reference.md — 4 core values with paragraph descriptions; 10-principle reference table (definition, EIA parts, regulatory instruments); !!! quote UNESCO preamble
• docs/eia/crosswalk.md — Regulatory crosswalk with 5 content tabs: NIST AI RMF, EU AI Act (with FRIA Article 27 note), OECD Principles, ISO/IEC 42001, CoE HUDERIA; cross-framework summary table

B. Reusable Templates (eia/templates/)

• eia/templates/eia-template.md — Fillable Markdown EIA with front matter, Parts 1–3, all 10 principles, sign-off table
• eia/templates/impact-mapping.md — Standalone impact tables for all 10 principles
• eia/templates/eia.schema.json — JSON Schema draft-07 with all required fields (schema_version, system_name, assessment_date, status, assessors, part1_scoping, part2_principles, part3_impacts); part3_impacts items include principle enum, impact_type enum (positive/negative), likelihood/severity integers 1–5; status enum (draft/in-review/complete/archived)
• eia/templates/eia.example.yaml — Realistic example for an LLM-based HR screening tool (ResumeRank v1.2) with 5 assessors, filled scoping section, 3 principles with safeguards/gaps/mitigations, 7 impact entries (mix of positive and negative), mitigation owners and due dates

C. GitHub Issue Forms (.github/ISSUE_TEMPLATE/)

Maps EIA stages to GitHub Issue Forms — one form per stage:

• eia-stage-1-scoping.yml — Labels: eia, eia-stage-1; fields: system_name, system_description, intended_use, data_sources, affected_stakeholders, decision_type (dropdown), regulatory_context, assessment_lead, target_completion
• eia-stage-2-team.yml — Labels: eia, eia-stage-2; fields: team_members, disciplines_represented (checkboxes: 9 disciplines), gaps_in_representation
• eia-stage-3-async.yml — Labels: eia, eia-stage-3; fields: assigned_to, system_ref, principles_reviewed (checkboxes for all 10), notes_per_principle, blockers
• eia-stage-4-workshop.yml — Labels: eia, eia-stage-4; fields: workshop_date, attendees, key_decisions, unresolved_issues, revised_impact_scores
• eia-stage-5-stakeholders.yml — Labels: eia, eia-stage-5; fields: stakeholder_groups_engaged, engagement_method (dropdown: 5 methods), key_feedback, assessment_revisions
• eia-stage-6-signoff.yml — Labels: eia, eia-stage-6; fields: assessment_lead, final_status (dropdown: approved/approved-with-conditions/deferred/rejected), conditions, publication_url, next_review_date, lessons_learned

D. CI Updates

• .github/workflows/ci.yml — Added markdownlint job (Node 20, markdownlint-cli, covers docs/**/*.md and eia/templates/**/*.md, ignores docs/literature/**, || true during initial rollout) and link-check job (lycheeverse/lychee-action@v2, fail: false during initial rollout). Existing test job (pytest) is unchanged.
• .markdownlint.json — Root config: MD013 (line length) off, MD033 (inline HTML) off, MD041 (first line heading) off, MD007 indent: 2
• .github/workflows/deploy-docs.yml — Not modified (existing CI preserved)

E. README Update

• README.md — Added "UNESCO Ethical Impact Assessment" section after "Related Projects" with links to EIA module, issue templates, JSON schema, and regulatory crosswalk; attribution blockquote

F. mkdocs.yml Update

• mkdocs.yml — Added UNESCO EIA nav section (7 pages) between Governance Mapping and Literature
• Replaced pymdownx.superfences with the Mermaid-enabled custom_fences block
• Added content.tabs.link to theme features
• Added https://unpkg.com/mermaid@10/dist/mermaid.min.js to extra_javascript

---

EIA Structure Mapping

Deliverable	EIA Part	EIA Stages
docs/eia/scoping.md, Issue Form Stage 1	Part 1 — Scoping	Stage 1, Stage 3
docs/eia/principles.md, Issue Forms Stages 2–4	Part 2 — Principles	Stages 2, 3, 4
docs/eia/impact-mapping.md, Issue Form Stage 4	Part 3 — Impacts	Stages 3, 4
docs/eia/how-to-run.md, Issue Forms Stages 5–6	All parts	Stages 5, 6
eia/templates/eia.schema.json	All parts	Machine-readable output of all stages

---

Linting and Link-Checking Note

Both markdownlint and lychee are added with soft failure (|| true / fail: false) during initial rollout to avoid blocking CI while the config is tuned and external links are verified. Set fail: true / remove || true once the baseline is clean.

---

Attribution

The UNESCO Ethical Impact Assessment is a tool developed by UNESCO. Official resources and the EIA workbook are at https://www.unesco.org/ethics-ai/en/eia. The Recommendation on the Ethics of Artificial Intelligence (2021) is at https://unesdoc.unesco.org/ark:/48223/pf0000381137.

Specific EIA workbook question wording that could not be verified from publicly accessible sources is marked with > **TODO(source):** placeholders in docs/eia/scoping.md and docs/eia/principles.md.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01WFc4mqrrwQKn4ieExoB1rX

---

Generated by Claude Code