docs(readme): expand stub README to full structure

[hyperpolymath]

Summary

Expands the previous stub README (< 20 lines) into a substantive README covering: project description, layout, quickstart, status, and companion-repo cross-references. Grounded in this repo's actual content; no fabricated features.

Closes Row-2 Phase 1 of the 2026-05-26 estate tech-debt audit chain (covers this repo's HIGH-severity finding from standards#197).

Companion

• standards#197 — estate documentation-debt audit (the audit that flagged this).
• rsr-template-repo#75 — the docs-template/ seed this README's structure mirrors.

🤖 Generated with Claude Code

[github-actions]

🔍 Hypatia Security Scan

Findings: 80 issues detected

Severity	Count
🔴 Critical	6
🟠 High	39
🟡 Medium	35

⚠️ Action Required: Critical security issues found!

View findings

[
  {
    "reason": "Action hyperpolymath/standards/.github/workflows/governance-reusable.yml@main needs attention",
    "type": "unpinned_action",
    "file": "governance.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "unwrap_or(0) with dangerous default (1 occurrences, CWE-754)",
    "type": "unwrap_dangerous_default",
    "file": "/home/runner/work/my-lang/my-lang/_exploratory/me-scaffolding/crates/parser/src/lib.rs",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "critical"
  },
  {
    "reason": "expect() in hot path (80 occurrences, CWE-754)",
    "type": "expect_in_hot_path",
    "file": "/home/runner/work/my-lang/my-lang/_exploratory/me-scaffolding/crates/parser/src/lib.rs",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "medium"
  },
  {
    "reason": "unwrap() without prior check -- DoS via panic (1 occurrences, CWE-754)",
    "type": "unwrap_without_check",
    "file": "/home/runner/work/my-lang/my-lang/my-ssg/src/generator.rs",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "high"
  },
  {
    "reason": "expect() in hot path (5 occurrences, CWE-754)",
    "type": "expect_in_hot_path",
    "file": "/home/runner/work/my-lang/my-lang/crates/my-mir/src/lib.rs",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "medium"
  },
  {
    "reason": "unwrap() without prior check -- DoS via panic (26 occurrences, CWE-754)",
    "type": "unwrap_without_check",
    "file": "/home/runner/work/my-lang/my-lang/crates/my-fmt/src/lib.rs",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "high"
  },
  {
    "reason": "unwrap() without prior check -- DoS via panic (1 occurrences, CWE-754)",
    "type": "unwrap_without_check",
    "file": "/home/runner/work/my-lang/my-lang/crates/my-hir/src/lib.rs",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "high"
  },
  {
    "reason": "unwrap() without prior check -- DoS via panic (3 occurrences, CWE-754)",
    "type": "unwrap_without_check",
    "file": "/home/runner/work/my-lang/my-lang/crates/my-llvm/src/lib.rs",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "high"
  },
  {
    "reason": "unsafe block -- requires SAFETY comment (1 occurrences, CWE-676)",
    "type": "unsafe_block",
    "file": "/home/runner/work/my-lang/my-lang/crates/my-llvm/src/lib.rs",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "medium"
  },
  {
    "reason": "mem::transmute bypasses type safety with unchecked bit reinterpretation (1 occurrences, CWE-704)",
    "type": "transmute",
    "file": "/home/runner/work/my-lang/my-lang/crates/my-llvm/src/lib.rs",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "critical"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence