ai-collab-open-system 0.1.0

package/docs/open-system/04-core-mechanisms.md

@@ -0,0 +1,34 @@
+# 04 Core Mechanisms
+
+The AI Collaboration Open System ships local-first mechanism packages in `.aict/mechanisms/`. Each package has README, prompt, template, synthetic example, and failure modes.
+
+## Mechanisms
+
+- Dual Guard: a cross-family guard is the binding gate and a same-family guard is a non-binding reference, so a fluent answer is not trusted just because it reads well; passes merge by strictness, where one evidence-grounded blocker outweighs fluent approval.
+- SCOUT Review Controller: exploration, challenge, and controller decision stay separate.
+- One-Click Dispatch: compact work packet for another AI tool.
+- Task Splitting: a five-question pre-dispatch self-check; if any answer is yes, split the task by topic or deliverable (not line count) into self-contained sub-packets so an oversized prompt does not stall or degrade.
+- Anti-Drift Partner: a long thinking conversation with an AI that pushes back instead of agreeing — it surfaces blind spots, probes at most two rounds, then commits to a judgment, so the talk never drifts into fluent confirmation.
+- Blind-Spot Scan: borrows an outside viewpoint (customer, competitor, expert, opponent, your-future-self), re-reads the decision through that seat, and returns the concrete dead angles you cannot see from your own plus the one counter-question most worth sitting with — and the borrowed viewpoint must genuinely challenge, never flatter from a costume.
+- Root-Cause Brake: when the same artifact is rejected twice in a row, the brake trips — no more patches until four diagnostic questions are answered, the real cause is named, and the next version is rebuilt around it.
+- Half-Product Review: blocks release claims when docs outrun runnable proof.
+- Handoff A/B/C: three handoff modes for three situations - A high-interaction (lightweight same-tool resume), B programmatic (a defined task an executor drives to completion), C delivery overview (a human-facing account of a finished phase) - all carrying the same load-bearing fields.
+- Harvest and External Recap: a conversation is swept into harvest cards (one per decision, lesson, method, or stable preference), the human confirms them, and redaction runs before filing; External Recap is a separate role that recaps many conversations at once, gated by a double lock (a fresh session plus an explicit human declaration).
+- Do Not Handle Yet: parks tempting adjacent work without losing it.
+- Plain-Language First Screen: makes the first user view runnable before theoretical.
+- Honest Calibration: leads every ask for a rating or recommendation with a short candor prefix (be candid, do not inflate, do not over-hedge) that offsets the model's pull to please and re-aims the baseline from make-you-happy to tell-the-truth.
+- Feedback-Absorption Ledger: when merging feedback from several sources, scores each item across five tiers (absorb fully / refine / add a boundary / partly absorb / reject with a reason) so independent judgment is kept instead of rubber-stamping — the absorb/reject ratio is an outcome, not a target.
+- Collaboration Coach: the assistant proactively reminds the user of the matching collaboration step at six recurring moments (define done, review a completion claim, hand off, harvest, update the profile), restrained by default — once per moment, never every turn, because over-prompting is the fastest way to get the system uninstalled.
+- Single-Tool Guard: the default starting guard for a one-model-family user — a new conversation plus an adversarial reviewer prompt — whose verdict is always labeled single-family-only with the residual risk named, honestly capped at L2 and never recorded as a passed cross-family binding gate, which is the upgrade ceiling.
+
+## How to use a mechanism
+
+1. Open the mechanism package.
+2. Fill the template with redacted local material.
+3. Paste the prompt plus context and acceptance into your AI tool.
+4. Save the result into handoff or harvest.
+5. Run guard review if the result will be trusted by another session.
+
+## Why mechanisms are public-safe
+
+They preserve the workflow shape without exposing private profiles, source conversations, non-public routes, or account material.

package/docs/open-system/05-failure-patterns.md

