Fix stale CellScript 0.21 documentation

Author: a19q3

README.md

@@ -438,7 +438,7 @@ or CellFabric intent engine.
 - [Collections matrix example](docs/examples/collections_matrix.md)
 - [Deployment manifest example](docs/examples/deployment_manifest.md)
 - [Output append example](docs/examples/output_append.md)
-- [0.20 generated builder roadmap](docs/CELLSCRIPT_0_20_ROADMAP.md)
+- [0.20 generated builder roadmap](docs/archive/0.20/CELLSCRIPT_0_20_ROADMAP.md)
 - [Roadmap overview](roadmap/CELLSCRIPT_ROADMAP.md)
 - [0.13 release scope](docs/releases/CELLSCRIPT_0_13_RELEASE_SCOPE.md)
 - [0.14 roadmap](roadmap/CELLSCRIPT_0_14_ROADMAP.md)
@@ -448,8 +448,8 @@ or CellFabric intent engine.
 - [0.16 roadmap](roadmap/CELLSCRIPT_0_16_ROADMAP.md)
 - [0.16 release notes](docs/releases/CELLSCRIPT_0_16_RELEASE_NOTES.md)
 - [0.17 roadmap](docs/archive/0.17/CELLSCRIPT_0_17_ROADMAP.md)
-- [0.18 roadmap](docs/CELLSCRIPT_0_18_ROADMAP.md)
-- [0.19 roadmap](docs/CELLSCRIPT_0_19_ROADMAP.md)
+- [0.18 roadmap](docs/archive/0.18/CELLSCRIPT_0_18_ROADMAP.md)
+- [0.19 roadmap](docs/archive/0.19/CELLSCRIPT_0_19_ROADMAP.md)
 
 ---
 

docs/CELLSCRIPT_CKB_ADAPTER.md

@@ -1,7 +1,10 @@
 # CellScript CKB Adapter
 
-**Status**: formal 0.19 headless Rust adapter crate with full transaction lifecycle
-bridge plus focused local-node acceptance evidence.
+**Status**: production contract for the current CellScript CKB profile. The
+headless Rust adapter crate landed in the 0.19 line; 0.21 extends the builder
+resolution surface with materialised action plans, action-aware scan selector
+evidence, variable-length `args_parts`, manifest-backed CellDep completion, and
+fail-closed live-cell evidence validation.
 
 This document defines which CKB-facing responsibilities belong to CellScript,
 `ckb-std`, `ckb-sdk-rust`, and the adapter.
@@ -304,6 +307,11 @@ Focused local gate:
 ./scripts/cellscript_ckb_ecosystem_reuse_gate.sh full
 ```
 
+These ecosystem-reuse scripts are standalone manual tools, not unified gate
+modes and not release-evidence claims. See
+[`CELLSCRIPT_GATE_POLICY.md`](CELLSCRIPT_GATE_POLICY.md) for the release gate
+boundary.
+
 Focused local-node adapter gate:
 
 ```text
@@ -314,7 +322,8 @@ That script starts a local CKB devnet, checks a compiler action plan, verifies
 the formal adapter crate materialization path, runs `estimate_cycles`, runs
 `test_tx_pool_accept`, submits the deploy transaction, generates blocks until
 committed, and verifies the code cell is live on-chain. It is adapter-boundary
-evidence, not a replacement for stateful business-flow acceptance.
+evidence, not a replacement for stateful business-flow acceptance and not a
+unified `cellscript_gate.sh` release mode.
 
 ## Validation Loop
 

docs/CELLSCRIPT_CKB_STD_COMPAT.md

@@ -1,9 +1,12 @@
 # CellScript ckb-std Compatibility
 
-**Status**: 0.19 scope compatibility contract with implementation landed for
-ckb-std constant parity, SourceView decoding, WitnessArgs layout fixtures,
-occupied-capacity field lowering, the formal headless CKB adapter crate, and
-focused local-node adapter acceptance.
+**Status**: production compatibility contract for the current CellScript CKB
+profile. The 0.19 line landed ckb-std constant parity, SourceView decoding,
+WitnessArgs layout fixtures, occupied-capacity field lowering, the formal
+headless CKB adapter crate, and focused local-node adapter acceptance; 0.21
+extends the builder-facing boundary with action-aware scan selectors,
+`args_parts`, manifest-backed CellDep completion, and helper-backed aggregate
+invariant evidence.
 
 See also [`CELLSCRIPT_CKB_ADAPTER.md`](CELLSCRIPT_CKB_ADAPTER.md) for the
 transaction-realisation boundary with `ckb-sdk-rust`.
