done-done-axi 0.1.0 → 0.1.1

package/README.md

@@ -94,13 +94,13 @@ npm install -g --prefix ~/.local --allow-git=all github:umeranjum17/done-done-ax
 
 To skip the install, run `npx -y --allow-git=all github:umeranjum17/done-done-axi` wherever this README says `done-done`.
 
-Once 0.1.0 is published, the registry line takes over as the install:
+Once done-done-axi is published to npm, the registry line takes over as the install:
 
 ```sh
 npm install -g --prefix ~/.local done-done-axi
 ```
 
-<!-- TODO(dd-npm-name): when done-done-axi 0.1.0 is published, flip the primary back to the registry line above and make `npx -y done-done-axi` the skip-the-install path. -->
+<!-- TODO(dd-npm-name): when done-done-axi is published to npm, flip the primary back to the registry line above and make `npx -y done-done-axi` the skip-the-install path. -->
 
 **2. Set it up in your app's repo**
 
@@ -109,7 +109,7 @@ cd your-app
 done-done init
 ```
 
-`init` writes a minimal `.done-done.yaml` (only if you don't already have one) that names your app. It never overwrites an existing config. Evidence lives outside the repo, in `~/.done-done/evidence/<app>`, so it outlives the checkout that captured it. Then describe how to capture proof — swap the command for whatever drives your real app and saves screenshots, recordings or logs:
+`init` writes a minimal `.done-done.yaml` (only if you don't already have one) that names your app. A plain `init` never overwrites an existing config. Evidence lives outside the repo, in `~/.done-done/evidence/<app>`, so it outlives the checkout that captured it. Then describe how to capture proof — swap the command for whatever drives your real app and saves screenshots, recordings or logs:
 
 ```yaml
 journeys:
@@ -119,15 +119,18 @@ journeys:
 
 The command runs from the repo root with `DONE_DONE_EVIDENCE_ROOT` (a new folder for this run in the evidence root) and `DONE_DONE_RUN_ID` set, and `${RUN_ID}` in it is replaced. A run that writes nothing into its folder fails.
 
-Optional: `done-done init --agent claude` adds a Claude Code SessionStart hook to the repo's `.claude/settings.json` that shows each session the bare `done-done` state. See the [reference](docs/reference.md#set-up-a-repo). Codex and opencode are not supported yet.
+Optional: `done-done init --agent claude` adds a Claude Code SessionStart hook to the repo's `.claude/settings.json` that shows each session the bare `done-done` state, `done-done init --agent codex` adds the same SessionStart hook to the repo's `.codex/hooks.json` for Codex, and `done-done init --agent opencode` adds a plugin to the repo's `.opencode/plugins/` that adds the state to the first message of each opencode session. See the [reference](docs/reference.md#set-up-a-repo).
 
-Commit the config (and `.claude/settings.json` if you added the hook), because proof only counts from a clean tree:
+Record the recipe in the repo so anyone can re-run the proof, then commit it (and `.claude/settings.json`, `.codex/hooks.json`, or `.opencode/plugins/done-done.js` if you added a hook):
 
 ```sh
+done-done init --journey smoke -- 'npm test > $DONE_DONE_EVIDENCE_ROOT/${RUN_ID}.log'
 git add .done-done.yaml
 git commit -m "Add done-done"
 ```
 
+A `run -- <command>` whose command matches no recorded journey still runs, but its result hints that the recipe is not in the repo.
+
 **3. Run it, then check it**
 
 ```sh
@@ -173,7 +176,7 @@ cp "$(npm root -g)/done-done-axi/integrations/firstmate/merge-gate" "$FM_HOME/co
 ```
 
 - **`brief-include.md`**: Firstmate adds `config/brief-include.md` to every worker brief. It tells the worker to set up done-done, run a journey on its committed change, write a `## Checks` block, pass `check`, and record a `receipt`. The evidence and receipt stay in `~/.done-done/evidence/<app>` after teardown deletes the worktree.
