ai-collab-open-system 0.1.0

package/.aict/skills/profile/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: profile
+description: Build and maintain collaboration profiles.
+---
+
+# profile skill
+
+## When to use
+
+Use before recurring or high-context work where the assistant's tone, autonomy, challenge style, and safety boundaries affect the result.
+
+## Inputs
+
+- The shared core contract.
+- A redacted task context.
+- The relevant layer template.
+- Any acceptance criteria or review findings.
+
+## Process
+
+1. Extract reusable collaboration preferences from redacted material.
+2. Separate stable preferences from task facts.
+3. Mark inferred preferences as provisional until confirmed.
+4. Return a compact profile card that future sessions can apply.
+
+## Output
+
+- Working style
+- Decision preferences
+- Hard boundaries
+- Challenge and review preferences
+- Update rule
+
+## Safety
+
+- Do not store secrets, client names, local paths, account details, or raw private conversations.
+- Do not infer identity traits that the user did not provide.
+- Do not turn a temporary mood into a permanent rule.
+
+## Example
+
+Create a profile that says: direct risk calls, no publishing without consent, ask before irreversible actions. Include a short evidence note for every stable preference: 'seen in repeated release work' is acceptable, while 'user sounded impatient once' stays provisional. The profile should help the next assistant choose autonomy level, response length, challenge style, and consent boundaries without copying private task history.

package/.aict/skills/red-team/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: red-team
+description: Find the failure path before shipping an idea.
+---
+
+# red-team skill
+
+## When to use
+
+Use for public releases, irreversible operations, broad claims, security-sensitive behavior, or expensive direction choices.
+
+## Inputs
+
+- The shared core contract.
+- A redacted task context.
+- The relevant layer template.
+- Any acceptance criteria or review findings.
+
+## Process
+
+1. Name the most damaging plausible failure.
+2. Attack assumptions through user behavior, safety, evidence, and rollback.
+3. Separate blockers from tolerable risk.
+4. Recommend the smallest mitigation or test.
+
+## Output
+
+- Worst plausible failure
+- Attack paths
+- Evidence gaps
+- Mitigations
+- Residual risk
+
+## Safety
+
+- Do not invent dramatic but irrelevant threats.
+- Do not skip mundane data-loss or privacy failures.
+- Do not treat red-team output as owner approval.
+
+## Example
+
+Before publishing, challenge whether README claims 'integration' when adapters are only guidance files.

package/.aict/skills/single-tool-guard/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: single-tool-guard
+description: Run the minimum guard when only one model family is available, with the ceiling named on the record.
+---
+
+# single-tool-guard skill
+
+## When to use
+
+Use at a completion claim when no second, different model family exists to run the cross-family binding gate, and you would otherwise trust the same assistant that just wrote the work.
+
+## Inputs
+
+- The shared core contract.
+- A redacted task context.
+- The relevant layer template.
+- Any acceptance criteria or review findings.
+
+## Process
+
+1. Open a brand new conversation rather than reusing the drafting thread, whose eagerness to please suppresses objections.
+2. Paste an adversarial prompt that defaults to refuting and hunts for missing evidence, tying each finding to a line or section.
+3. Bound the verdict at the single-tool ceiling: this tops out at L2 / pass_with_risk and may never be filed as a passed cross-family gate.
+4. Name the residual risk a same-family reviewer most likely shares, and leave the upgrade note to run one cross-family pass once a second family appears.
+
+## Output
+
+- Verdict bounded at pass_with_risk (never a plain pass)
+- Findings tied to specific lines or sections
+- Residual risk a same-family reviewer would share
+- Owner sign-off required before pass_with_risk counts as accepted
+- Upgrade note: cross-family pass still owed
+
+## Safety
+
+- Do not record a single-family review as if the cross-family binding gate cleared it.
+- Do not let pass_with_risk count as accepted without an explicit owner sign-off on the named risk.
+- Do not reuse the thread that just claimed done, and do not leave the residual risk blank.
+
+## Example
+
+With only one tool available, a fresh adversarial pass downgrades a done claim to pass_with_risk, names the CSV-escaping blind spot a same-family reviewer would share, and leaves an upgrade note to run a cross-family pass later.

package/.aict/state/CURRENT_STATE.md

@@ -0,0 +1,13 @@
+# Current State
+
+Use this file for local state only. Do not publish private task details.
+
+## Current goal
+
+## Active context package
+
+## Active acceptance card
+
+## Current mode
+
+## Next action

