ai-collab-open-system 0.1.0

package/README.md

@@ -0,0 +1,245 @@
+# AI Collaboration Open System
+
+Does your AI keep saying "done" when it is not? This is an **open-source personal AI collaboration workspace** — a thin discipline pack you drop into the AI you already use (Claude, Cursor, Codex, and others). It does not write your code and does not think for you. It does one thing: it makes your AI prove a "done" claim with evidence, gets a second AI to re-check it, and lets you switch tools or pick the work up tomorrow without re-explaining the background. Why a workspace beats a better prompt: [docs/WHY_THIS_EXISTS.md](./docs/WHY_THIS_EXISTS.md). New here? Start at [START_HERE.md](./START_HERE.md).
+
+> Runs today from a clone (`node bin/ai-collab.js`); the npm package and global `ai-collab` command are not published yet — see [Release Status](#release-status).
+
+中文：你的 AI 是不是老跟你说"搞定了"，其实没做完？这是一套塞进你现有 AI（Claude、Cursor、Codex 等）的开源"协作纪律包"。它不替你写代码、不替你想，只干一件事：让 AI 说"做完了"前先拿证据自证、让另一个 AI 复核一遍、让你换工具或隔天再接着干时不用重讲背景。为什么是工作区而不是提示词，见 docs/WHY_THIS_EXISTS.md；新手从 START_HERE.md 开始。
+
+## See it in one glance
+
+Here is the same messy request, before and after. Messy input:
+
+```text
+I need this task board cleaned up. Add drag-and-drop, maybe keyboard support,
+make it prettier, keep tests passing, and don't rewrite too much. Last chat
+already changed things but I forgot what.
+```
+
+Raw AI output usually says:
+
+```text
+Sure. I will refactor the board, improve drag and drop, add keyboard support,
+modernize the UI, and update tests.
+```
+
+This workspace turns the same input into:
+
+```text
+Context: current slice is reorder behavior; visual redesign is out of scope.
+Acceptance: existing data survives; drag and keyboard reorder both need tests.
+Guard: reject completion until keyboard movement has evidence.
+Handoff: mouse and keyboard reorder done and tested, guard accepted; only visual polish unverified.
+Harvest: long coding tasks need acceptance before implementation and guard before handoff.
+```
+
+That is the value: less smooth guessing, more visible state. This is a local AI collaboration workspace made of plain files, not a prompt pack: it carries task state (context, acceptance, guard, handoff, harvest), not just better one-off instructions.
+
+## Run it in 2 minutes
+
+One main path. Clone, init a workspace, then open the 10-minute walkthrough — that is the whole on-ramp.
+
+> The package is not on npm yet, so the commands below use the local CLI entry `node bin/ai-collab.js`. After the npm package ships, the same commands work under the global `ai-collab` name (e.g. `ai-collab init ...`); until then, keep using `node bin/ai-collab.js`.
+
+```bash
+git clone https://github.com/aaronyi97/ai-collab-open-system.git
+cd ai-collab-open-system
+node bin/ai-collab.js init --target ./my-ai-workspace
+```
+
+Now open `./my-ai-workspace/.aict/walkthroughs/10-minute-your-task.md`. In 10 minutes you will feel three things on your own task: **the AI defines *done* before it touches the work**, an **independent re-check pressure-tests the "completed" claim against the evidence — passing, rejecting, or flagging insufficient evidence depending on what the evidence shows**, and **task state stops living only in the chat scroll** (it sits in plain files you can reopen, hand off, and resume).
+
+(To open the file: macOS `open <file>` · Linux `xdg-open <file>` · Windows `start <file>`. `init` writes a local `.aict/` workspace of plain files; it does not use the network.)
+
+### Or taste it with zero install (60 seconds)
+
+Not ready to clone? Open the AI you already use, think of one real task that is a bit messy, and paste this:
+
+```text
+I have a task in front of me that's a bit messy. Before writing any implementation, do this:
+Task (redacted — replace any private name/path/number with a placeholder): [your one-paragraph plain-language description]
+1) Boundary card: this slice does only X; explicitly list what is NOT in scope.
+2) Acceptance card: a numbered list of hard, checkable standards (AC1, AC2, ...), and mark anything that would be out of scope.
+Do not start the work yet — just return the boundary card and the acceptance card.
+```
+
+That is the first move of the loop — the AI defines *done* before it acts, on your own task. To make it repeatable across tools and sessions (saved as local files), run the 2-minute path above. The full three-step loop (boundary → build → independent re-check) is in the [10-Minute Experience](#10-minute-experience) below.
+
+## Start with one AI
+
+One AI is enough to start — you do not need two tools. With a single AI, this system turns "the AI said it's done" into a result that has evidence, can be re-checked, handed off, and harvested. That alone is most of the value; the single-tool guard runs a real adversarial review (a fresh conversation + a reviewer prompt) instead of trusting the same assistant that just wrote it. This is the front door, not a downgrade. Adding a second, different model family makes the re-check stronger — an independent review a single tool cannot give itself — but that is the ceiling, not the entry bar. (How the guard levels are computed, and why a single tool's cross-family claim is marked unverified, is in the [Commands](#commands) section and `--help`.)
+
+For the full public-system explanation, read [docs/open-system/00-start-here.md](./docs/open-system/00-start-here.md). For privacy and source-to-public rewriting, read [docs/PUBLIC_MAPPING.md](./docs/PUBLIC_MAPPING.md).
+
+中文：一个AI也能开始：先把"做完了"变成有证据、可复核、可交接、可沉淀的结果。这就是大部分价值。有第二个模型族时，可以升级成跨族双守卫。那是一个单工具给不了自己的独立复核。守卫等级怎么算、为什么单工具自称的跨族复核会被标成"未验证"，见下面 Commands 和 --help。
+
+## First Run (keep the workspace as local files)
+
+This is the same `init` as the 2-minute path, with the cross-platform openers spelled out. You only need it if you want the workspace saved locally so the same rules drive every tool and survive across sessions:
+
+```bash
+node bin/ai-collab.js init --target ./my-ai-workspace
+# then open these two files in your editor — pick your platform's opener:
+#   macOS:   open ./my-ai-workspace/.aict/START_HERE.md
+#   Linux:   xdg-open ./my-ai-workspace/.aict/START_HERE.md
+#   Windows: start .\my-ai-workspace\.aict\START_HERE.md
+# (then the same for ./my-ai-workspace/.aict/walkthroughs/10-minute-your-task.md)
+```
+
+`init` writes a local `.aict/` workspace of plain files. Network: not used at runtime. If you ran this inside a clone of *this* repo, the generated `my-ai-workspace/` is already in our `.gitignore`, so it will not show up as untracked files or dirty your `git status`. Next, take the 10-minute first experience below: the main path runs the loop on *your own* real task; if you would rather watch the flow on a prepared example first, the demo preview (`.aict/walkthroughs/10-minute.md`) is the optional second path.
+
+### What the first conversation looks like
+
+Once the workspace is installed, the rules **instruct** your AI to open the first conversation proactively, rather than waiting to be asked: introduce itself, offer to take ~30 seconds to scan your recent work, and state the privacy boundary *before* scanning (the scan is run by the cloud AI you already use, so its content passes through your provider like any normal chat — this is **not** "zero data leaves your machine"; the `ai-collab` tool itself sends nothing). You stay in control: answer "yes", "just the X project", or "not now". Whether the AI actually opens this way depends on your tool loading this rule — some tools follow workspace instructions more eagerly than others. If you would rather drive it yourself, run `node bin/ai-collab.js bootstrap --yes` for the same read-only baseline at any time.
+
+中文：装好工作区后，这套规则会**指示**你的 AI 在第一次对话时主动开口（而不是等你问）：先自我介绍、提出花约 30 秒扫一眼你最近的活，并在扫描**之前**说清隐私边界——扫描是由你本来就在用的那个云端 AI 执行的，内容会像平常聊天一样经过你的服务商，所以这**不是**「零数据离开你的机器」；`ai-collab` 工具本身不向任何第三方发送东西。主动权在你：回「好」「只看 X 项目」或「先不要」。AI 是否真的这样开口，取决于你的工具有没有加载这条规则——有的工具比别的更听工作区指令。想自己来，随时跑 `node bin/ai-collab.js bootstrap --yes` 拿同样的只读基线。
+
+## 10-Minute Experience
+
+Two ways in. Pick one.
+
+### Path 1 (recommended): run the loop on your own real task
+
+This is the fast way to feel why it matters: you watch the discipline work on *your* task, and an independent AI catch a thin "done" on something you actually care about.
+
+1. Run `node bin/ai-collab.js init --target ./my-ai-workspace`.
+2. Open `./my-ai-workspace/.aict/walkthroughs/10-minute-your-task.md` and follow its five steps.
+3. You describe one real (lightly redacted) task and the AI returns a boundary card and an acceptance card — *done* defined before any work.
+4. You let it do only the accepted slice and report what it changed, ran, and did not verify.
+5. You open a fresh chat (ideally a different AI brand) and have it re-check the result against evidence — watch it pressure-test the "done" claim and either pass it, reject it, or flag insufficient evidence, depending on what the evidence shows rather than the tone.
+
+### Path 2: watch the prepared demo first
+
+Pick this if your task feels too sensitive to paste right now, or you just want to see what the flow looks like before running it on your own work.
+
+1. Run the same `init` as above.
+2. Open `./my-ai-workspace/.aict/walkthroughs/10-minute.md` (the demo preview) and follow its five steps.
+3. It walks you through the prepared `examples/ai-coding-long-task/CASE.md` and its artifacts.
+4. You copy the context, acceptance, and execution prompt into your AI tool.
+5. You run guard review and watch it catch a false "done" the prepared case plants — then come back and run Path 1 on your own task.
+
+中文路径：两条路任选其一。**路 1（推荐）跑你自己的真实任务**：跑 `node bin/ai-collab.js init --target ./my-ai-workspace`（发布到 npm 后才能用全局 `ai-collab`），打开 `.aict/walkthroughs/10-minute-your-task.md`，把你手头一个（脱敏的）真实乱任务丢进去，看 AI 先给边界卡和验收卡（先把“做完”定义清楚），再只做验收卡里的那一小块，最后你新开一个对话（最好换个牌子的 AI）逼它拿证据复核——它会拿证据压你的“做完了”，可能放行、可能驳回、也可能判证据不足，取决于证据本身，而不是替你假设结论。**路 2 先看演示**：怕任务敏感、或想先看流程长啥样，就先打开 `.aict/walkthroughs/10-minute.md`（演示预览版）走旗舰案例，再回来跑路 1。
+
+### Optional: prove it is the discipline, not the model (two-track comparison)
+
+Want hard proof the structure is doing the work, not just a smarter model? After Path 1, run the same task a second way with no discipline and compare:
+
+1. **Track A — no discipline.** Paste your messy one-paragraph task straight into the AI with no structure and ask it to just do it. Screenshot the smooth "Sure, I'll do X, Y, Z" reply — that smooth line is your real before-evidence, generated on your own task.
+2. **Track B — with the loop.** This is just Path 1 above (boundary → build → independent re-check).
+3. **Put them side by side.** Ask the AI to lay both tracks into one table with four rows: *scope*, *definition of done*, *completion claim*, *what would have been missed*. The point lands when you see, on your own work, how thin Track A's "done" was.
+
+Want to try it on your own work and tell us what happened? See the [Dogfood Guide](./docs/DOGFOOD.md) (who it is for, 10-minute and 30-minute paths, and — importantly — what *not* to upload), then report back through [docs/FEEDBACK.md](./docs/FEEDBACK.md). Feedback collects your experience, never your private material.
+
+## 60-Minute Setup
+
+1. Fill a light profile for how you want AI to collaborate.
+2. Fill one context package for a real task, with private details redacted.
+3. Define acceptance before asking for output.
+4. Use your tool adapter or install guidance files with `node bin/ai-collab.js adapters install --target <repo>`.
+5. Run a guard review on the first artifact.
+6. Write a handoff note.
+7. Extract one harvest seed for future reuse.
+
+## Commands
+
+Before publish, run every command as `node bin/ai-collab.js <args>` from a clone. After the package is published to npm, the same commands work under the global `ai-collab` name shown here:
+
+```bash
+node bin/ai-collab.js init --target ./my-ai-workspace
+node bin/ai-collab.js init --target ./my-ai-workspace --dry-run
+node bin/ai-collab.js guide
+node bin/ai-collab.js demo
+node bin/ai-collab.js check --workspace ./my-ai-workspace
+node bin/ai-collab.js adapters install --target ./my-repo
+npm run check
+```
+
+Once a workspace exists, operate the loop on a real task with the **run layer** — these are the commands that actually produce the evidence, receipts, and guard levels this README is about (omit `--workspace` to use `./.aict` here; a state command refuses if no workspace exists rather than scattering files):
+
+```bash
+node bin/ai-collab.js task create   --title "Fix the flaky reorder test" --workspace ./my-ai-workspace/.aict
+node bin/ai-collab.js run start      --task t1 --command "npm test"        --workspace ./my-ai-workspace/.aict
+node bin/ai-collab.js run finish     --task t1 --exit 0                    --workspace ./my-ai-workspace/.aict
+node bin/ai-collab.js evidence add   --task t1 --kind output --summary "npm test -> exit 0, suite green" --workspace ./my-ai-workspace/.aict
+node bin/ai-collab.js receipt create --task t1 --verdict pass_with_risk --review-mode self --evidence e2 --workspace ./my-ai-workspace/.aict
+node bin/ai-collab.js receipt accept --id c1 --owner you                  --workspace ./my-ai-workspace/.aict
+node bin/ai-collab.js status                                              --workspace ./my-ai-workspace/.aict
+```
+
+Run that and the receipt prints `guardLevel: L2 (computed)` — exactly the single-tool ceiling described next. (Cite only a bare `--kind note` instead and it computes `L1`, which cannot pass; you need run/output evidence to reach L2.)
+
+The guard level (L0–L4) is **computed from the evidence you cite, never self-asserted**: a single tool tops out at L2 (`pass_with_risk`); a plain `pass` needs an L3+ review from a *different* model family; and L4 needs **both** that cross-family review **and** a rerun reconciled to a recorded run — a reconciled rerun on its own is just the author re-running their own command, so it stays L2. Use `run exec` to actually run a command and record its **real** exit code (`run start/finish` only record an exit you report). **Safety: `run exec` runs a real shell command locally — read the command first, especially if an AI suggested it.** A receipt records *who claimed what* — it is a local audit trail, **not** a cryptographic proof or an independent-execution guarantee (the cross-family family label is self-declared; the tool runs locally and cannot verify it). The full ladder is in `node bin/ai-collab.js --help`.
+
+`demo` is a no-setup preview: it writes a throwaway workspace into a new temporary directory so you can see the layout without touching your project. In a strictly read-only environment that temp write can fail; use `init --target <writable-dir>` instead. `init` writes to a directory you choose and is what you keep.
+
+## What You Get
+
+This is a collaboration operating system, not a prompt collection. What makes it one is the chains it carries, not how many prompts ship inside it:
+
+- **A visible task-state chain**: context -> acceptance -> guard -> handoff -> harvest, as plain files, so work has inspectable state instead of living in a chat scroll.
+- **A handoff chain** (handoff A/B/C): any session or tool resumes from where the work actually is, instead of you re-explaining the background each time.
+- **A review chain** (dual guard + SCOUT review controller + half-product review): output gets challenged for evidence before it is trusted, and a confident "done" with no runnable proof gets caught.
+- Six collaboration layers behind that chain: profile, context, acceptance, guard review, handoff, harvest.
+- 16 mechanism packages that operate the chains: dual guard, SCOUT review controller, one-click dispatch, task splitting, anti-drift partner, blind-spot scan, root-cause brake, half-product review, handoff A/B/C, harvest and external recap, do-not-handle-yet, plain-language first screen, honest calibration, feedback-absorption ledger, collaboration coach, and single-tool guard.
+- A complete `.aict/` workspace with `START_HERE.md` and public OS directories: profile, context, acceptance, guard, handoff, harvest, roles, modes, mechanisms, examples, cookbook, and state.
+- Adapter guidance files so common AI tools all work off one shared contract instead of six drifting rule sets.
+- A flagship synthetic case plus additional synthetic cases, and privacy / commercial-boundary docs.
+- The reusable prompt and skill library that powers the above (11 distinct prompts for different workflow moments; 10 distinct skills with process, output, and safety rules) — the count is the supply, the chains above are the point.
+- Contract checks that prevent the project from drifting back into a thin prompt pack.
+
+## Honesty Boundary
+
+- This is not a hosted assistant.
+- This is not an autonomous agent framework.
+- We do not disguise a single-tool self-review as a cross-family pass. The guard level is computed from evidence, not self-asserted: a single tool tops out at L2 (pass-with-risk); a plain pass requires L3+ with a different model family. 中文：我们不会把单工具自审伪装成跨族通过。
+- Adapter files are guidance, not deep integration with every tool.
+- The CLI does not call external AI APIs, upload content, or run telemetry.
+- Known limitations are documented honestly, not hidden — e.g. concurrent writes to one workspace can produce a duplicate ledger id (rare for a single local user), which `check` catches after the fact. See [KNOWN_LIMITATIONS.md](./KNOWN_LIMITATIONS.md).
+- Paid help, if offered by a maintainer, may calibrate the generic system for a real workflow, but the open method is complete enough to self-run. The open method is never gated behind payment; paid help is only calibration / setup / migration / review / pairing. See [docs/FREE_VS_PAID.md](./docs/FREE_VS_PAID.md).
+
+## Release Status
+
+This project moves through four explicit release states. Being honest about which one we are
+in is part of the product: the docs must never describe a step that has not happened yet as if
+it already has.
+
+| State | Meaning | Reached? | What it means for you (plain language) |
+| --- | --- | --- | --- |
+| **local candidate** | Built and verified on a local machine; committed to git locally. | Yes | (Superseded.) The earliest state; the source is now on GitHub. |
+| **publishable candidate** | All release checks green, packed tarball install-smoke passes, version/CHANGELOG prepared. | Yes | (Superseded.) The quality bar was met before the source was pushed. |
+| **GitHub source release** | Pushed to the public GitHub repo; CI green on the pushed commit. Not git-tagged yet. | **Current** | You can `git clone` it from GitHub and run `node bin/ai-collab.js`. There is **no** `npm install` and no global `ai-collab` command yet, and no version tag. |
+| **npm package** | Published to npm via `npm publish`. | No | Only then does `npm install -g ai-collab-open-system` (the package name) install the global `ai-collab` command so it works as written elsewhere in this README. |
+
+**The source is on GitHub and CI is green, but it is still not an npm package.** The code,
+privacy, and packaging checks (`npm test`, `npm run check`, `npm pack --dry-run`) all pass on the
+pushed `main`, and CI is green. What has **not** happened: a git version tag, and the actual
+`npm publish`. "Release-ready" is a quality bar, not a release event, so no doc here claims an
+`npm install` works today.
+
+Everywhere this README (or `ai-collab guide`/`--help`) shows a global `ai-collab ...` command or an
+`npm install`, read it as **"available after the npm package state"**. Until then the working
+command is `node bin/ai-collab.js <args>` from a clone.
+
+The exact remaining steps that move this from the current **GitHub source release** to an **npm
+package** (tag, publish, post-publish verification) are listed in
+[RELEASE_CHECKLIST.md](./RELEASE_CHECKLIST.md).
+
+## Release Checks
+
+```bash
+npm test
+npm run check
+npm pack --dry-run
+```
+
+See [PRODUCT_CONTRACT.md](./PRODUCT_CONTRACT.md), [docs/PUBLIC_BOUNDARY.md](./docs/PUBLIC_BOUNDARY.md), and [privacy-manifest.json](./privacy-manifest.json).
+
+## How this fits with Spec Kit / BMAD / AGENTS.md
+
+This is a **collaboration discipline + state layer**, not a development methodology or an agent framework. It complements, rather than replaces, tools like Spec Kit, BMAD, or an `AGENTS.md`: keep using those to plan and drive the work; this adds the evidence, guard, handoff, and harvest layer that makes a "done" claim checkable and resumable across tools and sessions.
+
+## Contact
+
+- Security issues: see [SECURITY.md](./SECURITY.md) (private channel).
+- General: **X/Twitter** [@AaronYiaazw](https://x.com/AaronYiaazw) · **Email** yi19970319@gmail.com
+- Source & issues: https://github.com/aaronyi97/ai-collab-open-system

package/RELEASE_CHECKLIST.md

@@ -0,0 +1,78 @@
+# Release Checklist
+
+Use this before labeling a commit as a public release candidate, and to move it through the
+release states. The four states are defined in [README Release Status](./README.md#release-status):
+**local candidate → publishable candidate → GitHub source release → npm package**.
+
+Current state of `main`: **GitHub source release** (pushed to GitHub, CI green; not git-tagged,
+not npm-published). All automated gates are green (`npm test`, `npm run check` — contract +
+privacy + pack — and `npm pack --dry-run`) and the changes have been reviewed. "Release-ready" is
+a quality bar, not a release event: the source is on GitHub, but it moves to an **npm package**
+only when the maintainer performs the tag + publish steps below. The remaining boxes are those
+publish actions, which have not been run yet.
+
+## Required local checks
+
+- [ ] `npm ci` (reproducible install from the committed `package-lock.json`)
+- [ ] `npm test`
+- [ ] `npm run check` (test + contract + privacy + pack)
+- [ ] `npm pack --dry-run`
+
+## Fresh-tarball install smoke
+
+Mirrors the CI `Tarball install smoke` job. The point is to prove the *packed artifact* installs
+and the *installed* `ai-collab` bin runs — not just that the source tree runs.
+
+- [ ] `npm pack` to produce `ai-collab-open-system-<version>.tgz`.
+- [ ] In a clean temp dir, `npm init -y` then `npm install <path-to-tgz>`.
+- [ ] Confirm `node_modules/.bin/ai-collab` exists and resolves to the package bin.
+- [ ] Run the installed bin (e.g. `./node_modules/.bin/ai-collab ...`), each must exit 0:
+  - [ ] `ai-collab init --target <dir> --force`
+  - [ ] `ai-collab guide`
+  - [ ] `ai-collab demo`
+  - [ ] `ai-collab check --workspace <dir>/.aict`
+- [ ] (Pre-publish, the documented user path is `node bin/ai-collab.js <cmd>` from a clone; CI also
+      smoke-tests that source entry. The global `ai-collab` name only works after the npm-package state.)
+
+## Product surface
+
+- [ ] README first screen shows messy input -> structured result.
+- [ ] README Release Status section states the honest current state, and global `ai-collab` /
+      `npm install` mentions are marked "after publish".
+- [ ] Generated `.aict/START_HERE.md` supports both 10-minute experience and 60-minute setup.
+- [ ] The flagship case includes `raw-input`, `baseline-output`, `system-run`, `artifacts`, `comparison`, and `next-step`.
+- [ ] Other cases contain enough detail to run and review, not one-line filler.
+- [ ] Prompt and skill similarity tests pass.
+
+## Safety and honesty
+
+- [ ] `--force` backs up existing `.aict` content before replacement.
+- [ ] Adapter files are called adapter guidance, not deep integration.
+- [ ] No claim says the CLI automatically understands a user's real business.
+- [ ] No doc states an unreached release step as already done (no false "published to npm",
+      no live `npm install ai-collab` as if it works today).
+- [ ] CHANGELOG shows the current version as unreleased (GitHub source, CI green; not npm-published) with no fake release date.
+- [ ] No private source material, local personal paths, tokens, email addresses, customer data, or private governance content are present.
+- [ ] Privacy scan passes on the source tree and generated workspace.
+- [ ] **Maintainer ran the privacy scan with their LOCAL override active.** The shipped `privacy-manifest.json` deliberately contains only generic, anyone-applies markers — it does NOT list this maintainer's own private directory names (e.g. a personal governance folder or knowledge base), because the manifest itself is published and listing them would leak the very names we are protecting. Those names live ONLY in the gitignored `privacy-scan.local.json` (copy `privacy-scan.local.json.example`, fill in the real folder names under `paths`). Before publishing, confirm that file exists and run `npm run privacy:scan` once with it in place, so any stray reference to your private dirs is caught and blocked from the tarball. Verify (and re-confirm after the run) that `privacy-scan.local.json` is still gitignored and is NOT staged/committed — it must never ship.
+
+## From GitHub source release to npm package
+
+These are the steps (and their state gates) that take this repo from earliest build all the way to
+a published **npm package**. Each step is also a re-verification point. Steps 1 and 2 (through the
+current **GitHub source release**) are done except git-tagging; the remaining work is the tag plus
+the npm publish in step 3.
+
+1. **local candidate → publishable candidate** (done)
+   - [x] All "Required local checks", "Fresh-tarball install smoke", and "Safety and honesty" boxes above are green.
+   - [x] Decide the version. If it changes, update `version` in `package.json` and `package-lock.json`, and add a dated CHANGELOG entry.
+   - [x] Working tree clean; no stray `*.tgz` or `*.aict-backup-*` / `.aict.backup-*` artifacts tracked (they are gitignored).
+2. **publishable candidate → GitHub source release** (done except tag)
+   - [x] `git push` the release commit to the public GitHub repo.
+   - [x] Confirm CI is green on the pushed commit (matrix + tarball install smoke + CLI smoke).
+   - [ ] `git tag v<version>` and `git push --tags` (or create a GitHub Release for the tag).
+3. **GitHub source release → npm package**
+   - [ ] Confirm npm auth (`npm whoami`) and that the `name`/`version` are publishable (not already taken/published).
+   - [ ] `npm publish` (consider `npm publish --dry-run` first; the package is public, Apache-2.0).
+   - [ ] Post-publish: in a clean dir, `npm install -g ai-collab-open-system` (the package name) and verify the global `ai-collab init/guide/demo/check` command all work.
+   - [ ] Only after this step do README/CHANGELOG statements about the global `ai-collab` command and `npm install` become literally true; update the Release Status table to mark **npm package** reached and set the CHANGELOG release date.

package/SECURITY.md

@@ -0,0 +1,56 @@
+# Security Policy
+
+## Local-first boundary
+
+The CLI does not call external AI APIs, upload user content, scan the whole disk, go online, or install hooks without consent.
+
+One command runs code by design: `ai-collab run exec --task <id> --command "..."` executes the command **you** supply, in your own shell, **locally** (to record a real exit code) — exactly like a task runner. It never runs anything you did not pass it, and it still does not go online. The `run start` / `run finish` commands do **not** execute anything — they only record a command and exit code you report.
+
+### Dangerous-command guard (`run exec`)
+
+`run exec` adds a conservative, deliberately **narrow** safety check. A small set of well-known destructive command shapes trips a guard before anything runs:
+
+- `rm -rf` / `rm -fr` (recursive force delete)
+- `sudo ` (privilege escalation)
+- a fork bomb (`:(){ ... }`)
+- a network download piped straight into a shell (`curl ... | sh`, `wget ... | bash`)
+- `dd ` (raw disk write) and `mkfs` (format a filesystem)
+- a redirect into a `/dev/` device node (e.g. `> /dev/sda`; harmless sinks like `>/dev/null` are excluded)
+- `chmod -R 777` (world-writable, recursive)
+- a redirect (`>`/`>>`) into a **system path** (`/etc`, `/usr`, `/bin`, `/sbin`, `/boot`, `/lib`, …)
+
+When a command matches:
+
+- **On an interactive terminal**, the CLI prints the matched pattern(s) and the command, then asks `[y/N]`. The default is **N** — pressing Enter (or anything other than `y`/`yes`) declines, and **nothing is executed and nothing is recorded**.
+- **Without an interactive terminal** (a script, CI, or an AI calling the CLI), the command is **refused** outright. Pass `--yes` (or `--force`) to run it anyway.
+
+Ordinary commands are **rarely** affected — narrow false positives are possible, and `--yes` (or `--force`) always overrides. The guard ignores a danger word that is quoted as data (`echo 'rm -rf ...'`) or used as an argument rather than the command being run (`grep sudo file`), so common cases do not trip it; if no pattern matches, behavior is exactly as before. A knowingly-approved dangerous run is recorded with `dangerousConfirmed: true` so the ledger shows it was confirmed on purpose. The guard is intentionally narrow to avoid false alarms; it is a speed bump for the obviously-destructive case, **not** a sandbox — always read a command (especially an AI-suggested one) before running it.
+
+## Reporting
+
+Please report security issues **privately** — do not open a public issue or publish exploit details. Use either private channel:
+
+- **GitHub Security Advisory** (preferred): open a draft advisory at
+  https://github.com/aaronyi97/ai-collab-open-system/security/advisories/new
+- **Email**: yi19970319@gmail.com (X/Twitter: https://x.com/AaronYiaazw)
+
+Please allow a few days for an acknowledgement. This is a local-first tool with no
+server and no telemetry, so most reports will concern the CLI's file writes,
+packaging, or the privacy scanner.
+
+## Sensitive material
+
+Never include:
+
+- Tokens, keys, cookies, or credentials.
+- Local machine paths.
+- Raw private conversations.
+- Actual client material.
+- Non-public automation or tool-routing details.
+- Unredacted screenshots.
+
+Run:
+
+```bash
+node scripts/privacy-scan.js
+```

package/START_HERE.md

@@ -0,0 +1,89 @@
+# START_HERE
+
+This is the repository entry point — how to start. (Different file from the workspace map: once you run `init`, the generated `./my-ai-workspace/.aict/START_HERE.md` is *your own workspace's* map. This root file gets you there; that one navigates what you built.)
+
+Give the AI you already use a thin collaboration discipline: it has to prove a "done" claim before you trust it, let a second AI re-check it, and let you switch tools or pick up tomorrow without re-explaining the background. It treats four process diseases of AI work: the chat that drifts off-task, the AI that says it finished when it did not, output you cannot trust, and the lesson you lose by tomorrow. It does not do the work for you, it does not go online, and it is not another AI assistant.
+
+中文：这是仓库入口（怎么开始）。注意和工作区地图不是同一个文件：你跑完 init 后，生成的 .aict/START_HERE.md 才是你自己工作区的地图——根目录这个文件带你进门，那个文件带你逛你建好的工作区。给你现有的 AI 装一套协作纪律：让它说“做完”前先自证、让另一个 AI 复核、换工具不用重讲背景。治四种病：聊跑偏、AI 假装做完、输出不敢信、经验留不住。不替你干活、不联网、不是新助手。
+
+This system is extracted from a long-running, real AI-collaboration practice. It does not replace your judgment with automation — it makes AI work visible: define done, guard against false completion, hand off context, harvest lessons, and grow a profile that makes the next round better. AI productivity is a product, not a sum (see docs/WHY_THIS_EXISTS.md) — this gives you the factors beyond the model itself.
+
+中文：这套体系抽取自长期真实的 AI 协作实践。它不是用自动化替你判断，而是让 AI 的工作显性化：定义“做完”、守住虚假完成、交接上下文、收割经验、积累一份让下一轮更准的画像。AI 生产力是乘法不是加法（见 docs/WHY_THIS_EXISTS.md）——这套给你模型本身之外的那些因子。
+
+## One AI is enough to start
+
+You do not need two tools to begin. With a single AI, the completion-claim check runs through `single-tool-guard`: a real adversarial review (a fresh conversation + a reviewer prompt) instead of trusting the same assistant that just wrote it. This is the front door, not a downgrade. Adding a second, different model family makes the re-check stronger (`dual-guard`) — an independent review a single tool cannot give itself — but it is the optional upgrade, not the entry bar. Don't have a second family yet? `.aict/cookbook/bridge-to-a-second-family.md` shows how to set one up (manual or auto). How the guard levels (L0–L4) are computed, and why a single tool's cross-family claim is marked unverified, is the honesty detail covered once you are inside the workspace and in the README's Commands section — not something you need before your first run.
+
+中文：一个 AI 也能开始：先把"做完了"变成有证据、可复核、可交接、可沉淀的结果。有第二个不同模型族时复核更强，但那是可选升级、不是入门门槛。守卫等级（L0–L4）怎么算、为什么单工具自称的跨族复核会被标成"未验证"，是进了工作区和 README Commands 里才需要看的诚实细节，第一次跑之前不用纠结。
+
+Start with the result, not the concept.
+
+The source is on GitHub (CI green), but the package is not published to npm yet. Run the CLI from a clone with `node bin/ai-collab.js`. The global `ai-collab` command shown in docs only works after the package is published.
+
+## 10 minutes
+
+Two ways in; pick one.
+
+**Path 1 (recommended) — run the loop on your own real task:**
+
+```bash
+node bin/ai-collab.js init --target ./my-ai-workspace
+# then open in your editor — macOS: open <file> · Linux: xdg-open <file> · Windows: start <file>
+#   ./my-ai-workspace/.aict/walkthroughs/10-minute-your-task.md
+```
+
+Follow the five steps in `.aict/walkthroughs/10-minute-your-task.md`. You describe one real (lightly redacted) task; the AI returns a boundary card and an acceptance card (done defined before any work); you let it do only the accepted slice; then you open a fresh chat — your own tool is enough to start, a different AI family is the optional upgrade — and have it re-check the result against evidence: it pressure-tests the "done" claim and either passes it, rejects it, or flags insufficient evidence, depending on what the evidence shows rather than the tone. This is the fast way to feel the value on work you actually care about.
+
+**Path 2 — watch the prepared demo first** (pick this if your task feels too sensitive to paste, or you want to see the flow first):
+
+```bash
+node bin/ai-collab.js init --target ./my-ai-workspace
+# then open in your editor — macOS: open <file> · Linux: xdg-open <file> · Windows: start <file>
+#   ./my-ai-workspace/.aict/walkthroughs/10-minute.md
+```
+
+Follow the five steps in `.aict/walkthroughs/10-minute.md` (the demo preview). It walks you through the prepared case `examples/ai-coding-long-task/CASE.md` and its artifacts in order: context -> acceptance -> first AI output -> guard -> revised -> handoff -> harvest, then catches a false "done" the case plants. After it, run Path 1 on your own task.
+
+Either way you should see why the system is different from a single raw AI chat: it keeps task state, acceptance, review, handoff, and reusable learning visible.
+
+Want the AI to remind you on its own — to ping you to review every time it claims "done", instead of you remembering? Install the adapter into your tool's always-on instructions with `node bin/ai-collab.js adapters install --target <repo>`. It turns on restrained coaching reminders; if you only use one tool, the completion-claim check routes through `single-tool-guard` (a fresh adversarial pass in the same tool).
+
+Then open `docs/open-system/00-start-here.md` in this repository if you want the full public-system explanation.
+
+> The file paths in the next two sections live **inside the generated workspace**, not in this repo. They do not exist until you run `node bin/ai-collab.js init --target ./my-ai-workspace` (see the 10-minute path above), which writes them under `./my-ai-workspace/.aict/`. Paths below are shown relative to that `.aict/` workspace root.
+
+## 30 minutes
+
+Adapt one layer to a current task (run `init` first, then work inside the generated `.aict/`):
+
+1. Fill `.aict/context/TEMPLATE.md` or `.aict/acceptance/TEMPLATE.md`.
+2. Open `.aict/adapters/SHARED_CORE_CONTRACT.md`.
+3. Paste the shared contract and your filled template into your AI tool.
+4. Ask for one guard review or handoff note.
+5. Save the artifact back into the workspace.
+
+## 60 minutes
+
+Run one real task through the loop (again, all paths are inside the generated `.aict/`):
+
+1. Fill `.aict/profile/TEMPLATE.md` lightly.
+2. Fill `.aict/context/TEMPLATE.md`.
+3. Fill `.aict/acceptance/TEMPLATE.md`.
+4. Ask your AI tool to execute only against that acceptance card.
+5. Run `.aict/guard/PROMPT.md`.
+6. Save `.aict/handoff/TEMPLATE.md`.
+7. Save one lesson in `.aict/harvest/TEMPLATE.md`.
+
+## What is inside `.aict`
+
+`init` generates the `.aict/` workspace; these directories do not exist in this repo until then:
+
+- `profile/`, `context/`, `acceptance/`, `guard/`, `handoff/`, `harvest/`
+- `roles/`, `modes/`, `mechanisms/`, `examples/`, `cookbook/`, `state/`
+- adapter guidance for Codex, Claude Code, Cursor, Cline, Windsurf, and Copilot
+
+## 中文路径
+
+先拿你自己的真实任务跑一遍，不要先读一堆概念（按上面 Path 1：`init` 后打开 `.aict/walkthroughs/10-minute-your-task.md`）。任务太敏感不方便贴、或想先看一遍流程，再走 Path 2 的演示版 `.aict/walkthroughs/10-minute.md`。你要看的不是“这个系统怎么自我介绍”，而是你自己那段混乱需求如何被拆成：目标边界、完成标准、审查意见、交接状态、可复用经验。
+
+想让 AI 自己提醒你、每次说“做完了”都主动喊你复核，而不是你自己记着？用 `node bin/ai-collab.js adapters install --target <repo>` 把 adapter 装进工具的常驻指令，就会打开克制的提醒；只有一个工具时，完成自检会走 `single-tool-guard`（同一个工具里新开一轮对抗式复核）。

package/bin/ai-collab.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../src/cli.js";

package/docs/DOGFOOD.md

@@ -0,0 +1,85 @@
+# Dogfood Guide
+
+Try this workspace on your own AI collaboration, then tell us what actually happened. This page is for trying it; [docs/FEEDBACK.md](./FEEDBACK.md) is for reporting back.
+
+Everything here is local-first and synthetic. You read and copy plain files into the AI tools you already use. Nothing is uploaded by the CLI, and we do not want you to upload anything private to us either. See [What NOT to upload](#what-not-to-upload) before you start.
+
+## Who should try it
+
+This is worth ten minutes if you work across more than one AI tool and you keep hitting one of these:
+
+- **Context keeps getting lost.** You re-explain the same task boundary every session, and the AI still drifts out of scope.
+- **The AI claims it finished, but it did not.** You get a fluent "done — added X, Y, Z with tests" and only later find a piece was never implemented.
+- **You repeat your background across sessions.** Every new chat starts cold; the previous chat's state is gone and you retype it.
+- **You cannot tell which AI is right.** Two tools (or two sessions) disagree and you have no structured way to decide which one to trust.
+
+If none of those bite you, this probably is not for you, and that is a fine outcome to report. Skipping it for low-stakes, throwaway work is the right call — running structure over trivial work is just ceremony.
+
+## Try it in 10 minutes (on your own task — recommended)
+
+Run the whole loop on one real task of *yours*, in three short rounds, and watch an independent AI catch a thin "done" on work you actually care about. This is the fastest way to feel why it matters.
+
+1. Initialize a throwaway workspace:
+   ```bash
+   node bin/ai-collab.js init --target ./my-ai-workspace
+   ```
+2. Open `./my-ai-workspace/.aict/walkthroughs/10-minute-your-task.md` and follow its five steps.
+3. You describe one real (lightly redacted) task; the AI returns a **boundary card** and an **acceptance card** — *done* defined before any work — then does only the accepted slice and reports what it changed, ran, and did not verify.
+4. The point to notice: you open a fresh chat (ideally a different AI brand) and have it re-check the result against evidence. Where the work over-claimed, it returns `reject` with the defect pinned to a location — on your task, not a prepared one.
+
+What you should feel by the end: your own task had visible state (what is in scope, what "done" means, what is still unproven) instead of one smooth guess — and a thin "done" got caught before you trusted it. Redact before you paste (see [What NOT to upload](#what-not-to-upload)); the loop works on a redacted description and needs no private original.
+
+### Prefer to watch a prepared demo first? (optional)
+
+If your task feels too sensitive to paste right now, or you just want to see the flow first, open `./my-ai-workspace/.aict/walkthroughs/10-minute.md` (the demo preview) instead. It runs the same loop on the prepared `ai-coding-long-task` case: the first output claims arrow-key reorder works, the guard proves the keyboard handler is a stub that never moves anything, and it returns `reject` with a line citation — not a vibe. Then come back and run the loop on your own task above.
+
+## Try it in 30 minutes
+
+Go deeper: take one mechanism and point it at *your own* half-finished work. The cleanest one to start with is **dual-guard**: use it to review a deliverable that claims to be done.
+
+1. Read the recipe: `./my-ai-workspace/.aict/cookbook/review-a-half-product.md`. It explains why each step exists and how to adapt it.
+2. Pick something of yours that says "done but maybe not" — a draft, a small feature, a doc whose first-run path you are not sure actually works.
+3. Redact it first (see below), then paste the redacted artifact plus the copy-paste block from the cookbook (the dual-guard review prompt) into a second AI tool — ideally a **different model family** from whatever produced the work, because a different family is the pass most likely to see what the author missed.
+4. Demand findings tied to specific lines or missing evidence, ordered by severity, with a pass or reject. Do not accept "looks fine".
+5. The underlying mechanism is `./my-ai-workspace/.aict/mechanisms/dual-guard/` — read its `PROMPT.md` and `README.md` if you want the full two-layer version (cross-family binding guard + same-family reference guard).
+
+What you should feel by the end: you got an evidence-grounded second opinion on your own work without handing your private original to anyone — the review runs on a redacted artifact plus its evidence.
+
+## What to report back
+
+After either path, open [docs/FEEDBACK.md](./FEEDBACK.md) and fill it in. We mostly want to know:
+
+- Which AI tools you use, and which pain point pulled you in.
+- Where the first experience stalled, if it did.
+- Which mechanism was the most useful, and which one you could not make sense of.
+- Whether you would use this on a real workflow, and whether paying to save calibration time would be worth it to you.
+
+Report the *experience*, not your task. The feedback template asks only for感受-level answers, never the work itself. (中文：只反馈体验感受，不要把真实任务内容贴进来。)
+
+## What NOT to upload
+
+The honest rule of this project is local-first: the open method is complete on your own machine, and we do not collect your work. So when you report back, give us your **experience**, never your **material**. Do not paste, attach, or screenshot any of the following into an issue, a discussion, or anywhere it leaves your machine:
+
+- Actual customer or contact material, or names of people and companies.
+- Tokens, API keys, cookies, passwords, or any credential.
+- Absolute local machine paths (anything that reveals your home directory or internal folder layout).
+- Private chat logs, raw session transcripts, or the unredacted original of whatever you reviewed.
+- Company-internal information: private routing, internal numbers, non-public processes, or proprietary docs.
+- Unredacted screenshots that show any of the above.
+
+If you want to show an example, rewrite it as a synthetic placeholder first (same shape as the cases in `examples/`), or just describe what happened in words. The review mechanisms are built to work on a redacted artifact plus its evidence — they never need the private original.
+
+Before you post anything, you can sanity-check your own repo the same way this project checks itself:
+
+```bash
+node scripts/privacy-scan.js
+```
+
+中文（同义）：本地优先，方法在你自己机器上就完整可用，我们不收集你的工作内容。反馈时只给体验感受，不要上传任何隐私材料：客户或联系人信息、密钥口令、本机绝对路径、私有对话原文、公司内部信息、未脱敏截图。要举例就先改写成合成占位例子，或者直接用文字描述。
+
+## Why dogfood this at all
+
+Two reasons, stated plainly:
+
+- It makes the project better. Real friction reports — where the first run stalls, which mechanism reads as jargon — are what fix the open system. A confused first-run is a bug we want to know about.
+- It is how a real working relationship can start, honestly. If the open method helps but you would rather have it tuned to your own tools and workflow, that is what paid help is for — calibration, setup, migration, review, pairing. The method here stays complete and free; paid help only saves you the trial-and-error of calibrating it. See [docs/FREE_VS_PAID.md](./FREE_VS_PAID.md). We never gate the basic method behind payment, and we never tell you "you have a problem, pay to see the answer."