@@ -12,10 +15,9 @@ transaction-realisation boundary with `ckb-sdk-rust`.
 CellScript should treat it as the contract-side ABI and runtime oracle, not as a
 transaction builder and not as a compiler-core dependency.
 
-This document belongs to the 0.19 registry/deployment/adapter scope. It defines
-the compatibility contract that the 0.19 adapter boundary and the 0.20
-generated Action Builder must respect; it is not counted as 0.18
-protocol-equivalence evidence.
+This document defines the compatibility contract that the adapter boundary,
+generated Action Builder, and CKB-facing metadata must respect across the
+current 0.21 RC line. It is not counted as 0.18 protocol-equivalence evidence.
 
 In practical terms:
 
@@ -35,6 +37,24 @@ The three components sit on different sides of the same production workflow:
 | `ckb-sdk-rust` (5.x) | Provide off-chain CKB data structures (`ckb-types` 1.0.0), sync and async RPC / indexer clients, `CellCollector` (Default / Offchain / LightClient), `CellDepResolver`, `HeaderDepResolver`, `Signer` and lock-specific `ScriptUnlocker` (SecpSighash, SecpMultisig Legacy/V2, ACP, Cheque, OmniLock), `CapacityBalancer` / `CapacityProvider`, protocol `tx_builder` modules, acceptance, and submission. |
 | CKB node | Execute the script, measure cycles, and accept or reject the concrete transaction. |
 
+## 0.21 Extensions
+
+The 0.21 RC keeps the same ckb-std compatibility boundary but extends what
+builders and adapters must preserve:
+
+- action-aware scan selectors identify which live-cell or transaction-shape
+  evidence a builder must supply;
+- `args_parts` lets adapters construct variable-length `Script.args` from
+  typed byte fragments while rejecting ambiguous drafts that also set non-empty
+  `args`;
+- manifest-backed CellDep completion resolves script dependencies from
+  deployment records rather than action-name convention;
+- helper-backed aggregate invariant evidence distinguishes
+  `gap:metadata-only`, `gap:runtime-helper-required`, and `checked-runtime`.
+
+These extensions do not turn compile-only evidence into CKB node acceptance.
+They make the adapter contract fail closed before signing or submission.
+
 ## Boundary
 
 The compiler core must not depend on `ckb-std`.
@@ -209,10 +229,10 @@ that a CellScript artifact behaves like the corresponding CKB contract-side
 ABI, and that a concrete transaction carrying that artifact is accepted or
 rejected by the node for the expected reason.
 
-The current 0.19 evidence now covers ABI compatibility, headless adapter
-materialization, and focused local-node adapter acceptance. It is still not a
-wallet UI, CellFabric, package registry production gate, external audit, or
-exhaustive adversarial state-space proof.
+The current evidence covers ABI compatibility, headless adapter materialization,
+0.21 builder-resolution metadata, and focused local-node adapter acceptance. It
+is still not a wallet UI, CellFabric, package registry production gate,
+external audit, or exhaustive adversarial state-space proof.
 
 ## Cookbook Topics
 

docs/CELLSCRIPT_EXAMPLE_BUSINESS_FLOWS.md

@@ -29,11 +29,14 @@ locks strict-compile under the CKB profile and are exercised with builder-backed
 local CKB valid-spend and invalid-spend transactions. The production report keeps
 the matrix explicit in `lock_acceptance_scope.onchain_lock_spend_matrix_scope`.
 
-`examples/registry.cell` and every checked-in `examples/language/*.cell` file
-are not part of the seven-example CKB production action matrix. They are
-language/tooling examples for compiler surfaces such as bounded local `Vec<T>`,
-stdlib patterns, CKB source/witness, TYPE_ID, Spawn/IPC, capacity/time, and
-dynamic BLAKE2b.
+`examples/registry.cell`, `examples/atomic_swap.cell`,
+`examples/multi_phase_dao.cell`, and every checked-in `examples/language/*.cell`
+file are not part of the seven-example CKB production action matrix. They are
+language/tooling or explicitly non-production business-flow examples for
+compiler surfaces such as bounded local `Vec<T>`, stdlib patterns, CKB
+source/witness, TYPE_ID, Spawn/IPC, capacity/time, dynamic BLAKE2b,
+flow-edge membership validation, and multi-stage state-transition lifecycle
+checks.
 
 ## Cell Lifecycle Vocabulary
 

