docs(localization): clarify progressive slice delivery

[giodl73-repo]

Follows accepted RFC #42.

What this clarifies

• 22 registered locales: English source plus 21 translation targets.
• 15 required product surfaces: 315 translation-target cells; 315/315 is the full product target, not today's shipped state.
• Each surface owns its copy, catalogs, renderer, workflow, and review policy while reusing shared per-repository gates and evidence contracts.
• Ready same-repository PRs targeting the default branch use a blocking drift gate plus a trusted in-place refresh. Fork and cross-repository paths use one post-merge generated PR.

One string, end to end

flowchart TB
  EN["1. Ready English source PR<br/><code>wizard.completion.enable</code>"]
  GATE["2. Credential-free gate fails<br/>zh-CN + zh-TW are stale"]
  ACTION["3. Maintainer runs Localization Catalog Refresh<br/>protected-main tooling • exact PR head"]
  UPDATE["4. Bot commits one translation batch<br/>to the unchanged source branch"]
  CHECK["5. Same PR reruns strict checks + review"]
  MERGE["6. Maintainer merges the complete review unit"]
  SHIP["7. Owner artifact ships"]
  OUTPUT["8. Owner renders<br/>为 openclaw 启用 zsh shell completion？"]
  FORK["Fork / cross-repo<br/>merge English, then one generated follow-up PR"]
  FAIL["Failure or moved head<br/>publish nothing • English fallback stays live"]
  EN --> GATE --> ACTION --> UPDATE --> CHECK --> MERGE --> SHIP --> OUTPUT
  EN -. source branch cannot be updated .-> FORK --> CHECK
  ACTION -. generation, validation, or lease fails .-> FAIL

Loading

The workflow executes generator code from protected main; the PR registry and English catalogs are validated data only. It never executes PR scripts, actions, dependencies, or hooks with provider credentials. Before pushing, it rechecks open/ready/same-repository/base/head state and uses an exact-head lease. Automation does not approve or merge its output.

Delivery

Each owner slice enrolls one bounded surface in the shared gate and refresh workflow, or proves its existing owner pipeline conforms. The 47 projected slices remain grouped into 16 delivery packages toward the September 1, 2026 completion decision. Live delivery stays in openclaw#113105.

Core exemplar: openclaw#112784. Surface registration: openclaw#112801.

Review decision

Project direction and progressive owner onboarding were aligned with Patrick and Vince in Discord. Patrick remains the primary implementation-stack reviewer; semantic, security, platform, and publication owners still review their boundaries.

Validation

Exact head: 0e19881be5a456bfcbf29a81bcc87dbcaf471b08

MAIN_RFC words=2076
RFC_LINKS checked=16 broken=0
SLICE_IDS unique=47
MERMAID_BLOCKS recognized=2
DIFF_CHECK clean

AI-assisted: yes. I reviewed the wording and validation evidence.

[giodl73-repo]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed July 24, 2026, 9:48 AM ET / 13:48 UTC.

ClawSweeper review

What this changes

This PR updates RFC 0024 planning documents to describe progressive localization-slice documentation obligations, gate ownership, lifecycle states, and the live implementation ledger.

Merge readiness

⛔ Blocked until stronger real behavior proof is added - 8 items remain

This PR is not already implemented on current main: it adds new RFC 0024 delivery obligations and lifecycle wording. The clarification is useful, but the mandatory inventory, workflow, guidance, and alias requirements need explicit product-direction confirmation because they expand the accepted RFC’s owner-slice contract.