-- **`merge-gate`** (optional): `merge-gate <task-id> <worktree> <head> <pr-url|->`. In the worktree, it refuses a PR whose head is not `<head>`, then runs `done-done check --from <PR URL or $FM_HOME/data/<task-id>/checks.md> --trusted-ref <default branch>` (`origin/HEAD`, else `origin/main` or `origin/master`, else the local `main` or `master` in a repo with no remote), then `done-done receipt --verify <head>`. Both paths read done-done's rules from your default branch, never from the task's own branch, so merge `.done-done.yaml` there before you rely on it. The gate does not fetch: it reads the local `origin` refs, so run `git fetch origin` before you run it. It needs `done-done` on PATH (the `npm install` line above). A nonzero exit refuses the merge, and done-done's output says why. Upstream Firstmate does not call a merge gate yet, so this file has no effect until it does; you can run it by hand before a merge.
+- **`merge-gate`** (optional): `merge-gate <task-id> <worktree|-> <head> <pr-url|->`. In the worktree, it refuses a PR whose head is not `<head>`, then runs `done-done check --from <PR URL or $FM_HOME/data/<task-id>/checks.md> --trusted-ref <default branch>` (`origin/HEAD`, else `origin/main` or `origin/master`, else the local `main` or `master` in a repo with no remote), then `done-done receipt --verify <head>`. Both paths read done-done's rules from your default branch, never from the task's own branch, so merge `.done-done.yaml` there before you rely on it. The gate does not fetch: it reads the local `origin` refs, so run `git fetch origin` before you run it. It needs `done-done` on PATH (the `npm install` line above). A nonzero exit refuses the merge, and done-done's output says why. A worktree of `-` means the task recorded none: the gate does not cd and runs git and done-done in the current directory (the caller's project clone). Upstream Firstmate does not call a merge gate yet, so this file has no effect until it does; you can run it by hand before a merge.
 
 Another fleet works the same way: add the include text to whatever your workers read first, and run `merge-gate` before each merge, with `FM_HOME` set to the folder that holds `data/<task-id>/checks.md` for local-only tasks.
 
@@ -184,7 +187,7 @@ Another fleet works the same way: add the include text to whatever your workers
 
 ## What's next
 
-So far: `init`, `run`, `check`, `receipt`, the opt-in screenshot judge and the opt-in Claude Code session hook. Coming next: help writing the proof steps for your app.
+So far: `init`, `run`, `check`, `receipt`, the opt-in screenshot judge and the opt-in Claude Code, Codex and opencode session hooks. Coming next: help writing the proof steps for your app.
 
 ## Develop
 

package/dist/cli.js

@@ -6,6 +6,7 @@ import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, matchesGlob, relative, resolve, sep } from 'node:path';
 import { parseArgs } from 'node:util';
 import { encode } from '@toon-format/toon';
+import { Document, parseDocument } from 'yaml';
 import { loadConfig, UsageError } from './config.js';
 import { judge } from './judge.js';
 import { checkMedia } from './media.js';
@@ -24,6 +25,7 @@ const CHECKS_TEXT = `Checks block (--from): the newest "## Checks" heading, then
 // One table drives `--help` and every `<command> --help`: each command's usage lines and the flags it takes.
 const FLAGS = {
     '-- <command...>': 'run this command instead of a journey; ${RUN_ID} in it becomes the run id',
+    '--journey <name>': 'record this command as a journey in .done-done.yaml; ${RUN_ID} in it becomes the run id',
     '--open': 'open a run for a hand- or agent-driven proof; prints its id and folder',
     '--close <run-id>': 'seal an open run and record the files in its folder',
     '--outcome "<claim>"': 'the outcome the evidence files prove; the files follow as arguments',
@@ -32,7 +34,7 @@ const FLAGS = {
     '--claim-id <id>': 'the claim the evidence proves; evidence already used for another claim id is reuse (default: the current branch, or the PR branch with --from <PR URL>; required on a detached HEAD)',
     '--judge': 'a model says whether each PNG/JPEG capture shows the outcome (off by default; or judge.enabled: true)',
     '--verify <head>': 'read-only: verify the receipt recorded for <head>',
-    '--agent claude': 'also add a SessionStart hook to .claude/settings.json that shows `done-done` to each session (opt-in)',
+    '--agent <agent>': 'also add a SessionStart hook to .claude/settings.json (claude) or .codex/hooks.json (codex) that shows `done-done` to each session, or a plugin to .opencode/plugins that adds it to the first message of each opencode session (opt-in)',
 };
 // `more` is the reference text a command needs beyond its flags, shared with the top-level help.
 const COMMANDS = {
@@ -40,8 +42,11 @@ const COMMANDS = {
         usage: [
             ['done-done init', 'write a minimal .done-done.yaml (evidence lives outside the repo)'],
             ['done-done init --agent claude', 'also show this repo\'s done-done state at each Claude Code session start'],
+            ['done-done init --agent codex', 'also show this repo\'s done-done state at each Codex session start'],
+            ['done-done init --agent opencode', 'also add this repo\'s done-done state to the first message of each opencode session'],
+            ['done-done init --journey <name> -- <command...>', "record a journey's capture recipe in .done-done.yaml"],
         ],
-        flags: ['--agent claude'],
+        flags: ['--agent <agent>', '--journey <name>', '-- <command...>'],
         more: [JOURNEYS_TEXT],
     },
     run: {
@@ -214,6 +219,14 @@ function closeRun(repo, cfg, rec) {
     result.help = [reason
             ? `Fix the capture, commit, then re-run: ${captureHint(cfg)}`
             : `Check this proof: done-done check --outcome "<what you proved>" ${rel(rec.files[0].path)}`];
+    // A command that matches no repo-recorded journey cannot be re-run from the repo recipe.
+    // A journey run expands ${RUN_ID} to the run id, so compare with the placeholder restored.
+    if (rec.command) {
+        const template = rec.command.replaceAll(rec.run_id, '${RUN_ID}');
+        const recorded = Object.values(cfg.journeys).some((j) => j.command === template);
+        if (!recorded)
+            result.help.push(`this command's recipe is not in the repo (.done-done.yaml journeys); record it with: done-done init --journey <name> -- <command>`);
+    }
     emit(result);
     return reason ? FAIL : PASS;
 }
