feat: harden dev workflow with safety guards, deterministic builds, and tool-agnostic agent config

- Add AGENTS.md as tool-agnostic AI config, CLAUDE.md becomes a symlink
- Add ccc-dev/status.sh to detect pending work before destructive operations
- Make ccc-dev/patch.sh produce deterministic commits (fixed author/date)
- Guard ccc:record, ccc:clean, ccc:reset against data loss
- Replace scripts/pr.sh and scripts/review.sh with inline agent workflows
- Add telemetry opt-out env vars and wl-clipboard to devcontainer
- Rename pnpm claude to pnpm coworker, add coworker:ask for scripting
- Reorder check pipeline: lint before build for faster feedback
- Update pnpm to 10.30.0 and typescript-eslint to 8.56.0
- Update all docs to reflect new tooling and workflows

Author: phroi

.devcontainer/devcontainer.json

@@ -11,7 +11,13 @@
 
   "containerEnv": {
     "DEVCONTAINER": "true",
-    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
+    "DEVCONTAINERS_NO_TELEMETRY": "true",
+    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
+    "CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY": "1",
+    "DO_NOT_TRACK": "1",
+    "NEXT_TELEMETRY_DISABLED": "1",
+    "NO_UPDATE_NOTIFIER": "1",
+    "npm_config_update_notifier": "false"
   },
 
   // Persisted volumes to speed installs and avoid repeated network requests
@@ -24,10 +30,12 @@
   "postCreateCommand": {
     // Enable corepack and fix workspace ownership for non-root user
     "permissions": "sudo corepack enable && sudo chown -R node:node /home/node ${containerWorkspaceFolder}",
-    // Needed for anthropic.claude-code extension to work with a pnpm claude installation
-    "aliases": "echo \"alias claude='pnpm claude'\" >> ~/.bash_aliases",
+    // Needed for AI Coworker extension to work with a pnpm installation
+    "aliases": "echo \"alias claude='pnpm coworker'\" >> ~/.bash_aliases",
     // Install GSD
-    "gsd": "pnpm dlx get-shit-done-cc@latest --claude --global --force-statusline"
+    "gsd": "pnpm dlx get-shit-done-cc@latest --claude --global --force-statusline",
+    // Clipboard support for wl-copy/wl-paste (used by CLAUDE.md)
+    "clipboard": "sudo apt-get update -qq && sudo apt-get install -y -qq wl-clipboard"
   },
 
   // Run each time the container starts. Ensures updated dependencies are installed inside the container user environment.

.gitignore

@@ -8,3 +8,6 @@
 # Reference repos
 contracts/
 whitepaper/
+
+# AI tool config symlink
+CLAUDE.md

.planning/codebase/CONVENTIONS.md

@@ -5,7 +5,7 @@
 ## Important Context
 
 **Tooling:**
-- `gh` CLI is NOT available and must NOT be installed. Use `pnpm pr` to open PRs and `pnpm review` to fetch PR comments.
+- `gh` CLI is NOT available and must NOT be installed. PR and review workflows are handled inline by the AI Coworker (see AGENTS.md).
 
 **Legacy vs. New code:**
 - `@ickb/lumos-utils@1.4.2` and `@ickb/v1-core@1.4.2` are **LEGACY and DEPRECATED** npm packages. The apps (`apps/bot`, `apps/tester`, `apps/interface`) still depend on them.

.planning/codebase/STACK.md

@@ -101,11 +101,11 @@ The repo supports using a local development build of CCC for testing unpublished
 **`ccc-dev/record.sh`:**
 - Clones the CCC repo (`https://github.com/ckb-devrel/ccc.git`) into `./ccc-dev/ccc/`
 - Accepts refs as args: branch names, PR numbers, or commit SHAs
-- Merges specified refs onto a `wip` branch (uses Claude CLI for merge conflict resolution)
+- Merges specified refs onto a `wip` branch (uses AI Coworker CLI for merge conflict resolution)
 - Builds CCC locally: `pnpm build:prepare && pnpm build`
 - Run via: `pnpm ccc:record` (default invocation: `bash ccc-dev/record.sh releases/next releases/udt`)
 - The `ccc-dev/ccc/` directory is gitignored
-- Skips if `ccc-dev/ccc/` already exists (remove it to redo setup)
+- Aborts if `ccc-dev/ccc/` has pending work (any changes vs pinned commit, diverged HEAD, or untracked files)
 
 **`.pnpmfile.cjs`:**
 - A pnpm `readPackage` hook that auto-discovers all packages in `ccc-dev/ccc/packages/*/package.json`

.planning/codebase/STRUCTURE.md