docs/CELLSCRIPT_GATE_POLICY.md

@@ -14,8 +14,8 @@ deciding whether a change is ready.
 
 | Mode | When to run | Evidence boundary |
 |---|---|---|
-| `dev` | Local development before pushing | Formatting, Rust check, strict backend quick audit, syntax-combination quick audit, whitespace diff check |
-| `ci` | Pull requests, pushes, and routine merge readiness | Full Rust tests, clippy, strict backend CI audit, syntax-combination CI audit through the strict backend runner, package verification, script syntax checks |
+| `dev` | Local development before pushing | Formatting, Rust check, strict backend quick audit, syntax-combination quick audit, skill-pack freshness, README-linked CellScript doc Status freshness, local markdown link check, whitespace diff check |
+| `ci` | Pull requests, pushes, and routine merge readiness | Full Rust tests, clippy, strict backend CI audit, syntax-combination CI audit through the strict backend runner, package verification, skill-pack and CellScript doc Status freshness, local markdown link check, script syntax checks |
 | `backend` | Changes touching IR, codegen, assembler, ABI, ELF, or RISC-V behavior | Full Rust tests, clippy, and strict backend full audit, including stateful CKB scenarios |
 | `release` | Nightly/stable release candidates and any production CKB claim | `ci` plus tooling/docs boundary checks, VS Code validation, builder-backed CKB production acceptance, and stateful scenario/action coverage |
 | `release-quick` | Wrapper compatibility and local compile-only preflight | `ci` plus compile-only production acceptance; not external live/devnet evidence |

docs/CELLSCRIPT_GRAMMAR_GOVERNANCE_RFC.md

@@ -2,7 +2,11 @@
 
 ## Status
 
-Active 0.19 grammar-governance contract.
+Active grammar-governance contract. The 0.19 matrix below remains the baseline
+for canonical action/lock syntax; the current 0.21 RC extends that surface with
+aggregate-invariant helper coverage, flow-edge membership validation,
+TemplateLayout metadata, compile receipts, nested CLI command groups,
+structured diagnostic transport, and the `cellscript-mcp` skill-pack surface.
 
 This document defines the public syntax boundary that parser, formatter, LSP,
 examples, docs, lowering metadata, and release gates must keep aligned.
@@ -24,7 +28,7 @@ Short form:
 
 ## Canonical Surface
 
-The 0.19 public action form is:
+The canonical public action form is:
 
 ```cellscript
 action NAME(params...) -> outputs {
@@ -43,7 +47,7 @@ action NAME(params...) -> outputs {
 }
 ```
 