@@ -689,9 +702,13 @@ function ensureIgnored(repo, rel) {
     appendFileSync(file, `${text && !text.endsWith('\n') ? '\n' : ''}${entry}\n`);
     return true;
 }
-// The Claude Code SessionStart hook `init --agent claude` adds; Claude Code shows its stdout to the session.
+// The session-start hook `init --agent <agent>` adds; the agent shows its stdout to the session.
 // Without done-done on PATH it prints nothing and exits 0, so it never breaks a session.
-const CLAUDE_HOOK = 'command -v done-done >/dev/null && done-done || true';
+// Claude Code reads it from the repo's .claude/settings.json, Codex from the repo's .codex/hooks.json
+// (project scope; Codex docs: <repo>/.codex/hooks.json, SessionStart, matcher omitted matches every start).
+const HOOK_COMMAND = 'command -v done-done >/dev/null && done-done || true';
+const CLAUDE_HOOK = HOOK_COMMAND;
+const CODEX_HOOK = HOOK_COMMAND;
 // The repo's .claude/settings.json with the hook merged in, keeping every other key and hook; no text when it is already there.
 function claudeSettings(repo) {
     const file = join(repo, '.claude', 'settings.json');
@@ -718,15 +735,135 @@ function claudeSettings(repo) {
     settings.hooks = { ...settings.hooks, SessionStart: [...start, { hooks: [{ type: 'command', command: CLAUDE_HOOK }] }] };
     return { file, text: `${JSON.stringify(settings, null, 2)}\n` };
 }
+// The repo's .codex/hooks.json with the hook merged in, keeping every other key and hook; no text when it is already there.
+function codexSettings(repo) {
+    const file = join(repo, '.codex', 'hooks.json');
+    const bad = (why) => new UsageError(`.codex/hooks.json ${why}`, 'Fix .codex/hooks.json, then re-run: done-done init --agent codex');
+    const isObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+    let settings = {};
+    if (existsSync(file)) {
+        try {
+            settings = JSON.parse(readFileSync(file, 'utf8'));
+        }
+        catch (e) {
+            throw bad(`is not valid JSON (${e.message})`);
+        }
+    }
+    if (!isObject(settings))
+        throw bad('is not a JSON object');
+    if (settings.hooks !== undefined && !isObject(settings.hooks))
+        throw bad('has "hooks" that is not an object');
+    const start = settings.hooks?.SessionStart ?? [];
+    if (!Array.isArray(start))
+        throw bad('has "hooks.SessionStart" that is not a list');
+    if (start.some((m) => Array.isArray(m?.hooks) && m.hooks.some((h) => h?.command === CODEX_HOOK)))
+        return { file };
+    settings.hooks = { ...settings.hooks, SessionStart: [...start, { hooks: [{ type: 'command', command: CODEX_HOOK }] }] };
+    return { file, text: `${JSON.stringify(settings, null, 2)}\n` };
+}
+// The opencode session plugin `init --agent opencode` adds: a project-scope file in
+// .opencode/plugins/ (auto-loaded; the home config is never touched) whose chat.message
+// hook runs the session command below on the first message of each session and appends
+// the bare `done-done` state to the message parts. The appended part carries the prt_ id
+// plus the session id from the hook input and the message id from the hook output (opencode
+// passes no messageID to the hook), because opencode validates every
+// part before save and drops the whole first message when one is invalid. Without
+// done-done on PATH it appends nothing and never throws, so it never breaks a session.
+function opencodePlugin(repo) {
+    const file = join(repo, '.opencode', 'plugins', 'done-done.js');
+    const text = `// Written by \`done-done init --agent opencode\`: shows this repo's bare \`done-done\`
+// state to each opencode session. On the first message of a session the chat.message
+// hook runs \`${CLAUDE_HOOK}\` and appends its output to the message parts.
+// Without done-done on PATH it appends nothing and never throws, so it never breaks
+// a session. Other files in .opencode/plugins/ are untouched; delete this file to opt out.
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+
+const COMMAND = "${CLAUDE_HOOK}";
+
+const seen = new Set();
+const firstMessage = (sessionID) => {
+  if (seen.has(sessionID)) return false;
+  seen.add(sessionID);
+  return true;
+};
+
+const run = (cwd) => new Promise((resolve) => {
+  execFile("sh", ["-c", COMMAND], { cwd, encoding: "utf8", timeout: 30000 }, (error, stdout) => resolve(error ? "" : stdout.trim()));
+});
+
+export const DoneDonePlugin = async ({ directory }) => {
+  return {
+    "chat.message": async (input, output) => {
+      if (!firstMessage(input.sessionID)) return;
+      const state = await run(directory);
+      if (state) output.parts.push({ id: \`prt_\${randomUUID()}\`, messageID: output.message.id, sessionID: input.sessionID, type: "text", text: state });
+    },
+  };
+};
+`;
+    if (existsSync(file)) {
+        if (readFileSync(file, 'utf8') === text)
+            return { file };
+        throw new UsageError('.opencode/plugins/done-done.js already exists with other content, so init will not overwrite it', 'Delete .opencode/plugins/done-done.js, then re-run: done-done init --agent opencode');
+    }
+    return { file, text };
+}
 function cmdInit(argv) {
-    const { values } = parseArgs({ args: argv, options: { agent: { type: 'string' } }, allowPositionals: false });
-    if (values.agent !== undefined && values.agent !== 'claude')
-        throw new UsageError(`--agent ${values.agent} is not supported; the supported value is claude`, 'Run: done-done init --agent claude');
+    const dash = argv.indexOf('--');
+    const { values } = parseArgs({
+        args: dash < 0 ? argv : argv.slice(0, dash),
+        options: { agent: { type: 'string' }, journey: { type: 'string' } },
+        allowPositionals: false,
+    });
+    const parts = dash < 0 ? [] : argv.slice(dash + 1);
+    const journey = values.journey ?? null;
+    if (values.agent !== undefined && values.agent !== 'claude' && values.agent !== 'codex' && values.agent !== 'opencode')
+        throw new UsageError(`--agent ${values.agent} is not supported; the supported values are claude, codex, opencode`, 'Run: done-done init --agent <claude|codex|opencode>');
+    if (journey === null && parts.length)
+        throw new UsageError('init needs --journey <name> to record a command after --');
+    if (journey !== null && !parts.some((p) => p.trim()))
+        throw new UsageError(`init --journey ${journey} needs a command after --`);
+    if (journey !== null && !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(journey))
+        throw new UsageError(`invalid journey name ${journey}; use letters, digits, - or _`);
     const repo = repoRoot();
     const file = join(repo, '.done-done.yaml');
     const existed = existsSync(file);
     const cfg = loadConfig(repo); // validates the existing project config; malformed -> exit 2, no writes
-    const hook = values.agent ? claudeSettings(repo) : undefined; // likewise validated before any write
+    const hook = values.agent === 'claude' ? claudeSettings(repo) : values.agent === 'codex' ? codexSettings(repo) : values.agent === 'opencode' ? opencodePlugin(repo) : undefined; // likewise validated before any write
+    if (journey !== null) {
+        // Record the capture recipe in the repo so any checkout can re-run the proof.
+        // The command is stored verbatim; ${RUN_ID} in it becomes the run id, like a run -- command.
+        const command = parts.join(' ');
+        const doc = existed ? parseDocument(readFileSync(file, 'utf8')) : new Document({ app: cfg.app });
+        const top = (doc.toJS() ?? {});
+        if (typeof top !== 'object' || Array.isArray(top))
+            throw new UsageError(`${file}: top level must be a mapping`);
+        const journeys = top.journeys ?? {};
+        if (typeof journeys !== 'object' || Array.isArray(journeys))
+            throw new UsageError(`${file}: journeys must be a mapping`);
+        if (top.journeys == null)
+            doc.set('journeys', doc.createNode({}));
+        doc.setIn(['journeys', journey, 'command'], command);
+        writeFileSync(`${file}.tmp`, doc.toString({ lineWidth: 0 }));
+        renameSync(`${file}.tmp`, file);
+        const fresh = loadConfig(repo);
+        const rel = under(repo, fresh.evidence.root);
+        const added = !!rel && ensureIgnored(repo, rel);
+        const root = shown(repo, fresh.evidence.root);
+        const check = 'done-done check --outcome "<what you proved>" <files it recorded>';
+        emit({
+            command: 'init',
+            result: 'pass',
+            config: existed ? 'updated' : 'written',
+            journey,
+            app: fresh.app,
+            evidence_root: root,
+            gitignore: added ? `added ${rel.replace(/\/+$/, '')}/` : 'unchanged',
+            help: [`Capture proof: done-done run ${journey}, then: ${check}`],
+        });
+        return PASS;
+    }
     if (!existed) {
         // No evidence.root: proof goes to <local_root>/<app>, outside the repo, so it outlives this checkout.
         // The pinned app name is what lets every checkout of the repo find the same evidence and receipts.
@@ -751,12 +888,23 @@ function cmdInit(argv) {
         app: cfg.app,
         evidence_root: root,
         gitignore: added ? `added ${rel.replace(/\/+$/, '')}/` : 'unchanged',
-        ...(hook && { claude_hook: hook.text ? 'added to .claude/settings.json' : 'unchanged' }),
+        ...(hook &&
+            (values.agent === 'codex'
+                ? { codex_hook: hook.text ? 'added to .codex/hooks.json' : 'unchanged' }
+                : values.agent === 'opencode'
+                    ? { opencode_plugin: hook.text ? 'added to .opencode/plugins/done-done.js' : 'unchanged' }
+                    : { claude_hook: hook.text ? 'added to .claude/settings.json' : 'unchanged' })),
         help: [
             ...(Object.keys(cfg.journeys).length
                 ? [`Capture proof: ${captureHint(cfg)}, then: ${check}`]
                 : [`Add a journey that drives the real app and saves proof under $DONE_DONE_EVIDENCE_ROOT (each run's own folder in ${root}), e.g. ${journeyExample}`, `Then commit, run \`done-done run smoke\`, and: ${check}`]),
-            ...(hook?.text ? ['Commit .claude/settings.json: each Claude Code session in this repo then starts with `done-done` output (it needs done-done on PATH)'] : []),
+            ...(hook?.text
+                ? values.agent === 'codex'
+                    ? ['Commit .codex/hooks.json: each Codex session in this repo then starts with `done-done` output (it needs done-done on PATH)']
+                    : values.agent === 'opencode'
+                        ? ['Commit .opencode/plugins/done-done.js: the first message of each opencode session in this repo then gets `done-done` output added (it needs done-done on PATH)']
+                        : ['Commit .claude/settings.json: each Claude Code session in this repo then starts with `done-done` output (it needs done-done on PATH)']
+                : []),
         ],
     });
     return PASS;

package/docs/reference.md

@@ -14,13 +14,33 @@ For the install steps, see the [README](../README.md#use-it-from-your-agent). do
 done-done init
 ```
 
-`init` writes a minimal `.done-done.yaml` only when one does not exist: just `app`, the repo directory name, so every checkout of the repo finds the same evidence (see [Where proof lives](#where-proof-lives)). It sets no `evidence.root`, so evidence goes outside the repo. When an existing config puts `evidence.root` inside the repo (an older `root: .proof`), `init` adds it to `.gitignore` when git does not already ignore it. It never rewrites the config: re-running is a no-op and a customized `.done-done.yaml` is left byte-for-byte; `.gitignore` gains a line only when the ignore entry is missing. A malformed `.done-done.yaml` makes `init` exit 2 with the file named and untouched. Its result says whether the config was `written` or left `unchanged`, the evidence root, what it added to `.gitignore`, and the next step.
+`init` writes a minimal `.done-done.yaml` only when one does not exist: just `app`, the repo directory name, so every checkout of the repo finds the same evidence (see [Where proof lives](#where-proof-lives)). It sets no `evidence.root`, so evidence goes outside the repo. When an existing config puts `evidence.root` inside the repo (an older `root: .proof`), `init` adds it to `.gitignore` when git does not already ignore it. A plain `init` never rewrites the config: re-running is a no-op and a customized `.done-done.yaml` is left byte-for-byte; `.gitignore` gains a line only when the ignore entry is missing. A malformed `.done-done.yaml` makes `init` exit 2 with the file named and untouched. Its result says whether the config was `written` or left `unchanged`, the evidence root, what it added to `.gitignore`, and the next step.
+
+Record a journey's capture recipe in the repo so any checkout can re-run the proof:
+
+```sh
+done-done init --journey smoke -- 'echo added: milk > $DONE_DONE_EVIDENCE_ROOT/${RUN_ID}.log'
+```
+
+`init --journey <name> -- <command>` writes `journeys.<name>.command` into `.done-done.yaml` (creating the file with the pinned `app` when missing) and reports `written` or `updated` with the journey name. `${RUN_ID}` in the command becomes the run id, exactly as in `run`. Commit the config: proof only counts from a clean tree.
 
 ```sh
 done-done init --agent claude
 ```
 
-`--agent claude` also adds a Claude Code SessionStart hook to the repo's `.claude/settings.json` (project scope; your `~/.claude` is never touched), so each session starts with the bare `done-done` state as context. The hook runs `command -v done-done >/dev/null && done-done || true`: without done-done on PATH it prints nothing and exits 0, so it never breaks a session. An existing settings file keeps every other key and hook; re-running adds no duplicate. The result's `claude_hook` says `added to .claude/settings.json` or `unchanged`. Any other `--agent` value exits 2 naming the supported value, and a malformed `.claude/settings.json` exits 2 untouched. Commit `.claude/settings.json` to share the hook.
+`--agent claude` also adds a Claude Code SessionStart hook to the repo's `.claude/settings.json` (project scope; your `~/.claude` is never touched), so each session starts with the bare `done-done` state as context. The hook runs `command -v done-done >/dev/null && done-done || true`: without done-done on PATH it prints nothing and exits 0, so it never breaks a session. An existing settings file keeps every other key and hook; re-running adds no duplicate. The result's `claude_hook` says `added to .claude/settings.json` or `unchanged`. Any other `--agent` value exits 2 naming the supported values, and a malformed `.claude/settings.json` exits 2 untouched. Commit `.claude/settings.json` to share the hook.
+
+```sh
+done-done init --agent codex
+```
+
+`--agent codex` also adds a Codex SessionStart hook to the repo's `.codex/hooks.json` (project scope; your `~/.codex` is never touched), so each session starts with the bare `done-done` state as context. Same contract as the Claude hook: it runs `command -v done-done >/dev/null && done-done || true`, keeps every other key and hook, adds no duplicate on re-run, and the result's `codex_hook` says `added to .codex/hooks.json` or `unchanged`. A malformed `.codex/hooks.json` exits 2 untouched. Commit `.codex/hooks.json` to share the hook.
+
+```sh
+done-done init --agent opencode
+```
+
+`--agent opencode` instead writes a session-start plugin to the repo's `.opencode/plugins/done-done.js` (project scope; your `~/.config/opencode` is never touched), so the bare `done-done` state is added to the first message of each session, not at session open (opencode's plugin hooks cannot add context when a session is created). The plugin remembers sessions in memory, so a resumed session gets the state again after opencode restarts. That `chat.message` hook runs `command -v done-done >/dev/null && done-done || true` and waits for it (up to 30 seconds) before appending the output to the message: without done-done on PATH it appends nothing and never throws, so it never breaks a session. Other files in `.opencode/plugins/` are untouched; re-running adds no duplicate. The result's `opencode_plugin` says `added to .opencode/plugins/done-done.js` or `unchanged`. Delete the file to opt out. Commit it to share the plugin.
 
 ### Run a journey
 
@@ -48,7 +68,7 @@ done-done run review
 - hashes every file in the run's folder. Every checkout of a repo shares the evidence root, so a run records only its own folder and never another run's files;
 - writes a run record to `<root>/.done-done/runs/<run-id>.json`.
 
-A non-zero command exit, or a run that wrote nothing, fails.
+A non-zero command exit, or a run that wrote nothing, fails. A run that wrote nothing names its folder and the two names the command gets it under: `DONE_DONE_EVIDENCE_ROOT` and `DONE_DONE_RUN_ID` (or `${RUN_ID}` in the command).
 
 For a proof you drive by hand or through an agent:
 
@@ -59,6 +79,7 @@ done-done run --close <run-id>
 ```
 
 You can also run a one-off command without a journey: `done-done run -- <command>`.
+A run whose command matches no repo-recorded journey says so in its `help`: the recipe is not in the repo, so nobody can re-run the proof from the config. Record it with `done-done init --journey <name> -- <command>` and commit.
 Run `done-done` outside wrappers that expand `${...}` themselves (`systemd-run` does): put such a wrapper inside the command, or it eats `${RUN_ID}`.
 
 ### Check a claim

package/integrations/firstmate/brief-include.md

@@ -5,9 +5,10 @@ Before you report done, load the done-done skill and follow it. If the skill is
 Run the CLI as `done-done` if it is on PATH; otherwise run `npx -y --allow-git=all github:umeranjum17/done-done-axi`
 wherever this text or the skill says `done-done`. If done-done cannot run, report that instead of writing proof by hand.
 
-1. If the repo has no `.done-done.yaml`, run `done-done init`, then add a journey to it that drives the real
-   app and writes its screenshots, recordings or logs into `$DONE_DONE_EVIDENCE_ROOT` (done-done sets it to the
-   run's own folder). Commit `.done-done.yaml` and the journey script.
+1. If the repo has no `.done-done.yaml`, run `done-done init`. Then record a journey that drives the real app and
+   writes its screenshots, recordings or logs into `$DONE_DONE_EVIDENCE_ROOT` (done-done sets it to the run's own
+   folder): `done-done init --journey <name> -- <command>`, so the recipe lives in the repo and anyone can re-run the
+   proof. Commit `.done-done.yaml` and the journey script.
 2. Commit your change, then run `done-done run <journey>` from the repo root. Proof only counts from a clean,
    committed tree.
 3. Write a Checks block (the shape `done-done --help` prints) that cites the run's files by the paths `run` printed:

package/integrations/firstmate/merge-gate

@@ -1,12 +1,16 @@
 #!/bin/sh
-# merge-gate <task-id> <worktree> <head> <pr-url|->
+# merge-gate <task-id> <worktree|-> <head> <pr-url|->
 # Run before a merge: it passes only when done-done passes the task's Checks block and the receipt for <head>.
 # Both a PR and a local-only task (-, read from $FM_HOME/data/<task-id>/checks.md) are checked against the rules
 # on the default branch, never the task's own branch. A nonzero exit refuses the merge; done-done's output says why.
+# A worktree of - means the task recorded no worktree: do not cd, run git and done-done in the current directory
+# (the caller's project clone).
 set -eu
-[ $# -eq 4 ] || { echo "usage: merge-gate <task-id> <worktree> <head> <pr-url|->" >&2; exit 2; }
+[ $# -eq 4 ] || { echo "usage: merge-gate <task-id> <worktree|-> <head> <pr-url|->" >&2; exit 2; }
 id=$1 head=$3 pr=$4
-cd "$2" || exit 2
+if [ "$2" != - ]; then
+  cd "$2" 2>/dev/null || { echo "merge-gate: cannot enter worktree $2" >&2; exit 2; }
+fi
 ref=$(git symbolic-ref -q --short refs/remotes/origin/HEAD) ||
   for ref in origin/main origin/master main master; do
     git rev-parse -q --verify "$ref^{commit}" >/dev/null && break

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "done-done-axi",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "Apache-2.0",
   "description": "Proof that the real product works before a task is called done: commit-bound evidence runs and evidence checks.",
   "type": "module",