l-follow-zudo-doc-cloud-update

Review every new zudo-doc-cloud main commit since the last checked SHA, decide which upstream changes zudo-text must follow, apply and verify clear consumer changes, and advance the checked SHA only a...

File Structure

l-follow-zudo-doc-cloud-update/
├── SKILL.md
└── references/
    └── consumer-impact.md

• references/consumer-impact.md

Follow zudo-doc-cloud updates

Compare the last reviewed upstream revision with current zudolab/zudo-doc-cloud main, inspect the actual code delta, and decide deliberately what zudo-text must adopt. This is a consumer-impact review, not a request to mirror the upstream SPA.

Tracked review state

Checked upstream commit: a4f7f6ddfd5dd3b7e21742b3017c17be8d04b004

Checked on: 2026-09-04

The commit above means “every upstream change through this revision was reviewed for zudo-text impact.” It is deliberately separate from the exact source pins in packages/doc-cloud-client/VENDORED.md and packages/doc-cloud-preview/VENDORED.md. Advance a vendored pin only when its named source files were actually re-synced and the corresponding parity tests passed.

Bootstrap provenance: the original Doc Cloud implementation audited 30dbe1d9f41d27141138747dee8b6f0fb4a991fa. The 20-commit delta from that revision through da62a346029bb076a01d4bbf462a21f7cb6931c7 was reviewed when this skill was created. It introduced upstream command-palette and editor-chrome behavior, did not touch either vendored source set, and required no zudo-text consumer change.

The 233-commit range from 319f5c974cf6c030abd959dcf51c37034609fe6e through a4f7f6ddfd5dd3b7e21742b3017c17be8d04b004 was reviewed in this epic. Ignore list: error-code renames on routes zudo-text never calls (asset-filename-conflict → asset-path-conflict, new asset and outline-v2 codes); outline V2 command routes (no outline commands sent); preset schema additions (tags, assetViewer* features, logo { mode: "asset", assetId }, slot unions); locale routes and localization fields; asset composite routes and the wider X-Zudo-Asset header (byte GET unchanged); personal publish capability-unavailable (503, already the retry-same-key path); community worker routes, canonical hash rewrite, site map; editor tab-strip overflow, squared dialogs, Assets Library chrome, floating panel (zudo-text owns its frame chrome). The outstanding #5947 wasm pin move remains follow-up work under the mac gate; the live @takazudo/zfb-md-wasm pin is 2.15.1.

Arguments

Accept exactly these forms:

• no argument — fetch upstream main into FETCH_HEAD and review it without changing the upstream checkout's branch or working tree;

• -p or --pull — first fast-forward a clean local upstream main checkout, then review its new HEAD.

-p and --pull are identical. Reject any other argument rather than guessing. Never combine this command with a force pull, rebase, reset, stash, or branch switch in the upstream repository.

Phase 1 — Resolve and refresh the trusted upstream checkout

Run from the zudo-text repository root. Resolve the upstream checkout in this order:

1. $ZUDO_DOC_CLOUD_REPO, when set;

2. $HOME/repos/zp/zudo-doc-cloud;

3. a zudo-doc-cloud sibling beside the zudo-text checkout.

Require a Git worktree whose origin is zudolab/zudo-doc-cloud (HTTPS or SSH). If none is available, stop without editing the checked commit and report the paths examined. Do not create a surprise clone inside zudo-text.

No-argument refresh:

git -C "$ZDC_REPO" fetch --no-tags origin main
git -C "$ZDC_REPO" rev-parse FETCH_HEAD

This deliberately refreshes only Git metadata. It must not alter upstream HEAD or files.

For -p / --pull, inspect the upstream checkout before mutation:

git -C "$ZDC_REPO" branch --show-current
git -C "$ZDC_REPO" status --porcelain=v1
git -C "$ZDC_REPO" fetch --no-tags origin main
git -C "$ZDC_REPO" rev-parse FETCH_HEAD
git -C "$ZDC_REPO" merge-base --is-ancestor HEAD FETCH_HEAD
git -C "$ZDC_REPO" pull --ff-only origin main
git -C "$ZDC_REPO" rev-parse FETCH_HEAD
git -C "$ZDC_REPO" rev-parse HEAD

Only run the pull when the branch is exactly main, the worktree is clean, and local HEAD is an ancestor of the fetched remote commit. After pulling, require HEAD to equal the new FETCH_HEAD; this prevents a clean but locally-ahead checkout from becoming the review target. If any condition fails, do not stash, switch, reset, or overwrite anything; fall back to the no-argument fetch-only review and report why the pull was skipped.

Phase 2 — Establish a safe comparison range

