Skip to content

docs: record adoption audit and plan v0.4 release #74

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tanka420 merged 1 commit into from
Aug 20, 2026
Merged

docs: record adoption audit and plan v0.4 release #74

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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"
Expand Down
499 changes: 499 additions & 0 deletions docs/exec-plans/active/R01.md
View file
Open in desktop

Large diffs are not rendered by default.

39 changes: 22 additions & 17 deletions docs/final-npm-publish-checklist.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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

Expand All @@ -41,7 +44,7 @@ dist/index.js
package.json
```

## Required Pre-Publish Commands
## Commands Used for the Historical Candidate

Run from the repository root:

Expand All @@ -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
Expand Down
27 changes: 18 additions & 9 deletions docs/npm-publishing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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:

Expand Down Expand Up @@ -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

Expand Down
133 changes: 133 additions & 0 deletions docs/research/A02.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
88 changes: 88 additions & 0 deletions docs/research/A03.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Loading
Loading