diff --git a/README.md b/README.md index 242555f..4344657 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,14 @@ ArcReady helps developers catch common Arc integration mistakes before release. > ArcReady is an independent open-source project. It is not an official Circle or Arc product. +> Release boundary: the install and Action examples below deliberately run the +> published `arcready@0.3.0` release. The main branch contains later, unreleased +> rule and runtime changes. In particular, v0.3.0 still runs +> `wallet/NO_ETH_GAS_LABEL` as a default critical rule, while current main +> exposes it only as default-excluded, deprecated `info` advice. Use the +> versioned release notes for v0.3.0 behavior and the current rule catalog for +> main-branch behavior. + ## What It Is ArcReady scans source files for common Arc-specific integration assumptions across three presets: @@ -114,6 +122,9 @@ jobs: The action runs the published npm CLI and defaults to `arcready@0.3.0`. You can pin or override the CLI package version: +The `v0.3.0` Action tag therefore runs v0.3.0 package behavior, not unreleased +main-branch behavior. + ```yaml with: arcready-version: "0.3.0" diff --git a/docs/exec-plans/active/R01.md b/docs/exec-plans/active/R01.md new file mode 100644 index 0000000..702e37f --- /dev/null +++ b/docs/exec-plans/active/R01.md @@ -0,0 +1,499 @@ +# R01 — Coordinated ArcReady v0.4.0 Release + +Status: Approved — E1 implementation not started + +Risk class: R3 distribution and external contract + +Owner: ArcReady maintainers + +Base branch: `main` + +Base SHA: `24321a570f842d66ea9b86e7620caced1a3afdee` + +Last reviewed: 2026-08-20 + +## 1. Product brief + +### Problem + +The public npm package and exact GitHub Action release remain on v0.3.0, while +main contains the merged C04–C12 rule hardening, bounded analyzers, experimental +canonical JSON output, dependency, default-selection, and remediation changes. +The current repository README must distinguish those surfaces because a user +following its pinned v0.3.0 commands does not receive current main behavior. + +The mismatch is directly harmful for C12: npm v0.3.0 runs +`wallet/NO_ETH_GAS_LABEL` as a default critical rule, while merged main +default-excludes it as deprecated `info` advice after measured real-repository +false positives. + +### Why now + +The [A02 adoption audit](../../research/A02.md) found zero default findings in +eight pinned repositories with the merged post-C12 package. The +[A03 distribution audit](../../research/A03.md) proved that npm `latest` and the +`v0.3.0` Action cannot reproduce that result because they still deliver the +older release. + +### Product value + +Users can install and pin one reviewed release whose npm CLI, Action default, +versioned documentation, rule inventory, and declared behavior agree. The +release makes already-merged precision work available without expanding the +analyzer surface. + +## 2. Decision and risk + +Decision: Build a coordinated `0.4.0` release in staged publication checkpoints. + +This is R3 because package version, installed dependencies, CLI capabilities, +default rule selection, public rule export inventory, Action default, Git tag, +and release claims are external contracts. + +`0.4.0` is selected because the change is too large for a patch release but does +not establish 1.0 maturity: + +- the package adds the public `arcUsdcAmountConversionRule` export; +- the CLI adds the opt-in `--json-v2` surface; +- default rule execution changes while known compatibility exports remain; +- two pinned runtime dependencies are added; +- multiple existing detectors are materially hardened within their approved + contracts; +- ArcReady remains pre-1.0, and no package file or existing library export was + found deleted relative to v0.3.0. + +The experimental canonical document keeps `contractVersion: "2.0"`; package +SemVer and the internal contract version remain independent. + +## 3. Premise and uncertainty + +Verified on 2026-08-20: + +| Boundary | Evidence | +| --------------------- | ------------------------------------------------------------------- | +| npm latest | `arcready@0.3.0`, published 2026-06-13T17:07:22.227Z | +| npm package source | `gitHead` `108759757d047236cab19272c3246bacc3261f1a` | +| Git release tag | `v0.3.0` resolves to `e4a1244e5363bafee2dcf7446467e7f6fabe921e` | +| Current main | `24321a570f842d66ea9b86e7620caced1a3afdee` | +| Change size | 181 files, 60,385 insertions, 1,150 deletions from tag to main | +| File deletion | no deleted path in the tag-to-main diff | +| Published package | 7 entries, 18,109-byte tarball, 79,982 bytes unpacked | +| Current built package | 10 entries, 91,643-byte tarball, 435,733 bytes unpacked | +| Runtime dependencies | `@solidity-parser/parser@0.20.2`, `typescript@5.9.3` | +| Dependency licenses | parser MIT with no declared dependency; TypeScript Apache-2.0 | +| Dependency Node floor | TypeScript >=14.17; ArcReady >=22 | +| Rule inventory | 19 known, 15 default, 7 known wallet, 6 default wallet, 4 canonical | + +The size comparison is evidence, not a budget. The release review must explain +the added private PREVRANDAO entry and external parser/compiler dependencies and +must verify package licenses, integrity, installation, and lazy loading. + +Remaining before implementation: + +- confirmation that the A02/A03 documentation prerequisite is merged cleanly; +- npm authentication and package-owner authorization; +- exact GitHub release permissions and tag protection state; +- a complete public declaration/API comparison of packed v0.3.0 and the v0.4.0 + candidate; +- whether any main change after the base SHA should be included or deferred. + +Any new runtime-affecting main change resets the release base and requires a new +cumulative inventory. + +## 4. Supported and unsupported surface + +### Supported + +R01 releases the behavior already merged at the selected base plus release-only +metadata and documentation: + +- package version `0.4.0` and matching packed metadata; +- current legacy CLI/report behavior; +- opt-in `scan --json-v2` with canonical contract version `2.0`; +- current 19-known/15-default rule selection and explicit advice opt-in; +- the current public `arcUsdcAmountConversionRule` addition; +- the pinned TypeScript and Solidity parser runtime dependencies; +- package README, root README, GitHub Action guide, release notes, publish + checklist, and version examples; +- exact `v0.4.0` Action release after npm 0.4.0 exists; +- external tagged Action smoke after the tag exists. + +### Unsupported + +- any analyzer, ownership, syntax, language, path, rule, severity, score, + reporter, schema, or canonical-runtime expansion beyond merged main; +- claiming A02 certifies the scanned repositories; +- changing `contractVersion` from `2.0`; +- floating or unpinned runtime dependencies; +- publishing from a dirty tree, unmerged branch, or unreviewed SHA; +- treating a local pack or dry-run as proof of registry behavior; +- rewriting historical v0.3.0 launch posts or release notes as v0.4.0 claims. + +### Non-goals + +- C13 or any new analyzer milestone; +- a 1.0 stability claim; +- a moving `v0` or `latest` Git tag; +- npm provenance, signing, or release automation not already supported by the + repository; +- deprecating or unpublishing v0.3.0; +- publishing, tagging, creating a GitHub Release, or merging without the + maintainer's explicit approval at that checkpoint. + +## 5. Architecture spike and decision + +### Spike + +The release spike compared the npm registry, npm tarball, Git tag, main package +source, public entrypoint, CLI, presets, Action wrapper, external Action smoke, +package dry-run, dependency manifest, roadmap, and completed milestone history. + +Findings: + +- a docs-only defer preserves a known installed-behavior mismatch; +- a `0.3.1` patch understates additive CLI/API and default-selection changes; +- `1.0.0` overstates current stability and analyzer coverage; +- `0.4.0` accurately marks a new pre-1.0 capability and behavior line; +- the Action cannot default to 0.4.0 before npm 0.4.0 exists; +- the external workflow cannot resolve `@v0.4.0` before the Git tag exists; +- therefore package publication, Action/tag publication, and tagged external + validation require ordered checkpoints. + +### Options considered + +1. **Docs-only defer.** Rejected because users remain on known noisy v0.3.0 + behavior and cannot consume the merged fixes through the supported install + path. +2. **Patch release 0.3.1.** Rejected because the cumulative external change is + not patch-sized. +3. **Single atomic 0.4.0 commit.** Rejected because pre-publication CI would + reference an npm version and Git tag that do not yet exist. +4. **Staged 0.4.0 publication.** Selected because every external reference is + introduced only after its prerequisite artifact exists. + +### Chosen approach + +#### E1 — npm package candidate and publication + +1. Start from the exact reviewed release base after the A02/A03 prerequisite is + merged. +2. Change the package version to `0.4.0`; update only package/release metadata, + versioned release notes, package README, and the phase-specific checklist. +3. Keep the root Action default and external tagged smoke on v0.3.0. +4. Prove the package API, contents, dependencies, CLI, legacy behavior, + canonical opt-in, inventory, real-repository probe, and full gate. +5. Obtain final independent review and exact-head CI, then merge with explicit + approval. +6. Only after the merge SHA is selected and npm authorization is confirmed, + publish `arcready@0.4.0` with separate explicit approval. +7. Verify registry version, integrity, `gitHead`, clean installation, CLI output, + default C12 behavior, and canonical opt-in from the registry artifact. + +#### E2 — Action default and exact-SHA external proof + +E2 has two ordered merge checkpoints: + +1. **E2A — Action candidate.** After npm 0.4.0 verification, update + `action.yml`, its structural test, current README, GitHub Action guide, and + current version examples to 0.4.0. Keep the external tagged smoke on v0.3.0. + Run the local Action smoke and an installed npm 0.4.0 consumer probe, obtain + review and exact-head CI, then merge with explicit approval. This E2A merge + SHA is the proposed immutable `v0.4.0` tag target. +2. Prove that E2A changes no publishable package input by requiring zero diff + from the published E1 source across `packages/arcready/package.json`, + `packages/arcready/README.md`, `packages/arcready/src`, + `packages/arcready/core`, `packages/arcready/presets`, + `packages/arcready/rules`, `packages/arcready/reporters`, + `packages/arcready/tsconfig.json`, `packages/arcready/tsup.config.ts`, and + the transitive root build inputs `tsconfig.base.json`, `package.json`, + `pnpm-workspace.yaml`, and `pnpm-lock.yaml`. The Action-only structural + assertion in `packages/arcready/test/github-action.test.ts` is deliberately + outside this publishable-input comparison. +3. Independently rebuild and pack E2A, extract it beside the verified registry + E1 tarball, and compare the sorted entry paths plus SHA-256 of every unpacked + file. No package-entry content difference is permitted. If gzip/container + metadata prevents whole-tarball byte equality, only the container hash may + differ; the complete extracted entry set and hashes must still be exact. +4. **E2B — pre-tag exact-SHA consumer proof.** In a follow-up candidate, change + the external good/bad workflow and its structural assertion to reference the + immutable E2A merge SHA, not a branch or nonexistent tag. Merge E2B only + after its own review and exact-head CI, then require the push-triggered + external workflow to pass against that exact E2A SHA. +5. Only after E2B's external good/bad jobs, artifacts, and expected failure + behavior pass may the maintainer explicitly approve creation of immutable + tag `v0.4.0` pointing to the already-tested E2A SHA. Do not create the GitHub + Release yet. + +The npm `gitHead` may identify the E1 package commit while the Git tag identifies +the E2A Action commit. The completion record must preserve the E1 package SHA, +E2A Action/tag SHA, and E2B validation-harness SHA and prove both transitive +build-input equality and extracted package-entry equality rather than falsely +claiming they are one commit. + +#### E3 — tagged validation, GitHub Release, and closeout + +E3 has two ordered checkpoints: + +1. **E3A — tag-resolution harness.** Update the external Action smoke and its + structural test from the E2A commit SHA to exact tag `v0.4.0` only after the + tag exists. Push the reviewed candidate, optionally dispatch the existing + workflow against that candidate ref, and verify every recorded run's + `headSha` matches the intended candidate. Merge E3A with explicit approval, + then require the push-triggered tagged good/bad jobs, artifacts, and expected + failure behavior to pass on the exact E3A merge SHA. +2. Only after the post-merge tagged workflow passes may the maintainer create + the matching GitHub Release with separate explicit approval. +3. **E3B — completion record.** Record npm integrity, package SHA, Action/tag + SHA, E2B proof SHA, E3A tagged-smoke SHA/run, GitHub Release, and residual + boundaries in the release notes, roadmap, and completed plan. Validate and + merge this documentation closeout with explicit approval. + +If the post-tag workflow fails for a transient external reason, preserve the +tag, record the evidence, and rerun without changing code. If it exposes a +deterministic Action, package, or tag defect, do not create the GitHub Release, +do not move or delete `v0.4.0`, and open a separately reviewed corrective patch +release with a new package version and immutable tag. + +### Stop conditions + +Stop and reset or split the milestone if: + +- A02/A03 is not accepted or the release base is not an ancestor of main; +- another runtime-affecting commit lands after the selected base; +- the packed public API has an undocumented removal or incompatible change; +- package contents include source, maps, tests, artifacts, credentials, or an + unexplained entry; +- dependency licenses, integrity, Node compatibility, lazy loading, or install + behavior fail verification; +- v0.3 legacy CLI behavior changes outside an approved release-note item; +- the default or canonical inventories differ from the approved main contract; +- npm 0.4.0 already exists, npm ownership is unavailable, or publish identity + cannot be verified; +- Action 0.4.0 cannot resolve the exact npm package; +- E2A changes a declared transitive build input relative to E1; +- any extracted E2A package entry path or SHA-256 differs from the verified E1 + registry artifact; +- the exact-E2A-SHA external good/bad proof fails before tag creation; +- a deterministic post-tag failure would require moving or deleting v0.4.0 + instead of a corrective release; +- any required gate, independent review, or exact-head CI fails; +- a tag or release would point at an unmerged or different candidate. + +## 6. Vertical-slice contract + +The first release slice is an installed tarball, not a new analyzer path: + +```text +merged main behavior +→ package version 0.4.0 +→ build and npm pack +→ install in a clean temporary consumer +→ run legacy scan and explicit json-v2 scan +→ verify output, inventory, package metadata, and exit behavior +``` + +Accepted slice: + +- clean install under supported Node; +- `arcready --help` and `arcready init` work; +- a default ArcLens-style case produces no gas-label finding; +- explicit `info` configuration can select the deprecated advice; +- `scan --json-v2` emits one valid canonical document and exits zero; +- conflicting json-v2 options and invalid configuration exit two; +- legacy terminal/JSON/Markdown/HTML scans preserve approved behavior; +- packed metadata says exactly `0.4.0`. + +Safe boundary: + +- no registry publish, Action version change, tag, or GitHub Release occurs in + the slice; +- no result is described as compatibility certification. + +## 7. Representative regression classes + +| ID | Class | Representative check | Expected result | Risk covered | +| --- | ----------------- | ---------------------------------------------- | -------------------------------------------------------- | ---------------------- | +| P01 | Package | Install packed 0.4.0 in an empty consumer | CLI and library import succeed | package shape | +| P02 | Legacy CLI | Run all four legacy reporters | approved output and exits | compatibility | +| P03 | Canonical CLI | Run explicit `--json-v2` | valid contract v2 JSON | additive CLI | +| P04 | Advice policy | Default and explicit gas-label scans | zero default; explicit info record | C12 delivery | +| P05 | Action | Local wrapper resolves npm 0.4.0 after publish | good passes; bad fails | Action/package link | +| P06 | Pre-tag Action | External workflow uses exact E2A SHA | good/bad jobs and artifacts pass | exact Action candidate | +| P07 | Tagged Action | External workflow uses exact v0.4.0 | same result as E2A SHA | tag resolution | +| S01 | Legacy release | Historical v0.3.0 docs remain unchanged | no rewritten history | release truth | +| N01 | Option conflict | `--json-v2` plus legacy output option | exit two, stderr only | CLI boundary | +| N02 | Default advice | no explicit gas-label configuration | rule not selected | false-positive control | +| A01 | SHA split | npm, Action, and proof commits differ | all SHAs recorded; build inputs and packed entries equal | provenance | +| M01 | Package shape | unexpected packed path or map | release stops | leakage | +| C01 | Registry conflict | npm 0.4.0 already exists or integrity differs | release stops | immutability | + +Executable tests and scripts remain the single source for counts and complete +matrices. + +## 8. Validation and review + +### Targeted development commands + +```text +corepack pnpm exec prettier --check +git diff --check +corepack pnpm --filter arcready test +corepack pnpm build +corepack pnpm smoke:package +npm pack --dry-run --json +``` + +Add release-specific probes for: + +- v0.3.0 versus v0.4.0 packed declaration/API comparison; +- exact package entry list, sizes, dependency metadata, licenses, and integrity; +- E1 registry versus E2A rebuild extracted entry paths and SHA-256 values; +- clean tarball installation under the supported Node version; +- legacy and canonical CLI output and exit behavior; +- current rule/default/canonical inventories; +- A02's pinned adoption corpus on the exact package candidate; +- local Action wrapper using the published npm 0.4.0 package; +- external Action good/bad behavior against the exact E2A merge SHA before tag + creation; +- exact tagged external Action good/bad behavior after tag publication. + +### Architecture review + +Approved on the exact staged-only `architecture-corrected-v3` bundle with +`0 blocker / 0 major / 0 minor`. The reviewed patch SHA-256 is +`1011e5fbc82f941b6e075940ceee5705ec1ddb97d49458c7b8cd50e9a2b5db9a`. + +Two earlier review rounds required corrections to package/build provenance, +pre-tag Action proof, immutable failure handling, candidate wording, and E3 +ordering. The approved v3 contract closes those findings without changing +analyzer semantics. + +### Final independent review + +Pending for the exact E1 package candidate and exact E2A Action/tag candidate. +Corrections that change only E3 closeout prose do not require a new full +analyzer review; any package or Action execution change does. + +### Full repository gate + +```text +corepack pnpm verify:full +``` + +Run on stable E1 and again on stable E2A because E2A changes executable Action +selection. E2B runs targeted workflow/structural validation and exact-head CI; +rerun the full gate if it changes anything beyond the external reference, +structural assertion, and release evidence. Do not substitute historical +per-milestone gates for the cumulative release gate. + +### Additional release-candidate checks + +- `npm whoami` and package-owner verification immediately before publish; +- `npm view arcready@0.4.0` absence before publish and exact metadata after; +- `npm publish --dry-run --json` from the package directory; +- registry tarball install and integrity verification after publish; +- exact-head required GitHub workflows for E1, E2A, and E2B; +- pre-tag external Action workflow against E2A's immutable SHA; +- post-tag external Action workflow for E3 before GitHub Release creation; +- clean working tree at every selected SHA. + +## 9. Boundary impact and progress + +Intended impact: + +- package SemVer: `0.3.0` → `0.4.0`; +- npm `latest`: `0.3.0` → `0.4.0` only after explicit publish; +- exact Action tag: add immutable `v0.4.0` at the externally tested E2A SHA only + after E2B proof and explicit approval; +- Action default CLI: `0.3.0` → `0.4.0` only after npm publication; +- library export: additive `arcUsdcAmountConversionRule` relative to v0.3.0; +- CLI: additive experimental `--json-v2` relative to v0.3.0; +- dependencies: add the two already-pinned runtime dependencies; +- default execution: publish the already-approved 19-known/15-default policy; +- canonical contract: remain exactly version `2.0` and four rules; +- no new analyzer behavior in R01. + +Progress: + +- [x] baseline verified +- [x] product brief drafted +- [x] registry/tag premise verified +- [x] release spike completed +- [ ] A02/A03 prerequisite merged +- [x] architecture reviewed +- [ ] E1 package vertical slice working at version 0.4.0 +- [ ] v0.3/v0.4 API and package comparison complete +- [ ] targeted validation passed +- [ ] E1 final independent review passed +- [ ] E1 full validation passed +- [ ] E1 exact-head CI passed and merged +- [ ] npm 0.4.0 explicitly approved, published, and verified +- [ ] E2A Action candidate reviewed, validated, and merged +- [ ] E2A transitive build-input equality with E1 passed +- [ ] E2A rebuilt package entry hashes equal E1 registry artifact +- [ ] E2B exact-SHA external smoke passed +- [ ] v0.4.0 tag explicitly approved and created at E2A SHA +- [ ] E3A tagged external Action smoke passed on its exact merge SHA +- [ ] GitHub Release explicitly approved and created after tagged smoke +- [ ] E3B documentation and closeout aligned + +## 10. Exit and completion record + +### Residual limitations + +- Release publication does not broaden analysis coverage or certify user + repositories. +- JSX/TSX, HTML, imported/cross-file values, rendered UI, generated code, and + runtime behavior remain bounded exactly as current docs state. +- npm publication is effectively immutable; rollback should use a corrected new + version or npm deprecation, not assume unpublish is available. +- The npm package, exact Action tag, and pre-tag validation harness have + different commit SHAs by design; transitive build-input equality, extracted + package-entry equality, and all provenance records are required. + +### Exit criteria + +R01 is complete only when: + +1. A02/A03 is merged and the exact release base is frozen; +2. `0.4.0` package metadata, public API, dependencies, contents, and licenses are + verified; +3. legacy and canonical CLI probes pass from a clean installed tarball; +4. current inventory/default/canonical boundaries match approved main; +5. full validation and independent review pass on the exact E1 candidate; +6. npm publish is explicitly approved and registry integrity is verified; +7. Action default/docs are updated only after npm availability; +8. E2A exact-head CI and review pass, no declared transitive build input differs + from E1, and every rebuilt package entry path/hash equals the registry E1 + artifact; +9. E2B external good/bad smoke passes against the exact E2A merge SHA before + tag creation; +10. tag creation is explicitly approved and points to the tested E2A SHA; +11. E3A is merged and tagged external good/bad smoke passes on its exact merge + SHA before GitHub Release creation; +12. GitHub Release creation is explicitly approved and points to the immutable + v0.4.0 tag; +13. E3B release notes record npm, Action/tag, E2B proof, and E3A tagged-smoke + provenance SHAs and runs; +14. code, package, Action, docs, roadmap, and public claims agree; +15. no known blocker remains and every working tree is clean. + +### Completion record + +Pending. + +### Decision log + +- 2026-08-20: Selected a staged `0.4.0` release rather than docs-only defer, + patch release, 1.0 claim, or one-commit publication. +- 2026-08-20: Required E1 npm, E2A Action, E2B exact-SHA pre-tag proof, and E3 + tagged-smoke checkpoints because external artifacts cannot be validated + before their prerequisites exist. +- 2026-08-20: Deferred GitHub Release creation until tagged smoke passes and + selected a new corrective release, never tag movement, for deterministic + post-tag failure. +- 2026-08-20: Closed E1/E2A provenance over both the complete transitive build + input set and extracted package-entry hashes; package subtree equality alone + is insufficient because Action structural tests live under that subtree. +- 2026-08-20: Independent architecture review approved corrected v3 with + `0 blocker / 0 major / 0 minor`; E1 remains unstarted and separately gated. diff --git a/docs/final-npm-publish-checklist.md b/docs/final-npm-publish-checklist.md index f591579..a814f4f 100644 --- a/docs/final-npm-publish-checklist.md +++ b/docs/final-npm-publish-checklist.md @@ -1,8 +1,11 @@ -# Final npm Publish Checklist +# Historical v0.3.0 npm Publish Checklist -ArcReady is prepared for the next npm publish as `arcready@0.3.0`. +Status: Completed historical record -Do not run the real publish command until the maintainer explicitly approves. +ArcReady v0.3.0 was published on 2026-06-13. This document records that release +candidate and must not be reused to publish the same immutable version. Prepare +a new versioned checklist after a separately approved release selects the next +candidate. ## Package @@ -16,16 +19,16 @@ Do not run the real publish command until the maintainer explicitly approves. ## Gate Results -| Check | Status | -| ------------------ | -------------------------------------------------------------------------------- | -| npm package status | `arcready@0.2.0` is already published; `0.3.0` is the next npm release candidate | -| npm login | `npm whoami` returned `ENEEDAUTH`; npm login is required before real publish | -| Build | Passed | -| Test | Passed | -| Lint | Passed | -| Fixture validation | Passed | -| Package smoke test | Passed | -| Publish dry-run | Passed | +| Check | Status | +| ------------------ | ---------------------------------------------------------------------------- | +| npm package status | `arcready@0.3.0` was published on 2026-06-13 | +| npm login | `npm whoami` returned `ENEEDAUTH`; npm login is required before real publish | +| Build | Passed | +| Test | Passed | +| Lint | Passed | +| Fixture validation | Passed | +| Package smoke test | Passed | +| Publish dry-run | Passed | ## Package Contents @@ -41,7 +44,7 @@ dist/index.js package.json ``` -## Required Pre-Publish Commands +## Commands Used for the Historical Candidate Run from the repository root: @@ -60,16 +63,18 @@ cd packages/arcready npm publish --dry-run ``` -## Do Not Run Until Release Approval +## Historical Publish Command -The real publish command has not been run yet. Use it only after explicit maintainer approval: +The following command belonged to the completed v0.3.0 release and must not be +run again for that version: ```powershell cd packages/arcready npm publish --access public ``` -Before running the real publish, verify npm login: +For any future release, first select a new version and create a new checklist. +Before an explicitly approved publish, verify npm login: ```powershell npm whoami diff --git a/docs/npm-publishing.md b/docs/npm-publishing.md index ccdd0a2..c1e62ef 100644 --- a/docs/npm-publishing.md +++ b/docs/npm-publishing.md @@ -1,16 +1,19 @@ # npm Publishing -ArcReady is being prepared for npm publishing as an installable CLI package. +ArcReady is published on npm as an installable CLI package. The current public +version is `arcready@0.3.0`. The architecture-approved R01 plan selects `0.4.0`, +but E1 implementation has not started and no publishable candidate exists yet. ## Current Package -| Field | Value | -| ------------ | ---------- | -| Package name | `arcready` | -| Version | `0.3.0` | -| License | MIT | -| Node.js | `>=22` | -| CLI bin | `arcready` | +| Field | Value | +| --------------------- | ----------------------------- | +| Package name | `arcready` | +| Published version | `0.3.0` | +| Selected next version | `0.4.0` (R01; E1 not started) | +| License | MIT | +| Node.js | `>=22` | +| CLI bin | `arcready` | The npm package should include only: @@ -45,7 +48,13 @@ cd packages/arcready npm publish --dry-run ``` -Inspect the output before release. The dry run should show `arcready@0.3.0` and only the expected package files. +Inspect the output before release. The dry run must show the separately approved, +unpublished candidate version and only the expected package files. Do not try to +publish `arcready@0.3.0` again. + +During E1, after the exact operational candidate and selected release SHA exist, +replace the pre-implementation language in this guide before any publish command +is authorized. ## Before Real Publish diff --git a/docs/research/A02.md b/docs/research/A02.md new file mode 100644 index 0000000..5563c55 --- /dev/null +++ b/docs/research/A02.md @@ -0,0 +1,133 @@ +# A02 — Post-C12 Adoption Audit + +Status: Complete — No-Build decision + +Risk class: R0 evidence and roadmap record + +ArcReady baseline: `24321a570f842d66ea9b86e7620caced1a3afdee` + +Reviewed: 2026-08-20 + +## 1. Question + +After the C12 gas-label migration, does the pinned adoption corpus provide +enough concrete false-positive, false-negative, unsupported-pattern, or user +failure evidence to authorize another analyzer milestone? + +The product decision test requires all three conditions before material rule +work: + +1. Arc developers realistically encounter the problem; +2. ArcReady can detect it within a narrow, truthful, maintainable boundary; +3. the finding provides a clear corrective action. + +## 2. Method + +The audit reran the built ArcReady package from the merged C12 baseline against +eight previously pinned, clean repositories. Each repository was scanned with +its normal discovered presets and default configuration. A targeted source +review then checked representative chain metadata, native and ERC-20 amount +formatting, transaction submission, finality, and bridge terminology without +treating unmatched source as safe. + +The audit target was the package built from merged main, not the currently +published `arcready@0.3.0` package. A02 therefore measures the post-C12 candidate +behavior only; it does not claim that npm or the `v0.3.0` Action already ships +that behavior. + +The first local probe ran inside a filesystem sandbox that could not read the +pnpm TypeScript junction and therefore emitted two synthetic rule-failure +warnings per wallet project. That run is invalid product evidence. Repeating +the same built-package scan with normal dependency access produced the results +below. The installed-package smoke test independently owns the packaged +TypeScript dependency boundary. + +## 3. Pinned corpus + +| Repository | Commit | Discovered files | Detected presets | +| ----------------------------------------------------------------------------------------- | ------------------------------------------ | ---------------: | ----------------------- | +| [`circlefin/arc-commerce`](https://github.com/circlefin/arc-commerce) | `1a3a5e0d738daec127d9c95f790a73ed33bf00a3` | 95 | App Kit, bridge, wallet | +| [`circlefin/arc-defi-lend-borrow`](https://github.com/circlefin/arc-defi-lend-borrow) | `d621644e29ddac521fefb55dd923adba5c797d0d` | 36 | Wallet | +| [`circlefin/arc-ecommerce-payments`](https://github.com/circlefin/arc-ecommerce-payments) | `15ffae6373cb0b06177bc026f1d247a1af4799fb` | 90 | Wallet | +| [`circlefin/arc-stablecoin-fx`](https://github.com/circlefin/arc-stablecoin-fx) | `779eb1a683cc2f78746df5547987e9a06bcbbe90` | 44 | App Kit, wallet | +| [`duck131199/arcflow-pay`](https://github.com/duck131199/arcflow-pay) | `a74806c92543ce9bd84ac4e990340d0dbdc6b68f` | 3 | App Kit, wallet | +| [`arclens-app/arclens`](https://github.com/arclens-app/arclens) | `85ea2dbb1692b7faf04359fc0ed033fa259969ef` | 152 | App Kit, bridge, wallet | +| [`0xsheyn/RivoKit`](https://github.com/0xsheyn/RivoKit) | `e166bdca94638e3c655e5eb9b08eb973b3ab73fe` | 62 | App Kit, bridge, wallet | +| [`linux070/stac-defi`](https://github.com/linux070/stac-defi) | `373670a2da284ff1f538d215a1ecaf870ea9be68` | 63 | App Kit, bridge, wallet | + +All clones were clean at the pinned commit. The executable scan discovered 545 +files in total. + +## 4. Results + +Every repository produced the same default outcome: + +```text +score=100 +status=pass +critical=0 +warning=0 +info=0 +findings=0 +``` + +This is evidence that C12 removed the measured ArcLens default noise without +introducing a new default finding in the pinned corpus. It is not evidence that +the repositories are complete, correct, secure, deployable, or fully analyzed. + +Representative manual checks found internally coherent supported examples: + +- Stac DeFi formats Arc native `getBalance` values with 18 decimals and direct + token `balanceOf` values with six decimals in the inspected balance flow; +- Arc Commerce formats a direct ERC-20 USDC `balanceOf` value with six decimals; +- ArcLens documentation examples use six decimals for the Arc USDC ERC-20 + contract and use Gwei as an internal gas-price unit rather than proof of an + incorrect rendered Arc fee label; +- the inspected Arc Commerce confirmation configuration uses one confirmation; +- no reviewed example established an exact supported Arc type-3/EIP-4844 + submission or another proven default-rule violation. + +## 5. Coverage limits + +The zero-finding result must remain bounded: + +- ArcFlow Pay keeps substantial integration logic in root HTML and generated or + archived assets while only three files fall inside the normal discovered + paths; +- several repositories place integration code in JSX or TSX, while the deeper + amount and transaction analyzers intentionally support only plain JavaScript + and TypeScript files; +- imported ownership, cross-file values, runtime configuration, rendered UI, + generated bundles, and live network behavior remain outside current support; +- the npm `latest` tag and `v0.3.0` Action remain on the older v0.3.0 behavior, + so these post-C12 scan results do not describe the installed public release; +- the audit did not execute repository applications or certify behavior. + +These are coverage observations, not demonstrated compatibility defects. No +single observation supplies both a proven violation and a narrow detector +contract. + +## 6. Decision + +Do not open C13 or broaden an analyzer from A02. + +The corpus supplies neither a new default false positive nor a concrete false +negative inside a supported boundary. It also does not show the same proven +unsupported violation in two real consumers. Building JSX/TSX, HTML, cross-file, +or rendered-UI infrastructure now would be speculative and would fail the +product decision test. + +Continue adoption work and reopen prioritization only from one of these +triggers: + +- a concrete user or repository failure with an actionable Arc-specific fix; +- a proven false positive or false negative inside a declared rule boundary; +- the same unsupported violation pattern in at least two real repositories; +- first-party premise or version evidence that changes a current decision; or +- two real rule consumers needing the same stable analysis semantics. + +## 7. Boundary impact + +A02 changes no code, rule, preset, severity, inventory, canonical runtime, +FindingV2 contract, schema, reporter, dependency, package export, score, status, +or exit behavior. It records a No-Build adoption decision only. diff --git a/docs/research/A03.md b/docs/research/A03.md new file mode 100644 index 0000000..1d8c53d --- /dev/null +++ b/docs/research/A03.md @@ -0,0 +1,88 @@ +# A03 — Post-C12 Distribution Alignment Audit + +Status: Complete — release planning required + +Risk class: R1 public documentation and usage correction; any version, package, +tag, or Action-default change is a separate R3 release milestone + +Reviewed: 2026-08-20 + +## 1. Problem + +The repository README tells users to run `arcready@0.3.0` and +`tanka420/arcready@v0.3.0`, while parts of the same README and current rule +documentation describe behavior merged after the v0.3.0 release. Users can +therefore install a package whose default findings differ materially from the +current main-branch claim. + +This is a distribution-boundary problem, not evidence for another analyzer. + +## 2. Exact evidence + +| Boundary | Verified state | +| ----------------------------------- | ------------------------------------------------------ | +| npm `latest` | `arcready@0.3.0` | +| npm publish time | 2026-06-13T17:07:22.227Z | +| npm v0.3.0 `gitHead` | `108759757d047236cab19272c3246bacc3261f1a` | +| Git tag | `v0.3.0` at `e4a1244e5363bafee2dcf7446467e7f6fabe921e` | +| Current merged baseline | `24321a570f842d66ea9b86e7620caced1a3afdee` | +| Action default on main and v0.3.0 | `arcready-version: "0.3.0"` | +| Package manifest on main and v0.3.0 | version `0.3.0` | + +The behavioral mismatch is concrete: + +- v0.3.0 declares `wallet/NO_ETH_GAS_LABEL` as `critical` and includes all + wallet rules in the default preset; +- current main declares the same public rule as deprecated `info` advice and + excludes it from default wallet selection; +- A02's eight-repository, zero-finding result used the package built from merged + main, not npm v0.3.0; +- the current Action still downloads npm v0.3.0, so it cannot reproduce A02's + post-C12 result by default. + +The generic npm publishing documents also still described v0.3.0 as an upcoming +candidate even though it is already published. + +## 3. Decision + +Correct current documentation immediately, but do not mutate distribution: + +1. disclose the published-vs-main boundary in the root README; +2. preserve versioned v0.3.0 launch posts and release notes as historical + records; +3. mark the final v0.3.0 publish checklist as a completed historical record; +4. make the generic publishing guide require an approved, unpublished candidate + version instead of instructing another v0.3.0 publish; +5. do not change the package version, npm tag, Git tag, release commit, or Action + default in A03. + +## 4. Required release follow-up + +A separately authorized R3 release milestone should: + +- select the exact release commit and next semantic version; +- inventory public API, schema, runtime, rule, severity, default-selection, + dependency, package-shape, CLI, and Action changes since v0.3.0; +- write versioned release notes and migration guidance; +- update the package manifest and Action default only as one coordinated + candidate; +- run `corepack pnpm verify:full`, package smoke, publish dry-run, installed CLI + probes, and exact-head CI; +- obtain independent adversarial review before publish or tag mutation; +- require explicit maintainer approval for npm publish, Git tag, GitHub release, + Action release, and any moving major tag. + +The next version is deliberately not selected here. The change set appears to +require at least a minor release because public runtime and default-selection +behavior changed, but the R3 release review owns that decision. + +Follow-up: the [R01 release plan](../exec-plans/active/R01.md) selects `0.4.0` +and passed independent architecture review with `0 blocker / 0 major / 0 +minor`. E1 implementation has not started, and A03 itself still authorizes no +release mutation. + +## 5. Boundary impact + +A03 changes documentation only. It changes no package version, package content, +rule, severity, preset, default selection, runtime, schema, score, exit behavior, +npm dist-tag, Git tag, GitHub release, or Action execution. diff --git a/docs/roadmap.md b/docs/roadmap.md index a488a1d..accf01f 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -285,6 +285,15 @@ six. Focused tests, the full test suite, fixture validation, built-CLI probes, the pinned ArcLens adoption probe, final independent review, and the full repository gate pass. The PR owns the final exact-head CI and merge record. +### A02 — Complete: post-C12 adoption audit, No Build + +The [A02 adoption record](research/A02.md) reran the merged C12 package against +the eight pinned clean repositories and manually reviewed representative +high-impact pattern families. It found no new default noise or proven supported +violation, while documenting HTML/path, JSX/TSX, cross-file, and runtime coverage +limits. Those limits do not yet provide a narrow detector contract or repeated +real violation, so no C13 analyzer milestone is authorized. + ## Adoption and developer-experience track With C07C integration complete, prioritize product usefulness before expanding @@ -306,6 +315,20 @@ proceed independently of engineering milestones after verifying package contents, CLI installation, Action references, release notes, and CI on the selected release commit. +The [A03 distribution audit](research/A03.md) confirms that npm `latest` and the +`v0.3.0` Action still run v0.3.0 while main documents later behavior, including +the C12 default exclusion. Current documentation must disclose that boundary. +A separately authorized R3 release milestone must select and verify the next +version before changing the package manifest, Action default, tag, or release; +A03 performs none of those distribution mutations. + +The [R01 release plan](exec-plans/active/R01.md) selects a staged v0.4.0 +candidate: npm package first, then the Action default, exact-SHA external proof, +immutable tag, tagged external smoke, and finally the GitHub Release. Its +architecture review passed with `0 blocker / 0 major / 0 minor`; E1 has not +started, and explicit approval remains required at every merge, publish, tag, +and GitHub Release checkpoint. + Core milestones must not silently change an already selected release commit. ## Later product capabilities diff --git a/docs/rule-development-backlog.md b/docs/rule-development-backlog.md index d01c648..9bc1981 100644 --- a/docs/rule-development-backlog.md +++ b/docs/rule-development-backlog.md @@ -291,6 +291,7 @@ C09A Complete: bounded analyzer and compatibility-shell migration C10 Complete: Research / Defer; no versioned App Kit rule authorized C11 Complete: exact Arc chain hexadecimal identity correction C12 Complete: default-excluded deprecated gas-label advice +A02 Complete: post-C12 adoption audit; no analyzer build authorized ``` C09-R1, C09-R2, C09-R3-A, C09-R3-B, C09-D, C09A, and C10 are complete. C10 @@ -302,6 +303,9 @@ reports should set the next priority. The measured `wallet/NO_ETH_GAS_LABEL` false positives triggered the separately reviewed C12 R3 implementation of its existing Advice-only decision, published in PR #73, not another unreviewed regex patch. +The post-C12 A02 audit then found no new default noise or proven supported +violation across the eight pinned repositories, so no C13 analyzer milestone is +authorized. The compatibility inventory is `19 known / 15 default / 7 known wallet / 6 default wallet / 4 canonical`. C09A grammar, artifact, or shell expansion requires real user or repository evidence and a separately reviewed milestone.