overlord-cli 0.2605160931.0 → 0.2605170853.0

package/bin/_cli/cli-update.mjs

@@ -2,6 +2,9 @@
 
 import { spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 
 const require = createRequire(import.meta.url);
 const cliPackage = require('../../package.json');
@@ -50,6 +53,41 @@ export async function fetchLatestCliVersion({
   }
 }
 
+function pruneOldCliVersions() {
+  const cliInstallRoot = path.join(os.homedir(), '.ovld', 'cli');
+  if (!fs.existsSync(cliInstallRoot)) return;
+
+  let entries;
+  try {
+    entries = fs.readdirSync(cliInstallRoot);
+  } catch {
+    return;
+  }
+
+  const versionDirs = entries
+    .filter(name => name.startsWith('overlord-cli-'))
+    .flatMap(name => {
+      const dirPath = path.join(cliInstallRoot, name);
+      try {
+        const stat = fs.statSync(dirPath);
+        if (!stat.isDirectory()) return [];
+        return [{ dirPath, mtime: stat.mtimeMs }];
+      } catch {
+        return [];
+      }
+    });
+
+  // Sort newest-first, keep current + 1 previous, delete the rest
+  versionDirs.sort((a, b) => b.mtime - a.mtime);
+  for (const { dirPath } of versionDirs.slice(2)) {
+    try {
+      fs.rmSync(dirPath, { recursive: true, force: true });
+    } catch {
+      // Best-effort cleanup
+    }
+  }
+}
+
 export async function checkForCliUpdate(options = {}) {
   const currentVersion = options.currentVersion ?? CURRENT_CLI_VERSION;
   const latestVersion = await fetchLatestCliVersion(options);
@@ -115,5 +153,7 @@ export async function runCliUpdateCommand({
     logger.log('Overlord CLI update complete. Run `ovld version` to confirm the installed version.');
   }
 
+  pruneOldCliVersions();
+
   return { alreadyLatest: false, currentVersion, latestVersion, result };
 }

package/bin/_cli/local-config.mjs

@@ -0,0 +1,91 @@
+// Read/merge/write logic for the per-folder `overlord.json` file.
+// Mirrors lib/overlord-config/local-config.ts for CLI use.
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+export const OVERLORD_CONFIG_FILENAME = 'overlord.json';
+
+const FILE_COMMENT =
+  'This file lets Overlord (https://www.ovld.ai) identify which project this folder belongs to. It is created automatically when the folder is added as a project resource. DO NOT EDIT MANUALLY.';
+
+function buildConfig(projects) {
+  return { _comment: FILE_COMMENT, projects };
+}
+
+function isProjectArray(value) {
+  return (
+    Array.isArray(value) &&
+    value.every(
+      entry =>
+        entry &&
+        typeof entry === 'object' &&
+        typeof entry.id === 'string' &&
+        typeof entry.name === 'string'
+    )
+  );
+}
+
+async function readExistingProjects(filePath) {
+  try {
+    const raw = await fs.readFile(filePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && isProjectArray(parsed.projects)) {
+      return parsed.projects;
+    }
+    return [];
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+/**
+ * Ensures `directoryPath/overlord.json` lists the project. Returns
+ * `{ filePath, action: 'created' | 'added-project' | 'unchanged' }`.
+ */
+export async function upsertLocalOverlordConfig({ directoryPath, project }) {
+  const filePath = path.join(directoryPath, OVERLORD_CONFIG_FILENAME);
+  const existing = await readExistingProjects(filePath);
+
+  if (existing === null) {
+    await fs.writeFile(filePath, `${JSON.stringify(buildConfig([project]), null, 2)}\n`, 'utf8');
+    return { filePath, action: 'created' };
+  }
+
+  const idx = existing.findIndex(entry => entry.id === project.id);
+  if (idx >= 0) {
+    if (existing[idx].name === project.name) return { filePath, action: 'unchanged' };
+    const updated = existing.slice();
+    updated[idx] = project;
+    await fs.writeFile(filePath, `${JSON.stringify(buildConfig(updated), null, 2)}\n`, 'utf8');
+    return { filePath, action: 'unchanged' };
+  }
+
+  const merged = [...existing, project];
+  await fs.writeFile(filePath, `${JSON.stringify(buildConfig(merged), null, 2)}\n`, 'utf8');
+  return { filePath, action: 'added-project' };
+}
+
+/**
+ * Removes `projectId` from `directoryPath/overlord.json`. Deletes the file
+ * when the resulting projects list is empty. Returns
+ * `{ filePath, action: 'removed-project' | 'deleted-file' | 'not-found' | 'unchanged' }`.
+ */
+export async function removeProjectFromLocalOverlordConfig({ directoryPath, projectId }) {
+  const filePath = path.join(directoryPath, OVERLORD_CONFIG_FILENAME);
+  const existing = await readExistingProjects(filePath);
+
+  if (existing === null) return { filePath, action: 'not-found' };
+
+  const filtered = existing.filter(entry => entry.id !== projectId);
+  if (filtered.length === existing.length) return { filePath, action: 'unchanged' };
+
+  if (filtered.length === 0) {
+    await fs.unlink(filePath);
+    return { filePath, action: 'deleted-file' };
+  }
+
+  await fs.writeFile(filePath, `${JSON.stringify(buildConfig(filtered), null, 2)}\n`, 'utf8');
+  return { filePath, action: 'removed-project' };
+}

package/bin/_cli/protocol.mjs

@@ -1035,6 +1035,42 @@ async function protocolAsk(args) {
   console.log(JSON.stringify(data, null, 2));
 }
 
+// ---------------------------------------------------------------------------
+// request-approval-gate
+// ---------------------------------------------------------------------------
+
+async function protocolRequestApprovalGate(args) {
+  const flags = parseFlags(args);
+  const { sessionKey, ticketId } = resolveSessionFlags(flags);
+  if (!sessionKey) throw new Error('--session-key is required (or set SESSION_KEY)');
+  if (!ticketId) throw new Error('--ticket-id is required (or set TICKET_ID)');
+  const reason = flags['reason-file']
+    ? await readTextFileOrStdin(String(flags['reason-file']), '--reason-file')
+    : requireFlag(flags, 'reason', undefined);
+
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags, ticketId);
+  const timeoutMs = resolveTimeout(flags);
+
+  const body = {
+    sessionKey,
+    ticketId,
+    reason,
+    ...(flags['objective-id'] ? { objectiveId: String(flags['objective-id']) } : {})
+  };
+
+  const data = await apiPost(
+    platformUrl,
+    bearerToken,
+    localSecret,
+    organizationId,
+    '/api/protocol/request-approval-gate',
+    body,
+    timeoutMs
+  );
+  console.log(JSON.stringify(data, null, 2));
+}
+
 // ---------------------------------------------------------------------------
 // permission-request
 // ---------------------------------------------------------------------------
@@ -1684,6 +1720,21 @@ async function protocolAddProjectResource(args) {
   if (data.resource?.id) {
     process.stderr.write(`\nRESOURCE_ID=${data.resource.id}\n`);
   }
+
+  if (data.project?.id && data.project?.name) {
+    try {
+      const { upsertLocalOverlordConfig } = await import('./local-config.mjs');
+      const result = await upsertLocalOverlordConfig({
+        directoryPath,
+        project: { id: data.project.id, name: data.project.name }
+      });
+      process.stderr.write(`OVERLORD_CONFIG=${result.filePath} (${result.action})\n`);
+    } catch (configError) {
+      process.stderr.write(
+        `\nWarning: could not write overlord.json: ${configError instanceof Error ? configError.message : configError}\n`
+      );
+    }
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -2238,6 +2289,7 @@ Subcommands:
   update                    Post progress, activity events, and optional change rationales
   record-change-rationales  Persist structured change rationales without a progress update
   ask                       Post a blocking question and move the ticket to review
+  request-approval-gate     Flip auto_advance=false on the next queued future objective
   permission-request        Notify Overlord that the agent is requesting tool permission
   hook-event                Record a lifecycle hook event without a session key
   read-context              Read shared persistent context for this ticket
@@ -2779,6 +2831,10 @@ EOF
     await protocolAsk(args);
     return;
   }
+  if (subcommand === 'request-approval-gate') {
+    await protocolRequestApprovalGate(args);
+    return;
+  }
   if (subcommand === 'permission-request') {
     await protocolPermissionRequest(args);
     return;

package/bin/_cli/setup.mjs

@@ -407,6 +407,24 @@ disable-model-invocation: true
 ---
 
 Run \`ovld protocol prompt --agent claude-code\` with \`$ARGUMENTS\`. If no flags are present, treat the arguments as the objective and call \`ovld protocol prompt --agent claude-code --objective "<objective>"\`.`
+      },
+      {
+        path: path.join(base, 'record-work.md'),
+        content: `---
+description: Record completed-from-chat work as a ticket in review + feed post (no attach)
+argument-hint: [optional additional context]
+disable-model-invocation: true
+---
+
+Immediately record the work you just completed in this chat as a new Overlord ticket via \`ovld protocol record-work\`. No agent session is opened — the work is already done.
+
+Synthesize from the current conversation: \`objective\` (what was asked/done), \`summary\` (reviewer-friendly narrative), \`changeRationales\` (one entry per meaningful git-tracked file change — \`label\`, \`file_path\`, \`summary\`, \`why\`, \`impact\`, optional \`hunks\`; use \`git status\`/\`git diff\` to enumerate), and optional \`artifacts\` (\`next_steps\`, \`test_results\`, \`decision\`, \`note\`, \`url\`).
+
+If \`$ARGUMENTS\` is non-empty, treat it as additional context for the summary.
+
+Run \`ovld protocol record-work --payload-file -\` and stream the JSON payload \`{ "objective": "...", "summary": "...", "artifacts": [...], "changeRationales": [...] }\` on stdin via a single-quoted heredoc. Report the new \`TICKET_ID\`.
+
+Do NOT use this for in-progress work — use \`/prompt\` for that. The CLI validates that every changed git-tracked file is represented in \`changeRationales\` unless \`--skip-file-change-check\` is passed. If project resolution fails, re-run with \`--project-id <id>\` or \`--personal\`.`
       }
     ];
   }
@@ -433,6 +451,11 @@ Run \`ovld protocol prompt --agent claude-code\` with \`$ARGUMENTS\`. If no flag
         path: path.join(base, 'prompt.md'),
         content:
           'Create a new Overlord ticket.\n\nRun `ovld protocol prompt --agent cursor --objective "<objective>"` using the text after `/prompt` unless raw flags were provided. If raw flags were provided, pass them after `ovld protocol prompt --agent cursor`.\n'
+      },
+      {
+        path: path.join(base, 'record-work.md'),
+        content:
+          'Record completed-from-chat work as a ticket in review + feed post (no attach).\n\nImmediately record the work you just completed in this chat as a new Overlord ticket via `ovld protocol record-work`. No agent session is opened — the work is already done.\n\nSynthesize from the current conversation: `objective` (what was asked/done), `summary` (reviewer-friendly narrative), `changeRationales` (one entry per meaningful git-tracked file change — `label`, `file_path`, `summary`, `why`, `impact`, optional `hunks`; use `git status`/`git diff` to enumerate), and optional `artifacts` (`next_steps`, `test_results`, `decision`, `note`, `url`).\n\nIf text was provided after `/record-work`, treat it as additional context for the summary.\n\nRun `ovld protocol record-work --payload-file -` and stream the JSON payload on stdin via a single-quoted heredoc. Report the new TICKET_ID.\n\nDo NOT use for in-progress work — use `/prompt` for that. The CLI validates that every changed git-tracked file is represented in `changeRationales` unless `--skip-file-change-check` is passed. If project resolution fails, re-run with `--project-id <id>` or `--personal`.\n'
       }
     ];
   }
@@ -459,6 +482,11 @@ Run \`ovld protocol prompt --agent claude-code\` with \`$ARGUMENTS\`. If no flag
         path: path.join(base, 'prompt.toml'),
         content:
           'description = "Create a new Overlord ticket from the current conversation."\nprompt = """\nRun `ovld protocol prompt --agent gemini --objective "<objective>"` using `{{args}}` as the objective unless raw flags were provided. If raw flags were provided, pass them after `ovld protocol prompt --agent gemini`.\n"""\n'
+      },
+      {
+        path: path.join(base, 'record-work.toml'),
+        content:
+          'description = "Record completed-from-chat work as a ticket in review + feed post (no attach)."\nprompt = """\nImmediately record the work you just completed in this chat as a new Overlord ticket via `ovld protocol record-work`. No agent session is opened — the work is already done.\n\nSynthesize from the current conversation: `objective` (what was asked/done), `summary` (reviewer-friendly narrative), `changeRationales` (one entry per meaningful git-tracked file change — `label`, `file_path`, `summary`, `why`, `impact`, optional `hunks`; use `git status`/`git diff` to enumerate), and optional `artifacts` (`next_steps`, `test_results`, `decision`, `note`, `url`).\n\nIf `{{args}}` is non-empty, treat it as additional context for the summary.\n\nRun `ovld protocol record-work --payload-file -` and stream the JSON payload on stdin via a single-quoted heredoc. Report the new TICKET_ID.\n\nDo NOT use for in-progress work — use `/prompt` for that. The CLI validates that every changed git-tracked file is represented in `changeRationales` unless `--skip-file-change-check` is passed. If project resolution fails, re-run with `--project-id <id>` or `--personal`.\n"""\n'
       }
     ];
   }
@@ -500,6 +528,23 @@ agent: build
 ---
 
 Run \`ovld protocol prompt --agent opencode\` with \`$ARGUMENTS\`. If no flags are present, treat the arguments as the objective and call \`ovld protocol prompt --agent opencode --objective "<objective>"\`.`
+    },
+    {
+      path: path.join(base, 'record-work.md'),
+      content: `---
+description: Record completed-from-chat work as a ticket in review + feed post (no attach)
+agent: build
+---
+
+Immediately record the work you just completed in this chat as a new Overlord ticket via \`ovld protocol record-work\`. No agent session is opened — the work is already done.
+
+Synthesize from the current conversation: \`objective\` (what was asked/done), \`summary\` (reviewer-friendly narrative), \`changeRationales\` (one entry per meaningful git-tracked file change — \`label\`, \`file_path\`, \`summary\`, \`why\`, \`impact\`, optional \`hunks\`; use \`git status\`/\`git diff\` to enumerate), and optional \`artifacts\` (\`next_steps\`, \`test_results\`, \`decision\`, \`note\`, \`url\`).
+
+If \`$ARGUMENTS\` is non-empty, treat it as additional context for the summary.
+
+Run \`ovld protocol record-work --payload-file -\` and stream the JSON payload on stdin via a single-quoted heredoc. Report the new \`TICKET_ID\`.
+
+Do NOT use for in-progress work — use \`/prompt\` for that. The CLI validates that every changed git-tracked file is represented in \`changeRationales\` unless \`--skip-file-change-check\` is passed. If project resolution fails, re-run with \`--project-id <id>\` or \`--personal\`.`
     }
   ];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord-cli",