@@ -73,7 +73,7 @@
 │   │   ├── REFS                    # Pinned branch HEADs
 │   │   └── resolutions/            # Merge conflict resolutions
 │   ├── ccc/                        # Gitignored: ephemeral CCC clone (auto-generated)
-│   ├── record.sh                   # Records new pins with Claude conflict resolution
+│   ├── record.sh                   # Records new pins with AI Coworker conflict resolution
 │   ├── replay.sh                   # Deterministically rebuilds ccc/ from pins
 │   └── tsc.mjs                     # TypeScript compilation script override
 ├── contracts/                      # Reference: Rust on-chain contracts (git-ignored, clone via `pnpm reference`)
@@ -345,19 +345,15 @@
 - System: Record/replay mechanism for deterministic, conflict-free builds
 - `pins/`: Committed directory containing:
   - `REFS`: Pinned branch HEADs for merging
-  - `resolutions/`: Serialized conflict resolutions with Claude aid
+  - `resolutions/`: Serialized conflict resolutions with AI Coworker aid
 - `ccc/`: Generated from pins; auto-deleted and rebuilt on `pnpm install`
 - Activation: `.pnpmfile.cjs` hook triggers `replay.sh` and overrides package resolution
 - Commands:
-  - Record: `pnpm ccc:record releases/next releases/udt` (requires Claude CLI)
+  - Record: `pnpm ccc:record releases/next releases/udt` (requires AI Coworker CLI)
+  - Status: `pnpm ccc:status` (check for pending work in `ccc/`)
   - Rebuild: `pnpm install` (automatic)
-  - Clean: `pnpm ccc:nuke && pnpm install`
-
-**scripts/:**
-- Purpose: Developer convenience scripts
-- Files: `pr.sh` (GitHub PR creation), `review.sh` (fetch PR comments)
-- Execution: Via `pnpm pr` and `pnpm review` shortcuts
-- Committed: Yes
+  - Clean (re-replay): `pnpm ccc:clean && pnpm install` (guarded)
+  - Reset (published): `pnpm ccc:reset && pnpm install` (guarded)
 
 **node_modules/:**
 - Purpose: Installed npm/pnpm dependencies

AGENTS.md