Read the full 40-character checked commit from this file. The target is always the full remote main commit in FETCH_HEAD; a successful pull additionally proves upstream HEAD equals that target. Verify checked and target are commit objects.

Classify the relationship before reading patches:

git -C "$ZDC_REPO" merge-base --is-ancestor "$CHECKED_SHA" "$TARGET_SHA"
git -C "$ZDC_REPO" merge-base --is-ancestor "$TARGET_SHA" "$CHECKED_SHA"

• Equal commits: report Already checked and make no edits.

• Checked is an ancestor of target: review CHECKED_SHA..TARGET_SHA.

• Target is older than checked: never move the marker backward; report the stale target.

• Neither is an ancestor: treat it as rewritten/diverged upstream history. Inspect the merge base and report the situation, but do not advance the marker or apply speculative consumer changes.

If a shallow clone lacks the checked object, deepen the existing clone enough to resolve it. Never substitute a nearby commit or date-based guess.

Start an advancing review with compact evidence:

git -C "$ZDC_REPO" log --reverse --format='%h%x09%s' "$CHECKED_SHA..$TARGET_SHA"
git -C "$ZDC_REPO" diff --stat "$CHECKED_SHA..$TARGET_SHA"
git -C "$ZDC_REPO" diff --name-status "$CHECKED_SHA..$TARGET_SHA"

Do not update the marker yet.

Phase 3 — Assess consumer impact

Read all of these before judging the delta:

• references/consumer-impact.md

• doc/src/content/docs/architecture/doc-cloud.mdx

• packages/doc-cloud-client/VENDORED.md

• packages/doc-cloud-preview/VENDORED.md

Use the changed-file survey to select patches; do not read a huge upstream diff linearly. Inspect every changed file that intersects an authoritative vendored path or one of the wire/security/runtime surfaces in the consumer map. For renames, inspect both the old and new paths. Read upstream tests with the code: they often state nullability, status codes, retry rules, and lifecycle behavior more precisely than implementation comments.

Then search the current zudo-text tree for the affected route, field, event, error code, option, token, or behavior. Compare behavior rather than matching names mechanically. A preserved wire contract with an upstream internal refactor is normally ignorable; a changed status, DTO, guard, sanitizer rule, SSE meaning, auth rule, or version pin is not.

Classify each meaningful upstream change as exactly one of:

1. Apply — zudo-text consumes the contract or intentionally mirrors the behavior. Make the smallest coherent consumer edit and add/update tests.

2. Follow-up required — the impact is real but needs product judgment, upstream work, credentials, macOS evidence, or a larger project. Leave the checked marker unchanged until that work is completed; state the exact blocker and affected local surface.

3. Ignore — upstream-only SPA chrome, administration, implementation detail, or behavior zudo-text deliberately owns differently. State the concrete boundary that makes it irrelevant.

Do not import upstream command-palette, routing, shell, theme, or layout work merely for UI parity. zudo-text owns its frame chrome and command system. Do follow upstream changes when they alter the Personal authoring product contract or expose an operation that zudo-text already promises through its own UI.

Phase 4 — Apply and verify required changes

For every Apply item:

1. update producers and consumers together — this repository is pre-release and does not carry compatibility migrations;

2. preserve unknown-event forward compatibility and raw upstream error data;

3. update the relevant vendored note only if its exact source set was re-synced;

4. run the narrow package/component checks from the consumer map;

5. run pnpm check and the relevant build/typecheck before accepting the result; use pnpm b4push when product code changed or the caller requested a full landing gate.

Do not run installs, builds, migrations, or tests inside zudo-doc-cloud. The upstream checkout is evidence only, apart from the explicitly requested fast-forward pull.

Phase 5 — Advance the marker atomically

Advance the two lines under Tracked review state to the target SHA and the current YYYY-MM-DD only after all changed commits have one of these outcomes:

• irrelevant with a recorded reason in the run report; or

• required consumer edits completed and their relevant checks passed.

If any required work remains unresolved, leave both lines untouched. Never advance to a partially reviewed commit, never record a short SHA, and never advance merely because the upstream diff compiled on its own.

Review the final zudo-text diff. The marker edit and any consumer changes belong to one logical change so future history explains why that upstream range was accepted. This skill does not commit or push by itself unless the caller's workflow also requested that.

Report

Use verdict headings and include:

• checked SHA → target SHA and commit count;

• whether --pull fast-forwarded the upstream checkout or fetch-only mode was used;

• Applied items with local files and checks;

• Ignored items with one concrete reason each;

• unresolved blockers, if any;

• the final checked marker and whether either VENDORED.md pin changed.