ibex 0.2.0 → 0.3.0

data/docs/development.md

@@ -1,3 +1,8 @@
+---
+title: Development and quality checks
+description: Contributor workflow, reproducibility checks, and quality gates for Ibex.
+---
+
 # Development and quality checks
 
 This document describes contributor workflow and repository quality gates.
@@ -20,6 +25,11 @@ Additional repository checks are:
 bundle exec rake frontend:check
 bundle exec rake grammar:test
 bundle exec rake quality:error_ux
+bundle exec rake quality:error_ux_round2
+bundle exec rake quality:workloads
+bundle exec rake quality:direct_ielr_decision
+bundle exec rake quality:maturity
+bundle exec rake quality:runtime_abi
 npm ci
 npm run test:site
 actionlint
@@ -33,6 +43,172 @@ The matrix uses the intentionally unlocked `gemfiles/compat.Gemfile` so each
 supported Ruby resolves compatible test dependencies. Contributors use the
 root `Gemfile` and its committed lockfile for every development tool.
 
+Feature development may proceed while a release decision is `HOLD`. Before
+merging the first user-visible change for a feature, check the active-track
+limits in [`stability.md`](stability.md#feature-development-budget) and update
+that inventory in the same pull request.
+
+For the active declarative parser-construction track, change the canonical
+frontend grammar and shadow grammar together, run `bundle exec rake
+frontend:generate`, and review the generated parser diff. Then run
+`frontend:check`, the parser-configuration frontend/LSP/IR/CLI tests,
+`test:no_exec`, and `test:zero_cost`. A source `parser` declaration must promote
+normalization to the current Grammar IR without changing parser-table format v6;
+declaration-free inputs must retain their existing current-format golden bytes.
+
+## Stage A safety net
+
+The pre-v1 safety suite keeps independent property tests and adds reviewable
+cross-feature orchestration:
+
+```sh
+bundle exec rake test:matrix
+bundle exec rake test:matrix:full
+bundle exec rake test:zero_cost
+bundle exec rake test:reproducible
+bundle exec rake test:compat
+bundle exec rake test:ir_schema
+bundle exec rake test:no_exec
+bundle exec rake test:adversarial
+bundle exec rake gallery:build
+bundle exec rake gallery:conflicts
+bundle exec rake fuzz:short
+bundle exec rake fuzz:direct
+bundle exec rake fuzz:injection
+bundle exec rake verify
+bundle exec rake verify:injection
+bundle exec rake verify:strict
+bundle exec rake equiv:regression
+bundle exec rake analysis:test
+bundle exec rake fix:test
+bundle exec rake i18n:coverage
+bundle exec rake deps:zero
+bundle exec rake network:zero
+```
+
+`test/matrix.yml` declares the algorithm, table, CST, semantic-location, and
+entry axes. Pull requests run twelve representative combinations; the
+scheduled workflow runs all 96. `test/golden/generated/` contains reviewable
+feature-off generated bytes and `test/golden/digests.yml` detects an
+unreviewed change. Use `bundle exec rake golden:update` only when the generated
+source change is intentional and review the normal version-control diff.
+
+`test:no_exec` is a representative static-path regression for sentence
+generation and internal differential fuzzing. Its fixture contains parser
+actions, generated lexer actions, and all user-code sections and fails if those
+commands execute any of them. Command-level tests retain responsibility for the
+other static entries in the [execution trust matrix](../README.md#execution-trust-matrix).
+`test/runtime/cst_incremental_test.rb` covers the generated syntax-only side
+with independent sentinels: lexer actions execute while parser production
+actions do not. These guarantees do not make a generated parser a sandbox;
+test generated files only when their embedded Ruby is trusted.
+
+The committed `gallery/` grammars are self-authored and separately licensed.
+Their valid/invalid corpora run through all algorithms and table formats, and
+their state/conflict metrics are fixed. The short fuzzer derives 100
+fixed-seed sentences per grammar and applies one-token insert/delete/replace
+mutations; scheduled CI raises this to 100,000. All searches have token,
+depth, expansion, action, stack, or subprocess-trial bounds. Timing and memory
+remain observations, not pass/fail thresholds.
+
+`quality:workloads` validates the [public workload registry](workloads.md),
+including exact source and license-evidence identities, measured versus
+not-measured states, benchmark eligibility, and cross-manifest consistency.
+It recomputes repository-owned grammar counts without downloading external
+source. Synthetic gallery evidence remains distinct from public and production
+workloads.
+
+`quality:error_ux_round2` regenerates the fixed H003 multi-shape diagnostic
+and repair capture in memory, validates its closed schema and required case
+coverage, and compares it byte-for-byte with the committed evidence. It also
+keeps the completed repository capture separate from the still-HOLD external
+subjective gate, validates the digest-bound independent-review registry and
+reviewer/disagreement inventory, and binds the unchanged R001 normative
+snapshot.
+
+`quality:maturity` validates the exact 18 Preview and two Experimental records
+in the [maturity audit](maturity.md), including activation, evidence gaps,
+external-use classification, issue-audit freshness, decisions, source digests,
+feature budgets, release blockers, and the synchronized public summary.
+This is an audit-integrity gate, not a promise that every Preview implementation
+or historical evidence capture remains runtime-compatible before v1.0.
+
+`quality:runtime_abi` is contract-only: it cross-checks the published [runtime ABI evolution
+policy](runtime-abi-evolution.md) and [test-interaction
+policy](test-interactions.md) against implementation constants, schemas, the
+96-case matrix, scheduled gates, and golden inputs, and ignores ambient GitHub
+event variables. The minimal `runtime-abi-assessment` CI job runs only checkout,
+Ruby setup, and the `quality:runtime_abi_pr` entry, which explicitly receives the
+pull-request event and requires the template's structured assessment when a
+declared runtime-facing path changes. Free-form prose is not parsed as an
+assessment; reviewers still decide whether the selected boundary and evidence
+are correct.
+
+When `ibex fuzz` finds a differential failure it automatically performs
+trial-bounded reduction and atomically saves a versioned fixture under
+`test/fuzz/regressions/`. Reproduce the fixed-seed fixture, add a focused test,
+and only then commit it; incomplete reduction is explicitly recorded and must
+not be called minimal. External comparisons require an explicit
+`--against-runtime` description so their runtime configuration is not omitted
+from the report or saved fixture. Per-sentence time and output limits prevent a
+stuck external target from hanging the fuzz run, and child process groups are
+cleaned up so a checker cannot leave descendants behind. `--against=COMMAND`
+is nevertheless an explicit unsafe opt-in: it executes that program with the
+developer's host permissions and is not a sandbox.
+
+`rake verify` covers every gallery grammar, construction algorithm, and plain
+or compact table representation with the default independent checks.
+`verify:injection` requires all twenty structurally valid Automaton IR
+mutations to be detected. Scheduled and manually dispatched CI additionally
+runs `verify:strict`, whose completeness checks have higher construction cost.
+`equiv:regression` fixes ten equivalent and ten non-equivalent grammar pairs,
+concrete shortest witnesses, tree mappings, and exit status 2 for exhausted
+product-state budgets.
+`analysis:test` validates the closed JSON contracts and added/removed/changed
+classification for `diff`, plus deterministic recursion and table counts for
+`metrics`.
+`fix:test` proves that emitted repairs eliminate their target without adding
+another conflict, pass the independent verifier, and find no language or
+mapped-tree difference within their reported bounds. It also replays the
+committed twenty-conflict measurement.
+The fuzz and reducer CLIs default to their versioned JSON reports and also
+exercise `--format=text` so automation and terminal use share the same result
+and exit-status contracts. Reducer subprocesses additionally have explicit
+time, output, input, and trial budgets; budget exhaustion is not accepted as a
+reproduced failure. `reduce --command=COMMAND` executes arbitrary checker code;
+those budgets do not sandbox its filesystem, network, process, or other side
+effects.
+`i18n:coverage` requires exact message-ID and interpolation parity across every
+built-in language catalog, and exercises option, environment, fallback, text,
+and JSON paths.
+
+## Release basis
+
+Before selecting a release revision, run:
+
+```sh
+bundle exec rake release:reproducible
+```
+
+The gate normalizes the RBS declarations named in
+`tool/quality/stable-api-v1.yml` and requires zero differences from the
+v0.2.0 baseline. Comments and blank lines do not affect the fingerprint. The
+lock covers the Stable runtime, batch CST, current IR, and table surfaces;
+Preview- and Experimental-only signature files are not promoted by appearing
+elsewhere in the generated RBS tree.
+
+The same task builds `ibex-runtime` and `ibex` twice in separate temporary
+directories with different locale, timezone, and frozen-string settings. It
+requires byte-identical `.gem` files, rejects unsafe or development-only
+package paths, and prints the SHA-256 digest for each artifact. It never
+publishes a package and leaves no release artifact in the repository.
+
+Artifact signing is deliberately not simulated with a repository-local key.
+The release remains blocked until the outcome gates in
+[`release-readiness.md`](release-readiness.md) pass. When that happens, the
+release environment must provide a protected external signing identity and
+bind its signature or provenance attestation to the printed artifact digest.
+
 ## Browser site and API documentation
 
 Install the locked browser dependencies and build the same self-hosted site
@@ -82,7 +258,7 @@ ruby -e '
   sources = Dir.glob("lib/**/*.rb").sort
   exec("bundle", "exec", "rbs-inline", "--opt-out", "--base=lib", "--output=sig", *sources)
 '
-bundle exec rbs -r digest -r json -r optparse -r tempfile -r timeout -r tmpdir -r uri -I sig validate
+bundle exec rbs -r digest -r fileutils -r json -r optparse -r tempfile -r timeout -r tmpdir -r uri -I sig validate
 bundle exec steep check
 bundle exec ruby tool/type_stats.rb --write
 ```
@@ -113,7 +289,8 @@ tool's Ruby floor does not change the library's Ruby floor.
 Performance observations are not ordinary CI timing thresholds. Follow the
 [benchmark guide](../benchmark/README.md) for workload identities, formal
 comparison commands, environment matching, artifact validation, and
-append-only result history.
+append-only result history. Use stable workload and problem IDs from the
+[workload registry](workloads.md) when proposing or prioritizing improvements.
 
 The development bundle includes the exact-version external-grammar profiler:
 

data/docs/direct-ielr-decision.md

@@ -0,0 +1,120 @@
+# Direct IELR decision dossier
+
+I001 is **NO-GO** for release promotion. An experimental direct IELR
+implementation may exist behind an explicit opt-in, but it is not authorized as
+the default or as a release-readiness claim; I002 remains
+blocked. This decision is a feature gate, not a claim that direct IELR has no
+future value.
+
+The final decision date is 2026-08-11. Revision
+`d77aeeaf7eb47ad3b7cc70e7ba64f070194164ff` is the repository evidence snapshot
+reviewed immediately before this dossier was published; it is not a claim that
+the dossier itself existed in that revision. The machine record marks the
+decision `final_no_go`, its basis `repository_evidence`, and its review state
+`validated`. It asserts no signer, consent, or personal decision attribution.
+
+The closed machine record is
+[`direct-ielr-decision-v1.json`](../tool/quality/evidence/direct-ielr-decision-v1.json),
+validated by
+[`direct-ielr-decision-v1.schema.json`](../schema/direct-ielr-decision-v1.schema.json).
+Run its evidence and policy gate with:
+
+```sh
+bundle exec ruby -Ilib -r./tool/quality/direct_ielr_decision \
+  -e 'Ibex::Quality::DirectIELRDecision.new.verify!'
+```
+
+## Decision rules
+
+A GO requires every GO condition. The current record satisfies none of them.
+
+| GO condition | Status | Current evidence |
+| --- | --- | --- |
+| At least two representative real grammars show practical canonical-state or item cost. | Not satisfied | H005 has one measured real grammar. |
+| IELR is required by those representative grammars. | Not satisfied | There are zero real IELR-required workloads and zero semantically reviewed conflict removals. |
+| An algorithm and specification owner exists. | Not satisfied | No accepted owner is recorded. |
+| A noncanonical verification plan exists. | Not satisfied | No accepted scale-independent plan exists; the current verified workflow requires full canonical LR(1). |
+| The maintenance budget is accepted. | Not satisfied | No accepted ongoing implementation, verification, review, and maintenance budget is recorded. |
+
+A single NO-GO condition is sufficient. All five conditions remain explicit so
+that later reviews cannot silently narrow the policy.
+
+| NO-GO condition | Status | Current evidence |
+| --- | --- | --- |
+| No real workload requires IELR. | Satisfied | No measured real workload currently requires IELR. |
+| Canonical LR(1) completes within the current project budget. | Satisfied for the measured scope | The one measured real grammar completes without observed exhaustion. This is not a general scale bound. |
+| LR(1) or a grammar rewrite is simpler. | Not assessable | There is no concrete real conflict case on which to compare alternatives. |
+| The verifier would still enumerate the full canonical collection. | Satisfied | Default and strict `ielr1` verification both enumerate full canonical LR(1). |
+| The benefit is only state-count vanity. | Satisfied | No semantic conflict-removal benefit is established. Structural counts alone do not justify a second construction algorithm. |
+
+The decision is therefore NO-GO on more than one independent ground. In
+particular, promoting a direct builder now would leave the dominant
+canonical-collection cost in the verified workflow.
+
+## Bound observations and verification gaps
+
+H005 records one measured real workload, `ibex-frontend`: 227 LR(0) states and
+633 LR(0) items, 456 canonical states and 10,482 canonical items, and 227 final
+IELR states. It has no unresolved conflict requiring IELR. The three registered
+public-real workloads were not run, so there are zero verified public
+checkouts in this capture.
+
+The canonical scale problem is unresolved. Completion of the one measured real
+grammar does not establish an upper bound for other grammars. Conversely, the
+current default and strict verifier both build full canonical LR(1), so direct
+construction alone cannot remove that cost from a verified build.
+
+V001's supported IELR check establishes membership in a canonical-core union
+and, in strict mode, union coverage. It does not verify IELR adequacy, conflict
+preservation, why a state was split, or split witnesses. The dossier records
+all three relevant assurances as `not_verified`.
+
+## Reconsideration gate
+
+Reconsideration requires all of the following new evidence:
+
+1. At least two verified representative real grammars.
+2. Material canonical state/item cost or observed bounded exhaustion on those grammars.
+3. Semantically reviewed, meaningful conflicts that IELR removes on those grammars.
+4. A bounded verification plan that does not make full canonical LR(1) enumeration mandatory.
+5. An identified owner who accepts the algorithm and specification.
+6. An accepted implementation, verification, review, and maintenance budget.
+
+State-count reduction without a real semantic or operational need does not
+reopen the gate.
+
+## Legal and implementation provenance
+
+Any future direct IELR design must be independently derived from papers and
+specifications. GPL implementation source, including GNU Bison implementation
+source, must not be inspected as a design input or translated. No GPL
+implementation source was used or translated for this decision. This rule does
+not replace project license review if the gate is reconsidered.
+
+## Evidence identity
+
+The machine dossier binds the H005 human report, H005 machine evidence and
+schema, the V001 trust-boundary report, and the current reference-collection
+and verifier implementations by path and SHA-256 at the reviewed revision. It
+also binds:
+
+- H005 capture base revision
+  `b5933ae49297422546113577072efce59878009f`;
+- H005 bound-path digest
+  `27b5abf3e1ec20b9b904e46c9f7283ebb6b9a710bb3f0d05a6cad067d9627ac3`;
+- H005 implementation digest
+  `6c62c6c1ca7f9ad078405019502d1e7bed8364d1786a4f45755480d372122aac`;
+- V001 revision `c7e5cad89ccd00591f3127fdb76a789bbeb202ab`.
+
+The quality gate verifies the schema, exact GO/NO-GO inventory, follow-on
+block, H005 thresholds and measurements, V001 boundary statements, legal
+lineage, revision ancestry, every current and reviewed-revision source digest,
+and the aggregate source-list digest. A changed source requires an explicit new
+decision record rather than silently inheriting this decision. In particular,
+the final H005 recapture must be followed by a dossier refresh, even if its
+high-level NO-GO result is unchanged.
+
+Exact reviewed history is part of the evidence contract. A shallow checkout
+that omits the decision or V001 revision fails closed with an unavailable
+revision error. Jobs running this gate must fetch complete history; they must
+not silently weaken source verification to accommodate a depth-one checkout.

data/docs/direct-multi-entry-decision.md

@@ -0,0 +1,82 @@
+# Direct multi-entry construction decision
+
+M001 is **MORE DATA**. Production direct shared multi-entry construction,
+public experiments, and default-path changes are not authorized. This is not a
+NO-GO claim: the current evidence is insufficient to make the feature a GO.
+
+Evidence acquisition before GO may include a bounded design proof or
+reachability analysis, an independent semantic oracle, and an adversarial
+synthetic conflicting fixture or prototype. These activities must remain
+bounded evidence work; they do not authorize a production implementation or a
+public experiment.
+
+The machine authority remains H005's closed
+[`construction-profile-v1.json`](../tool/profile/evidence/construction-profile-v1.json),
+validated by
+[`construction-profile-v1.schema.json`](../schema/construction-profile-v1.schema.json).
+Its `direct-multi-entry` decision is `MORE DATA`. M001 adds no second decision
+record or competing schema.
+
+## GO conditions
+
+The first three M001 conditions require verified real-workload evidence. The
+conflict-attribution condition may instead be established with adversarial
+synthetic conflicting fixtures checked by an independent semantic oracle. None
+is currently satisfied.
+
+| GO condition | Status | Current evidence |
+| --- | --- | --- |
+| Actual verified grammars with multiple entries exist. | Not satisfied | H005 records zero real multi-entry workloads. Its decision threshold requires at least two representative real multi-entry grammars. |
+| Canonical fallback cost is material. | Not satisfied | No verified real multi-entry run records canonical fallback exhaustion or at least twofold structural overhead. Host timing is an observation, not a decision gate. |
+| Shared construction has a clear benefit over isolation. | Not satisfied | The synthetic matrix shows no structural advantage for shared LALR construction over isolation. This does not establish a benefit on a verified real workload. |
+| Shared-entry conflict attribution can be preserved. | Not satisfied | The synthetic matrix has zero conflicts and exercises no direct construction mechanism, so it supplies no attribution evidence. |
+
+The `matrix-multi-entry` fixture remains diagnostic coverage, not a GO
+threshold. It has two entries and exercises shared and isolated construction,
+but it is a `repository_synthetic` workload. It cannot satisfy any of the first
+three real-workload GO conditions or prove conflict attribution. Its elapsed
+measurements have `release_gate: false`.
+
+## Exact evidence required for reconsideration
+
+Reconsideration requires a fresh H005 capture at a fresh exact revision under
+the existing source-digest, environment, and measurement-policy provenance
+contract, recording:
+
+1. At least two verified real grammars with exact identity, revision, grammar
+   digest, entry count, and entry names, plus completed comparable shared and
+   isolated runs.
+2. Material canonical fallback cost on those grammars: observed canonical
+   fallback exhaustion or at least twofold structural overhead on verified real
+   inputs.
+3. A clear shared-over-isolated benefit from comparable structural evidence;
+   host timing alone is insufficient.
+4. Adversarial synthetic conflicting fixtures and an independent semantic
+   oracle showing that a direct mechanism preserves per-entry attribution.
+5. An identified owner who accepts the semantic specification and ongoing
+   implementation, verification, review, and maintenance budget.
+
+The closed H005 decision must then change to `GO`. Adding a real workload or a
+faster synthetic observation without satisfying the other conditions does not
+authorize follow-on work.
+
+## Independence and follow-on boundary
+
+M001 is independent of the direct IELR decision. Direct IELR remains NO-GO,
+and neither decision supplies evidence for the other. A future multi-entry GO
+may share code with direct IELR only where independently specified invariants
+genuinely coincide; it must not inherit an algorithm or verification plan by
+coupling the two tracks.
+
+Until a recorded GO, no production adequacy specification, production direct
+constructor, public experiment, or default-path change analogous to I002-I006
+is authorized. The bounded proof, reachability analysis, oracle, and adversarial
+synthetic prototype described above are permitted only to acquire the four GO
+conditions. Existing shared multi-entry construction and the default generation
+path remain unchanged.
+
+Run the focused policy test with:
+
+```sh
+bundle exec ruby -Itest test/quality/direct_multi_entry_decision_test.rb
+```

data/docs/editor-setup.md

@@ -22,4 +22,5 @@ query/fragment URI components, and ambiguous encoded separators are rejected. Op
 closing first clears the buffer diagnostics and then restores the disk snapshot.
 
 For a generic editor configuration, use command `ibex`, arguments `lsp --stdio`, language id `ibex`, and file pattern `*.y`.
-Ibex never executes semantic actions or `header`, `inner`, or `footer` code while serving editor requests.
+Ibex never executes parser actions, generated lexer actions, or `header`, `inner`, or `footer` code while serving editor
+requests.

data/docs/error-ux-review-rubric-v1.md

@@ -0,0 +1,117 @@
+# Independent error UX review rubric v1
+
+This rubric defines the independent human review required by release gate R001.
+It applies only to the ten observations in
+[`json-errors-v1.json`](../test/fixtures/error_ux/json-errors-v1.json). The
+observations and the maintainer's repair assessment remain normative historical
+evidence; an independent record is a separate artifact and never silently
+rewrites them.
+
+The machine-readable record contract is
+[`error-ux-review-v1.schema.json`](../schema/error-ux-review-v1.schema.json).
+The current gate state and immutable kit identity are published in
+[`error-ux-review-status-v1.json`](error-ux-review-status-v1.json).
+
+## Reviewer qualification
+
+The reviewer must provide their canonical GitHub login, display name,
+affiliation, and relevant conflicts of interest. They must compare that login,
+case-insensitively, with the complete maintainer roster embedded in the kit;
+the v1 roster includes `ydah`. A rostered maintainer cannot satisfy the gate.
+An `@login`, profile URL, display-name alias, or maintainer-selected substitute
+is not an identity. The review must be the reviewer's own assessment. A
+maintainer may answer reproduction questions but must not choose labels or
+rewrite rationales.
+
+The reviewer evaluates only what the fixed evidence exposes. The Racc column is
+the public `on_error` callback without an application-specific message layer.
+The repair column is Ibex's selected opt-in bounded repair, not a claim about
+Racc recovery. Ten cases cannot establish a general error-experience ordering.
+
+## Fixed labels
+
+Choose exactly one diagnostic label for every case:
+
+- `useful`: the diagnostic identifies the relevant location and gives enough
+  concrete information to guide the next correction.
+- `not_useful`: the diagnostic is materially misleading, points at the wrong
+  place, or does not provide actionable information for this input.
+- `unclear`: the reviewer cannot decide from the fixed observation or the
+  diagnostic has important helpful and unhelpful aspects.
+
+Choose exactly one repair label for every case:
+
+- `useful`: applying the displayed plan is a reasonable correction for this
+  malformed input and does not introduce an unexpected semantic direction.
+- `not_useful`: the plan completes parsing but is not a reasonable likely
+  correction for this input.
+- `unsafe`: applying the plan could conceal or introduce a materially different
+  meaning, or the fixed evidence is insufficient to rule that out.
+- `unclear`: the reviewer cannot choose another label from the fixed evidence.
+
+`unsafe` is deliberately repair-only. Do not translate these labels to a
+numeric score. Each diagnostic and repair label requires its own non-empty
+rationale.
+
+## Review procedure
+
+1. Check out the exact repository revision to be reviewed with no local source
+   changes. Run `bundle exec ruby tool/error_ux_snapshot.rb`; it must report a
+   byte-for-byte match.
+2. Run `bundle exec ruby tool/error_ux_review.rb template review.json`. The
+   generated draft records the exact repository, snapshot, grammar, Ruby, Racc,
+   command, and host identities observed by the tool.
+3. Inspect cases `EUX-01` through `EUX-10` in that order. Assign both labels and
+   replace every rationale placeholder. Do not add, remove, reorder, or omit a
+   case or a failure row.
+4. Compare the independent repair judgment with the maintainer's `useful` and
+   `assessment` fields in the normative snapshot. Record every disagreement,
+   including disagreement with a diagnostic observation. A disagreement is
+   retained in the review record; it is not resolved by editing the snapshot.
+5. Set a stable record ID, canonical reviewer GitHub login, display name,
+   affiliation, ISO 8601 review date, and conflict disclosure. Confirm the
+   exact reviewed maintainer roster. Set all four structured consent fields—
+   storage of identity, labels, and rationales, plus republication of the
+   review—to `true`. Set `record_state` to `published` only after the assessment
+   is final.
+6. Publish that final payload JSON unchanged in a reviewer-controlled GitHub
+   repository. The payload deliberately contains no URL or publication
+   metadata, so its bytes can be committed without a self-referential commit
+   hash. Send the canonical
+   `https://github.com/<owner>/<repo>/blob/<40-hex-sha>/<nonempty-path>` URL to
+   the maintainers. Branches, tags, commit-only URLs, issue or pull-request
+   comments, releases, query strings, fragments, encoded traversal, and
+   abbreviated revisions are not accepted.
+7. Maintainers fetch the immutable blob and copy its bytes without any
+   normalization into `docs/error-ux-reviews/v1/records/`. The separate status
+   entry records its local path and SHA-256, canonical blob URL, derived raw URL
+   and source identity, publisher login, and an import-vetting attestation. The
+   release gate fetches those bytes again without redirects and uses GitHub's
+   primary commit API to require that the source repository owner, publication
+   author, status publisher, and reviewer's canonical login match
+   case-insensitively. Network, authentication, redirect, byte, digest, or
+   account-metadata uncertainty fails closed. Maintainers may reject a malformed
+   record but must not rewrite labels, rationales, or disagreement statements.
+
+The generated file is intentionally a `draft`. A draft, a self-review, an
+unpublished or locally reconstructed payload, a mutable or noncanonical link,
+missing structured consent, placeholder text, or an incomplete assessment
+cannot satisfy R001.
+
+The import-vetting attestation records who manually checked the source bytes and
+GitHub account metadata. The owner/author/login agreement establishes only
+control of the named GitHub namespace plus the account metadata returned by
+GitHub. It is not a cryptographic identity proof, a signature proof, proof of
+human independence or coercion resistance, or proof that an affiliation or
+conflict disclosure is true. Immutable source bytes, namespace/account
+agreement, maintainer-roster exclusion, and the manual check are recorded; the
+remaining human claims stay explicit limitations.
+
+## Interpretation
+
+R001 passes when at least one independently authored, published record validates
+against the closed schema, reproduces the immutable ten-case evidence, and is
+listed without alteration in the public status registry. Additional independent
+records are retained even when they disagree with each other or with the
+maintainer assessment. Passing R001 completes this narrow external review gate;
+it does not prove general diagnostic or repair superiority.

data/docs/error-ux-reviews/v1/records/README.md

@@ -0,0 +1,22 @@
+# Independent error UX review records v1
+
+Published third-party payload JSON records belong in this directory and are
+registered by path, SHA-256, immutable blob/raw identity, source-owner and
+publisher logins, and manual import-vetting fields in
+[`error-ux-review-status-v1.json`](../../../error-ux-review-status-v1.json).
+The directory intentionally contains no JSON while R001 is on HOLD.
+
+Import the exact bytes fetched from the reviewer's full-SHA GitHub blob. Do not
+normalize line endings, formatting, wording, labels, rationales, or disagreement
+notes. Publication metadata is stored only in the separate status registry so
+the payload has no self-referential URL. The quality tasks reject unregistered
+files, drafts, rostered-maintainer reviews, mutable or noncanonical publication
+links, incomplete structured consent, placeholders, identity drift, and
+incomplete case sets.
+
+The source owner, commit API author, publisher, and reviewer logins must agree
+case-insensitively. That check records control of the named GitHub namespace and
+GitHub account metadata; it is not a cryptographic identity proof or signature.
+
+See the [v1 rubric](../../../error-ux-review-rubric-v1.md) for the independent
+review and publication workflow.

data/docs/error-ux-round2-review-status-v1.json

@@ -0,0 +1,27 @@
+{
+  "schema_version": 1,
+  "gate_id": "H003-external-subjective-review",
+  "status": "HOLD",
+  "reason": "awaiting-at-least-two-independent-reviews",
+  "evidence": {
+    "path": "docs/error-ux-round2-v1.json",
+    "sha256": "6b0620a64bed0aec85b8cec58ce7ccc71703d2d28a5a3895373d333b60b300b6"
+  },
+  "allowed_labels": [
+    "useful",
+    "misleading",
+    "unsafe",
+    "unclear"
+  ],
+  "required_case_ids": [
+    "H003-DELIMITER-01",
+    "H003-STATEMENT-01",
+    "H003-STATEFUL-01",
+    "H003-EOF-01",
+    "H003-MULTI-01",
+    "H003-UNKNOWN-01",
+    "H003-LEXER-01"
+  ],
+  "records": [],
+  "disagreements": []
+}

data/docs/error-ux-round2-reviews/v1/records/README.md

@@ -0,0 +1,30 @@
+# H003 independent review records
+
+Review the byte-bound machine evidence in
+[`error-ux-round2-v1.json`](../../../error-ux-round2-v1.json). The repository
+capture is complete, but it is not an external judgment. Do not copy a
+repository-authored risk statement into a review without independently
+assessing the diagnostic, caret, proposed edit, fresh-reparse result, and
+semantic-value risk.
+
+An accepted record must match the `review_record` definition in
+[`error-ux-round2-review-v1.schema.json`](../../../../schema/error-ux-round2-review-v1.schema.json)
+and is published in the `records` array of the
+[`H003 status registry`](../../../error-ux-round2-review-status-v1.json).
+It must identify an external reviewer, attest independence and publication
+consent, bind the exact evidence SHA-256, and include exactly one assessment
+for each of the seven required case IDs. Each assessment needs one of
+`useful`, `misleading`, `unsafe`, or `unclear`, a rationale, and a separate
+semantic-value risk assessment.
+
+The registry stays `HOLD` until at least two normalized-distinct external
+reviewers have complete records. Reviewer names are compared after Unicode
+NFKC normalization, full case folding, trimming, and whitespace collapse. If
+their labels differ for any case, retain
+every reviewer pair and its two labels in `disagreements`; do not collapse
+them into a majority label. The quality gate verifies that disagreement
+inventory against the records.
+
+This directory intentionally contains no example or placeholder record.
+Adding reviewer-looking data without a real external review would fabricate
+evidence.