docs: update docs and remove old ccc-dev/ directory

- AGENTS.md: document fork-scripts/ workflow and per-fork structure
- README.md: update developer script examples for fork:* format
- Delete ccc-dev/: replaced by fork-scripts/ + ccc-fork/

Author: phroi

.changeset/generalize-fork-management.md

@@ -0,0 +1,4 @@
+---
+---
+
+Generalize ccc-dev/ into multi-repo fork management tool

AGENTS.md

@@ -18,32 +18,45 @@
 
 ## PR Workflow
 
-1. **Routine Pre-PR Validation**: `pnpm check:full`, it wipes derived state and regenerates from scratch. If `ccc-dev/ccc/` has pending work, the wipe is skipped to prevent data loss — re-record or push CCC changes first for a clean validation
+1. **Routine Pre-PR Validation**: `pnpm check:full`, it wipes derived state and regenerates from scratch. If any fork clone has pending work, the wipe is skipped to prevent data loss — re-record or push fork changes first for a clean validation
 2. **Open a PR**: Run `pnpm changeset` to generate a changeset entry, then push the branch and present a clickable markdown link `[title](url)` where the URL is a GitHub compare URL (`quick_pull=1`). Base branch is `master`. Prefill "title" (concise, under 70 chars) and "body" (markdown with ## Why and ## Changes sections)
 3. **Fetch PR review comments**: Use the GitHub REST API via curl. Fetch all three comment types (issue comments, reviews, and inline comments). Categorize feedback by actionability (action required / informational), not by source (human / bot). Reviewers reply asynchronously — poll every minute until comments arrive
 
-## CCC Local Development (ccc-dev/)
+## Fork Management (fork-scripts/ + *-fork/)
 
-The `ccc-dev/` system uses a record/replay mechanism for deterministic builds of a local CCC fork:
+The `fork-scripts/` system uses a record/replay mechanism for deterministic builds of external repo forks. Each fork lives in a `<name>-fork/` directory with a `config.json` specifying upstream URL, fork URL, merge refs, and workspace config. Scripts in `fork-scripts/` are generic and accept the fork directory as their first argument.
 
-- `ccc-dev/pins/` is **committed** to git (base SHAs, merge refs, conflict resolutions, local patches), regenerated by `pnpm ccc:record`
-- `ccc-dev/ccc/` is **not in git** — it is rebuilt from pins on `pnpm install`
-- The developer may have **pending work** in `ccc-dev/ccc/`. Run `pnpm ccc:status` (exit 0 = safe to wipe, exit 1 = has custom work) before any operation that would destroy it. `pnpm ccc:record`, `pnpm ccc:clean`, and `pnpm ccc:reset` already guard against this automatically
-- `.pnpmfile.cjs` silently rewrites all `@ckb-ccc/*` dependencies to `workspace:*` when `ccc-dev/ccc/` exists. Local CCC packages override published ones without any visible change in package.json files
-- `pnpm install` has a side effect: if `ccc-dev/pins/REFS` exists but `ccc-dev/ccc/` does not, it automatically runs `ccc-dev/replay.sh` to rebuild CCC from pins. This is intentional
-- `ccc-dev/patch.sh` rewrites CCC package exports to point at `.ts` source instead of `.d.ts`, then creates a deterministic git commit (fixed author/date) so record and replay produce the same `pins/HEAD` hash. This is why imports from `@ckb-ccc/*` resolve to TypeScript source files inside `node_modules` — it is not a bug
-- `ccc-dev/tsgo-filter.sh` is a bash wrapper around `tsgo` that filters out diagnostics originating from `ccc-dev/ccc/`. CCC source does not satisfy this repo's strict tsconfig (`verbatimModuleSyntax`, `noUncheckedIndexedAccess`, `noImplicitOverride`), so the wrapper suppresses those errors while still reporting errors in stack source
+### Per-fork directory structure
 
-### Opening a CCC upstream PR
+Each `<name>-fork/` contains:
+- `config.json` — upstream URL, fork URL, refs to merge, cloneDir, workspace include/exclude
+- `pins/` — **committed** to git (manifest + counted resolutions + local patches), regenerated by `pnpm fork:record <name>-fork`
+  - `pins/HEAD` — expected final SHA after full replay
+  - `pins/manifest` — base SHA + merge refs (TSV, one per line)
+  - `pins/res-N.resolution` — conflict resolution for merge step N (counted format: `--- path` file headers, `CONFLICT ours=N base=M theirs=K resolution=R` conflict headers followed by R resolution lines; parser is purely positional — reads counts and skips lines, never inspects content)
+  - `pins/local-*.patch` — local development patches (applied after merges + patch.sh)
+- `<cloneDir>/` — **not in git** — rebuilt from pins on `pnpm install`
 
-In `ccc-dev/ccc/`, branch off `origin/master` (or relevant branch), push to fork (`phroi/ccc`), open PR against `ckb-devrel/ccc`. Before pushing, run the CCC CI steps (`ccc-dev/ccc/.github/workflows/check.yaml`) with `CI=true`.
+### Key behaviors
 
-Once the PR is open, replace the local patch with a merge ref:
+- The developer may have **pending work** in a fork clone. Run `pnpm fork:status <name>-fork` (exit 0 = safe to wipe, exit 1 = has custom work) before any operation that would destroy it. `fork:record`, `fork:clean`, and `fork:reset` already guard against this automatically
+- `.pnpmfile.cjs` scans all `*-fork/config.json` directories and silently rewrites matching dependencies to `workspace:*` when clones exist. Local fork packages override published ones without any visible change in package.json files
+- `pnpm install` has a side effect: if `<name>-fork/pins/manifest` exists but the clone does not, it automatically runs `fork-scripts/replay.sh` to rebuild from pins. This is intentional
+- `fork-scripts/patch.sh` rewrites fork package exports to point at `.ts` source instead of `.d.ts`, then creates a deterministic git commit (fixed author/date) so record and replay produce the same HEAD hash. This is why imports from fork packages resolve to TypeScript source files — it is not a bug
+- `fork-scripts/tsgo-filter.sh` is a bash wrapper around `tsgo` that filters out diagnostics originating from all `*-fork/` clone paths. Fork source may not satisfy this repo's strict tsconfig, so the wrapper suppresses those errors while still reporting errors in stack source
+- `pnpm fork:save <name>-fork [description]` captures local work as a patch in `pins/`. Patches survive re-records and replays
+- `pnpm fork:record` regenerates the fork workspace entries in `pnpm-workspace.yaml` (between `@generated` markers) from all `*-fork/config.json` files — manual edits to that section are overwritten on re-record
 
-1. Delete the patch from `ccc-dev/pins/local/`
-2. Add the PR number to `ccc:record` in `package.json` — order PRs by target branch from upstream to downstream, so each group merges cleanly onto its base before the next layer begins
-3. Run `pnpm ccc:record`
-4. Run `pnpm check:full` to verify the merge ref reproduces what the local patch achieved
+### CCC upstream contributions
+
+Work locally via `ccc-fork/` first. Only push to the fork (`phroi/ccc`) when changes are validated against the stack. Do not open PRs against `ckb-devrel/ccc` prematurely — keep changes on the fork until they are production-ready and the maintainer decides to upstream.
+
+1. Develop and test in `ccc-fork/ccc/` on the `wip` branch
+2. When ready, use `pnpm fork:push ccc-fork` to cherry-pick commits onto a PR branch
+3. Push the PR branch to `phroi/ccc` for review
+4. Add the PR number to `refs` in `ccc-fork/config.json` — order PRs by target branch from upstream to downstream, so each group merges cleanly onto its base before the next layer begins
+5. Run `pnpm fork:record ccc-fork` and `pnpm check:full` to verify
+6. Only open an upstream PR against `ckb-devrel/ccc` when the maintainer explicitly decides to upstream
 
 ## Reference Repos
 

README.md

@@ -54,17 +54,17 @@ graph TD;
     click F "https://github.com/ickb/stack/tree/master/packages/sdk" "Go to @ickb/sdk"
 ```
 
-## Develop CCC
+## Develop with Forks
 
-When `ccc-dev/pins/REFS` is committed, `pnpm install` automatically sets up the CCC local development environment on first run (by replaying pinned merges via `ccc-dev/replay.sh`). No manual setup step is needed — just clone and install:
+When `<name>-fork/pins/manifest` is committed, `pnpm install` automatically sets up the local fork development environment on first run (by replaying pinned merges via `fork-scripts/replay.sh`). No manual setup step is needed — just clone and install:
 
 ```bash
 git clone git@github.com:ickb/stack.git && cd stack && pnpm install
 ```
 
-To redo the setup from scratch: `pnpm ccc:clean && pnpm install`.
+To redo the setup from scratch: `pnpm fork:clean-all && pnpm install`.
 
-See [ccc-dev/README.md](ccc-dev/README.md) for recording new pins, developing CCC PRs, and the full workflow.
+See [ccc-fork/README.md](ccc-fork/README.md) for recording new pins, developing CCC PRs, and the full workflow.
 
 ## Reference
 
@@ -81,15 +81,17 @@ This clones two repos into the project root (both are git-ignored and made read-
 
 ## Developer Scripts
 
-| Command             | Description                                                                           |
-| ------------------- | ------------------------------------------------------------------------------------- |
-| `pnpm coworker`     | Launch an interactive AI Coworker session (full autonomy, opus model).                 |
-| `pnpm coworker:ask` | One-shot AI query for scripting (sonnet model, stateless). Used by `pnpm ccc:record`. |
-| `pnpm ccc:status`   | Check if CCC clone matches pinned state. Exit 0 = safe to wipe.          |
-| `pnpm ccc:record`   | Record CCC pins (clone, merge refs, build). Guarded against pending work.             |
-| `pnpm ccc:clean`    | Remove CCC clone, keep pins (guarded). Re-replay on next `pnpm install`.              |
-| `pnpm ccc:reset`    | Remove CCC clone and pins (guarded). Restores published CCC packages.                 |
-| `pnpm check:full`   | Wipe derived state and validate from scratch. Skips wipe if CCC has pending work.     |
+| Command                          | Description                                                                       |
+| -------------------------------- | --------------------------------------------------------------------------------- |
+| `pnpm coworker`                  | Launch an interactive AI Coworker session (full autonomy, opus model).             |
+| `pnpm coworker:ask`              | One-shot AI query for scripting (sonnet model, stateless). Used by fork:record.    |
+| `pnpm fork:status <name>-fork`   | Check if fork clone matches pinned state. Exit 0 = safe to wipe.                  |
+| `pnpm fork:record <name>-fork`   | Record fork pins (clone, merge refs, build). Guarded against pending work.         |
+| `pnpm fork:save <name>-fork`     | Capture local fork work as a patch in pins/ (survives re-records and replays).     |
+| `pnpm fork:push <name>-fork`     | Cherry-pick commits from wip branch onto a PR branch for pushing to the fork.      |
+| `pnpm fork:clean <name>-fork`    | Remove fork clone, keep pins (guarded). Re-replay on next `pnpm install`.          |
+| `pnpm fork:reset <name>-fork`    | Remove fork clone and pins (guarded). Restores published packages.                 |
+| `pnpm check:full`                | Wipe derived state and validate from scratch. Skips wipe if forks have pending work.|
 
 ## Epoch Semantic Versioning