@@ -0,0 +1,38 @@
+# AI Coworker Configuration
+
+This file is the tool-agnostic agent config:
+
+- Never add `Co-Authored-By` lines to commit messages.
+- Never add AI tool attribution or branding to PR descriptions, commit messages, or code comments (e.g. "Generated with ...", "Built by ...", "Powered by ...").
+- Refer to yourself as "AI Coworker" in docs and comments, not by product or company name.
+- Do not install or use `gh` CLI.
+- **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.
+- **Open a PR**: Push the branch, then construct and present a GitHub compare URL
+  (`quick_pull=1`) to the user. Base branch is `master`. Prefill "title" (concise, under 70 chars) and "body" (markdown with ## Why and ## Changes sections). Be brief.
+- **Fetch PR review comments**: Use the GitHub REST API via curl. Fetch all three comment types (issue comments, reviews, and inline comments). Reviewers reply asynchronously — poll every minute until comments arrive.
+- **Copy to clipboard**:
+  ```
+  head -c -1 <<'EOF' | wl-copy
+  content goes here
+  EOF
+  ```
+
+# CCC Local Development (ccc-dev/)
+
+The `ccc-dev/` system uses a record/replay mechanism for deterministic builds of a local CCC fork:
+
+- `ccc-dev/pins/` is **committed** to git (base SHAs, merge refs, conflict resolutions), 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/tsc.mjs` is a custom `tsc` wrapper 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.
+
+# Reference Repos
+
+`contracts/` and `whitepaper/` (cloned via `pnpm reference`) are made **read-only** with `chmod -R a-w`. To refresh, delete the directory and re-run `pnpm reference`.
+
+# Versioning
+
+All packages use version `1001.0.0` (Epoch Semantic Versioning), managed by changesets (`pnpm changeset`).

README.md

@@ -8,23 +8,23 @@ This monorepo is developing the **new generation** of iCKB libraries, replacing
 
 **New packages** (under `packages/`, built on CCC):
 
-| Package | Purpose | Status |
-|---|---|---|
+| Package       | Purpose                                                                    | Status             |
+| ------------- | -------------------------------------------------------------------------- | ------------------ |
 | `@ickb/utils` | Blockchain primitives, transaction helpers, epoch arithmetic, UDT handling | Active development |
-| `@ickb/dao` | Nervos DAO abstraction layer | Active development |
-| `@ickb/order` | Limit order cell management | Active development |
-| `@ickb/core` | iCKB core protocol logic (deposits, receipts, owned owner) | Active development |
-| `@ickb/sdk` | High-level SDK composing all packages | Active development |
+| `@ickb/dao`   | Nervos DAO abstraction layer                                               | Active development |
+| `@ickb/order` | Limit order cell management                                                | Active development |
+| `@ickb/core`  | iCKB core protocol logic (deposits, receipts, owned owner)                 | Active development |
+| `@ickb/sdk`   | High-level SDK composing all packages                                      | Active development |
 
 **Apps migration status:**
 
-| App | Purpose | Stack |
-|---|---|---|
-| `apps/faucet` | Testnet CKB distribution | **Migrated** to new packages + CCC |
-| `apps/sampler` | iCKB exchange rate sampling | **Migrated** to new packages + CCC |
-| `apps/bot` | Automated order matching | Legacy (`@ickb/v1-core` + Lumos) |
-| `apps/tester` | Order creation simulator | Legacy (`@ickb/v1-core` + Lumos) |
-| `apps/interface` | React web UI | Legacy (`@ickb/v1-core` + Lumos) |
+| App              | Purpose                     | Stack                              |
+| ---------------- | --------------------------- | ---------------------------------- |
+| `apps/faucet`    | Testnet CKB distribution    | **Migrated** to new packages + CCC |
+| `apps/sampler`   | iCKB exchange rate sampling | **Migrated** to new packages + CCC |
+| `apps/bot`       | Automated order matching    | Legacy (`@ickb/v1-core` + Lumos)   |
+| `apps/tester`    | Order creation simulator    | Legacy (`@ickb/v1-core` + Lumos)   |
+| `apps/interface` | React web UI                | Legacy (`@ickb/v1-core` + Lumos)   |
 
 **Key upstream contributions:** UDT and Epoch support were contributed to CCC upstream and have been merged. Some local utilities may overlap with features now available natively in CCC.
 
@@ -58,10 +58,10 @@ graph TD;
 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:
 
 ```bash
-git clone <repo-url> && cd stack && pnpm install
+git clone git@github.com:ickb/stack.git && cd stack && pnpm install
 ```
 
-To redo the setup from scratch: `rm -rf ccc-dev/ccc && pnpm install`.
+To redo the setup from scratch: `pnpm ccc:clean && pnpm install`.
 
 See [ccc-dev/README.md](ccc-dev/README.md) for recording new pins, developing CCC PRs, and the full workflow.
 
@@ -80,12 +80,15 @@ This clones two repos into the project root (both are git-ignored and made read-
 
 ## Developer Scripts
 
-| Command | Description |
-|---|---|
-| `pnpm pr` | Open a GitHub PR creation page for the current branch. Uses Claude to auto-generate title and body when available, falls back to branch name and commit log. |
-| `pnpm review` | Fetch and display PR review comments from GitHub for the current branch (or `pnpm review -- --pr <number>` for a specific PR). |
-
-> **Note:** `gh` CLI is not available in this environment. Use `pnpm pr` and `pnpm review` instead.
+| 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.     |
 
 ## Epoch Semantic Versioning
 

ccc-dev/README.md

@@ -10,7 +10,7 @@ CCC has unreleased branches (`releases/next`, `releases/udt`) that this project
 
 2. **Workspace override** — When `ccc-dev/ccc/` is present, `.pnpmfile.cjs` auto-discovers all CCC packages and rewrites `@ckb-ccc/*` dependencies to `workspace:*` — no manual `pnpm.overrides` needed. This is necessary because `catalog:` specifiers resolve to a semver range _before_ pnpm considers workspace linking — even with `link-workspace-packages = true`, pnpm fetches from the registry without this hook. When CCC is not cloned, the hook is a no-op and deps resolve from the registry normally.
 
-3. **Source-level types** — `patch.sh` (called by both `record.sh` and `replay.sh`) patches CCC's `package.json` exports to point TypeScript at `.ts` source instead of built `.d.ts`. This gives real-time type feedback when editing across the CCC/stack boundary — changes in CCC source are immediately visible to stack packages without rebuilding.
+3. **Source-level types** — `patch.sh` (called by both `record.sh` and `replay.sh`) patches CCC's `package.json` exports to point TypeScript at `.ts` source instead of built `.d.ts`, then creates a deterministic git commit (fixed author/date) so record and replay produce the same `pins/HEAD` hash. This gives real-time type feedback when editing across the CCC/stack boundary — changes in CCC source are immediately visible to stack packages without rebuilding.
 
 4. **Diagnostic filtering** — `ccc-dev/tsc.mjs` is a tsc wrapper used by stack package builds. Because CCC `.ts` source is type-checked under the stack's stricter tsconfig (`verbatimModuleSyntax`, `noImplicitOverride`, `noUncheckedIndexedAccess`), plain `tsc` would report hundreds of CCC diagnostics that aren't real integration errors. The wrapper emits output normally and only fails on diagnostics from stack source files. When CCC is not cloned, packages fall back to plain `tsc`.
 
@@ -33,7 +33,7 @@ Recording captures the current upstream state and any conflict resolutions:
 pnpm ccc:record
 ```
 
-This runs `ccc-dev/record.sh` which clones CCC, merges the configured refs, uses Claude CLI to resolve any conflicts, patches for source-level type resolution, and writes `pins/`. Commit the resulting `ccc-dev/pins/` directory so other contributors get the same build.
+This runs `ccc-dev/record.sh` which clones CCC, merges the configured refs, uses AI Coworker to resolve any conflicts, patches for source-level type resolution, and writes `pins/`. Commit the resulting `ccc-dev/pins/` directory so other contributors get the same build.
 
 The `ccc:record` script in `package.json` is preconfigured with the current refs:
 
@@ -61,7 +61,7 @@ bash ccc-dev/record.sh 268 releases/next
 bash ccc-dev/record.sh abc1234
 ```
 
-Refs are merged sequentially onto a `wip` branch, then CCC is built. On merge conflicts, the script auto-resolves them using Claude.
+Refs are merged sequentially onto a `wip` branch, then CCC is built. On merge conflicts, the script auto-resolves them using AI Coworker.
 
 ## Developing CCC PRs
 
@@ -96,15 +96,17 @@ git checkout wip  # return to development
 
 ## Switching modes
 
+**Check for pending work:** `pnpm ccc:status` — exit 0 if `ccc-dev/ccc/` matches pinned state (safe to wipe), exit 1 otherwise.
+
 **Local CCC (default when `pins/` is committed):** `pnpm install` auto-replays pins and overrides deps.
 
 **Published CCC:** `pnpm ccc:reset && pnpm install` — removes clone and pins, restores published packages.
 
-**Re-record:** `pnpm ccc:record` wipes and re-records everything from scratch.
+**Re-record:** `pnpm ccc:record` wipes and re-records everything from scratch. Aborts if `ccc-dev/ccc/` has pending work.
 
 **Force re-replay:** `pnpm ccc:clean && pnpm install` — removes clone but keeps pins, replays on next install.
 
 ## Requirements
 
-- **Recording** (`pnpm ccc:record`): Requires [Claude CLI](https://www.npmjs.com/package/@anthropic-ai/claude-code) for automated conflict resolution (only when merging refs).
+- **Recording** (`pnpm ccc:record`): Requires the AI Coworker CLI (installed as a devDependency; invoked via `pnpm coworker:ask`) for automated conflict resolution (only when merging refs).
 - **Replay** (`pnpm install`): No extra tools needed — works for any contributor with just pnpm.

ccc-dev/patch.sh

@@ -2,9 +2,10 @@
 set -euo pipefail
 
 # Patch a CCC clone for use in the stack workspace.
-# Usage: ccc-dev/patch.sh <ccc-repo-dir>
+# Usage: ccc-dev/patch.sh <ccc-repo-dir> <merge-count>
 
-REPO_DIR="${1:?Usage: patch.sh <ccc-repo-dir>}"
+REPO_DIR="${1:?Usage: patch.sh <ccc-repo-dir> <merge-count>}"
+MERGE_COUNT="${2:?Missing merge-count argument}"
 
 # Remove CCC's own lockfile so deps are recorded in the root pnpm-lock.yaml
 rm -f "$REPO_DIR/pnpm-lock.yaml"
@@ -24,3 +25,11 @@ for pkg_json in "$REPO_DIR"/packages/*/package.json; do
       else . end
     ) else . end' "$pkg_json" > "$pkg_json.tmp" && mv "$pkg_json.tmp" "$pkg_json"
 done
+
+# Commit patched files with deterministic identity so record and replay produce the same hash
+export GIT_AUTHOR_NAME="ci" GIT_AUTHOR_EMAIL="ci@local"
+export GIT_COMMITTER_NAME="ci" GIT_COMMITTER_EMAIL="ci@local"
+PATCH_TS="@$((MERGE_COUNT + 1)) +0000"
+export GIT_AUTHOR_DATE="$PATCH_TS" GIT_COMMITTER_DATE="$PATCH_TS"
+git -C "$REPO_DIR" add -A
+git -C "$REPO_DIR" commit -m "patch: source-level type resolution"

ccc-dev/pins/HEAD

@@ -1 +1 @@
-c6eb9a0aeb74f91b5fceedd56dde418ed71d151e
+ddd976a81f71d14135714a2b365cb6e3653126fc