@@ -0,0 +1,31 @@
+# 05 Failure Patterns
+
+AI Collaboration Open System exists because local-first AI work fails in repeatable ways when everything stays inside a single chat.
+
+## Smooth wrong answer
+
+The assistant gives a confident answer before acceptance exists. Fix: write acceptance first and run guard review after the artifact.
+
+## Scope drift
+
+A coding task becomes design, research, and release work in one response. Fix: use task splitting and do-not-handle-yet.
+
+## Half product
+
+README, architecture, or launch copy claims more than the runnable files prove. Fix: run half-product review and package smoke checks.
+
+## Lost handoff
+
+A later session restarts because the previous chat never separated done, pending, blocked, and unverified. Fix: write handoff before stopping.
+
+## No harvest
+
+The same lesson is rediscovered every week. Fix: extract one reusable harvest seed after each meaningful loop.
+
+## Privacy erosion
+
+Useful examples slowly accumulate private details. Fix: rewrite cases as synthetic labs and run the privacy scan before packaging.
+
+## Human judgment replaced
+
+The AI starts deciding values, risk tolerance, or product direction. Fix: keep controller and guardian roles separate and mark decisions that need the user.

package/docs/open-system/06-how-to-adapt-to-your-workflow.md

@@ -0,0 +1,31 @@
+# 06 How to Adapt to Your Workflow
+
+AI Collaboration Open System is local-first and tool-agnostic. You adapt it by copying files into the AI tools you already use.
+
+## Codex
+
+Paste the shared contract, context package, and acceptance card into the task. Ask Codex to return changed files, checks run, failures, and unverified areas.
+
+## Claude Code
+
+Use the same context and acceptance files. For review work, ask Claude Code to act as system guardian and lead with findings.
+
+## Cursor or Copilot
+
+Keep the shared contract in project instructions. For each task, attach context and acceptance, then save a handoff note before stopping.
+
+## Cline or Windsurf
+
+Use adapter guidance as a thin pointer to `.aict/`. Do not maintain a second rule system inside the tool.
+
+## Team workflow
+
+1. Keep `.aict/` in a repo or local folder.
+2. Redact before sharing.
+3. Make every long task produce context, acceptance, guard, handoff, and harvest.
+4. Use mechanisms only when they reduce real risk or drift.
+5. Run `ai-collab check --workspace <dir>` before trusting a generated workspace.
+
+## Adaptation rule
+
+Change examples and language freely, but keep the loop: context before execution, acceptance before completion, guard before trust, handoff before switching, harvest after learning.

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "ai-collab-open-system",
+  "version": "0.1.0",
+  "description": "Local-first open-source AI collaboration workspace with profile, context, acceptance, guard, handoff, and harvest structure.",
+  "type": "module",
+  "bin": {
+    "ai-collab": "./bin/ai-collab.js"
+  },
+  "scripts": {
+    "test": "node --test",
+    "contract:check": "node scripts/validate-contract.js",
+    "privacy:scan": "node scripts/privacy-scan.js",
+    "pack:check": "node scripts/pack-check.js",
+    "check": "node --test && node scripts/validate-contract.js && node scripts/privacy-scan.js && node scripts/pack-check.js",
+    "prepublishOnly": "npm run check"
+  },
+  "keywords": [
+    "ai",
+    "collaboration",
+    "local-first",
+    "workspace",
+    "codex",
+    "claude-code",
+    "cursor",
+    "agents",
+    "handoff",
+    "guard-review"
+  ],
+  "author": {
+    "name": "Aaron Yi",
+    "email": "yi19970319@gmail.com",
+    "url": "https://x.com/AaronYiaazw"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aaronyi97/ai-collab-open-system.git"
+  },
+  "bugs": {
+    "url": "https://github.com/aaronyi97/ai-collab-open-system/issues"
+  },
+  "homepage": "https://github.com/aaronyi97/ai-collab-open-system#readme",
+  "files": [
+    ".aict",
+    "bin",
+    "docs",
+    "scripts",
+    "src",
+    "tests",
+    "README.md",
+    "START_HERE.md",
+    "PRODUCT_CONTRACT.md",
+    "CHANGELOG.md",
+    "KNOWN_LIMITATIONS.md",
+    "RELEASE_CHECKLIST.md",
+    "privacy-manifest.json",
+    "privacy-scan.local.json.example",
+    "LICENSE",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "CODE_OF_CONDUCT.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/privacy-manifest.json

@@ -0,0 +1,78 @@
+{
+  "localFirst": true,
+  "defaultNetworkUse": "none",
+  "publicAllowed": [
+    "generic architecture",
+    "generic prompts",
+    "generic templates",
+    "thin tool adapters",
+    "synthetic examples",
+    "privacy docs",
+    "setup docs",
+    "self-build guide",
+    "known limitations"
+  ],
+  "publicForbidden": [
+    "real private governance contents",
+    "private knowledge-base source material",
+    "real personal profile",
+    "actual client material",
+    "raw private conversations",
+    "non-public automation details",
+    "non-public routing details",
+    "internal calibration thresholds",
+    "internal scoring weights",
+    "account-specific habits",
+    "local machine paths",
+    "tokens, keys, cookies, credentials",
+    "unredacted screenshots",
+    "full internal service SOP"
+  ],
+  "scanner": "scripts/privacy-scan.js",
+  "publicContactsComment": "EXACT-string allowlist for the privacy scanner's email rule. The scanner blocks EVERY email address EXCEPT one that exactly matches an entry here — this is a narrow, explainable exemption for the project's PUBLISHED public contact only, NOT a domain or category allowlist (a different address, even at the same domain, still fails the scan). Keep this to the maintainer's intentionally-public contact email; never add a customer/private address here.",
+  "publicContacts": [
+    "yi19970319@gmail.com"
+  ],
+  "scanDenylist": {
+    "comment": "Maintainable central denylist consumed by scripts/privacy-scan.js. Extend these arrays to harden the gate without touching scanner code. Keep entries PUBLIC-SAFE and GENERIC (anyone-applies): list generic markers and placeholders, never paste a real secret/customer/path or your OWN private directory name here (this manifest ships in the public package and is itself scanned). For YOUR personal private dir names / terms, use the gitignored local override instead — copy privacy-scan.local.json.example to privacy-scan.local.json; the scanner merges it on top of this list.",
+    "paths": [
+      ".claude/hooks"
+    ],
+    "pathsComment": ".claude/hooks is the standard Claude Code hooks directory every Claude Code user has, kept as a GENERIC marker so a user does not paste their own private hook contents. Add your personal private dirs via privacy-scan.local.json, not here.",
+    "terms": [],
+    "chineseTerms": [
+      "真实客户",
+      "真实项目",
+      "客户名单",
+      "原始对话",
+      "内部路由",
+      "内部阈值",
+      "内部权重",
+      "私有治理",
+      "私有体系",
+      "知识库源料"
+    ]
+  },
+  "bilingual": {
+    "comment": "The repo is intentionally bilingual: it ships a sanctioned Chinese onboarding surface alongside English. These rules tell the Chinese-leak heuristic which Chinese is allowed, so legitimate bilingual UX does not trip the gate while stray (unmarked) Chinese — a likely sign of pasted private material — still fails. sectionMarkers open a sanctioned bilingual block for the next contextWindow lines; lineAllow exempts a single line; zhKeyAllowed exempts localized `zh:` strings; sanctionedFiles names whole-file bilingual SOURCES (the i18n message catalog + its tests) where the unmarked-run heuristic is relaxed — the token/key/local-path/email rules and the chineseTerms denylist still apply to them.",
+    "sectionMarkers": [
+      "中文",
+      "Chinese positioning",
+      "Chinese path",
+      "Keyword-triggered modes"
+    ],
+    "lineAllow": [
+      "AI \\u534f\\u4f5c",
+      "\\u672c\\u5730\\u4f18\\u5148"
+    ],
+    "sanctionedFiles": [
+      "src/i18n.js",
+      "src/dialogue.js",
+      "tests/contract.test.js"
+    ],
+    "sanctionedFilesComment": "src/i18n.js is the bilingual message catalog (EN canonical + ZH faithful) — it is densely Chinese BY DESIGN, so the unmarked-run heuristic only produces noise there. src/dialogue.js is the dialogue-scan module: it ships Chinese completion/correction MARKER WORD TABLES (e.g. 已完成 / 搞定 / 不对) it must match against a user's bilingual chat export, so it carries sanctioned product Chinese by design. tests/contract.test.js asserts the localized ZH output (the honesty translations), so it too carries sanctioned product Chinese. All three remain subject to the hard token/key/local-path/email rules and the chineseTerms private-term denylist.",
+    "zhKeyAllowed": true,
+    "contextWindow": 12,
+    "minRun": 4
+  }
+}

package/privacy-scan.local.json.example

@@ -0,0 +1,18 @@
+{
+  "_comment": "OPTIONAL local override for the privacy scanner. Copy this file to `privacy-scan.local.json` (which is gitignored and never published) and add YOUR OWN private identifiers. The public package intentionally ships only GENERIC markers (emails, API keys, phone numbers, absolute /Users paths, .env, .pem/.key, .claude config) that apply to everyone. Your personal private directory names and private terms do not belong in the public manifest, so list them here instead. The scanner merges this file on top of privacy-manifest.json's scanDenylist when present.",
+
+  "_worked_example_comment": "WORKED EXAMPLE (this is exactly how THIS project's maintainer uses the override; the names are shown here only as a pattern to copy — the active arrays below stay as placeholders so the published .example file does not itself bake in any private dir name). The maintainer keeps a personal governance directory and a personal knowledge base on disk; their REAL gitignored privacy-scan.local.json adds both names to `paths`, e.g. paths: [\"<your-private-governance-dir>\", \"<your-knowledge-base-dir>\"]. With those entries present, any file the scanner reads that mentions either folder name FAILS the scan (reported as a denylisted path) and is also blocked from the npm tarball — so a stray reference to your private governance/knowledge dirs can never ship. Copy this file, then replace the two placeholders below with your own real folder names.",
+
+  "paths": [
+    "<your-private-governance-dir>",
+    "<your-knowledge-base-dir>"
+  ],
+
+  "_paths_comment": "Substring path markers to forbid in scanned file CONTENT, and to block from the npm tarball. Replace the placeholders with the names of your own private dirs (e.g. a personal governance folder or knowledge base — see the worked example above). Leave empty if you have none.",
+
+  "terms": [],
+  "_terms_comment": "Plain (English/ASCII) private terms to forbid in scanned content (e.g. an internal codename).",
+
+  "chineseTerms": [],
+  "_chineseTerms_comment": "Chinese private terms to forbid in scanned content."
+}

package/scripts/lib/forbidden-in-pack.js

@@ -0,0 +1,55 @@
+// Single source of truth for the "must never ship in the npm tarball" rules.
+//
+// Both scripts/privacy-scan.js (which scans `npm pack --dry-run` output as one of
+// its surfaces) and scripts/pack-check.js (the standalone release-safety gate)
+// enforce this list. Keeping it in one module prevents the two copies from
+// drifting apart — a divergence would mean one gate blocks a private file while
+// the other silently ships it.
+//
+// Each entry is [RegExp, humanLabel]. The regex is tested against a pack file
+// path (POSIX-style, as npm reports it). `.git/` and `node_modules/` are included
+// here as regexes so a single shared list fully covers the forbidden surface.
+//
+// Only GENERIC, anyone-applies markers live here as literals (a `.env`, a
+// `.claude/` config dir, a backup file, a secret/key). A maintainer's OWN private
+// directory names are NOT hard-coded here (that would ship the maintainer's
+// private dir name inside the public package). Instead, callers pass their own
+// private dir names via `extraPrivateDirs` — sourced from a gitignored local
+// config (see privacy-scan.local.json.example) — so the protection stays
+// configurable while the shipped code stays generic.
+
+export const FORBIDDEN_IN_PACK = [
+  [/(^|\/)\.env(\.|$)/i, ".env file"],
+  [/(^|\/)\.claude(\/|$)/i, "private Claude config dir"],
+  [/\.aict-backup-/i, "adapter backup file"],
+  [/\.aict\.backup-/i, "workspace backup file"],
+  [/(^|\/)(secrets?|credentials?)(\.|\/|$)/i, "secrets/credentials file"],
+  [/\.(pem|key|p12|pfx)$/i, "private key material"],
+  [/(^|\/)node_modules\//i, "node_modules"],
+  [/(^|\/)\.git\//i, ".git internals"]
+];
+
+// Build a pack rule that blocks a user-configured private directory (matched as a
+// path segment, the same way the literal rules above match `.claude/`). The dir
+// name is escaped so it is treated literally, not as a regex.
+function privateDirRule(dir) {
+  const safe = String(dir).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return [new RegExp(`(^|/)${safe}(/|$)`, "i"), `configured private dir (${dir})`];
+}
+
+// Return the list of "{label}: {file}" violations for a set of pack file paths.
+// `extraPrivateDirs` lets a caller add their own private dir names (from a local,
+// gitignored config) without those names ever being baked into this shipped file.
+export function findForbiddenPackFiles(files, extraPrivateDirs = []) {
+  const rules = [
+    ...FORBIDDEN_IN_PACK,
+    ...(extraPrivateDirs ?? []).filter(Boolean).map(privateDirRule)
+  ];
+  const violations = [];
+  for (const file of files) {
+    for (const [regex, label] of rules) {
+      if (regex.test(file)) violations.push({ file, label });
+    }
+  }
+  return violations;
+}

package/scripts/pack-check.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { findForbiddenPackFiles } from "./lib/forbidden-in-pack.js";
+
+const repoRoot = path.resolve(new URL("..", import.meta.url).pathname);
+
+// Private dir names to also block from the tarball, sourced exactly like the
+// privacy scanner: generic markers live in the shared forbidden-in-pack rules,
+// while a maintainer's OWN private dir names come from the (shipped, generic)
+// manifest denylist plus an optional gitignored local override — never baked
+// into the shared shipped module. Keeps both gates aligned with no drift.
+function readJsonIfPresent(file) {
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function resolveConfiguredPrivateDirs() {
+  const manifest = readJsonIfPresent(path.join(repoRoot, "privacy-manifest.json"));
+  const local = readJsonIfPresent(path.join(repoRoot, "privacy-scan.local.json"));
+  const dirs = [
+    ...(manifest?.scanDenylist?.paths ?? []),
+    ...(local?.paths ?? [])
+  ];
+  return [...new Set(dirs.filter((entry) => typeof entry === "string" && entry.length > 0))];
+}
+
+const configuredPrivateDirs = resolveConfiguredPrivateDirs();
+
+function parseArgs(argv) {
+  const args = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] === "--cache") {
+      args.cache = argv[index + 1];
+      index += 1;
+    }
+  }
+  return args;
+}
+
+function fail(errors) {
+  console.error(`Pack check failed:\n${errors.map((error) => `- ${error}`).join("\n")}`);
+  process.exit(1);
+}
+
+// `npm pack` wants to write logs to npm's cache dir (~/.npm/_logs by default). In a
+// strict read-only sandbox that is not writable and npm dies with a cryptic ENOENT
+// mkdir on the log dir. Point npm at a writable cache: an explicit --cache, an
+// existing npm_config_cache, or a fresh temp dir we create. If even the temp dir is
+// unwritable, surface a clear hint instead of the raw EPERM.
+function resolveCache(args) {
+  if (args.cache) return { cache: path.resolve(args.cache), created: false };
+  if (process.env.npm_config_cache) return { cache: process.env.npm_config_cache, created: false };
+  try {
+    return { cache: mkdtempSync(path.join(tmpdir(), "aicos-npm-cache-")), created: true };
+  } catch (error) {
+    return { cache: null, error };
+  }
+}
+
+const args = parseArgs(process.argv.slice(2));
+const { cache, error: cacheError } = resolveCache(args);
+
+if (!cache) {
+  fail([
+    `cannot create a writable npm cache (${cacheError?.code || cacheError?.message}).`,
+    `In a read-only sandbox, point npm at a writable dir and re-run:`,
+    `  node scripts/pack-check.js --cache <writable-dir>`,
+    `  (or: npm_config_cache=<writable-dir> node scripts/pack-check.js)`
+  ]);
+}
+
+let output;
+try {
+  output = execFileSync("npm", ["pack", "--dry-run", "--json", "--cache", cache], {
+    cwd: repoRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    env: { ...process.env, npm_config_cache: cache }
+  });
+} catch (error) {
+  fail([
+    `npm pack --dry-run failed (${error.code || "error"}).`,
+    `If this is an EPERM/ENOENT writing npm logs in a read-only sandbox, pass a writable cache:`,
+    `  node scripts/pack-check.js --cache <writable-dir>`,
+    error.stderr ? `npm said: ${String(error.stderr).trim().split("\n").slice(-3).join(" | ")}` : `(${error.message})`
+  ]);
+}
+
+const [pack] = JSON.parse(output);
+const files = new Set(pack.files.map((file) => file.path));
+const errors = [];
+
+for (const required of [
+  "README.md",
+  "START_HERE.md",
+  "PRODUCT_CONTRACT.md",
+  "CHANGELOG.md",
+  "RELEASE_CHECKLIST.md",
+  "privacy-manifest.json",
+  "CONTRIBUTING.md",
+  "SECURITY.md",
+  "CODE_OF_CONDUCT.md",
+  "bin/ai-collab.js",
+  "src/cli.js",
+  "scripts/validate-contract.js",
+  "docs/WHY_THIS_EXISTS.md",
+  "docs/PUBLIC_MAPPING.md",
+  "docs/open-system/00-start-here.md",
+  ".aict/START_HERE.md",
+  ".aict/adapters/SHARED_CORE_CONTRACT.md",
+  ".aict/examples/ai-coding-long-task/CASE.md",
+  ".aict/mechanisms/dual-guard/README.md",
+  ".aict/roles/README.md",
+  ".aict/modes/README.md",
+  ".aict/cookbook/README.md",
+  ".aict/state/CURRENT_STATE.md",
+  ".aict/state/tasks.jsonl",
+  ".aict/state/evidence.jsonl",
+  ".aict/state/runs.jsonl",
+  ".aict/state/receipts.jsonl",
+  ".aict/state/learning-ledger.jsonl",
+  ".aict/privacy/PRIVACY.md"
+]) {
+  if (!files.has(required)) errors.push(`package missing ${required}`);
+}
+
+// Defense in depth: the privacy scanner also checks the pack file list, but keep a
+// hard block here so a private file can never ship even if the scanner is skipped.
+// The forbidden-file rules (including .git/ and node_modules/) live in the shared
+// scripts/lib/forbidden-in-pack.js so this gate and the privacy scanner never drift.
+for (const { label, file } of findForbiddenPackFiles([...files], configuredPrivateDirs)) {
+  errors.push(`package would ship ${label}: ${file}`);
+}
+
+if (pack.size <= 0 || pack.unpackedSize <= 0) {
+  errors.push("package size metadata is empty");
+}
+
+if (errors.length > 0) {
+  fail(errors);
+}
+
+console.log(`Pack check passed.
+Files packed: ${pack.entryCount}
+Package: ${pack.filename}
+Cache: ${cache}
+`);