-  "version": "0.2605160931.0",
+  "version": "0.2605170853.0",
   "description": "Overlord CLI — launch AI agents on tickets from anywhere",
   "homepage": "https://www.ovld.ai/docs/",
   "type": "module",

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Overlord ticket protocol workflow for Claude Code — attach/update/ask/deliver, slash commands, and hook-driven activity capture.",
   "author": {
     "name": "Cooperativ",

package/plugins/claude/commands/record-work.md

@@ -0,0 +1,28 @@
+---
+description: Record completed-from-chat work as a ticket in review + feed post (no attach)
+argument-hint: [optional additional context]
+disable-model-invocation: true
+---
+
+Immediately record the work you just completed in this chat as a new Overlord ticket via `ovld protocol record-work`. No agent session is opened — the work is already done.
+
+Synthesize from the current conversation:
+- `objective`: what was asked / what was done (1–3 sentences).
+- `summary`: reviewer-friendly narrative of what changed and why.
+- `changeRationales`: one entry per meaningful git-tracked file change (`label`, `file_path`, `summary`, `why`, `impact`, optional `hunks`). Use `git status` and `git diff` to enumerate changed files.
+- `artifacts` (optional): `next_steps`, `test_results`, `decision`, `note`, `url`.
+
+If `$ARGUMENTS` is non-empty, treat it as additional context to weave into the summary.
+
+Run:
+`ovld protocol record-work --payload-file -`
+
+and stream a JSON object `{ "objective": "...", "summary": "...", "artifacts": [...], "changeRationales": [...] }` on stdin via a single-quoted heredoc (`<<'EOF'`).
+
+After the command succeeds, report the new `TICKET_ID`.
+
+Rules:
+- Do NOT use this for in-progress work. Use `/prompt` for that.
+- The CLI validates that every changed git-tracked file is represented in `changeRationales` unless `--skip-file-change-check` is passed.
+- If project resolution fails, re-run with `--project-id <id>` or `--personal`.
+- If `ovld` reports `OVERLORD_URL` is unreachable, stop and request permission escalation or network access before retrying.

package/plugins/claude/skills/overlord-ticket/SKILL.md

@@ -94,8 +94,7 @@ Use this mode when the conversation starts normally and the user asks Claude to
 1. If the user wants to create tickets (and does not ask to start execution), run `ovld protocol create --agent claude-code --objective "..."`.
    - When `--session-key` and `--ticket-id` are provided, it creates a follow-up draft.
    - When session flags are omitted, it resolves the project by matching current working directory (or `--working-directory`) to Overlord `local_working_directory`, then creates a standalone draft.
-2. Default to `create` for new draft tickets. Only use `/overlord:prompt` or `ovld protocol prompt --agent claude-code --objective "..."` when the user explicitly asks to create and execute immediately. If the work is already complete in chat and just needs to be recorded, use `ovld protocol record-work` instead.
-   `prompt` creates the ticket in `execute` status and attaches immediately.
+2. Default to `create` for new draft tickets. Only use `/overlord:prompt` or `ovld protocol prompt --agent claude-code --objective "..."` when the user explicitly asks to create and execute immediately. If the work is already complete in chat and just needs to be recorded, use `ovld protocol record-work` instead.`prompt` creates the ticket in `execute` status and attaches immediately.
 3. If the user already has a ticket ID and only wants to inspect it, use `/overlord:load` or run `ovld protocol load-context --ticket-id <ticket_id>`.
 4. If the user wants to route the current session onto an existing ticket by ID, use `/overlord:connect` or run `ovld protocol connect --ticket-id <ticket_id>`.
 5. If the user wants to establish a persistent session with a ticket by ID, use `/overlord:attach` or run `ovld protocol attach --ticket-id <ticket_id>`.
@@ -175,9 +174,6 @@ When creating tickets from within a repository:
 
 ```bash
 ovld protocol create --agent claude-code --objective "Capture follow-up work from this repository"
-```
-
-```bash
 ovld protocol prompt --agent claude-code --objective "Implement feature X" --priority medium
 ```
 
@@ -189,6 +185,24 @@ ovld protocol discover-project
 
 You can override with `--project-id` or `--working-directory` if needed.
 
+### Resolving the project ID when you don't have one
+
+When you need a project ID for a protocol command and the ticket prompt did not supply one, resolve it in this order.
+
+**Locally (CLI inside a shell on the user's machine):**
+
+1. `--project-id` if explicitly provided.
+2. Otherwise, let the CLI match the current working directory (the default behavior of `create`, `prompt`, `discover-project`).
+3. If working-directory resolution returns nothing, read `overlord.json` from the cwd (or any ancestor you have access to) and pass its project id via `--project-id`.
+
+**Over MCP (web agents and hosted tools, where the server cannot see the agent's cwd):**
+
+1. `--project-id` / `projectId` if explicitly provided.
+2. Read `overlord.json` from the directory the user is accessing and pass its project id as `projectId`.
+3. As a last resort, try `workingDirectory` resolution.
+
+If `overlord.json` contains more than one project, show the user the project **names** from that file and ask which one to use before calling any protocol command — never silently pick one.
+
 ### Choosing `--execution-target`
 
 Pass `--execution-target agent` or `--execution-target human` (default: `human`) when creating tickets.
@@ -210,6 +224,10 @@ ovld protocol attachment-download-url --session-key <sessionKey> --ticket-id $TI
 
 The `attach` and `load-context` responses already include `attachments` and `objectives` arrays — use those for `<attachment-id>` and `<objective-id>` values. Run `attachment-list` mid-session if new files have been uploaded since attach.
 
+Objective attachment uploads also expose two-step variants — `attachment-prepare-upload` and `attachment-finalize-upload` — for callers that need a signed URL directly. Prefer `attachment-upload-file` for one-shot uploads.
+
+"Artifacts" in `deliver` are the structured records an agent submits at delivery time (next_steps, test_results, migration, decision, note, url) — not user-uploaded files.
+
 ## Large Artifacts
 
 For large artifacts such as planning documents, architecture decisions, research summaries, or design documents: **save the full content as a markdown file in the linked repository, then summarize it in the artifact returned to the ticket.**
@@ -226,8 +244,6 @@ This keeps the ticket feed readable while preserving the full document in versio
 - Hosted Overlord MCP (`/functions/v1/mcp`) uses the same canonical tool names as any local MCP shim that shells into `ovld protocol` (`attach`, `update`, `deliver`, `record_work`, …). Hosted calls use camelCase JSON keys (`ticketId`, `sessionKey`) matching `POST /api/protocol/*` bodies; the local shim uses snake_case keys mapped to CLI flags (`ticket_id`, `session_key`).
 - `permission-request` is invoked by the Claude Code permission hook installed by the bundle. Agents do not normally call it directly.
 - `record_change_rationales` (MCP) and `ovld protocol record-change-rationales` (CLI) both write to the same `file_changes` table. The dedicated CLI route is `POST /api/protocol/record-change-rationales`.
-- Objective attachment tools follow the `<verb>_<noun>` MCP naming: `list_attachments`, `prepare_attachment_upload`, `finalize_attachment_upload`, `get_attachment_download_url`, `upload_attachment_file`. CLI commands use `attachment-*` and require `--objective-id` for upload/finalize.
-- "Artifacts" in `deliver` are the structured records an agent submits at delivery time (next_steps, test_results, migration, decision, note, url) — not user-uploaded files. Files attached by users live on objectives via the attachment tools above.
 
 ## Rules
 
@@ -242,4 +258,4 @@ This keeps the ticket feed readable while preserving the full document in versio
 - Do not add or commit changes unless the user explicitly asks you to commit.
 - Delivery is the concluding step. After delivering, stop unless the user follows up or the ticket is reopened.
 
-<!-- version: 0.4.10 -->
+<!-- version: 0.4.11 -->

package/plugins/cursor/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Local Overlord workflow plugin for Cursor terminal agents.",
   "author": {
     "name": "Cooperativ",

package/plugins/cursor/commands/record-work.md

@@ -0,0 +1,9 @@
+Run `ovld protocol record-work --payload-file -` to record completed-from-chat work as a ticket in review + feed post (no attach).
+
+Synthesize from the current conversation: `objective` (what was asked/done), `summary` (reviewer-friendly narrative), `changeRationales` (one entry per meaningful git-tracked file change — `label`, `file_path`, `summary`, `why`, `impact`, optional `hunks`; use `git status`/`git diff` to enumerate), and optional `artifacts` (`next_steps`, `test_results`, `decision`, `note`, `url`).
+
+If text was provided after `/record-work`, treat it as additional context for the summary.
+
+Stream the JSON payload on stdin via a single-quoted heredoc. Report the new TICKET_ID.
+
+Do NOT use for in-progress work — use `/prompt` for that. If `ovld` reports `OVERLORD_URL` is unreachable, stop and request permission escalation or network access before retrying.

package/plugins/cursor/skills/overlord-ticket/SKILL.md

@@ -90,6 +90,36 @@ ovld protocol revert --objective-id <objective-id>
 
 Use `ovld protocol record-work` when the user has done work directly in chat (no attached ticket) and wants to record it as a ticket plus publish a feed post. This is distinct from `create` (drafts future work), `prompt` (creates + executes), and `deliver` (concludes an attached session). `record-work` creates a ticket in `review` with a completed objective and triggers the feed-post generator atomically. Project resolution mirrors `prompt`: cwd is matched against `project_user.local_working_directory`; if no match, ask the user for `--project-id` or pass `--personal`. Do NOT use for in-progress work.
 
+Do NOT use `record-work` for in-progress work. Use it only when the work is already done in the chat.
+
+```bash
+ovld protocol record-work \
+  --objective "User asked me to X; I did Y by..." \
+  --summary  "Narrative for the feed post and reviewer." \
+  --change-rationales-file -
+```
+
+Or stream the full payload via stdin to avoid quote escaping:
+
+```bash
+ovld protocol record-work --payload-file - <<'EOF'
+{
+  "objective": "...",
+  "summary": "...",
+  "artifacts": [{"type": "next_steps", "label": "...", "content": "..."}],
+  "changeRationales": [{"label": "...", "file_path": "...", "summary": "...", "why": "...", "impact": "...", "hunks": [{"header": "@@ ..."}]}]
+}
+EOF
+```
+
+Project resolution mirrors `prompt`/`create`: cwd is matched against the caller's `project_user.local_working_directory`. If no match:
+
+1. **Ask the user for a `--project-id`** if the work is project-related. Show them a brief description of what you're about to record so they can pick the right project.
+2. If the user confirms the work is not tied to any project, pass `--personal` to create a private ticket.
+
+Validation: in a git workspace, `record-work` checks that uncommitted changes are represented by `changeRationales` and rejects if they aren't (same check as `deliver`). Pass `--skip-file-change-check` only when intentionally bypassing.
+
+
 ## Change Rationales
 
 Always include `changeRationales` when delivering. Optionally include them on updates during long-running work.
@@ -120,9 +150,32 @@ When creating tickets from within a repository:
 ```bash
 ovld protocol create --agent cursor --objective "Capture follow-up work from this repository"
 ovld protocol prompt --agent cursor --objective "Implement feature X" --priority medium
+```
+
+To inspect project resolution explicitly:
+
+```bash
 ovld protocol discover-project
 ```
 
+### Resolving the project ID when you don't have one
+
+When you need a project ID for a protocol command and the ticket prompt did not supply one, resolve it in this order.
+
+**Locally (CLI inside a shell on the user's machine):**
+
+1. `--project-id` if explicitly provided.
+2. Otherwise, let the CLI match the current working directory (the default behavior of `create`, `prompt`, `discover-project`).
+3. If working-directory resolution returns nothing, read `overlord.json` from the cwd (or any ancestor you have access to) and pass its project id via `--project-id`.
+
+**Over MCP (web agents and hosted tools, where the server cannot see the agent's cwd):**
+
+1. `--project-id` / `projectId` if explicitly provided.
+2. Read `overlord.json` from the directory the user is accessing and pass its project id as `projectId`.
+3. As a last resort, try `workingDirectory` resolution.
+
+If `overlord.json` contains more than one project, show the user the project **names** from that file and ask which one to use before calling any protocol command — never silently pick one.
+
 ### Choosing `--execution-target`
 
 Pass `--execution-target agent` or `--execution-target human` (default: `human`) when creating tickets.
@@ -174,6 +227,7 @@ This keeps the ticket feed readable while preserving the full document in versio
 - The `summary` in deliver is what the PM reads first, so write it as a narrative, not a command list.
 - If a protocol or MCP call fails with auth/session errors, run `ovld auth repair` yourself before asking the user to log in again or proceed without Overlord updates.
 - If you must run `ovld auth login`, always include `--organization-id <id>` — use the organization ID from the ticket prompt context to select the organization non-interactively and avoid a blocking TTY prompt.
+- Do not add or commit changes unless the user explicitly asks you to commit.
 - Delivery is the concluding step. After delivering, stop unless the user follows up or the ticket is reopened.
 
-<!-- version: 0.4.10 -->
+<!-- version: 0.4.11 -->

package/plugins/overlord/scripts/overlord-mcp.mjs

@@ -292,6 +292,31 @@ const tools = [
     }),
     subcommand: 'ask'
   },
+  {
+    name: 'request_approval_gate',
+    description:
+      'Flip auto_advance=false on the next queued future objective so a human must approve before it runs.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_key: { type: 'string' },
+        ticket_id: {
+          type: 'string',
+          description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.'
+        },
+        reason: { type: 'string' },
+        objective_id: { type: 'string' }
+      },
+      required: ['session_key', 'ticket_id', 'reason']
+    },
+    toCliFlags: args => ({
+      'session-key': args.session_key,
+      'ticket-id': args.ticket_id,
+      reason: args.reason,
+      'objective-id': args.objective_id
+    }),
+    subcommand: 'request-approval-gate'
+  },
   {
     name: 'read_context',
     description: 'Read persistent shared context entries for a ticket.',

package/plugins/overlord/skills/overlord-ticket/SKILL.md

@@ -106,6 +106,24 @@ ovld protocol create --agent codex --objective "Capture follow-up work from this
 ovld protocol prompt --agent codex --objective "Implement feature X" --priority medium
 ```
 
+### Resolving the project ID when you don't have one
+
+When you need a project ID for a protocol command and the ticket prompt did not supply one, resolve it in this order.
+
+**Locally (CLI inside a shell on the user's machine):**
+
+1. `--project-id` if explicitly provided.
+2. Otherwise, let the CLI match the current working directory (the default behavior of `create`, `prompt`, `discover-project`).
+3. If working-directory resolution returns nothing, read `overlord.json` from the cwd (or any ancestor you have access to) and pass its project id via `--project-id`.
+
+**Over MCP (web agents and hosted tools, where the server cannot see the agent's cwd):**
+
+1. `--project-id` / `projectId` if explicitly provided.
+2. Read `overlord.json` from the directory the user is accessing and pass its project id as `projectId`.
+3. As a last resort, try `workingDirectory` resolution.
+
+If `overlord.json` contains more than one project, show the user the project **names** from that file and ask which one to use before calling any protocol command — never silently pick one.
+
 ### Choosing `--execution-target`
 
 Pass `--execution-target agent` or `--execution-target human` (default: `human`) when creating tickets.
@@ -195,4 +213,4 @@ This keeps the ticket feed readable while preserving the full document in versio
 - If a protocol or MCP call fails with auth/session errors, run `ovld auth repair` yourself before asking the user to log in again or proceed without Overlord updates.
 - If you must run `ovld auth login`, always include `--organization-id <id>` — use the organization ID from the ticket prompt context to select the organization non-interactively and avoid a blocking TTY prompt.
 
-<!-- version: 0.4.10 -->
+<!-- version: 0.4.11 -->