-The 0.19 public lock form is:
+The canonical public lock form is:
 
 ```cellscript
 lock NAME(protected cell: T, witness arg: U) -> bool {
@@ -72,7 +76,7 @@ schema gains a field, either preserving a new field without review or leaving it
 outside the visible audit trail. The parser therefore rejects `except` and `*`
 inside `preserve` blocks and asks authors to write an explicit whitelist.
 
-## 0.19 Release Status Matrix
+## Baseline Release Status Matrix
 
 | Track | Status | Implementation / evidence | Release gate |
 |---|---|---|---|
@@ -88,6 +92,20 @@ This matrix is compiler-governance evidence. It is not a replacement for
 builder-backed CKB transaction acceptance, external audit, or exhaustive
 adversarial state-space verification.
 
+## 0.21 Governance Delta
+
+The 0.21 RC adds governance requirements that build on the baseline matrix:
+
+| Surface | Governance rule | Evidence |
+|---|---|---|
+| Aggregate helper coverage | xUDT group amount invariants must report `gap:metadata-only`, `gap:runtime-helper-required`, or `checked-runtime`; strict 0.17 rejects stale helper gaps with PP0170. | `CHANGELOG.md` 0.21.0-rc.1 and `tests/cli.rs` strict 0.17 cases. |
+| Flow-edge membership | An action transition must use an edge declared by the corresponding `flow` block; cyclic flows remain valid. | `src/flow/mod.rs` diagnostics and syntax-combo flow bug classes. |
+| TemplateLayout metadata | Layout records are metadata-only in this RC, mark cyclic flows as `RootRequired`, acyclic flows as `PathOnlyAllowed`, and reject unsupported `consensus_checked = true`. | `CompileMetadata.template_layouts` schema v44. |
+| Compile receipts | `cellc receipt`, `cellc sign-receipt`, `cellc verify-receipt`, and `verify-artifact --receipt` bind metadata/artifact evidence without claiming transaction validity. | `cellscript-compile-receipt-v1`. |
+| CLI command groups | Public discovery uses nested `explain`, `tx`, `deploy`, `registry`, `package`, and `auth capability` groups; hidden flat aliases are compatibility only. | `cellc --list` and CLI help. |
+| Diagnostic transport | `--message-format=json`, `--color=auto|always|never`, and `NO_COLOR` are part of the scripted diagnostics surface. | CLI command definitions and gate usage. |
+| Agent tooling | `cellscript-mcp` and the six `docs/skills/cellscript-*` skills are read-oriented compiler surfaces whose freshness is checked by dev/ci gates. | `scripts/check_cellscript_skill_pack.py`. |
+
 ## `verification`
 
 `verification` is a section header, not an execution body. It can contain local

docs/CELLSCRIPT_LINEAR_OWNERSHIP.md

@@ -25,6 +25,12 @@ These are compile-time checks. Generated verifier code may also clear consumed
 stack slots as a runtime defense, but stack clearing is not the primary
 ownership model.
 
+For state machines, 0.21 also validates flow-edge membership statically. An
+action that claims `transition before.state: A -> after.state: B` must use an
+edge declared by the corresponding `flow` block. This is a linearity rule for
+state continuation: undeclared transitions fail before lowering instead of
+leaving the verifier to infer protocol intent from action names.
+
 ## Required End States
 
 Every acquired cell-backed value must reach an explicit terminal operation:

docs/CELLSCRIPT_MOLECULE_IFRN_DESIGN_SPACE_IMPROVEMENT_REPORT.md

@@ -10,6 +10,23 @@ raised during review. It does not re-audit the external Infern repository; any
 Infern conclusions remain engineering inferences from the described raw-layout
 patterns and the current CellScript capability boundary.
 
+## 0.21 Closure Addendum
+
+The 0.21 RC keeps this report as the 0.20-era design-space closure record and
+adds three concrete follow-through points:
+
+- `cell_data_codec_manifest` remains the codec-identity bridge into generated
+  builders and deployment identity;
+- action-aware scan selectors now give adapters a structured live-cell evidence
+  vocabulary instead of relying on action names;
+- TemplateLayout records shipped as metadata-only evidence with
+  `consensus_checked = false`; executable template-commitment verification
+  remains future work.
+
+Raw-layout DSL support, multi-ABI builder codec backends, registry/indexer
+support for multiple ABI families, and full Infern parity evidence remain
+productisation work rather than 0.21 production claims.
+
 ## Closure Status
 
 The CellScript-repository P0/P1 design-space compression items are closed for
@@ -56,7 +73,7 @@ a real six-contract Infern parity matrix.
 | public scheduler policy witness remains Molecule-only | `src/lib.rs:3411-3416` |
 | `lock_args` is a fixed-width `Script.args` escape hatch | `docs/CELLSCRIPT_ENTRY_WITNESS_ABI.md:40-43` |
 | schema-backed dynamic witness payloads are Molecule data | `docs/CELLSCRIPT_ENTRY_WITNESS_ABI.md:70-80` |
-| raw cell data and OutPoint helpers exist | `docs/CELLSCRIPT_0_18_ROADMAP.md:93-110` |
+| raw cell data and OutPoint helpers exist | `docs/archive/0.18/CELLSCRIPT_0_18_ROADMAP.md:93-110` |
 | NovaSeal v0-mvp demonstrates raw byte-offset source expressibility | `proposals/novaseal/v0-mvp-skeleton/src/nova_state_lifecycle_type.cell:138-177`, `proposals/novaseal/v0-mvp-skeleton/src/nova_state_type.cell:125-155` |
 | v0-mvp packed layout is not a production ABI conclusion | `proposals/novaseal/v0-mvp-skeleton/docs/SCHEMA_LAYOUT.md:44-54` |
 | newer NovaSeal profiles mostly use whole-cell packed hashes | `proposals/novaseal/fungible-xudt-profile-v0/src/nova_fungible_xudt_lifecycle_type.cell:226-227`, `proposals/novaseal/btc-transaction-commitment-profile-v0/src/nova_btc_transaction_commitment_type.cell:361`, `proposals/novaseal/fiber-candidate-profile-v0/src/nova_fiber_candidate_type.cell:378` |

docs/CELLSCRIPT_PACKAGE_PROVENANCE_AND_DEPLOYMENT_IDENTITY.md

@@ -1,12 +1,15 @@
 # CellScript Package Provenance and Deployment Identity
 
-**Status**: RFC — early design discussion
+**Status**: implementation contract for the current CellScript CKB profile.
+Phase 1 landed in the 0.19 line; Phase 2 source-package, generated-builder,
+deployment identity, and trust-metadata checks extend through 0.20 and the
+0.21 RC.
 
 **Scope**: Source package registry, deployment registry, lockfile binding, and
 builder verification for CellScript on CKB
 
-**Depends on**: v0.12 stable developer surface, v0.17 CKB protocol semantics,
-v0.18 first-class ScriptRef / ScriptArgs work
+**Historical scope anchors**: v0.12 stable developer surface, v0.17 CKB
+protocol semantics, and v0.18 first-class ScriptRef / ScriptArgs work.
 
 **Forum thread**: <https://talk.nervos.org/t/cellscript-package-and-deployment-registry-early-design-discussion/10210>
 
@@ -412,7 +415,7 @@ namespace = "cellscript"
 source_hash = "blake2b:0xabcd..."
 
 [package.build]
-compiler_version = "0.19.0"
+compiler_version = "0.21.0-rc.1"
 target_profile = "ckb"
 artifact_hash = "blake2b:0x1234..."
 metadata_hash = "blake2b:0x5678..."
@@ -583,7 +586,7 @@ version = "1.2.0"
 source_hash = "blake2b:0xabcd..."
 
 [build]
-compiler_version = "0.19.0"
+compiler_version = "0.21.0-rc.1"
 artifact_hash = "blake2b:0x1234..."
 metadata_hash = "blake2b:0x5678..."
 schema_hash = "blake2b:0x9abc..."
@@ -704,7 +707,7 @@ namespace = "cellscript"
 source_hash = "blake2b:0xabcd..."
 
 [package.build]
-compiler_version = "0.19.0"
+compiler_version = "0.21.0-rc.1"
 target_profile = "ckb"
 artifact_hash = "blake2b:0x1234..."
 metadata_hash = "blake2b:0x5678..."
@@ -835,7 +838,7 @@ version = "1.2.0"
 source_hash = "blake2b:0xabcd..."
 
 [build]
-compiler_version = "0.19.0"
+compiler_version = "0.21.0-rc.1"
 artifact_hash = "blake2b:0x1234..."
 metadata_hash = "blake2b:0x5678..."
 schema_hash = "blake2b:0x9abc..."

docs/CELLSCRIPT_REGISTRY_PHASE1.md

@@ -1,5 +1,9 @@
 # CellScript Registry Phase 1: JoyID-Rooted Package Publishing for CKB Smart Contracts
 
+**Status**: public walkthrough of the Phase 1 registry contract for the current
+CellScript CKB profile. Policy decisions defer to
+[`CELLSCRIPT_REGISTRY_PRODUCTION_BOUNDARY_ADR.md`](CELLSCRIPT_REGISTRY_PRODUCTION_BOUNDARY_ADR.md).
+
 Publishing and consuming smart contract libraries should feel like a normal
 package workflow: `cellc publish` publishes a package, and the registry shows
 the new entry. The CellScript public registry policy therefore treats publish
@@ -187,7 +191,7 @@ namespace = "cellscript"
 source_hash = "blake2b:0xabcd..."
 
 [package.build]
-compiler_version = "0.19.0"
+compiler_version = "0.21.0-rc.1"
 target_profile = "ckb"
 artifact_hash = "blake2b:0x1234..."
 
@@ -217,7 +221,7 @@ version = "1.2.0"
 source_hash = "blake2b:0xabcd..."
 
 [build]
-compiler_version = "0.19.0"
+compiler_version = "0.21.0-rc.1"
 artifact_hash = "blake2b:0x1234..."
 
 [[deployments]]