Priority: P3
Reviewed head: 1c7b7426d492f611c1cc4dedcbbe3c2c3e0f8f79
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🧂 unranked krab (1/6)	The documentation work is coherent, but unresolved RFC policy direction and uninspectable validation evidence prevent merge readiness.
Proof confidence	🧂 unranked krab (1/6)	Needs stronger real behavior proof before merge: The PR reports validation checks, but does not provide inspectable after-change terminal output, a linked artifact, or a reproducible validation transcript; please attach redacted evidence for the link and slice-ID checks before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🦪 silver shellfish (2/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs stronger real behavior proof before merge: The PR reports validation checks, but does not provide inspectable after-change terminal output, a linked artifact, or a reproducible validation transcript; please attach redacted evidence for the link and slice-ID checks before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	4 items	Accepted RFC baseline: Current main contains the accepted RFC 0024 contract, whose migrated-surface requirements cover semantic meaning, locale authority, catalogs/rendering, compatibility, privacy, conformance evidence, and removal of superseded presentation paths; it does not establish the newly proposed mandatory inventory/workflow/guidance artifacts in this wording. Proposed contract expansion: The PR adds checked-in inventory, a public workflow index, owner-internal guidance, and additional public-contract documentation to the definition of a migrated surface, so this is more than a terminology-only clarification. RFC provenance: The accepted RFC was merged to current main from commit 267e575; this PR is a follow-up to that accepted contract rather than an implementation already present on main.
Findings	1 actionable finding	[P1] Confirm the new slice-completion contract before requiring it
Security	None	None.

How this fits together

RFC 0024 defines how localization work moves from bounded owner slices into reviewed runtime and catalog changes. These planning documents guide contributors from a proposed surface through owner review, generated artifacts, and eventual landing in the OpenClaw product repository.

flowchart LR
  A[Product surface change] --> B[Owner localization slice]
  B --> C[Inventory and workflow guidance]
  C --> D[Scoped gate review]
  D --> E[Source and generated artifacts]
  E --> F[Owner approval]
  F --> G[Live delivery ledger]

Loading

Decision needed

Question	Recommendation
Should RFC 0024 make checked-in inventory entries, a public workflow index, owner guidance, and the stated CLAUDE.md alias mandatory completion criteria for every adopted localization slice?	Keep the accepted contract narrow: Limit this PR to clarifying already accepted owner and evidence responsibilities, leaving any new mandatory workflow requirements to a separately approved RFC amendment.

Why: The accepted RFC establishes the localization contract, while this PR changes the operational obligations contributors must satisfy to declare a slice complete; that policy boundary needs maintainer intent rather than documentation inference.

Before merge

• Add real behavior proof - Needs stronger real behavior proof before merge: The PR reports validation checks, but does not provide inspectable after-change terminal output, a linked artifact, or a reproducible validation transcript; please attach redacted evidence for the link and slice-ID checks before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Confirm the new slice-completion contract before requiring it (P1) - This changes the accepted RFC from naming ownership/proof concerns to requiring specific inventory, workflow-index, and guidance artifacts for every migrated surface. Because that expands cross-slice delivery obligations, obtain explicit maintainer approval or limit the text to already accepted requirements before merging.
• Resolve merge risk (P1) - Merging the new mandatory delivery artifacts without explicit approval could turn a previously bounded RFC contract into a broader contributor and owner workflow requirement across future localization slices.
• Resolve merge risk (P1) - The reported validation is not yet backed by inspectable after-change output or an artifact, so reviewers cannot independently verify the link and registry checks from the PR discussion.
• Complete next step (P2) - A maintainer must decide whether these new cross-slice completion requirements belong in the accepted RFC before any mechanical documentation follow-up is appropriate.
• Improve patch quality - Get an explicit maintainer decision on the new mandatory slice-completion criteria.
• Improve patch quality - Attach redacted terminal output or a reproducible validation artifact for the reported link and projected-ID checks.

Findings

• [P1] Confirm the new slice-completion contract before requiring it — rfcs/0024-localization-runtime-and-coverage.md:69-71

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
RFC planning surface	3 files affected; 145 added, 39 removed	The PR changes the accepted RFC plus both implementation-planning sidecars, so its delivery-policy effect spans the full localization planning surface.

Merge-risk options

Maintainer options:

1. Confirm and bound the new contract (recommended)
   Obtain explicit approval for the new completion criteria, then define which owners and existing slices are subject to them before merge.
2. Keep the RFC at its accepted scope
   Remove or reframe the mandatory delivery obligations as non-normative planning guidance until a dedicated amendment is approved.
3. Pause the clarification
   Leave the PR open or close it until maintainers decide whether these cross-slice obligations belong in the accepted RFC.

Technical review

Best possible solution:

Confirm whether the accepted RFC should require these delivery artifacts for every adopted slice; if approved, retain narrowly scoped wording and attach redacted terminal output or a reproducible validation transcript for the documented checks.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a runtime bug: the relevant behavior is the proposed RFC wording, which is directly visible in the PR diff and differs from the accepted current-main contract.

Is this the best way to solve the issue?

No, not without maintainer confirmation. The proposed wording is a reasonable candidate policy, but it should either be explicitly accepted as an RFC contract expansion or constrained to already approved obligations.

Full review comments:

• [P1] Confirm the new slice-completion contract before requiring it — rfcs/0024-localization-runtime-and-coverage.md:69-71
  This changes the accepted RFC from naming ownership/proof concerns to requiring specific inventory, workflow-index, and guidance artifacts for every migrated surface. Because that expands cross-slice delivery obligations, obtain explicit maintainer approval or limit the text to already accepted requirements before merging.
  Confidence: 0.86

Overall correctness: patch is incorrect
Overall confidence: 0.84

AGENTS.md: unclear because the file could not be read completely.

Codex review notes: model internal, reasoning high; reviewed against faf2a3a5b1ac.

Labels

Label changes:

• add P3: This is a documentation and planning-policy clarification with no direct runtime behavior change.
• add merge-risk: 🚨 compatibility: The proposed mandatory completion criteria could change established contributor and owner expectations for existing and future localization slices.
• add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🦪 silver shellfish.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The PR reports validation checks, but does not provide inspectable after-change terminal output, a linked artifact, or a reproducible validation transcript; please attach redacted evidence for the link and slice-ID checks before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Label justifications:

• P3: This is a documentation and planning-policy clarification with no direct runtime behavior change.
• merge-risk: 🚨 compatibility: The proposed mandatory completion criteria could change established contributor and owner expectations for existing and future localization slices.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🦪 silver shellfish.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The PR reports validation checks, but does not provide inspectable after-change terminal output, a linked artifact, or a reproducible validation transcript; please attach redacted evidence for the link and slice-ID checks before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

What I checked:

• Accepted RFC baseline: Current main contains the accepted RFC 0024 contract, whose migrated-surface requirements cover semantic meaning, locale authority, catalogs/rendering, compatibility, privacy, conformance evidence, and removal of superseded presentation paths; it does not establish the newly proposed mandatory inventory/workflow/guidance artifacts in this wording. (rfcs/0024-localization-runtime-and-coverage.md:66, faf2a3a5b1ac)
• Proposed contract expansion: The PR adds checked-in inventory, a public workflow index, owner-internal guidance, and additional public-contract documentation to the definition of a migrated surface, so this is more than a terminology-only clarification. (rfcs/0024-localization-runtime-and-coverage.md:69, 1c7b7426d492)
• RFC provenance: The accepted RFC was merged to current main from commit 267e575; this PR is a follow-up to that accepted contract rather than an implementation already present on main. (rfcs/0024-localization-runtime-and-coverage.md:1, faf2a3a5b1ac)
• Proof assessment: The PR body reports link, uniqueness, and diff checks, but it does not include inspectable terminal output, a validation transcript, or an attached artifact showing the post-change results. (1c7b7426d492)

Likely related people:

• giodl73-repo: Authored the accepted RFC 0024 head that established the current localization contract and authored this follow-up clarification. (role: RFC author and original contract contributor; confidence: high; commits: 267e575a67e7, 1c7b7426d492; files: rfcs/0024-localization-runtime-and-coverage.md, rfcs/0024/implementation-plan.md, rfcs/0024/projected-owner-slice-registry.md)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[giodl73-repo]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

[giodl73-repo]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

[giodl73-repo]

Pre-merge cleanup is complete at exact head 55b382c: the system diagram is now a vertical 1. Own -> 2. Automate -> 3. Ship summary, and the PR body includes after-change link, slice-ID, diff, Mermaid-render, and semantic-review evidence. Patrick remains requested for the explicit mandatory slice-completion decision.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

[giodl73-repo]

The system overview now uses only searchable implementation names from openclaw/openclaw: localization/surfaces.json, localization/catalogs.json, the localization-catalogs CI job, Localization Catalog Refresh, @openclaw/localization-core, and LocalizationContext. RFC planning IDs are absent from the overview and diagram.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

[giodl73-repo]

The system diagram now gives every current owner-declared product surface its own box and shows the adoption fan-out explicitly: owner source, localization/surfaces.json, and either localization/catalogs.json, a named conforming owner pipeline, or a reviewed exception rationale. Public workflow guidance and nearest AGENTS.md/CLAUDE.md owner guidance are also shown as same-slice obligations.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

[giodl73-repo]

Added an exact-head, source-accurate end-to-end example at 015c4f8c4debff261db07c775b40bf67f1b09172:

• follows the real wizard.completion.enable English message;
• shows all three adoption records (owner source, localization/surfaces.json, localization/catalogs.json);
• separates source-PR detection from trusted refresh and strict generated-catalog validation;
• shows the actual zh-CN catalog value, catalogFamily load, LocalizationContext, parameters, and rendered output; and
• states that the checked-in target is human bootstrap-reviewed, so the first credentialed refresh remains a supervised rollout gate.

Validated the values and registry entries directly against openclaw#112784 / #112801. GitHub Markdown recognizes both Mermaid blocks in the RFC and PR body.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

[giodl73-repo]

Simplified at exact head 67bb6466193fd3497eaf27825f9921f9f1f6b40f.

The main RFC is now 1,677 words (down from 7,431) and leads with the real wizard string. Reference-level mechanics remain in the normative sidecars.

The product target is now unambiguous: English source + 21 translation targets across 15 required surfaces = 315 target cells, and only 315/315 is product-complete. A platform constraint may explain a blocker but no longer reduces the completion target to 313.

Validated: clean diff, 6/6 relative links, 47/47 unique slice IDs, both RFC Mermaid blocks recognized, and the example values/registrations asserted against openclaw#112784 and #112801.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

[giodl73-repo]

Sidecar clarity pass at exact head f320b4b65cbc63f8f1c92ad4d2a78fbea74acc7d:

• runtime, coverage, and metadata specs now open with a one-screen contract/ownership summary and reflect accepted RFC status;
• coverage now enumerates the exact 15 release-row IDs used by the implementation;
• release rows are explicitly distinct from finer delivery registries (for example, updater/Doctor contribute to cli, while approval work can contribute to runtime, gateway-errors, and server-rendered-channels);
• adding an adapter/package declaration no longer appears to silently expand the fixed 315-cell denominator; and
• the main RFC diagram now uses the exact release-row identifiers.

Validated 15/15 row-ID parity against REQUIRED_LOCALIZATION_SURFACES, 13 relative links with no breakage, 47 unique slice IDs, a clean diff, and both Mermaid render targets.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

[giodl73-repo]

Made the exemplar event-specific at exact head 1fc88cb6bbdc577cb59f6d15f6c87b798e6cc3f4 while retaining the 15 product-surface map:

1. contributor opens an English-only source PR;
2. credential-free PR checks confirm registration and report exact stale targets;
3. maintainer merges reviewed English to protected main;
4. that trusted main push automatically starts the credentialed refresh;
5. automation opens the generated translation PR with source-pinned evidence;
6. the generated PR runs strict catalog validation and review; and
7. after merge, the owner renderer serves the localized string.

This now matches #112784 exactly: PR detection is warning-only for ordinary source drift, generated-path changes run the strict check, and translation/provider/publisher credentials exist only in the trusted post-merge workflow. The implementation plan, coverage state machine, registry, RFC, and PR body use the same description.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

[giodl73-repo]

Applied a seven-lens .craft/roles / FACES review at exact head a6bb5d727543793b03e40ec91c9548017a32aa26:

• new-hire: made target versus current shipped state explicit;
• power-user + ciso: added generation, validation, and review failure behavior (publish nothing, English remains live, cells stay partial);
• platform-eng + founder: clarified that all 15 rows share a control loop without replacing conforming UI/native/docs owner workflows;
• gateway-eng + lorant-reviewer: inserted generated-PR merge and owner artifact shipment before runtime rendering.

The panel found no remaining architecture contradiction after these fixes. Main RFC remains under 2,000 words, all 15 product surfaces remain visible, both RFC Mermaid blocks and the PR-body Mermaid block render, and claims remain source-backed by #112784/#112801. This role review does not replace Patrick's current-head decision.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.