Skip to content

docs+meta: wiki source-of-truth + STATE.a2ml updated for Phase 0 closure#61

Merged
hyperpolymath merged 2 commits into
mainfrom
phase-0/wiki-and-machine-docs
May 25, 2026
Merged

docs+meta: wiki source-of-truth + STATE.a2ml updated for Phase 0 closure#61
hyperpolymath merged 2 commits into
mainfrom
phase-0/wiki-and-machine-docs

Conversation

@hyperpolymath
Copy link
Copy Markdown
Owner

Summary

Phase 0 documentation update for humans (wiki) and machines (.a2ml).

Wiki (docs/wiki/)

The GitHub wiki at hyperpolymath/typed-wasm/wiki had stale content (PMPL license, pre-restructure proof paths, no mention of production-path or current state). Sandboxed sessions can't write to the wiki repo directly — signing infrastructure is scoped to typed-wasm.git. So wiki content is now sourced from docs/wiki/ in this repo with a documented sync workflow.

Page Purpose
Home.md Landing — current state, 10-level table, killer feature, quick start, sibling projects, MPL-2.0 license corrected
Production-Path.md The 6-phase plan (companion to docs/PRODUCTION-PATH.adoc)
Phase-0-Status.md Live closure state with PR cross-links + test surface summary; documents which Phase 0 gates are met
Comparison.md Landscape vs MS-Wasm / CHERI-Wasm / wasmGC / AssemblyScript / Rust / CompCert at each maturity level
README.md Sync workflow + authoring rules