package/.aict/state/DECISIONS.md

@@ -0,0 +1,7 @@
+# Decisions
+
+Record decisions that future sessions should not reopen without new evidence.
+
+| Date | Decision | Evidence | Revisit condition |
+| --- | --- | --- | --- |
+| synthetic | Keep examples synthetic | privacy boundary | public-safe replacement needed |

package/.aict/state/TASK_LOG.md

@@ -0,0 +1,7 @@
+# Task Log
+
+Use this local log to keep AI work resumable.
+
+| Date | Task | Mode | Evidence | Next action |
+| --- | --- | --- | --- | --- |
+| synthetic | First loop | review | guard review exists | write handoff |

package/.aict/state/evidence.jsonl

@@ -0,0 +1,2 @@
+{"id":"e0","taskId":"t0","kind":"note","summary":"(synthetic) example evidence seed row bound to task t0","createdAt":"2026-01-01T00:00:00.000Z"}
+{"id":"e1","taskId":"t0","kind":"cross_family_guard","summary":"(synthetic) cross-family guard review seed row bound to task t0","reviewer":"(synthetic) example reviewer","family":"(synthetic) other-model-family","createdAt":"2026-01-01T00:00:00.000Z"}

package/.aict/state/learning-ledger.jsonl

@@ -0,0 +1 @@
+{"id":"l0","taskId":"t0","type":"harvest","content":"(synthetic) example learning seed row - written by the P4 harvest flow","status":"proposed","createdAt":"2026-01-01T00:00:00.000Z"}

package/.aict/state/receipts.jsonl

@@ -0,0 +1 @@
+{"id":"c0","taskId":"t0","verdict":"pass","guardLevel":"L3","reviewMode":"cross_family","evidenceIds":["e0","e1"],"familyUnverified":true,"status":"accepted","createdAt":"2026-01-01T00:00:00.000Z"}

package/.aict/state/runs.jsonl

@@ -0,0 +1 @@
+{"id":"r0","taskId":"t0","command":"echo synthetic-seed","startedAt":"2026-01-01T00:00:00.000Z","finishedAt":"2026-01-01T00:00:00.000Z","exitCode":0,"status":"finished"}

package/.aict/state/tasks.jsonl

@@ -0,0 +1 @@
+{"id":"t0","title":"(synthetic) example task seed row - replace with your own","status":"open","createdAt":"2026-01-01T00:00:00.000Z"}

package/.aict/walkthroughs/10-minute-your-task.md

