ai-collab-open-system 0.1.0

package/.aict/adapters/copilot/ADAPTER.md

@@ -0,0 +1,28 @@
+# GitHub Copilot Adapter
+
+Use repository instructions and prompt files to apply the shared workflow.
+
+## Shared contract pointer
+
+Read `../SHARED_CORE_CONTRACT.md` before acting. This adapter is intentionally thin so the profile, context, acceptance, guard, handoff, and harvest rules do not drift.
+
+## How to use
+
+1. Attach or paste `../SHARED_CORE_CONTRACT.md`.
+2. Attach the layer file you need, such as `../../context/TEMPLATE.md`.
+3. Attach the current context package or synthetic case.
+4. Ask GitHub Copilot to return the required artifact shape.
+
+## Minimal instruction
+
+```text
+Use the local AI collaboration workspace. Follow SHARED_CORE_CONTRACT.md. For this task, use profile, context, acceptance, guard, handoff, and harvest as explicit files. Do not invent hidden memory. Label assumptions and unverified claims.
+Follow the coaching layer in SHARED_CORE_CONTRACT.md: proactively remind me at key collaboration moments (defining done, reviewing completion claims, handoff, harvest, profile updates), restrained by default.
+```
+
+## What this adapter must not do
+
+- It must not duplicate the full core contract.
+- It must not create a separate rule system.
+- It must not upload private material.
+- It must not overwrite user files silently.

package/.aict/adapters/cursor/ADAPTER.md

@@ -0,0 +1,28 @@
+# Cursor Adapter
+
+Use Cursor rules to load the shared workspace contract and task files.
+
+## Shared contract pointer
+
+Read `../SHARED_CORE_CONTRACT.md` before acting. This adapter is intentionally thin so the profile, context, acceptance, guard, handoff, and harvest rules do not drift.
+
+## How to use
+
+1. Attach or paste `../SHARED_CORE_CONTRACT.md`.
+2. Attach the layer file you need, such as `../../context/TEMPLATE.md`.
+3. Attach the current context package or synthetic case.
+4. Ask Cursor to return the required artifact shape.
+
+## Minimal instruction
+
+```text
+Use the local AI collaboration workspace. Follow SHARED_CORE_CONTRACT.md. For this task, use profile, context, acceptance, guard, handoff, and harvest as explicit files. Do not invent hidden memory. Label assumptions and unverified claims.
+Follow the coaching layer in SHARED_CORE_CONTRACT.md: proactively remind me at key collaboration moments (defining done, reviewing completion claims, handoff, harvest, profile updates), restrained by default.
+```
+
+## What this adapter must not do
+
+- It must not duplicate the full core contract.
+- It must not create a separate rule system.
+- It must not upload private material.
+- It must not overwrite user files silently.

package/.aict/adapters/windsurf/ADAPTER.md

@@ -0,0 +1,28 @@
+# Windsurf Adapter
+
+Use Windsurf rules to keep the same six-layer workflow available.
+
+## Shared contract pointer
+
+Read `../SHARED_CORE_CONTRACT.md` before acting. This adapter is intentionally thin so the profile, context, acceptance, guard, handoff, and harvest rules do not drift.
+
+## How to use
+
+1. Attach or paste `../SHARED_CORE_CONTRACT.md`.
+2. Attach the layer file you need, such as `../../context/TEMPLATE.md`.
+3. Attach the current context package or synthetic case.
+4. Ask Windsurf to return the required artifact shape.
+
+## Minimal instruction
+
+```text
+Use the local AI collaboration workspace. Follow SHARED_CORE_CONTRACT.md. For this task, use profile, context, acceptance, guard, handoff, and harvest as explicit files. Do not invent hidden memory. Label assumptions and unverified claims.
+Follow the coaching layer in SHARED_CORE_CONTRACT.md: proactively remind me at key collaboration moments (defining done, reviewing completion claims, handoff, harvest, profile updates), restrained by default.
+```
+
+## What this adapter must not do
+
+- It must not duplicate the full core contract.
+- It must not create a separate rule system.
+- It must not upload private material.
+- It must not overwrite user files silently.

package/.aict/context/EXAMPLE.synthetic.md

@@ -0,0 +1,53 @@
+# Context Filled Synthetic Example
+
+## Purpose
+
+Package the task so an assistant can start from the right boundary, evidence, constraints, and unknowns without reading the whole history.
+
+## When to use
+
+Use at the start of any task that spans more than one message, touches files, involves judgment, or may be resumed later.
+
+## Input shape
+
+Goal, current state, relevant files or links, constraints, non-goals, known facts, assumptions, risks, and open questions.
+
+## Output shape
+
+A context package that lets another assistant continue without inventing missing background.
+
+## Copy-paste prompt
+
+Use `PROMPT.md` with the synthetic input below.
+
+## Blank template
+
+Use `TEMPLATE.md` for your own task.
+
+## Filled synthetic example
+
+Goal: Prepare a public beta onboarding flow for a synthetic note app.
+
+Current state: Landing copy exists; onboarding has not been tested.
+
+Relevant artifacts: README draft, onboarding checklist, synthetic tester notes.
+
+Constraints: No analytics SDK until privacy language is reviewed.
+
+Non-goals: Payment, account recovery, enterprise SSO.
+
+Facts: Three testers abandoned before creating a first note.
+
+Assumptions: The first-run prompt may be too abstract.
+
+Risks: Improving copy without testing the actual flow.
+
+Open questions: Which first action should count as activation?
+
+## Common failure modes
+
+See `FAILURE_MODES.md`.
+
+## How to hand it to Claude Code / Codex / Cursor / Windsurf / Copilot / Cline
+
+Paste this example into any tool with `../adapters/SHARED_CORE_CONTRACT.md` to see the expected shape.

package/.aict/context/FAILURE_MODES.md

@@ -0,0 +1,40 @@
+# Context Common Failure Modes
+
+## Purpose
+
+Package the task so an assistant can start from the right boundary, evidence, constraints, and unknowns without reading the whole history.
+
+## When to use
+
+Read this before trusting a context artifact.
+
+## Input shape
+
+The artifact plus the original context and acceptance card.
+
+## Output shape
+
+A short list of risks to fix before reuse.
+
+## Copy-paste prompt
+
+Ask your AI tool: "Check this context artifact against the failure modes below and name the first concrete fix."
+
+## Blank template
+
+Use `TEMPLATE.md` to rewrite the artifact.
+
+## Filled synthetic example
+
+Use `EXAMPLE.synthetic.md` to compare a safe example.
+
+## Common failure modes
+
+- Dumping the whole history instead of compressing decision-changing facts.
+- Not labeling assumptions.
+- Forgetting non-goals, causing assistants to expand scope.
+- Including private file paths or raw conversations.
+
+## How to hand it to Claude Code / Codex / Cursor / Windsurf / Copilot / Cline
+
+Paste this file after the artifact and ask for findings ordered by risk.

package/.aict/context/PROMPT.md

@@ -0,0 +1,47 @@
+# Context Prompt
+
+## Purpose
+
+Package the task so an assistant can start from the right boundary, evidence, constraints, and unknowns without reading the whole history.
+
+## When to use
+
+Use at the start of any task that spans more than one message, touches files, involves judgment, or may be resumed later.
+
+## Input shape
+
+Goal, current state, relevant files or links, constraints, non-goals, known facts, assumptions, risks, and open questions.
+
+## Output shape
+
+A context package that lets another assistant continue without inventing missing background.
+
+## Copy-paste prompt
+
+```text
+Turn this messy situation into a context package. Separate facts from assumptions. Include goal, current state, relevant artifacts, constraints, non-goals, risks, and open questions. Keep private material summarized or redacted.
+
+Input:
+[paste your redacted task material here]
+
+Output shape:
+A context package that lets another assistant continue without inventing missing background.
+
+Rules:
+- Keep private material local and redacted.
+- Label facts and assumptions.
+- If information is missing, ask at most three concrete questions.
+- Make the result usable in Claude Code / Codex / Cursor / Windsurf / Copilot / Cline.
+```
+
+## Blank template
+
+Use `TEMPLATE.md`.
+
+## Filled synthetic example
+
+Use `EXAMPLE.synthetic.md`.
+
+## Common failure modes
+
+Use `FAILURE_MODES.md`.

package/.aict/context/README.md

@@ -0,0 +1,44 @@
+# Context
+
+What the task boundary is, what is known, and what should not be assumed.
+
+中文：把当前任务边界写清楚，避免新会话靠猜。
+
+## Purpose
+
+Package the task so an assistant can start from the right boundary, evidence, constraints, and unknowns without reading the whole history.
+
+## When to use
+
+Use at the start of any task that spans more than one message, touches files, involves judgment, or may be resumed later.
+
+## Input shape
+
+Goal, current state, relevant files or links, constraints, non-goals, known facts, assumptions, risks, and open questions.
+
+## Output shape
+
+A context package that lets another assistant continue without inventing missing background.
+
+## Copy-paste prompt
+
+See `PROMPT.md`. The prompt is designed to work in Claude Code / Codex / Cursor / Windsurf / Copilot / Cline.
+
+## Blank template
+
+See `TEMPLATE.md`.
+
+## Filled synthetic example
+
+See `EXAMPLE.synthetic.md`.
+
+## Common failure modes
+
+See `FAILURE_MODES.md`.
+
+## How to hand it to Claude Code / Codex / Cursor / Windsurf / Copilot / Cline
+
+1. Open the adapter for your tool in `../adapters/`.
+2. Include `../adapters/SHARED_CORE_CONTRACT.md`.
+3. Paste this layer's `PROMPT.md` plus either `TEMPLATE.md` or `EXAMPLE.synthetic.md`.
+4. Ask the tool to return the layer's output shape exactly.

package/.aict/context/TEMPLATE.md

@@ -0,0 +1,63 @@
+# Context Template
+
+## Purpose
+
+Package the task so an assistant can start from the right boundary, evidence, constraints, and unknowns without reading the whole history.
+
+## When to use
+
+Use at the start of any task that spans more than one message, touches files, involves judgment, or may be resumed later.
+
+## Input shape
+
+Goal, current state, relevant files or links, constraints, non-goals, known facts, assumptions, risks, and open questions.
+
+## Output shape
+
+A context package that lets another assistant continue without inventing missing background.
+
+## Copy-paste prompt
+
+Open `PROMPT.md` and paste this completed template below it.
+
+## Blank template
+
+### Goal:
+
+
+### Current state:
+
+
+### Relevant artifacts:
+
+
+### Constraints:
+
+
+### Non-goals:
+
+
+### Facts:
+
+
+### Assumptions:
+
+
+### Risks:
+
+
+### Open questions:
+
+
+
+## Filled synthetic example
+
+See `EXAMPLE.synthetic.md`.
+
+## Common failure modes
+
+See `FAILURE_MODES.md`.
+
+## How to hand it to Claude Code / Codex / Cursor / Windsurf / Copilot / Cline
+
+Use the adapter in `../adapters/` and include the shared core contract.

package/.aict/cookbook/README.md

@@ -0,0 +1,8 @@
+# Cookbook
+
+Do-it recipes for running the AI Collaboration Open System. Each recipe is a full configuration: when to use it, prerequisites, steps, a copy-paste block you can actually run, expected output, failure handling, a privacy note, and a next step. The walkthroughs are operation cards ("press these in this order"); these recipes explain why each step exists and how to adapt it to your own task.
+
+- `run-a-first-loop.md`: run one complete collaboration loop end to end on your own real task; the prepared synthetic case is an optional "watch the flow first" track.
+- `connect-a-tool.md`: wire any AI tool (general chat AI, coding assistant, command-line AI) to the shared contract by copying files into its instruction slot.
+- `review-a-half-product.md`: audit a "done but maybe not" deliverable by forcing an independent AI to cite evidence and find the gap.
+- `bridge-to-a-second-family.md`: stand up the second, different-model-family AI the cross-family guard needs, and route a review across it — manual copy-paste (works anywhere) or an optional auto bridge.

package/.aict/cookbook/bridge-to-a-second-family.md

@@ -0,0 +1,103 @@
+# Bridge to a Second Family
+
+A do-it recipe: set up the second, different-model-family AI that the cross-family guard needs, and route a review across it. The rest of the system keeps telling you "when a second, different model family is available, you can upgrade to the cross-family double guard" — this recipe is the missing how. It does not redefine the guard: `../mechanisms/dual-guard/README.md` owns the judgment rules (L3 vs L4, binding vs reference, layered strictness over majority vote, the pass and reject bars). This recipe only covers the part those rules assume you already did: pick a second family, get your material across to it safely, and keep evidence that the second family actually ran.
+
+There are two tracks. The manual bridge (copy-paste between two AIs) is the main path: it works with any two tools, needs no setup, and never breaks. The auto bridge (a tool that dispatches the review to another family for you) is an optional convenience. Start manual; reach for auto only if a tool you already use offers it.
+
+## When to use this
+
+- A completion claim is about to be trusted by another session, tool, or person, and you want the cross-family binding gate the dual-guard mechanism describes — but you only have one tool wired up so far.
+- You keep stopping at "upgrade to a second model family" and do not know how to actually stand one up.
+- You have run `single-tool-guard` and want to move a result above its L2 ceiling with a genuine cross-family pass.
+
+Skip it for low-stakes, easily reversible work a human will fully re-check anyway. A single tool's own adversarial pass (`../mechanisms/single-tool-guard/README.md`) is the right tool there; bridging to a second family is the upgrade for work that will propagate.
+
+## Prerequisites
+
+- A redacted version of the artifact under review (swap private names, paths, and numbers for placeholders). Nothing private needs to leave your machine; a redacted copy is enough.
+- Its acceptance card or one-line "done" claim, and the evidence that supposedly backs it (command output, test result, a reproduced result, or a clear note that none exists).
+- One AI tool you already use as your primary (the family that drafted the work, or any family you treat as home base).
+- A second AI that is a DIFFERENT model family from your primary. That is the whole point: a different family does not share your primary's blind spots. (How to choose one is Step 1 below — you do not need it set up before you start.)
+
+## Track A — the manual bridge (main path, works with any two tools)
+
+### Step 1. Choose a second family
+
+Pick any AI that is a different model family from your primary tool. The families differ; the move does not. Concrete examples (each is just an example — substitute freely):
+
+- Primary is a Claude-family tool? Use a GPT-family or a Gemini-family AI as the second.
+- Primary is a GPT-family tool? Use a Claude-family or a Gemini-family AI as the second.
+- Primary is a Gemini-family tool? Use a Claude-family or a GPT-family AI as the second.
+
+Any different-family pairing works — the names above are illustrations, not a required list. What matters is "different family", not which brands. Two tools that wrap the same underlying family (for example two products both built on the same model) do NOT count as a cross-family pair; the dual-guard mechanism treats that as same-family, capped below the cross-family gate. If you are unsure whether two tools share a family, treat them as same-family until you can confirm otherwise.
+
+### Step 2. Redact before it leaves your primary
+
+The second AI cannot read your disk; to review your material it has to be pasted in. So redact first, exactly as in `connect-a-tool.md`: replace real product names, customer or person names, file paths, and internal numbers with placeholders. Do not paste a private profile, raw private chat logs, internal numbers, or non-public paths into the second AI. The review works on a redacted artifact plus its evidence; it does not need the private original.
+
+### Step 3. Send the package across and run the cross-family review
+
+This is your move to make, not the second AI's — it cannot read your disk, so you fetch the file contents and paste them in. On your own machine, open `../mechanisms/dual-guard/PROMPT.md` and copy its "Copy-paste prompt" body. Then paste one combined message into the second (different-family) AI: the carrier wrapper below, the dual-guard body you just copied, and your redacted material (artifact, acceptance card, context boundary, evidence). The carrier is a thin wrapper that hands the pasted dual-guard body to the second AI as its instructions; it does not restate the guard's rules, because the dual-guard mechanism owns them.
+
+### Step 4. Collect the verdict and record binding evidence
+
+Read back the verdict using the dual-guard pass and reject bars (do not re-derive them here). Then record what makes the result trustworthy later: which family was the binding guard, the findings, the fixes, and the residual risk. A bridge to a second family reaches L3 (a structured evidence pack reviewed by a different family). To reach L4, the binding guard must independently re-run the key evidence and reconcile it to a recorded run — re-running the critical check yourself across the second family is what raises a cross-family L3 to L4 (the strongest LOCAL-trust level, not cryptographic proof).
+
+## Copy-paste block (manual bridge)
+
+Paste this into the second, different-family AI. It carries your material to the dual-guard prompt; it deliberately does not repeat the guard's judgment rules.
+
+```text
+Run a cross-family review for me. You are the second, different-model-family guard.
+
+Your full instructions are the Dual Guard prompt body, which I have pasted directly below. Follow it exactly (process, output shape, pass bar, reject bar, guard-level rules). It is the source of truth; do not invent your own rubric. You cannot read my disk, so I am pasting the body in here rather than pointing you at a local file.
+
+--- Dual Guard PROMPT body (begin) ---
+[Paste the Dual Guard PROMPT.md "Copy-paste prompt" body here — open it locally and copy it in yourself; the second AI cannot read your disk.]
+--- Dual Guard PROMPT body (end) ---
+
+Then review this material under the Dual Guard prompt body pasted above:
+- Drafting model family (my primary): [name the family that produced the work]
+- Artifact under review (redacted, with line/section refs): [paste]
+- Acceptance card / definition of done: [paste]
+- Context boundary (goal, in-scope, non-goals): [paste]
+- Evidence provided: [paste command output / test result / reproduced result, or write "none provided"]
+
+Return exactly the dual-guard output shape (verdict, guard level, binding findings, required fixes, residual risk, next action). Work only from what I pasted; if key evidence is missing, say so rather than assume it passes. Keep examples public-safe.
+```
+
+## Track B — the auto bridge (optional, point-to-point, depends on your tool)
+
+Some tools can dispatch the review to a second family for you, so you do not hand-carry the paste. The shape is the same cross-family pass; the tool just automates the hand-off.
+
+Concrete example (an example, not a requirement): a coding tool that supports a "rescue" or cross-model plugin can route a review to a different family — for instance a Claude-family coding tool with a plugin that sends the review to a GPT-family model. That auto-dispatched second model is your cross-family bridge.
+
+Two rules make an auto bridge safe to trust:
+
+- Read-only is mandatory. The auto-dispatched second AI must review only — it must NOT be allowed to edit your files. If the bridge lets the second AI change the work, it is no longer an independent reviewer of that work, and the cross-family independence the whole gate depends on is gone. Configure the dispatch as read-only and confirm it actually ran read-only before you trust the verdict.
+- It is convenience, not a requirement. The auto bridge depends on a specific tool and integration, and those change over time. The manual bridge in Track A always works. Treat the auto bridge as a way to save effort, never as the only way to reach a second family.
+
+Everything else — which verdicts are allowed, the L3/L4 boundary, binding vs reference — is unchanged and still lives in `../mechanisms/dual-guard/README.md`. The auto bridge changes how the material gets there, not what counts as a pass.
+
+## Expected output
+
+- A cross-family review of your artifact, returned in the dual-guard output shape (verdict, guard level, findings, fixes, residual risk, next action).
+- A recorded note of which family was the binding guard, so a later session can trust the result without re-litigating it.
+- Honest leveling: an L3 result from the second family's review of your evidence pack, or L4 only if the binding guard re-ran the key evidence and showed that output. A bare claim that "a second family looked at it" is not a pass — the evidence is.
+
+## Failure handling
+
+- Your two tools turn out to share a model family. Then this is a same-family reference pass, not a cross-family gate; under the dual-guard rules it cannot clear the binding gate or move you above L2. Find a genuinely different family for the binding pass.
+- The second family just says "looks good" with no specifics. It is grading tone, not claims. Make sure you pasted the dual-guard prompt body (not only the carrier wrapper) so its "each finding cites a line/section/missing evidence" rule is in force; an empty finding list is only valid if it can say what it checked.
+- You only claimed a second family but kept no evidence. Family can be faked — anyone can say "a different AI reviewed this". What is hard to fake is a rerun and a reconciliation: record the binding family, the findings, and, for L4, your own rerun output. If you cannot show the review happened, treat the result as single-tool (L2), not cross-family.
+- The auto bridge ran with write access. Discard the verdict and re-run it read-only. A reviewer that could edit the work is not independent of it.
+
+## Privacy note
+
+A second family means a second place your material gets pasted, so the privacy bar is the same as `connect-a-tool.md`, applied twice. Redact before pasting into either tool: replace real product names, customer or person names, file paths, and internal numbers with placeholders. Do not paste a private profile, raw private chat logs, internal numbers, or non-public paths into any external AI. For an auto bridge, confirm the dispatched second AI is read-only and does not exfiltrate or store your content beyond the review. The cross-family review works on a redacted artifact plus its evidence; it never needs the private original.
+
+## Next step
+
+- Read the judgment rules this recipe feeds into: `../mechanisms/dual-guard/README.md` (L3 vs L4, binding vs reference, pass and reject bars).
+- Coming from one tool? See the L2 front door you are upgrading from: `../mechanisms/single-tool-guard/README.md`.
+- Wire the second family in as a standing tool so the bridge is one trigger away: `connect-a-tool.md`.

package/.aict/cookbook/connect-a-tool.md

@@ -0,0 +1,67 @@
+# Connect a Tool
+
+A do-it recipe: point any AI tool you already use at this workspace, so the same profile, context, acceptance, guard, handoff, and harvest rules drive every tool instead of six drifting rule systems. The key idea is that every mechanism here is just a Markdown file. You connect a tool by copying file contents into that tool's instruction slot. Nothing depends on this CLI staying installed; the CLI only writes the files.
+
+## When to use this
+
+- You have a favorite AI tool (a general chat AI, a coding assistant, or a command-line AI) and want it to follow this system's loop.
+- You use more than one tool and they each behave differently because each has its own ad hoc rules.
+- You want a mechanism (like a guard pass) available inside your tool as a reusable instruction, not something you re-type every time.
+
+Skip it if you only ever read these files by hand and never paste them into a tool.
+
+## Prerequisites
+
+- This workspace exists locally.
+- The AI tool you want to connect, and knowledge of where it accepts standing instructions. Three common shapes: a general chat AI uses a "system prompt" or "custom instructions" box; a coding assistant uses a project rules file (for example a `CLAUDE.md`, an `AGENTS.md`, a `.cursorrules`, a `.clinerules`, or an equivalent); a command-line AI uses its config or a per-project instruction file.
+- Two minutes per tool. This is copy and paste, not installation.
+
+## Steps
+
+1. Open the shared contract. Open `../adapters/SHARED_CORE_CONTRACT.md`. This is the one rule source every tool should share so the loop does not drift between tools.
+2. Open the adapter for your tool family. Look in `../adapters/` for the closest match to your tool (each adapter is a thin pointer, intentionally not a second copy of the contract). If none matches exactly, pick the nearest one. The adapter shows the minimal instruction your tool needs.
+3. Put the contract where your tool reads standing instructions. For a chat AI, paste the contract into the system-prompt or custom-instructions box. For a coding assistant, save it (or a pointer to it) into that tool's project rules file. For a command-line AI, add it to the tool's config or per-project instruction file. Use the copy-paste block below.
+4. Add one mechanism as a reusable instruction (optional but the high-value move). Pick a mechanism you want on tap, for example `../mechanisms/dual-guard/PROMPT.md` or `../guard/PROMPT.md`. Copy the prompt body from that file's "Copy-paste prompt" block into a saved prompt, snippet, or rule in your tool, so a guard pass is one trigger away instead of a retype.
+5. Verify the wiring with a throwaway ask. Tell the tool: "State the core loop you are now following and where each step's rules live." A correctly connected tool names profile, context, acceptance, guard, handoff, harvest and treats them as explicit files, instead of inventing hidden memory.
+6. Save anything worth keeping back into this workspace (a filled template, a handoff, a harvest card) so the next tool or session starts from the same files.
+
+## Copy-paste block
+
+Two pieces. The first wires the whole loop into a tool. The second drops a single mechanism in as a reusable instruction. Before pasting, open the referenced file and paste its real contents where marked; do not paste the file path and expect the tool to read your disk.
+
+```text
+[A / WIRE THE LOOP INTO A TOOL - paste into the tool's system prompt or project rules file]
+Follow this shared contract for our work. Treat profile, context, acceptance, guard/review, handoff, and harvest as explicit files in a local-first workspace, not as hidden memory. Work local-first; do not upload my content by default. Label facts, assumptions, decisions, and unverified claims. Use synthetic, redacted examples for anything I might share publicly.
+--- shared contract begins ---
+[paste the full contents of ../adapters/SHARED_CORE_CONTRACT.md here]
+--- shared contract ends ---
+
+[B / ADD ONE MECHANISM AS A REUSABLE INSTRUCTION - save as a snippet, saved prompt, or rule]
+When I invoke this, run the mechanism below on the material I provide. Keep private material local and redacted. Point findings to specific spots. Return the mechanism's stated output shape, not a vague summary.
+--- mechanism prompt begins ---
+[paste the "Copy-paste prompt" block from ../mechanisms/<mechanism>/PROMPT.md here]
+--- mechanism prompt ends ---
+```
+
+## Expected output
+
+- Your tool, when asked, can name the core loop (profile, context, acceptance, guard, handoff, harvest) and treats each as a file rather than invented memory.
+- At least one mechanism is reachable inside the tool as a saved instruction you can trigger without retyping it.
+- The same contract now drives every tool you connected this way, so behavior is consistent across tools.
+
+## Failure handling
+
+- The tool ignores the standing instruction. You likely pasted into a one-off chat turn instead of the persistent slot. Move the contract into the actual system-prompt box or project rules file so it survives across turns.
+- The tool "can't find" a referenced file. Tools generally cannot read your disk from a path in a prompt. Paste the file's contents inline (as the block marks), not just its path. Files are the source of truth; pasting is how a tool sees them.
+- Behavior still drifts between two tools. Confirm both point at the same single `SHARED_CORE_CONTRACT.md` and that neither has an older private rule set fighting it. One contract, many thin adapters; never six full rule systems.
+- The adapter looks too thin and you want to fatten it. Do not. The adapter is meant to be a pointer; thickening it recreates the drift the shared contract exists to prevent.
+
+## Privacy note
+
+Connecting a tool means standing instructions, not your private data. Paste the contract and mechanism prompts (they are public-safe). Do not paste a private profile, raw private chat logs, internal numbers, or non-public paths into a tool's instruction slot or an external AI. When you later run real tasks through the connected tool, redact first and keep originals local; the loop is designed to work on a redacted description.
+
+## Next step
+
+- Run a full loop through the tool you just connected: `run-a-first-loop.md`.
+- Use the connected tool to pressure-test a "done" artifact: `review-a-half-product.md`.
+- Browse the other mechanisms you can wire in the same way: `../mechanisms/README.md`.

package/.aict/cookbook/review-a-half-product.md

@@ -0,0 +1,79 @@
+# Review a Half Product
+
+A do-it recipe: audit a deliverable that says "done" but might not be, by forcing an independent AI to point at evidence and find the gap, instead of nodding along with "looks good". It uses the review mode plus the dual-guard and half-product-review mechanisms. The target is the classic half product: lots of docs, demo, and confident prose, but the thing it claims a stranger can do does not actually run.
+
+## When to use this
+
+- Someone (a tool, another session, a contributor) hands you work claimed complete and you will build on it or ship it.
+- A project has a polished README and architecture talk but you are not sure the first-run experience actually works.
+- A completion claim feels too smooth and you want a second, independent pass before you trust it.
+
+Skip it for low-stakes, easily reversible work, or a step you are about to fully re-check yourself anyway. Running a full review on trivial work is ceremony, and ceremony with no payoff trains people to skip review when it matters.
+
+## Prerequisites
+
+- The artifact under review, with stable references the reviewer can point to (line numbers, section anchors, or named files).
+- Its definition of done: an acceptance card, or at least the public claim it makes ("a stranger can do X in ten minutes").
+- The evidence that supposedly backs the claim: command output, test results, a reproduced result, or a clear note that none exists.
+- An AI tool to run the review in, ideally a different model family from whatever produced the artifact, since a different family is the pass most likely to see what the author cannot.
+
+## Steps
+
+1. Pin the claim. Write down, in one line, exactly what the artifact claims is done or usable. A claim you cannot state is a claim you cannot test. If it has an acceptance card, use that; if not, lift the strongest promise from its README or start page.
+2. Trace each claim to evidence. For every claim, find the file, command output, or test that proves it, or note that none exists. The half-product pattern is docs and demos that point at nothing runnable. A claim with no evidence is the finding.
+3. Try the first-run path. If the claim is "a stranger can do X", do X the way a stranger would: run the entry command, open the file the docs point to, follow the start page. Watch where it breaks or where a referenced artifact is missing.
+4. Run the independent guard. Paste the artifact, the acceptance card or pinned claim, and any evidence into the review prompt below, in a second tool. Demand findings tied to specific lines or missing evidence, ordered by severity, with a pass or reject. Do not accept a fluent "looks fine".
+5. Merge by strictness, not vote. If the guard names one real, evidence-grounded blocker, the artifact does not pass, even if everything else reads well. One concrete defect outweighs a pile of fluent approval. Compare against `../mechanisms/dual-guard/README.md` for how the binding pass works.
+6. Decide the wording. If the first-run path is not actually runnable, downgrade the release language (from "anyone can use this" to "early / not yet runnable end to end") or carry the gap as named residual risk the owner accepts on the record. Silent "good enough" is not allowed.
+
+## Copy-paste block
+
+Paste this into an independent AI tool, ideally a different model family from the one that produced the work. It is tuned to make the reviewer hunt for the gap and cite it, not to praise.
+
+```text
+You are an independent reviewer. The work below claims to be complete or usable. Assume it might not be, and prove it either way against the evidence, not the tone.
+
+Claim under test: [paste the one-line "done"/usable claim, or the acceptance card]
+Artifact: [paste the artifact, or the README/start page and the key files it points to]
+Evidence provided: [paste command output / test results / reproduced result, or write "none provided"]
+
+Do this:
+1. For each claim, name the specific evidence that backs it, or state that none was provided.
+2. Walk the first-run path a stranger would take. Say exactly where it breaks or where a referenced file/command is missing.
+3. List defects ordered by severity. Tie each to a line, section, or the specific missing evidence. No vague "looks good" or "seems fine".
+4. If any one real, evidence-grounded blocker exists, the verdict is REJECT even if the rest reads well.
+
+Return:
+- Verdict: pass / reject / insufficient_evidence / pass_with_risk (a plain pass needs an L3+ cross-family evidence pack; a single tool tops out at pass_with_risk; summary-only is insufficient_evidence)
+- Guard level: L0-L4, the strength of the evidence you actually had. The CLI COMPUTES this from your review method + the evidence (it is not self-declared); a cross-family L3 is shown "self-declared, unverified" because a local tool cannot verify the reviewer's family — L4 (that cross-family review AND a rerun reconciled to a recorded run) is the strongest LOCAL-trust level, not cryptographic proof.
+- Findings (each tied to a line, section, or missing evidence)
+- Required fixes (the smallest change each blocker needs)
+- Residual risk (what stays unverified and who must accept it; a pass_with_risk needs an explicit owner sign-off)
+- Recommended release wording (downgrade it if the first-run path is not runnable)
+
+Rules: work only from what I provided; if key evidence is missing, say so rather than assuming it passes; keep examples public-safe.
+```
+
+## Expected output
+
+- A verdict: pass, reject, insufficient_evidence, or pass_with_risk, plus the guard level (L0-L4) for the evidence seen.
+- A findings list where each item points to a line, section, or a specific missing piece of evidence, not a vibe.
+- The exact first-run step where the experience breaks, if it does.
+- The smallest fixes required before the work can wear its completion label, and recommended release wording.
+
+## Failure handling
+
+- The reviewer just approves it. It is grading tone, not claims. Re-run and force step 1: every claim must be matched to specific evidence or marked unproven; "looks good" is not a finding.
+- The reviewer invents evidence or assumes the path works. Tell it to work only from what you pasted and to say "none provided" rather than assume. If it cannot see the evidence, that absence is itself the result.
+- Two reviewers disagree (one approves, one rejects). Do not average them. If the rejection points to a real, evidence-grounded defect, it wins; one concrete blocker beats fluent approval.
+- You only have the same tool the author used. Run it anyway in a fresh session, but treat the pass as weaker: same model family tends to miss the same things, so a clean result here is a reference, not a guarantee.
+
+## Privacy note
+
+Review the work, not your private data. Redact before pasting: replace real product names, customer or person names, file paths, and internal numbers with placeholders. Do not paste a private profile, raw private chat logs, or non-public paths into an external AI for review. The review works on a redacted artifact plus its evidence; it does not need the private original.
+
+## Next step
+
+- Use the full two-layer review behind this on higher-stakes artifacts: `../mechanisms/dual-guard/README.md`.
+- See the dedicated mechanism for the docs-outrun-runtime pattern: `../mechanisms/half-product-review/README.md`.
+- After a reject, package the exact remaining work for whoever fixes it: `../mechanisms/handoff-abc/README.md`.