Cardano Updates

Two changes bundled:

1. Removed every comment in tracked files that pointed at the (uncommitted)
   roadmap plan or .codex-reviews/ logs. Plan-internal terminology (P1W1,
   P1W2, "Wave 1/2", "milestone log") is replaced with plain language that
   stands on its own. References to docs that don't exist (e.g.
   docs/how-to/add-framework.md, docs/reference/example-manifest.md, etc.)
   are removed; the surviving canonical docs are frameworks/SCHEMA.md and
   the inline comments themselves.

2. CI workflow gating made explicit:
   - All build jobs (discover, compile-aiken, test-offchain) continue to
     run on every PR. Triggers were already correct; added an explicit
     comment near the `pull_request:` trigger to make this guarantee
     visible.
   - The report job's matrix.json artifact upload (the data a future
     dashboard-publish workflow will consume) is now gated to non-PR
     events via `if: github.event_name != 'pull_request'`. PR runs still
     aggregate, render to step summary, and post the report as a PR
     comment — they just don't produce the artifact that would drive the
     public dashboard.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

The action's outputs: block previously enumerated specific libraries (aiken,
deno, node, jdk, jbang, yaci_devkit, protocol_version) so workflows could
reference them in `with:` blocks without triggering the GitHub Actions
language server's "Context access might be invalid" warning. That solved the
linter noise but broke the "zero edits to add a new library" promise — every
new pinned tool flowing into a `with:` block required a static outputs entry
in action.yml on top of the versions.yml line.

Now: action.yml has no outputs: block. Every key in versions.yml is exported
as <KEY>_VERSION via $GITHUB_ENV (already generic, untouched). Workflow `with:`
blocks reference ${{ env.X_VERSION }} directly. The linter shows three
expected yellow warnings (NODE_VERSION, DENO_VERSION, JDK_VERSION in the
test-offchain setup steps; AIKEN_VERSION in the cache key); runtime works
correctly. The action's description documents this trade-off.

Result: adding a new pinned library is now genuinely a one-file change to
versions.yml. The framework registry's "zero workflow edits" promise covers
toolchain pinning too.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

The autonomous milestone-level Codex review logs are local-only audit
artifacts and should not be tracked in the repository. Added .codex-reviews/
to .gitignore and removed the previously-committed p1w1-yaci-poc.md and
p1w1.md from the branch (kept locally on disk via git rm --cached).

Earlier commits in this branch's history still contain those files; this
commit only removes them from the current branch state. If a fully clean
history is needed, an interactive rebase + filter is required — call out
explicitly before doing that.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

The autonomous milestone-level Codex review loop converged on iteration 6.
No new substantive issue surfaced; iteration 5's matrix-aggregation gate
fix verified correct under all edge cases (Aiken skipped, Aiken ran with
all-pass, Aiken ran with partial-fail, no Aiken examples).

Three deliberate deviations carried forward (all documented and consistent
with the roadmap plan):
- S7: pin enforcement script deferred to P1W2 (right time given P1W2 touches
  every per-file pin during manifest migration anyway).
- S8: broader runner-contract migration deferred to P1W2 (only the named
  silent-fail in AtomicTransaction.java was fixed; other pilot examples are
  either library code or CLI utilities needing test runners — out of P1W1
  scope).
- N1: tutorial-grade READMEs deferred to P1W2 (the plan puts them at 1.7
  under Wave 2, not P1W1).

.codex-reviews/p1w1.md: full iteration ledger committed. Six iterations
total: prompt, response, action ledger per iteration. Codex's iteration-6
response with the explicit "CONVERGED" verdict is captured at the end.

Milestone status: ready for human review.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Iteration 4's plutus.json download gate (`needs.compile-aiken.result == 'success'`)
was too coarse: GitHub aggregates matrix-child results into the parent job's
`result`, so one failed Aiken cell made the aggregate non-success and
suppressed the download for every offchain matrix child — including ones
whose artifact actually existed. A localized compile failure became a global
artifact blackout.

Fixed: gate is now `needs.compile-aiken.result != 'skipped'` plus
`continue-on-error: true` on the download step. When compile-aiken is
skipped entirely (aiken not registered), the gate is false and the download
is skipped. When compile-aiken ran (regardless of whether some matrix
children failed), the download is attempted; missing artifacts for failed
cells produce a download error that continue-on-error swallows, and
downstream run-cell.sh invocations fail per-cell with their own clear errors.
Use cases whose Aiken compile succeeded continue to get their plutus.json
correctly.

Plus minor SCHEMA.md fix: replaced the non-existent `compile-onchain` job
reference with "a per-language compile job — today only compile-aiken,"
linking to the Pilot Limitations section that explains the per-language
shape.

.codex-reviews/p1w1.md: iteration 5 actions logged.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

(1) test-offchain previously inherited a skip from compile-aiken because its
`if:` condition only checked offchain output. When the new `compile-aiken`
gate skips that job (e.g. aiken not registered), GitHub Actions silently
skipped test-offchain too — undercutting the "limitation visible in CI logs"
claim. Fixed: `if: always() && needs.discover.result == 'success' && ...`.