@@ -0,0 +1,107 @@
+# 10-Minute Walkthrough (Your own task)
+
+This is the recommended first run. You run the whole collaboration loop on one real task of your own, instead of a prepared example, and feel the value on work you actually care about. If you would rather watch the flow on a prepared case first, use `10-minute.md` (the demo preview) and then come back here.
+
+Goal: take one messy task of yours and, in three short rounds, force the AI to (1) define "done" before it acts, (2) do only that, and (3) get re-checked by an independent AI that hunts for a thin "done" - then spend two minutes closing the loop into reusable cards so the next task starts ahead.
+
+Everything stays local-first. You paste a redacted description into the AI tools you already use; nothing is uploaded by this workspace. Redact before you paste: replace any real name, path, customer, or internal number with a placeholder. The loop works on a redacted description; it does not need the private original.
+
+What you need: one real task that is a bit messy, and one AI tool you can paste into. A second tool of a different model family (a different AI brand) makes Step 3 much stronger, but you can run all three rounds in one tool if that is all you have.
+
+Want the AI to prompt you for these steps on its own - to ping you to review every time it says "done", instead of you remembering to paste Step 3? Install the adapter into your tool's always-on instructions with `node bin/ai-collab.js adapters install --target <repo>`; it turns on the coaching reminders, and if you only have one tool it routes the completion-claim check through `single-tool-guard` (a fresh adversarial pass in the same tool).
+
+## Step 1 (2 min) - Define done before any work
+
+Paste this into your AI tool, with your own task in the brackets:
+
+```text
+I have a task in front of me that is a bit messy. Do NOT write any implementation yet.
+Task (redacted): [describe your task in plain language; replace any private name, path, or number with a placeholder]
+Return two things:
+1) Boundary card: this run does only this one small slice; explicitly list what is NOT in scope.
+2) Acceptance card: a numbered list of hard, checkable standards (AC1, AC2, ...). Mark anything that would be out of scope.
+```
+
+Expected: a boundary card and an acceptance card. You now have a written definition of "done" for your own task, before a line of work exists. This is the step people skip and then regret.
+
+## Step 2 (3 min) - Do only the accepted slice, then produce an Evidence Pack
+
+Paste this next, so the AI builds only what the acceptance card described and hands back a structured **Evidence Pack** the next round can actually check - not a prose "it's done":
+
+```text
+Do only the work the acceptance card describes. Do not expand scope.
+When you are done, produce an "Evidence Pack" in exactly this shape (it is the artifact the re-check will judge):
+1) Changed files / diff: the list of files you changed, with the key diff hunks (or the full patch). If you changed nothing, say so.
+2) Commands run: the exact commands you ran to verify the work (tests, build, lint, a manual reproduction). If you ran none, write "none".
+3) Command output summary: the real output of each command (paste it, do not paraphrase), trimmed to the relevant lines.
+4) Exit codes: the exit code of each command (0 = passed). If a command failed, keep its non-zero code and error visible - do NOT hide it.
+5) Acceptance mapping: for each acceptance criterion (AC1, AC2, ...), say PASS / FAIL / NOT-VERIFIED and point to the evidence above that backs it.
+6) Not verified: everything you could NOT prove (edge cases, things you skipped, criteria with no command behind them).
+Do not claim "done" for anything that does not have evidence in this pack.
+```
+
+Expected: an Evidence Pack with the six numbered parts above (changed files/diff, commands run, output summary, exit codes, acceptance mapping, not-verified). Keep this whole pack - it is exactly what the next round pressure-tests, and a missing or empty pack is itself a finding in Step 3.
+
+## Step 3 (3 min, the aha moment) - Independent re-check
+
+Open a fresh chat. Ideally use a different AI brand than the one that did Step 2 - a different model family is the pass most likely to catch what the first one missed. Paste this:
+
+```text
+You are an independent reviewer. The work below claims to be done. Assume it is NOT done and prove it from the evidence, not the tone.
+Acceptance card: [paste your Step 1 acceptance card]
+Evidence Pack under review: [paste the Step 2 Evidence Pack: changed files/diff, commands run, output summary, exit codes, acceptance mapping, not-verified]
+Do this, in order:
+1) First check the Evidence Pack itself. If there is no Evidence Pack, or it is missing real command output / exit codes, or a claimed PASS has no command behind it, you CANNOT pass the work: return the verdict INSUFFICIENT_EVIDENCE and list exactly what evidence is missing. A confident "done" with no evidence is INSUFFICIENT_EVIDENCE, not pass.
+2) For each acceptance criterion, point to the exact line/output in the Evidence Pack that backs it, or say there is no evidence for it.
+3) Walk it the way a stranger would actually use it and say exactly where it breaks.
+4) List defects by severity, each pinned to a specific location.
+5) Pick the verdict: REJECT if an evidence-grounded hard defect exists; INSUFFICIENT_EVIDENCE if the pack cannot support a pass; pass only if every criterion is backed by real evidence.
+Return: verdict (pass / REJECT / INSUFFICIENT_EVIDENCE) + defect or missing-evidence list (with locations) + the smallest fix for each + what is still unverified.
+```
+
+Expected (the aha): the independent reviewer first weighs your Evidence Pack. If Step 2 handed over a fluent "done" with no real evidence, it returns `INSUFFICIENT_EVIDENCE` and names what is missing; if the evidence exists but a criterion is not actually met, it returns `REJECT` with the defect pinned to a location - on your own task, not a tutorial's. Either way, that is the gap a single fluent chat would have hidden from you: no evidence pack means no pass.
+
+## Step 4 (2 min) - Close the loop so it compounds
+
+The re-check is the safety net; this step is where the loop starts paying you back. Keep it light - three short cards, not a report. Paste this:
+
+```text
+Close out this task in three short cards. Keep each card to a few lines - do NOT write a long report.
+1) Handoff card (so the next session or tool resumes without re-explaining), three columns:
+   - Done: what is finished and evidence-backed.
+   - To do: what is left.
+   - Not verified: what was claimed but not proven (carry over anything the re-check flagged).
+2) Harvest card: one reusable lesson from this task, as a single sentence I could apply to a future task.
+3) Profile candidate (only if one applies): if a stable preference about how I want you to work showed up more than once, propose it as one line, with status `proposed`. Do NOT add it to my long-term profile yet. If nothing stable showed up, say "no profile candidate this time".
+```
+
+Expected: a three-column handoff, a one-line harvest lesson, and either one `proposed` profile candidate or an explicit "none". Save the handoff and harvest cards into your workspace (`../handoff/` and `../harvest/`). A profile candidate does NOT go straight into your long-term profile - it lands in `../profile/CANDIDATES.md` as `proposed` first. It only moves into `profile/EXAMPLE.synthetic.md` (or your real profile) after you review it: mark it `confirmed` (use as-is), `edited` (reword first), or `dropped` (discard) in CANDIDATES.md, and only `confirmed`/`edited` ones graduate. That buffer is why one task makes the next one start ahead without an unreviewed guess hardening into a standing rule - you walk away with a re-checked result *and* something reusable, but nothing edits your profile behind your back.
+
+### Profile-candidate buffer (the state machine)
+
+A profile candidate is a guess about a standing preference. An unreviewed guess must not silently become a rule future sessions obey, so candidates move through four states in `../profile/CANDIDATES.md`:
+
+- `proposed` — the AI suggested it this loop; not yet trusted, not in your profile.
+- `confirmed` — you reviewed it and it is correct as written; it may now graduate into your profile.
+- `edited` — correct after you reword it; the edited line graduates, the original does not.
+- `dropped` — you reviewed it and it does not belong; it stays recorded as dropped so it is not re-proposed every loop.
+
+Rule: only `confirmed` and `edited` candidates graduate into your long-term profile, and only after you say so. `proposed` and `dropped` never edit your profile. Open `../profile/CANDIDATES.md` for the table and how to use it.
+
+Prefer to let the tool track this for you instead of hand-editing a table? The same four states are available as commands: `ai-collab learning add --type profile --content "..."` records the candidate (and `--type harvest` records the one-line lesson from card 2), then `ai-collab learning confirm` / `learning edit` / `learning drop` keep, reword, or discard it. Next time you run `ai-collab status`, it echoes back the one preference you most recently confirmed - so the next task literally starts with "still working the way you confirmed last time." Use the table or the commands, whichever you like; they share the same states, so you are never maintaining two systems.
+
+## Two-track comparison (optional, makes the point undeniable)
+
+Run your task once with no discipline first, then with the loop, and compare:
+
+1. Track A (no discipline): in a fresh chat, paste your messy task with no structure and just ask the AI to do it. Save the smooth "Sure, I will do X, Y, Z" reply. That smooth line is your real before-evidence, generated on your own task.
+2. Track B (the loop): the three steps above.
+3. Side by side: ask the AI to put both tracks into one table with four rows - scope, definition of done, completion claim, and what would have been missed. The messy half is real evidence from your own task, not something the tutorial invented.
+
+## Want the why behind each step
+
+This walkthrough is the operation card. For the reasoning behind each move and a longer copy-paste sequence to adapt, open `../cookbook/run-a-first-loop.md` (it runs this same loop on your own task and explains why each step exists). To turn Step 3 into a reusable habit on higher-stakes work, see `../cookbook/review-a-half-product.md` and `../mechanisms/dual-guard/README.md`.
+
+## Completion check
+
+You defined "done" before the work, had the AI do only that, had an independent AI re-check it against evidence, and closed the loop into a handoff card, a one-line harvest lesson, and (if one applied) a profile candidate - all on a real task of your own. You can name the exact place the re-check pointed to, and you leave with a re-checked result, reusable cards, and a habit (define done, do only that, get re-checked, then capture what is reusable) that makes your next task start ahead instead of from scratch.

package/.aict/walkthroughs/10-minute.md

@@ -0,0 +1,43 @@
+# 10-Minute Walkthrough (Demo preview)
+
+This is the demo preview: it runs the loop on a prepared case so you can see the flow without pasting anything of your own. To run the same loop on your own real task, use `10-minute-your-task.md` instead (that is the recommended first run). Pick this preview if your task feels too sensitive to paste right now, or you just want to watch the shape of the loop first.
+
+Goal: walk one AI collaboration loop end to end on the prepared TaskBoard case, and watch a guard catch a false completion claim that a single agent would have accepted.
+
+The case: a user asks an AI to add task reordering to a TaskBoard. The AI says it added mouse and keyboard reorder with tests. The guard proves the keyboard part was never implemented. You will see context, acceptance, first output, guard review, revised output, handoff, and harvest.
+
+Everything is local-first and synthetic. You only read and copy files; nothing is uploaded.
+
+## Step 1 (1 min) - Open the case
+
+Open `../examples/ai-coding-long-task/CASE.md` and read "Confusing raw input" and "Likely single-agent failure". This is the messy request and the answer a raw chat usually gives.
+
+Expected: you can say in one line why "I will refactor, add drag, keyboard, polish, and tests" is unsafe (it mixes scope and defines no pass standard).
+
+## Step 2 (2 min) - Set context and acceptance
+
+Open `../examples/ai-coding-long-task/artifacts/context-package.md`, then `acceptance-card.md`. Copy both into your AI tool together with `../adapters/SHARED_CORE_CONTRACT.md`.
+
+Expected: your tool now has five checkable acceptance criteria (AC1 mouse, AC2 keyboard, AC3 tests for both, AC4 data preserved, AC5 visual polish out of scope).
+
+## Step 3 (2 min) - Read the first AI output
+
+Open `../examples/ai-coding-long-task/artifacts/first-ai-output.md`. Read the completion claim, then the `TaskBoard.tsx` code block.
+
+Expected: you can point to the defect yourself. The claim says arrow-key reorder works, but `onKeyDown` (lines 27-30 of that code block) only logs the key and never calls `moveTask`, and the test block has no keyboard test.
+
+## Step 4 (2 min) - Run the guard review
+
+Open `../examples/ai-coding-long-task/artifacts/guard-review.md`. Optionally paste `first-ai-output.md` plus `../guard/PROMPT.md` into a second AI tool and ask it to review against the acceptance card.
+
+Expected: the guard returns a cause-and-effect chain, not a one-line verdict. It cites `first-ai-output.md` lines 27-30 (stub handler) and the missing keyboard test, maps them to AC2 and AC3, and returns reject. This is the line the guard checks.
+
+## Step 5 (2 min) - Read the revised output and close the loop
+
+Open `../examples/ai-coding-long-task/artifacts/revised-output.md`, then `handoff-note.md`, then `harvest-seed.md`.
+
+Expected: `onKeyDown` now calls `moveTask` for ArrowUp/ArrowDown, a keyboard test was added that fails on the old stub and passes on the fix, the handoff separates done / pending / unverified (visual polish), and the harvest seed is the reusable artifact you keep: verify completion claims with code and test evidence, do not trust a fluent "done".
+
+## Completion check
+
+You have walked context -> acceptance -> first output -> guard -> revised -> handoff -> harvest on one case, you can name the exact line the guard pointed to, and you leave with one reusable artifact (`harvest-seed.md`) you can apply to your own next task.

package/.aict/walkthroughs/30-minute.md

@@ -0,0 +1,22 @@
+# 30-Minute Walkthrough
+
+Goal: adapt one layer to a real task.
+
+## Input
+
+Choose one current task and redact private identifiers.
+
+## Steps
+
+1. Open `../context/TEMPLATE.md`.
+2. Fill goal, current state, constraints, facts, assumptions, risks, and open questions.
+3. Open the adapter for your tool in `../adapters/`.
+4. Ask the tool to produce one acceptance card or review note from your context.
+
+## Expected output file
+
+One completed context package or acceptance card.
+
+## Completion check
+
+Another session can tell what the task is, what is out of scope, and what evidence is still missing.

package/.aict/walkthroughs/60-minute.md

@@ -0,0 +1,27 @@
+# 60-Minute Walkthrough
+
+Goal: run one complete AI collaboration loop.
+
+## Steps
+
+1. Fill a light profile.
+2. Package task context.
+3. Define acceptance.
+4. Run one execution prompt.
+5. Challenge the result with guard review.
+6. Write a handoff note.
+7. Extract one harvest seed.
+
+## Expected output files
+
+- profile card
+- context package
+- acceptance card
+- execution artifact
+- guard review
+- handoff note
+- harvest seed
+
+## Completion check
+
+The next AI session can resume without asking what happened, and the useful lesson is saved for future reuse.

package/.aict/walkthroughs/synthetic-loop-transcript.md

@@ -0,0 +1,43 @@
+# Synthetic Loop Transcript
+
+This transcript demonstrates one complete loop using `ai-coding-long-task`.
+
+## Goal
+
+Show that one user can move from a messy starting point to context, acceptance, execution, guard review, handoff, and harvest without relying on a raw chat memory.
+
+## Expected output
+
+A complete artifact chain: context package, acceptance card, execution request, guard review result, handoff note, harvest seed, and a short comparison against single raw AI chat.
+
+## User
+
+A developer asks an assistant to refactor a small task board, then keeps adding bugs, design requests, accessibility requests, and test fixes across multiple sessions. Each new chat forgets which tradeoffs were rejected, whether keyboard movement is required, and which visual polish is out of scope.
+
+## Context package
+
+Profile: prefers direct bug risk calls, small verified steps, and no silent scope expansion. Context: synthetic task board, local-only, no auth, no deployment, existing task data must survive, keyboard accessibility matters, visual redesign is not in scope.
+
+## Acceptance card
+
+Done means the board preserves existing task data, supports drag and keyboard reorder, has tests for both flows, reports changed files and verification output, and leaves a handoff note listing visual polish as unverified rather than done.
+
+## Execution request
+
+Implement only the reorder behavior described in the acceptance card. Keep the existing data shape. Do not redesign the board. After code, report changed files, tests run, failures, and unverified areas.
+
+## Guard review result
+
+Guard finds that mouse reorder was tested but keyboard movement lacks evidence. It rejects completion until a keyboard reorder test exists and the handoff labels visual polish as unverified.
+
+## Handoff note
+
+Current state: mouse drag and keyboard arrow-key reorder are both implemented and covered by tests (2 passing), and the guard re-review accepted the fix. Completed: data shape preserved; keyboard reorder implemented and tested. Pending: only visual polish for the reorder affordance, carried as unverified. Next action: pick up the visual polish, not the keyboard work.
+
+## Harvest seed
+
+Reusable pattern: long coding tasks need an acceptance card before implementation, a guard pass before handoff, and an explicit unverified bucket for visual polish. Do not generalize the synthetic task board data model.
+
+## Difference from raw chat
+
+A raw chat produces a plausible refactor plan but loses rejected scope and unverified accessibility work. The six-layer workspace keeps the goal, done standard, review finding, next action, and reusable lesson visible.

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+This project's source is on GitHub with CI green, but it is **not published to npm**. The version
+below is prepared and unpublished; see [Release Status](./README.md#release-status) for the
+four-state ladder.
+
+## 0.1.0 — Unreleased (GitHub source on `main`, CI green)
+
+Status: source pushed to GitHub on `main` with CI green; **not git-tagged and not published to
+npm**. No release date is claimed because no npm release has happened. The date here will be
+filled in only when the package is actually published.
+
+- Hardened CI: Node 18/20/22 matrix running `npm ci`, `npm run check`, `npm pack`, a fresh-tarball
+  install smoke test (install the packed artifact into a clean dir and run the installed `ai-collab`
+  bin), and a CLI smoke (init/guide/demo/check), so CI blocks "installs but does not run" and broken
+  CLI commands.
+- Rebuilt the generated prompt and skill library as distinct capability packages.
+- Added a flagship synthetic case showing messy input, baseline raw AI output, six-layer intervention, artifacts, comparison, and next step.
+- Hardened CLI first-run behavior: real `ai-collab` commands, `init --dry-run`, required `--target`, required `--workspace`, JSON output, and bin-entry tests.
+- Changed `--force` behavior to back up existing `.aict` content before replacement.
+- Added adapter guidance installer for Codex, Claude Code, Cursor, GitHub Copilot, Cline, and Windsurf.
+- Added privacy scanner coverage for common token, email, and local-path leaks.
+- Added CI, issue templates, PR template, release checklist, and packed-package checks.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,20 @@
+# Code of Conduct
+
+This project is for building safer, more inspectable AI collaboration workflows.
+
+## Expected behavior
+
+- Be concrete and evidence-based.
+- Respect privacy boundaries.
+- Use synthetic examples for public discussion.
+- Separate facts, assumptions, and opinions.
+- Challenge claims without attacking people.
+
+## Unacceptable behavior
+
+- Sharing private user material without consent.
+- Publishing secrets, local paths, or raw private conversations.
+- Harassment or personal attacks.
+- Misrepresenting paid services as required for the open method.
+
+Maintainers may remove issues, discussions, or contributions that violate these boundaries.

package/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing
+
+This project is a local-first open collaboration workspace. Contributions should make the generated workspace more usable, safer to publish, or easier to verify.
+
+## Good contributions
+
+- Better synthetic cases.
+- Clearer templates.
+- More precise adapter instructions.
+- Stronger privacy checks.
+- Better contract tests.
+- Bilingual clarity improvements.
+
+## Not a fit
+
+- Uploading user content by default.
+- Adding hidden scoring or private calibration.
+- Turning the CLI into a hosted assistant.
+- Making paid help necessary for the generic loop.
+- Copying private workflows or real user material into examples.
+
+## Before opening a change
+
+Run:
+
+```bash
+npm run check
+```
+
+The check must pass before a change can be treated as release-ready.

package/KNOWN_LIMITATIONS.md

@@ -0,0 +1,54 @@
+# Known Limitations
+
+Honest, known boundaries of this tool. These are real and documented on purpose — the
+whole point of the project is to not pretend a "done" (or a tool) is more than it is, and
+that honesty applies to the tool itself. Nothing here is a secret failure mode; each entry
+says what the limit is, when it can bite, and what catches or works around it.
+
+## Concurrent writes and duplicate ids — now mitigated by a file lock
+
+**What it is.** Each ledger id (`t1`, `e2`, `c1`, `r1`, …) is allocated by reading the
+existing rows, taking the highest numeric suffix, and returning the next one (`nextId` in
+`src/ledger.js`). That is a *read-then-write*: the new id is decided from what is on disk at
+read time, then appended. Historically, if two writes ran **at the same moment** against the
+**same workspace** (e.g. two CLI processes, or two AI tools driving the same `.aict/` in
+parallel), both could read the same highest id and then both append the same next one —
+producing two rows with the same id in one ledger.
+
+**Mitigation (file lock).** The id-allocation path is now serialized with a short on-disk
+mutex. `withLedgerLock(stateDir, fn)` in `src/ledger.js` creates a lock file with
+`openSync(lockPath, 'wx')` (the `O_EXCL` "create only, fail if it exists" flag), so exactly
+one process holds it at a time; a loser retries with a small backoff (~25 ms) up to a ~5 s
+timeout, and a **stale** lock left by a crashed process is reclaimed once it is older than
+~10 s so the ledgers can never wedge permanently. The whole *read → compute next id → append*
+(and run finish's *read-all → patch → rewrite*) happens **inside** the lock, with the ledger
+re-read after the lock is held, so concurrent writers each see every row the others already
+committed and cannot mint the same id. Verified by a test that spawns 15 truly-parallel
+`task create`s and asserts zero duplicate ids (`tests/contract.test.js`, "B6a-2"); with the
+lock disabled the same test reliably fails, which is how we know the lock — not luck — is
+doing the work.
+
+**Residual edge.** This is a best-effort local lock, not a distributed transaction. The
+stale-lock reclamation window means a process paused (e.g. swapped out / suspended) for longer
+than ~10 s while mid-write could in theory have its lock stolen — vanishingly unlikely for the
+sub-millisecond ledger writes here, but not a hard mathematical guarantee. Networked or
+case-insensitive filesystems with unusual `O_EXCL` semantics are likewise out of scope.
+
+**What still catches anything that slips through.** The integrity check remains the backstop.
+`node bin/ai-collab.js check --workspace <dir>/.aict` (also run by `npm run check`) validates
+per-ledger id integrity and fails loudly with, for example:
+
+```text
+Contract check failed:
+- ledger tasks.jsonl has duplicate id "t1"
+```
+
+So even in the residual edge, a duplicate cannot silently corrupt your trust trail: the next
+`check` surfaces it with a pointable file + id. (The guard-level and acceptance logic also
+recompute from evidence rather than trusting a stored field, so a duplicated row cannot quietly
+upgrade a result.)
+
+**How to recover.** If `check` ever reports a duplicate id, open the named `.jsonl` ledger
+(plain JSON-lines, one record per line) and remove or renumber the offending duplicate row,
+then re-run `check` to confirm it is clean. The ledgers remain plain, hand-inspectable files;
+the lock is a thin coordination layer around the id allocation, not an opaque database.