tryblackjack · tryblackjack · Apr 20, 2026
diff --git a/EXECUTIVE_SUMMARY.md b/EXECUTIVE_SUMMARY.md
@@ -0,0 +1,31 @@
+# Executive Summary — AI-HPP-Standard External Review Readiness
+
+## Current readiness state
+
+AI-HPP-Standard contains substantial governance and conformance material, but it is split between a **minimal active surface** and a **richer archived surface**. This creates a high risk of reviewer confusion about what is authoritative. In its current state, the repository is **not yet fully expert-review ready** for skeptical AI safety auditors.
+
+## What is strong today
+
+- Clear high-level conceptual model in active docs (`signal`, `state`, `bridge`, `safety gate`).
+- Preserved historical evidence base (modules, annexes, schemas, regulator-sim assets) with no destructive cleanup.
+- Existing script infrastructure for structure and link checks.
+
+## Top blockers
+
+1. **Canonical ambiguity**: no single declared source-of-truth for standard modules/schemas/conformance/governance paths.
+2. **Broken references in active contributor path**: `CONTRIBUTING.md` points to missing files.
+3. **Translation parity gaps**: most language packs are partial relative to full English structure.
+4. **Failure taxonomy cross-language inconsistency**: IDs are not consistently surfaced across translations.
+5. **Traceability discoverability gap**: module-to-schema-to-conformance mapping is present in artifacts but not exposed as a canonical reviewer path.
+
+## Fastest path to “expert-review ready”
+
+1. **Declare canonical architecture explicitly** in root docs (what is normative now, what is archived history).
+2. **Fix active broken links** in contribution/readme entrypoints.
+3. **Publish a single traceability matrix** linking requirements, schemas, and conformance scripts/artifacts.
+4. **Stabilize translation policy** and ensure failure taxonomy IDs remain invariant across language sets.
+5. **Add an external-review quickstart checklist** that gives reviewers a deterministic audit flow.
+
+## Founder-oriented conclusion
+
+Your repository already has the ingredients of a credible governance standard; the immediate problem is **packaging for audit trust**, not lack of substance. If you execute the Priority 0 and Priority 1 stabilization items, you can materially improve reviewer confidence within one sprint and present AI-HPP as a serious candidate de-facto governance standard.
diff --git a/READINESS_GAP_ANALYSIS.md b/READINESS_GAP_ANALYSIS.md
@@ -0,0 +1,89 @@
+# Standards Readiness Gap Analysis — AI-HPP-Standard
+
+Date: 2026-04-20  
+Assessment target: readiness for skeptical external AI safety / governance review.
+
+## Scoring rubric
+
+0 = absent, 1 = very weak, 2 = early draft, 3 = usable with caveats, 4 = strong, 5 = review-ready best practice.
+
+## Scorecard (0–5)
+
+- **Structural maturity:** 2.5 / 5
+- **Specification maturity:** 2.0 / 5
+- **Audit readiness:** 2.5 / 5
+- **Translation readiness:** 2.0 / 5
+- **Governance readiness:** 2.5 / 5
+
+---
+
+## A) Specification maturity
+
+### Findings
+
+- Active surface (`docs/ai-hpp-standard.md`, `spec/*`) is concise and understandable, but does not expose the richer normative module architecture visible in archived v3.x materials.
+- Consistent RFC-style modality (`SHALL`/`SHOULD`/`MAY`) is not systematically applied in active canonical docs.
+- Version signaling exists (`v4.1.1` in active doc, v3.15/v3.17 markers in archive) but cross-version relationship is not explicitly defined.
+
+### Gap
+
+External reviewers cannot quickly determine if the minimal active standard supersedes, subsets, or diverges from archived normative modules.
+
+---
+
+## B) Evidence maturity
+
+### Findings
+
+- Evidence/conformance assets exist (schemas, conformance maps, regulator-sim templates), but are placed under archive paths.
+- Active docs do not clearly map:
+  - modules -> requirements,
+  - requirements -> schema artifacts,
+  - requirements -> conformance test scripts.
+- Some conformance scripts in `scripts/` are not linked from main docs.
+
+### Gap
+
+Traceability chain is present in fragments, not as a single auditable graph.
+
+---
+
+## C) Governance maturity
+
+### Findings
+
+- Governance-rich content (incident handling, conflict safeguards, adaptive governance, failure taxonomy) exists in archive annexes.
+- Operational pathways (escalation, CAPA-like control flow, regulator simulation procedures) are available but not prominently discoverable from root.
+- Failure taxonomy IDs are not consistently available across translation sets.
+
+### Gap
+
+Governance appears substantial but is discoverability-constrained and translation-fragile for external comparability.
+
+---
+
+## Blockers preventing external expert trust
+
+## Critical blockers
+
+1. **Canonical ambiguity:** no explicit declaration of authoritative standard surface (active minimal vs archived comprehensive).
+2. **Broken internal links in active governance process (`CONTRIBUTING.md`).**
+3. **Translation parity gap for failure taxonomy (Annex C not broadly translated), weakening cross-language audit equivalence.**
+
+## Major blockers
+
+4. Missing explicit module->schema->test traceability matrix in current canonical entrypoints.
+5. Mixed naming/versioning across translation folders (especially `uk-UA`) obscures authoritative documents.
+6. Archived docs include dead links to removed spec files, reducing perceived rigor.
+
+## Moderate blockers
+
+7. Orphaned active docs/examples are not reachable from root entrypoint.
+8. No clearly published external-review checklist (what to read, in what order, what evidence to verify).
+
+---
+
+## Expert-review readiness verdict
+
+**Current state: “Promising but not yet expert-review ready.”**  
+The repository contains meaningful governance material and evidence artifacts, but canonical path clarity and traceability packaging must be stabilized before external scrutiny by skeptical reviewers.
diff --git a/REMEDIATION_PLAN.md b/REMEDIATION_PLAN.md
@@ -0,0 +1,109 @@
+# Prioritized Remediation Plan — AI-HPP-Standard
+
+Date: 2026-04-20
+
+## Priority 0 — Critical blockers
+
+### P0-1: Declare a single canonical review surface
+- **Paths:** `README.md`, (new) `CANONICAL_PATHS.md` or `CANONICAL_PATHS.yaml`
+- **Issue:** External reviewers cannot determine whether active v4.1.1 docs or archived v3.x modules are authoritative.
+- **Recommended fix:** Add explicit canonical declaration and version-lineage mapping (e.g., “normative baseline = X; archive = historical reference”).
+- **Complexity:** Medium
+- **Dependencies:** none (should be first)
+
+### P0-2: Repair active broken contributor references
+- **Paths:** `CONTRIBUTING.md`
+- **Issue:** References to missing `docs/index.md` and `docs/templates/*` break contribution workflow credibility.
+- **Recommended fix:** Either restore referenced files or update links to valid current equivalents.
+- **Complexity:** Low
+- **Dependencies:** P0-1 (so new links point to canonical surface)
+
+### P0-3: Stabilize translation authority in `uk-UA`
+- **Paths:** `archive/2026-04-08/moved-to-docs/translations/uk-UA/*`
+- **Issue:** Mixed synced/legacy file sets and broken links in `Failure_Taxonomy.uk.md` create ambiguity.
+- **Recommended fix:** Add explicit “authoritative translation set” index and patch broken links or mark legacy file as historical.
+- **Complexity:** Medium
+- **Dependencies:** P0-1
+
+---
+
+## Priority 1 — Standard coherence blockers
+
+### P1-1: Publish module-to-evidence traceability map in canonical surface
+- **Paths:** `README.md`, `docs/ai-hpp-standard.md`, optionally new `docs/traceability.md`
+- **Issue:** Schemas and conformance logic exist but are not clearly mapped from canonical docs.
+- **Recommended fix:** Add explicit mapping table: module -> schema -> script/test -> artifact.
+- **Complexity:** Medium
+- **Dependencies:** P0-1
+
+### P1-2: Normalize translation parity policy
+- **Paths:** `archive/2026-04-08/moved-to-docs/translations/README.md`
+- **Issue:** Current translations are partial and taxonomy parity expectations are unclear.
+- **Recommended fix:** Define policy tiers (core-only/full-parity), expected files per tier, and SLA for sync.
+- **Complexity:** Medium
+- **Dependencies:** P0-1
+
+### P1-3: Ensure failure taxonomy ID cross-language consistency
+- **Paths:** `archive/2026-04-08/moved-to-docs/annex/C-FAILURE-TAXONOMY.md`, `archive/2026-04-08/moved-to-docs/translations/*`
+- **Issue:** IDs like `F-01`, `F-02`, `F-03`, `FT-A07` are not consistently represented across language sets.
+- **Recommended fix:** Add translated Annex C or explicit fallback rule preserving exact IDs across all languages.
+- **Complexity:** Medium-High
+- **Dependencies:** P1-2
+
+### P1-4: Clean dead links in archived technical docs
+- **Paths:**
+  - `archive/2026-04-08/moved-to-docs/ecosystem/spec/ai_hpp_protocol.md`
+  - `archive/2026-04-08/moved-to-docs/docs/reference-architecture.md`
+  - `archive/2026-04-08/moved-to-docs/docs/index.md`
+  - `archive/2026-04-08/moved-to-docs/docs/audit-logging.md`
+- **Issue:** Dead links to removed `spec/ai_hpp_specification.md` degrade trust.
+- **Recommended fix:** Retarget links to extant docs or mark as archived/stale with explanatory banner.
+- **Complexity:** Low-Medium
+- **Dependencies:** P0-1
+
+---
+
+## Priority 2 — Presentation and credibility improvements
+
+### P2-1: De-orphan examples and contributor docs
+- **Paths:** `README.md`, `examples/node/README.md`, `examples/python/README.md`, `CONTRIBUTING.md`
+- **Issue:** Useful docs are not reachable from root reading path.
+- **Recommended fix:** Add explicit section linking contribution guide and examples.
+- **Complexity:** Low
+- **Dependencies:** P0-1
+
+### P2-2: Add external reviewer quickstart checklist
+- **Paths:** new `EXTERNAL_REVIEW_CHECKLIST.md`
+- **Issue:** Reviewers lack guided audit flow.
+- **Recommended fix:** 30–60 minute checklist: canonical docs, schema checks, conformance run, governance walkthrough.
+- **Complexity:** Low
+- **Dependencies:** P1-1
+
+### P2-3: Add machine-readable repository map
+- **Paths:** new `REPO_MAP.yaml` (or `docs/repo-map.md`)
+- **Issue:** Document discoverability currently relies on manual navigation.
+- **Recommended fix:** Enumerate canonical files, archived sets, and status tags (`canonical`, `historical`, `translation-draft`).
+- **Complexity:** Medium
+- **Dependencies:** P0-1
+
+---
+
+## Dependency order (execution sequence)
+
+1. P0-1
+2. P0-2 + P0-3
+3. P1-1
+4. P1-2 -> P1-3
+5. P1-4
+6. P2-1, P2-2, P2-3
+
+---
+
+## Fastest path to expert-review readiness
+
+Minimum viable stabilization set:
+1. Canonical declaration (P0-1)
+2. Fix active broken links (P0-2)
+3. Publish traceability matrix (P1-1)
+4. Translate or canonicalize failure taxonomy IDs across languages (P1-3)
+5. Add reviewer quickstart checklist (P2-2)
diff --git a/STRUCTURAL_AUDIT.md b/STRUCTURAL_AUDIT.md
@@ -0,0 +1,116 @@
+# Structural Audit — AI-HPP-Standard
+
+Date: 2026-04-20  
+Scope audited: full repository tree, including `archive/2026-04-08/*`.
+
+## 1) Canonical document tree
+
+### A. Current active (top-level, externally discoverable) canonical path
+
+1. **Overview / entrypoint**
+   - `README.md`
+2. **Primary standard narrative (current active surface)**
+   - `docs/ai-hpp-standard.md` (full content)
+   - `docs/AI-HPP-Standard.md` (shim redirecting to lowercase file)
+3. **Architecture and concepts**
+   - `docs/architecture.md`
+   - `docs/glossary.md`
+4. **Technical spec primitives**
+   - `spec/core.md`
+   - `spec/signal.md`
+   - `spec/safety.md`
+5. **Conformance/check logic (script-based)**
+   - `scripts/validate.py`
+   - `scripts/check_links.py`
+   - `scripts/regulator_sim_check.py`
+   - `scripts/normative_fingerprint.py`
+
+### B. Archived comprehensive standard path (historical-but-complete structure)
+
+Located under: `archive/2026-04-08/moved-to-docs/`
+
+- **Modules (normative set)**: `standard/00..12-*.md`
+- **Annexes**: `annex/*.md`
+- **Schemas**: `schemas/*.schema.json`
+- **Regulator simulation/conformance artifacts**: `regulator-sim/**`
+- **Translations**: `translations/**`
+
+### C. Canonical-tree ambiguity to resolve
+
+There are currently **two competing “standard surfaces”**:
+- Minimal active surface (`docs/*` + `spec/*`), and
+- Full archived surface (`archive/2026-04-08/moved-to-docs/*`).
+
+This creates uncertainty for external reviewers about what is canonical for expert evaluation.
+
+---
+
+## 2) Broken structure map
+
+## Dead references (verified)
+
+### Active tree
+- `CONTRIBUTING.md` references missing files:
+  - `docs/templates/doc-template.md`
+  - `docs/templates/case-study-template.md`
+  - `docs/index.md`
+
+### Archived tree
+- `archive/2026-04-08/moved-to-docs/ecosystem/spec/ai_hpp_protocol.md` -> missing `../../spec/ai_hpp_specification.md`
+- `archive/2026-04-08/moved-to-docs/docs/reference-architecture.md` -> missing `../spec/ai_hpp_specification.md`
+- `archive/2026-04-08/moved-to-docs/docs/index.md` -> missing `../spec/ai_hpp_specification.md`
+- `archive/2026-04-08/moved-to-docs/docs/index.md` -> missing `../examples/`
+- `archive/2026-04-08/moved-to-docs/docs/audit-logging.md` -> missing `../spec/ai_hpp_specification.md`
+- `archive/2026-04-08/moved-to-docs/translations/uk-UA/Failure_Taxonomy.uk.md` contains 3 broken historical links.
+
+## Duplicate / ambiguous documents
+
+- `docs/AI-HPP-Standard.md` vs `docs/ai-hpp-standard.md` (same topic, different casing; one is a shim).
+- Extensive legacy duplication in `archive/2026-04-08/legacy/` and `archive/2026-04-08/moved-to-docs/` (expected for preservation, but not clearly segmented for reviewers).
+- Mixed naming styles in translation assets (e.g., `README.uk.md`, `AI-HPP-2026_Standard_v3.0.uk.md`, plus synced `README.md`/`INDEX.md`).
+
+## Orphaned markdown files (active tree reachability from `README.md`)
+
+Not reachable from active entry links:
+- `CONTRIBUTING.md`
+- `examples/node/README.md`
+- `examples/python/README.md`
+
+## Structural ambiguities / archive collisions
+
+- `archive/2026-04-08/moved-to-docs/` includes production-like artifacts (schemas, conformance maps, regulator simulation) that look canonical but are placed under archive.
+- Current root docs do not clearly state whether archived v3.x artifacts are authoritative references or historical snapshots only.
+
+---
+
+## 3) Canonicalization recommendations
+
+## Make canonical (single-source-of-truth)
+
+1. Define one public canonical standard lineage explicitly in `README.md`:
+   - **Option A (minimal v4.1.1 canonical):** keep `docs/ai-hpp-standard.md` + `spec/*` as canonical.
+   - **Option B (comprehensive v3.x canonical):** promote selected `archive/2026-04-08/moved-to-docs/{standard,annex,schemas,regulator-sim}` into top-level canonical folders.
+2. Preserve `docs/AI-HPP-Standard.md` as alias shim only; mark non-canonical.
+
+## Archive (retain, clarify scope)
+
+- Keep all files in `archive/` for traceability, but add an archive index stating:
+  - historical purpose,
+  - non-authoritative status (unless explicitly referenced),
+  - mapping to current canonical paths.
+
+## Deprecate
+
+- Deprecate active references to non-existent `docs/index.md` and `docs/templates/*` from `CONTRIBUTING.md`.
+- Deprecate stale archive links pointing to removed `spec/ai_hpp_specification.md`.
+
+## Merge / rationalize
+
+- Translation structure in `uk-UA` should be rationalized (legacy `.uk.md` + synced files): keep both, but add one explicit “authoritative translation set” pointer.
+- Consider adding a machine-readable canonical manifest (e.g., `CANONICAL_PATHS.yaml`) listing official overview/modules/schemas/conformance/governance/translations paths.
+
+---
+
+## Structural risk summary
+
+Critical confusion risk for external experts is not missing content; it is **canonical ambiguity + discoverability drift**. The repository contains high-value governance material, but it is split between active and archived surfaces without a strict canonical declaration.