(2) The plutus.json download step ran unconditionally, which would fail any
future offchain use case without a compiled Aiken artifact. Fixed: gated
the download on `needs.compile-aiken.result == 'success'`. When aiken is not
registered or compile-aiken failed, the download is skipped; offchain
examples that depend on plutus.json fail at run time with their own clear
error, surfaced as a fail cell in matrix.json rather than masked by an
artifact-system error.

(3) SCHEMA.md opened with "Adding a new framework requires no workflow YAML
edits" but later acknowledged onchain language additions require a sibling
job. The opening now distinguishes offchain SDKs (genuinely descriptor-only)
from onchain languages (descriptor + sibling workflow job), matching the
detailed Pilot Limitations section.

.codex-reviews/p1w1.md: iteration 4 actions logged.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Addresses iteration 3's three new substantive findings.

(1) Onchain descriptors not workflow-generic: added an explicit `if:` gate to
the compile-aiken job that requires `aiken` to be in `registered-onchain`. If
a non-aiken onchain framework is registered, the job is skipped and the
limitation is visible in CI logs. SCHEMA.md "Pilot limitations" rewritten to
document onchain CI generalization as P1W2 work — adding a new onchain
language requires both a descriptor AND a sibling compile-<framework> job.
The descriptor → matrix-membership half is generic; setup + artifact
handling remain framework-specific by design pending P1W2.

(2) manifest_key vs descriptor-filename mismatch: scripts/local-test-discovery.sh
now writes per-use-case offchain framework lists at
.local-test-results/uc/<use_case>.offchain.txt. These lists contain
**descriptor names** (not manifest keys); manifest_key → descriptor-name
resolution is centralized in discovery via the KEY_TO_FRAMEWORK map. The
workflow's offchain-cells step reads the file directly and passes descriptor
names straight to scripts/ci/run-cell.sh — no manifest_key lookup or
descriptor parsing in the workflow at all.

(3) Heuristic cwd predicate disagreement: the same per-use-case file is
already heuristic-aware via discovery's existing descriptor-cwd lookup. The
workflow no longer does its own heuristic detection. Eliminated the parallel
codepath that assumed `offchain/<descriptor-name>`.

The test-offchain job re-runs discovery at job start to generate the
per-use-case files (idempotent, sub-second).

Verified locally: all four pilot use cases and all 15 heuristic-fallback use
cases produce per-use-case offchain framework lists; vesting (previously
invisible to filename heuristics) now correctly resolves to its single
meshjs entry.

.codex-reviews/p1w1.md: iteration 3 actions logged in full.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Addresses Codex review iteration 2's "not converged" verdict. Three substantive
gaps closed:

- scripts/local-test-discovery.sh is now generic over `frameworks/*.yml`. The
  hard-coded `meshjs`, `lucid-evolution`, `ccl-java` cases are gone. Discovery
  enumerates registered frameworks, walks every use case for every framework
  (manifest mode + heuristic fallback using each descriptor's
  run.cwd_relative_to_example as the presence cue), and writes per-framework
  lists keyed by descriptor name. `use-cases-with-offchain` is now the union
  of every offchain framework's list, including any newly-registered SDKs.

- Deleted `.github/actions/run-framework/`. The composite action was a thin
  wrapper around `scripts/ci/run-cell.sh` that the workflow never called —
  Codex flagged the contract disagreement. The script is the single public
  runner interface; SCHEMA.md updated to point at it.

- Strengthened aggregator validation in scripts/aggregate-results.sh:
  requires `status` ∈ {pass, fail, skipped}, integer-coercible `duration_ms`,
  `framework`, and tier-specific identity (`use_case` for `use-case-example`,
  `use_case` + `id` for `use-case-scenario`, `id` for `primitive`). Cells
  failing validation surface as fails with `error_summary: "schema
  violation: …"` rather than silently passing through.

- frameworks/SCHEMA.md "Notes" section rewritten to honestly describe the
  runtime: script as entry, generic discovery, explicit P1W1 pilot limitation
  that `setup:` and `needs_yaci:` are documentation-only (the workflow
  installs every offchain runtime unconditionally). Future descriptor with
  `needs_yaci: false` will silently get Yaci anyway — a known labeled
  limitation, not a hidden bug.

- ecosystem-test.yml: removed dead `mesh-examples`, `lucid-examples`,
  `ccl-examples` outputs from the discover job. Surfaced `registered-onchain`
  and `registered-offchain` for downstream visibility.

- .codex-reviews/p1w1.md: iteration 2 actions logged. AtomicTransaction.java's
  change is reframed as "silent-fail hardening" (the original plan's named
  fix), not "runner-contract migration" — the descriptors honestly declare
  `convention: exit-code` and the broader migration is P1W2 work.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Addresses Codex review iteration 1 on the milestone diff. Key changes:

- scripts/ci/run-cell.sh becomes descriptor-aware. Reads frameworks/<name>.yml
  for cwd_relative_to_example, run.command, default_entry, manifest_key,
  result.convention. Reads <use-case>/example.yml for explicit entry under
  <kind>.<manifest_key>.entry. The framework registry is now load-bearing:
  adding a new framework descriptor + manifest entry is sufficient, no
  workflow YAML edits required.

- .github/actions/run-framework/ reduced to a thin wrapper around the script.
  No more inline Python with shell interpolation; safer and simpler.

- .github/workflows/ecosystem-test.yml: replaces three hard-coded per-framework
  cell steps with one descriptor-driven step that loops over the manifest's
  declared offchain frameworks and invokes run-cell.sh for each. Falls back
  to a registry-aware heuristic for unmanifested use cases.

- Aiken false-pass fixed: result.json synthesis now happens AFTER plutus.json
  existence check, so a missing plutus.json correctly produces a fail cell
  rather than a green pass with a later step failure.

- scripts/aggregate-results.sh: minimal schema validation. Invalid cells
  (bad tier, bad status, missing framework, non-integer duration_ms) are
  surfaced as fails with schema-violation reasons rather than silently
  dropped or weakly defaulted. Tested with malformed inputs.

- .codex-reviews/p1w1.md: full milestone log captures iteration 1 prompt,
  Codex's response, every action taken, and three deliberate deviations
  (S7 pin enforcement, S8 broader runner-contract migration, N1 tutorial
  READMEs) with rationales — all deferred to P1W2 and consistent with the
  plan.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

- Adds <use-case>/example.yml manifests for the four pilot use cases:
  escrow, vesting, atomic-transaction, simple-transfer. Vesting's manifest
  fixes a discovery gap noted in the plan's Context — vesting/offchain/meshjs
  has no deno.json and was previously invisible to filename-pattern
  detection. The manifest declares it explicitly.

- Rewrites .github/workflows/ecosystem-test.yml around the framework
  registry and manifest-driven discovery. Workflow now has three jobs:
    * discover: runs scripts/local-test-discovery.sh
    * compile-aiken: matrix={use_case}, builds the contract and emits
      result.json + plutus.json artifact per cell
    * test-offchain: matrix={use_case} (collapsed per the Yaci PoC
      decision); installs all required offchain runtimes once, starts a
      single Yaci DevKit, runs each declared offchain framework
      sequentially via scripts/ci/run-cell.sh
    * report: aggregates every *.result.json into matrix.json, renders to
      markdown step summary, comments on PRs

  All env vars and step outputs flow from .github/actions/load-versions.
  Triggers include the roadmap base branch (commented as TEMPORARY for
  removal at merge-to-main).

- Migrates AtomicTransaction.java to the runner contract. The example
  previously printed isSuccessful=false and exited 0 (silent fail) — the
  plan's highest-priority example fix. Now throws AssertionError when the
  wrong-password tx unexpectedly succeeds, when the correct-password tx
  fails, or when the script top-up fails. The CCL JBang launcher
  propagates the throw as a non-zero exit.

- Drops the caret from escrow/offchain/lucid-evolution/deno.json
  (^2.0.1 → 2.0.1). Other pilot deno.json files were already exact-pinned.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Adds the supporting scripts CI consumes:

- .github/actions/load-versions: parses versions.yml with pure awk (no PyYAML
  dependency), exports each pinned version as a GITHUB_ENV variable AND as a
  step output. Step outputs exist so the GitHub Actions language server can
  resolve `with:` blocks (env-vars set via GITHUB_ENV are not visible to the
  linter at parse time).

- .github/actions/run-framework: minimal building block — runs one cell with
  given working dir and command, writes log + result.json. Intentionally not
  a "mini CI platform"; the workflow keeps framework-specific knowledge for
  Wave 1 and the action is reusable scaffolding.

- scripts/ci/run-cell.sh: workflow-side helper that resolves the entry file
  by glob, runs the framework command, captures pass/fail, prefers any
  authored result.json, falls back to synthesizing one from exit code.

- scripts/aggregate-results.sh: collects every *.result.json in a directory
  into a single matrix.json (with summary + grouped cells).

- scripts/render-matrix.sh: renders matrix.json to a markdown report grouped
  by tier, with a failures section.

- scripts/local-test-discovery.sh: rewritten as dual-mode — manifest-mode
  for use cases with example.yml, legacy heuristic fallback for the rest
  until P1W2 completes the migration. Outputs a new use-cases-with-offchain
  list so the workflow can collapse the offchain matrix per use case.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Establishes the single source of truth for tool versions (versions.yml) and
the declarative framework registry (frameworks/<name>.yml + SCHEMA.md). Adds
the four pilot framework descriptors: aiken (onchain), meshjs, lucid-evolution,
ccl-java (offchain).

The Yaci-as-service-container PoC outcome is documented in
.codex-reviews/p1w1-yaci-poc.md: the bloxbean/yaci-devkit Docker image is
unmaintained (latest tag April 2024), so this milestone adopts the planned
fallback — collapsed offchain matrix with one Yaci npm install per use case.

This is the first of several P1W1 commits; CI workflow rewrite, composite
actions, and per-cell scripts follow.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>