To deploy: cp docs/wiki/*.md ~/twasm-wiki/ && cd ~/twasm-wiki && git add -A && git commit -m "Sync from typed-wasm" && git push

STATE.a2ml (machine-readable)

Comprehensive update for the Phase 0 closure pass — was anchored to 2026-04-12. Highlights:

Files

  • docs/wiki/Home.md — new
  • docs/wiki/Production-Path.md — new
  • docs/wiki/Phase-0-Status.md — new
  • docs/wiki/Comparison.md — new
  • docs/wiki/README.md — new (sync workflow)
  • .machine_readable/6a2/STATE.a2ml — comprehensive update

No code changes.

Test plan

  • Markdown renders cleanly when synced to wiki repo
  • STATE.a2ml parses as valid TOML
  • No regressions in existing test surfaces (no code changed)
  • All PR cross-links in Phase-0-Status.md resolve

Generated by Claude Code

…r Phase 0 closure

Two surfaces updated for humans and machines:

## Wiki (humans, outside readers)

GitHub wiki at hyperpolymath/typed-wasm/wiki had stale content:
- License referenced PMPL-1.0-or-later (project is now MPL-2.0)
- Idris2 proof paths pointed at src/abi/Proofs.idr
  (actual: src/abi/TypedWasm/ABI/Proofs.idr after restructure)
- Single Home page; no mention of production-path, phases,
  comparison landscape, current status, sibling projects,
  Rust verifier crate, tree-sitter scaffold

The wiki lives in a separate git repo (typed-wasm.wiki.git) that
sandboxed sessions in this workspace can't sign commits for —
signing infrastructure is scoped to typed-wasm.git. So the source
of truth for wiki content now lives at docs/wiki/ in this repo,
committed alongside the code, with a sync workflow documented in
docs/wiki/README.md.

New / rewritten pages staged at docs/wiki/:
- Home.md — current state, 10-level table, killer feature, quick
  start, sibling projects, MPL-2.0 license (fixed)
- Production-Path.md — the 6-phase plan (companion to
  docs/PRODUCTION-PATH.adoc)
- Phase-0-Status.md — live closure state with PR cross-links and
  test surface summary; documents which Phase 0 gates are met
- Comparison.md — landscape vs MS-Wasm / CHERI-Wasm / wasmGC /
  AssemblyScript / Rust / CompCert at each maturity level

## STATE.a2ml (machines, agents)

Comprehensive update for Phase 0 closure pass:
- last-updated 2026-04-12 -> 2026-05-24; session line replaced
  with this session's 7-PR summary
- completion-percentage 55 -> 70 (reflects defensibly-engineered
  foundation, codegen kickoff, test surface expansion)
- New keys: production-phase = "0", production-phase-status with
  the 3-gate breakdown
- milestones[]:
  * "Parser, Zig FFI, smoke-test surface" 80 -> 100
  * "De-template release/build metadata" 15 -> 60
    (security.txt + SPDX fixes in PR #57)
  * "Evidence-backed benchmarks and aspect coverage" 10 -> 70
    (property + security-envelope + proof-regression in PR #57)
  * Added 4 new milestones: production-path doc + tracking
    issues, tree-sitter scaffold (20%), CI persistent-reds
    hardening, ROADMAP truthfulness audit
- blockers-and-issues[]: dropped "Release/container scaffolding
  template residue" (fixed); added Track A codegen-v0,
  Track B AffineScript cross-repo, Build+E2E root cause,
  A2ML/K9 third-party action issues, anti-pattern policy
  (auto-fixed by Track A), Hypatia false-positive scanner
- critical-next-actions[]: replaced with Track A/B sequence,
  Build+E2E investigation, ADRs for D1-D6
- last-result warn -> pass (all gating CI is green; previously-red
  jobs are explicitly advisory now)
- open-warnings 1 -> 4 (Build+E2E + A2ML + K9 + anti-pattern,
  all documented advisories)
- Added [test-surface] section with 545+ assertion total across
  11 enumerated surfaces
- ecosystem.depends-on: removed ReScript (being-removed in Track A);
  added ships-to for AffineScript + Ephapax consumption
- Added [tracking-issues] mapping each phase to its GitHub issue

No code changes. Wiki content goes live by maintainer running the
sync workflow in docs/wiki/README.md.
@github-actions
Copy link
Copy Markdown

🔍 Hypatia Security Scan

Findings: 93 issues detected

Severity Count
🔴 Critical 6
🟠 High 36
🟡 Medium 51

⚠️ Action Required: Critical security issues found!

View findings
[
  {
    "reason": "Issue in quality.yml",
    "type": "missing_workflow",
    "file": "quality.yml",
    "action": "create",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "Issue in security-policy.yml",
    "type": "missing_workflow",
    "file": "security-policy.yml",
    "action": "create",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "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": "Action actions/upload-artifact@v4 needs attention",
    "type": "unpinned_action",
    "file": "release.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Action actions/download-artifact@v4 needs attention",
    "type": "unpinned_action",
    "file": "release.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "believe_me undermines formal verification (1 occurrences, CWE-704)",
    "type": "believe_me",
    "file": "/home/runner/work/typed-wasm/typed-wasm/src/abi/TypedWasm/ABI/SessionProtocol.idr",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "critical"
  },
  {
    "reason": "assert_total bypasses totality checker (1 occurrences, CWE-704)",
    "type": "assert_total",
    "file": "/home/runner/work/typed-wasm/typed-wasm/src/abi/TypedWasm/ABI/SessionProtocol.idr",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "high"
  },
  {
    "reason": "believe_me undermines formal verification (1 occurrences, CWE-704)",
    "type": "believe_me",
    "file": "/home/runner/work/typed-wasm/typed-wasm/src/abi/TypedWasm/ABI/Echo.idr",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "critical"
  },
  {
    "reason": "assert_total bypasses totality checker (1 occurrences, CWE-704)",
    "type": "assert_total",
    "file": "/home/runner/work/typed-wasm/typed-wasm/src/abi/TypedWasm/ABI/Echo.idr",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "high"
  },
  {
    "reason": "believe_me undermines formal verification (1 occurrences, CWE-704)",
    "type": "believe_me",
    "file": "/home/runner/work/typed-wasm/typed-wasm/src/abi/TypedWasm/ABI/ResourceCapabilities.idr",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "critical"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence

hyperpolymath added a commit that referenced this pull request May 25, 2026
- Delete rescript.json, create affinescript.json
- Rename .res files to .affine (7 files)
- Convert SafeDOMExample.affine to AffineScript syntax
- Replace all ReScript references with AffineScript in:
  - Documentation files
  - Configuration files (Justfile, package.json, web-project-deno.json)
  - .hypatia-ignore exemptions
- Parser .affine files retain OCaml-style syntax pending full migration

Addresses Language / package anti-pattern policy failures in PRs #61 and #62.

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
@hyperpolymath hyperpolymath merged commit e539466 into main May 25, 2026
25 of 27 checks passed
@hyperpolymath hyperpolymath deleted the phase-0/wiki-and-machine-docs branch May 25, 2026 15:31
hyperpolymath added a commit that referenced this pull request May 25, 2026
…dd audit/onboarding/status/proposals stubs (#63)

## Summary

Complete document tidy of the repo for humans and machines.
RSR-template-aligned taxonomy, deletions of worthless / template-residue
files, additions of missing taxonomy stubs, drift-detection enforcement
of the new structure.

## Deletions (8 files, ~all worthless)

| File | Why |
|---|---|
| `QUICKSTART-DEV.adoc` | Template residue — contained unfilled
`{{BUILD_CMD}}`, `{{TEST_CMD}}`, `{{LANG_STACK}}` placeholders |
| `QUICKSTART-USER.adoc` | Template residue — body literally said "Typed
Wasm — See README.adoc for details." |
| `QUICKSTART-MAINTAINER.adoc` | Template residue — same pattern |
| `README.adoc.invariants.md` | Auto-generated heuristic "invariant
suggestion" garbage; no purpose |
| `docs/WHITEPAPER.md.invariants.md` | Same pattern |
| `docs/wikis/0.2-AI-MANIFEST.a2ml` + `docs/wikis/README.adoc` | Empty
placeholder directory conflicting with `docs/wiki/` (from PR #61) —
that's where actual wiki source lives |
| `generated/abi/README.adoc` | Tracked file inside a `generated/`
directory that's supposed to be gitignored; content moved to
`docs/architecture/ABI-PIPELINE.adoc` |

The 3 deleted QUICKSTARTs are replaced by the single clean
`docs/QUICKSTART.adoc` that already exists (60-second build + test path;
no template residue).

## Additions (4 new files, RSR-template alignment)

| File | Purpose |
|---|---|
| `AUDIT.adoc` (root) | RSR-template hard-rules summary;
typed-wasm-specific audit posture; status pointers; bot rules |
| `docs/onboarding/README.adoc` | New-contributor entry point;
reading-order; by-role guidance (use / contribute / proofs / security) |
| `docs/status/README.adoc` | RSR taxonomy alignment — pointer to the
root status documents (LEVEL-STATUS / PROOF-NEEDS / TEST-NEEDS);
explains why they stay at root |
| `docs/proposals/README.adoc` | RSR taxonomy alignment — staging ground
for future design proposals; authoring rules |
| `docs/architecture/ABI-PIPELINE.adoc` | Content rescued from the
deleted `generated/abi/README.adoc`; now in the architectural layer it
belongs to |

## Updates

- **`README.adoc`** — Quick Tour rebuilt with current paths (uses
`src/abi/TypedWasm/ABI/*.idr`, includes tree-sitter grammar, verifier
crate, status documents, AUDIT.adoc, onboarding index)
- **`ffi/zig/src/main.zig`** — header comment updated to point at new
`docs/architecture/ABI-PIPELINE.adoc` instead of deleted
`generated/abi/README.adoc`
- **`.gitignore`** — gitignore
`tools/tree-sitter-twasm/package-lock.json` for consistency with the
existing "deno.lock is the lockfile of record" convention
- **`tests/aspect/claim-envelope.mjs`** — pinned new RSR taxonomy files
(`AUDIT.adoc`, `docs/onboarding/README.adoc`, `docs/status/README.adoc`,
`docs/PRODUCTION-PATH.adoc`) into the rsrFiles list so drift-detection
enforces the new structure going forward
- **`docs/wiki/Phase-0-Status.md`** — synced with PR #62 (tree-sitter
v1) merge + this tidy PR in flight

## RSR taxonomy alignment

Compared to `hyperpolymath/rsr-template-repo`:

| RSR template item | typed-wasm status |
|---|---|
| `AUDIT.adoc` (root) | ✅ added in this PR |
| `EXPLAINME.adoc` (root) | ✅ already present |
| `CHANGELOG.md` (root) | ✅ already present |
| Single `QUICKSTART.adoc` | ✅ at `docs/QUICKSTART.adoc`; 3 root
template-residue versions deleted |
| `docs/onboarding/` | ✅ added in this PR |
| `docs/status/` | ✅ added in this PR (root status docs remain for
visibility; this is a pointer) |
| `docs/proposals/` | ✅ added in this PR |
| `docs/decisions/` | ✅ already present |
| `docs/architecture/` | ✅ already present (+ new ABI-PIPELINE.adoc) |

## What's NOT changed (deliberate)

- **`LEVEL-STATUS.md`, `PROOF-NEEDS.md`, `TEST-NEEDS.md` stay at root.**
These are read every audit, every CI run, every reviewer's first-pass —
root visibility is load-bearing. The RSR alignment is achieved via
`docs/status/README.adoc` as a pointer rather than a move that would
break dozens of existing references in workflow files + aspect tests.
- **`SPARK-experiment/`** stays. It's lightweight (one README), clearly
self-marked as exploratory, costs nothing to keep, and represents a real
future direction.
- **`benchmarks/`** not renamed to RSR template's `benches/`. The plural
form is already integrated everywhere (Justfile, CI, aspect tests); the
rename cost exceeds the consistency benefit.
- **`docs/arxiv/`, `docs/governance/`, `docs/legal/`, `docs/practice/`,
etc.** — keeping them as-is; RSR template scaffolding that's already in
place.

## Verification

All test surfaces green after tidy:

| Surface | Result |
|---|---|
| `claim-envelope` aspect | **57 passed** (was 53; +4 from new RSR file
pins) |
| `security-envelope` aspect | 10 passed |
| `property_test` | 29 passed |
| `proof/regression` | 25 passed, 1 skipped (idris2 not on PATH) |

claim-envelope §8 (path-reference drift detection) confirms all 31 path
references across README/ROADMAP/EXPLAINME/CLAUDE.md resolve on disk
after the changes.

## Test plan

- [x] Test surfaces all green locally
- [x] No dangling references to deleted files (`git grep` confirms)
- [ ] CI on this PR matches expected pattern (cargo-audit / smoke /
structural / cargo-verify green; persistent-red advisories unchanged)
- [ ] Reviewer can read `docs/onboarding/README.adoc` and reach a
working build via `docs/QUICKSTART.adoc`

## Repo health summary after this PR lands

- ✅ Root directory: only load-bearing files (no template residue, no
stale heuristic artefacts)
- ✅ Documentation taxonomy: RSR-aligned without breaking existing
references
- ✅ Drift detection: enforces new structure (claim-envelope §3 + §8)
- ✅ Wiki source: tracked in `docs/wiki/` with sync workflow;
cross-referenced from `Phase-0-Status.md` page
- ✅ Machine-readable: `.machine_readable/6a2/STATE.a2ml` reflects
current state (post #61)
- ✅ Audit posture: explicit at `AUDIT.adoc`, machine + human readable
- ✅ Onboarding: `docs/onboarding/README.adoc` gives a 5-minute path for
any new role


---
_Generated by [Claude
Code](https://claude.ai/code/session_01ExgUTJmU5UQQNLKynwxDjm)_

---------

Co-authored-by: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants