Shared projects: Agent Contract

A folder is linked when .testmuai/assurance.json names a TestMu AI Test Manager project and the folder has no .context/. In a linked folder the commands below work in the shared project, so the team sees what each person saves. Link a folder with kane-cli context ingest <files> --project <id> --mode agent (or kane-cli context extract --project <id> --mode agent, or, where kane-cli context pull --help lists --project, kane-cli context pull --project <id> --mode agent); find the id with kane-cli projects list --search <name> --agent. In a folder with neither a link nor .context/, --mode agent without --project goes on locally without asking, as before: context ingest makes a local store, and context extract refuses NO_STORE until one exists.

Nothing reaches the project until kane-cli context sessions save. Other assurance commands are refused in a linked folder (REMOTE_UNSUPPORTED, §6). Local-store parsing stays in references/assurance-parsing.md.

1. Which flag

• Stderr. Only a command line holding --mode agent keeps stderr free of the "Skill update available" and "Update available" banners. Under --agent those lines can appear on stderr, and testrun run also writes its coverage lines and kane-cli evidence serve hints there. Parse stdout only; a stderr line is not a failure.
• No flag, no terminal. Linked context extract and design tests refuse with a stderr line (exit 2). Linked context ingest falls back to land-only: it uploads, prints text lines and leaves the session paused. Always pass the flag.
• Modes to avoid. --mode ci on linked extract, design or reconcile is refused as a stderr line (exit 2), even with --json. --json with --mode agent is refused as a stderr line (exit 2). --mode override answers every question with its recommended option: never use it for the person.
• Usage errors. With --mode agent anywhere on the command line, a parse error arrives as error USAGE + done{refused, 2}; --help and --version print only a done line.

2. Stream shape

Assurance stream (context …, design tests, maintain …, cover): one JSON object per line, envelope {"type": "<name>", "v": 1, "verb": "<verb>", …}. No stream_start, and don't rely on a ts field here. Verbs: sync (context pull in a linked folder; refusals of its flags and at its entry carry pull), extract (ingest and extract; reconcile from the upload on when the ingest is a new version of a source the project holds), design, evolve, reconcile, save, discard, cover. Refusals of context sessions (list, show, clean) are stamped save, and those of context list are stamped list.

Run stream (testmd run, testrun run): opens with stream_start {cli_version, surface, pid}; every line carries v and ts. Shapes: references/testmd.md, references/testrun.md; linked-folder additions in §3.7.

Outputs that are not the envelope and have no done (read the exit code):

Refusals of context list and context sessions do use the envelope: error + done.

Dispatch on type, never on position. The vocabulary is open: tolerate unknown event types and unknown fields. A stream that should end in done and doesn't means the process died: check kane-cli context sessions --mode agent before retrying anything paid.

3. Event catalogue

"Tell the person" is plain words. Never show event or field names.

3.1 Linking and loading (every assurance verb)

3.2 Ingest, extract, review, evolve

3.3 session_paused (exit 3)

Every pause has sid, expires_at: null and pending_questions[] (empty unless questions wait); most carry resume (the exact command). Branch on reason:

3.4 Save and discard

test_manager (when the project's Test Manager takes the cases): total, created, updated, already_there, waiting with waiting_on[{scenario, title, reason}] (changed_both_sides, not_pushable, archived, busy, not_accepted), next_run[{scenario, title}] (written by the next testmd run), not_covered?[], error?, support_id?, next?. Tell: "N test cases created and M updated in Test Manager"; name what waits and why.

test_files (design, reconcile and evolve sessions): written[] (paths in .testmuai/tests/), refused[{test, title, reason, file?}] (reason is prose; a file edited by hand is kept), replaced?[] (files of tests this save replaced: they stay in the folder, won't run any more, and a bare testrun run still picks them up; tell the person, and offer to move them out of .testmuai/tests/), variables_needed?{file, variables}, no_start_page?[], next?; or {written: [], refused: [], error: "TEST_FILES_NOT_WRITTEN", next}. Test files are written only by the save, only in the folder where it runs. Tell: "Wrote N test files." Fill variables_needed before any run.

3.5 Design

3.6 Cover

3.7 testmd run and testrun run in a linked folder

A file directly in .testmuai/tests/ with an assurance: header runs on its scenario's Test Manager case. Its first run authors (about 30–85 credits per test, approximate); later runs replay.

4. next

Shape: next: [{cmd, why}], one runnable command per item (design walls add title). Tolerate a plain string item.

Where: error, session_complete, session_paused, nothing_new, remote_overlap.sessions[], gate_refused, evolve_paused, evolve_skipped, child_end, session_save (saved, behind, and inside test_manager and test_files), a context list row whose tests are out of date, and done (it repeats a pause's next).

• Agent flag. Each cmd already carries --mode agent (--agent for testrun run, testmd run, projects); end a testrun run line in < /dev/null. If a cmd has no agent flag, add the one that command takes (§1) before running it.
• One at a time. Run each cmd as its own command. Never join them with &&.
• Placeholders. A cmd holding <files> (from nothing_new, a behind save) is a template: put in the person's real paths.
• Read it before running it. Some spend credits (context extract, context ingest, design tests, maintain evolve, testmd run, testrun run). Some need the person's word: --allow-unreviewed (designs from a use-case nobody approved), --force (replaces a use-case's tests), context sessions save --yes (publishes to the team's project and Test Manager), context sessions discard --yes (throws the session's work away). A next built from a partial --answer set carries the answers already given.
• No next? Read remedy: prose that may name a command. Add the agent flag that command takes (§1) before running it. Refusals at a folder's entry (linking, sign-in, access, REMOTE_UNSUPPORTED) carry remedy only; §6 gives the command for each. For projects, read stderr.

5. Exit codes

done.status follows the exit (0 complete, 2 refused, 3 paused, 130 interrupted, any other error), with two exceptions: context ingest and maintain reconcile refusals can end done{status:"refused", exit_code:1}, and a failed read of context list, context sessions or cover ends done{status:"error", exit_code:1}. Branch on exit_code.

On the assurance verbs, 3 is a pause (resumable), not a failure: run the pause loop. 130 is a forced stop: resumable only if a session_paused arrived. On testrun run, 3 means cancelled.

6. Refusal codes

Do says what to tell or ask the person and the exact command, so you can go on when the event has no next. "Ask the person:" marks a step only they (or an admin) can take. Never rerun a paid command (extract, ingest, design, evolve, testmd, testrun) blindly: an exit 1 after turns ran has spent credits. <the command> = the refused command as typed.

7. Support ids

A support id looks like as-YYYYMMDDTHHMM-xxxxxxxx. It names one command's attempt for TestMu AI support.

When you ask the person to get help, give them the support id, the command, the code and the message. With no id on the stream, give the rest; never rerun a paid command just to get an id. With KANE_TELEMETRY=0 the id still shows, but nothing is recorded under it: say so.