overlord-cli 0.2605240843.0 → 0.2605241416.0

package/README.md

@@ -127,7 +127,7 @@ Agents can find docs here: https://www.ovld.ai/docs/for-agents
 - `create` - create a draft ticket without attaching (standalone or follow-up)
 - `prompt` - create a ticket and attach to it immediately (`spawn` is a backward-compatible alias)
 - `record-work` - record already-completed chat work as a ticket in review with a completed objective and trigger feed-post generation
-- `update` - post progress, activity events, and optional change rationales
+- `update` - post progress, discussion/decision events, optional change rationales, and explicit `--begin-follow-up-work` transitions
 - `record-change-rationales` - persist structured change rationales without a normal progress update
 - `ask` - post a blocking question and move the ticket to review
 - `permission-request` - notify Overlord that the agent is requesting tool permission
@@ -151,6 +151,8 @@ Use `create` for future work you want to track, `prompt` for work that should st
 
 `ovld protocol deliver` accepts either discrete flags like `--summary` / `--artifacts-json`, an inline full payload with `--payload-json '{"summary":"...","artifacts":[...],"changeRationales":[...]}'`, or a file/stdin payload with `--payload-file <path|->`.
 
+After delivery, follow-up messages are recorded as discussion by default. To start implementation again on a delivered/review ticket, call `ovld protocol update --begin-follow-up-work --follow-up-intent execution --summary "Beginning follow-up work."` before moving back to `--phase execute`. Use `--event-type discussion_summary` or `--event-type decision` for important non-file outcomes. Once follow-up execution records a real work signal, such as an execution update, git snapshot, change rationales, deliverables, or explicit `pending_delivery` intent, Overlord marks the objective `pending_delivery` so redelivery is only required for actual post-delivery work.
+
 ## License
 
 Permission is granted to use this software for any purpose, free of charge. You may not modify, distribute, sublicense, or sell copies of the software without explicit permission from the author.

package/bin/_cli/add-cwd.mjs

@@ -3,7 +3,7 @@
 // `ovld add-cwd` — interactively add the current working directory as a
 // project resource. Lists the user's projects, prompts for a selection,
 // registers cwd as a primary resource for this device, and writes the
-// project entry into the directory's overlord.json file.
+// project entry into the directory's .overlord/project.json file.
 
 import os from 'node:os';
 import path from 'node:path';
@@ -100,7 +100,7 @@ export async function runAddCwdCommand(args) {
 
 Registers a directory (defaulting to the current working directory) as a
 project resource for this device, and writes the project entry into the
-directory's overlord.json file.
+directory's .overlord/project.json file.
 
 When --project-id is omitted, the command lists your projects and prompts
 you to pick one.
@@ -160,7 +160,7 @@ By default the registered resource is marked primary for this device. Pass
   if (!res.ok) {
     if (res.status === 409) {
       output.write(
-        `\nDirectory is already registered for "${project.name}" on this device. Updating overlord.json only.\n`
+        `\nDirectory is already registered for "${project.name}" on this device. Updating .overlord/project.json only.\n`
       );
     } else {
       console.error(
@@ -178,7 +178,7 @@ By default the registered resource is marked primary for this device. Pass
     output.write(`\nWrote ${result.filePath} (${result.action}).\n`);
   } catch (err) {
     output.write(
-      `\nWarning: could not update overlord.json: ${err instanceof Error ? err.message : err}\n`
+      `\nWarning: could not update .overlord/project.json: ${err instanceof Error ? err.message : err}\n`
     );
   }
 

package/bin/_cli/local-config.mjs

@@ -1,18 +1,60 @@
-// Read/merge/write logic for the per-folder `overlord.json` file.
+// Read/merge/write logic for the per-folder `.overlord/project.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';
+export const OVERLORD_CONFIG_DIRNAME = '.overlord';
+export const OVERLORD_CONFIG_FILENAME = 'project.json';
+export const OVERLORD_SCRATCH_DIRNAME = 'tmp';
+export const OVERLORD_LOG_DIRNAME = 'logs';
 
 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.';
+const GITIGNORE_ENTRIES = ['.overlord/tmp/', '.overlord/logs/'];
 
 function buildConfig(projects) {
   return { _comment: FILE_COMMENT, projects };
 }
 
+function configDirPath(directoryPath) {
+  return path.join(directoryPath, OVERLORD_CONFIG_DIRNAME);
+}
+
+function configFilePath(directoryPath) {
+  return path.join(configDirPath(directoryPath), OVERLORD_CONFIG_FILENAME);
+}
+
+function scratchDirPath(directoryPath) {
+  return path.join(configDirPath(directoryPath), OVERLORD_SCRATCH_DIRNAME);
+}
+
+async function ensureProjectLocalWorkspace(directoryPath) {
+  await fs.mkdir(configDirPath(directoryPath), { recursive: true });
+  await fs.mkdir(scratchDirPath(directoryPath), { recursive: true });
+  await ensureGitignoreEntries(directoryPath);
+}
+
+async function ensureGitignoreEntries(directoryPath) {
+  const gitignorePath = path.join(directoryPath, '.gitignore');
+  let raw = '';
+  try {
+    raw = await fs.readFile(gitignorePath, 'utf8');
+  } catch (error) {
+    if (!error || error.code !== 'ENOENT') throw error;
+  }
+
+  const lines = raw.split(/\r?\n/);
+  const existing = new Set(lines.map(line => line.trim()));
+  const missing = GITIGNORE_ENTRIES.filter(entry => !existing.has(entry));
+  if (missing.length === 0) return;
+
+  const next = raw.trimEnd()
+    ? `${raw.trimEnd()}\n\n# Overlord local scratch\n${missing.join('\n')}\n`
+    : `# Overlord local scratch\n${missing.join('\n')}\n`;
+  await fs.writeFile(gitignorePath, next, 'utf8');
+}
+
 function isProjectArray(value) {
   return (
     Array.isArray(value) &&
@@ -41,11 +83,12 @@ async function readExistingProjects(filePath) {
 }
 
 /**
- * Ensures `directoryPath/overlord.json` lists the project. Returns
+ * Ensures `directoryPath/.overlord/project.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 filePath = configFilePath(directoryPath);
+  await ensureProjectLocalWorkspace(directoryPath);
   const existing = await readExistingProjects(filePath);
 
   if (existing === null) {
@@ -68,12 +111,12 @@ export async function upsertLocalOverlordConfig({ directoryPath, project }) {
 }
 
 /**
- * Removes `projectId` from `directoryPath/overlord.json`. Deletes the file
+ * Removes `projectId` from `directoryPath/.overlord/project.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 filePath = configFilePath(directoryPath);
   const existing = await readExistingProjects(filePath);
 
   if (existing === null) return { filePath, action: 'not-found' };

package/bin/_cli/protocol.mjs

@@ -1023,6 +1023,8 @@ async function protocolUpdate(args) {
       : {}),
     ...(flags.phase ? { phase: String(flags.phase) } : {}),
     ...(flags['event-type'] ? { eventType: String(flags['event-type']) } : {}),
+    ...(flags['begin-follow-up-work'] !== undefined ? { beginFollowUpWork: true } : {}),
+    ...(flags['follow-up-intent'] ? { followUpIntent: String(flags['follow-up-intent']) } : {}),
     ...(flags['payload-json']
       ? { payload: parseJsonFlag('--payload-json', flags['payload-json']) }
       : {}),
@@ -1204,13 +1206,17 @@ async function protocolHookEvent(args) {
     await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
+  const sessionKey = String(flags['session-key'] ?? process.env.SESSION_KEY ?? '');
+
   const body = {
     hookType,
     ticketId,
     ...(flags.prompt !== undefined ? { prompt: String(flags.prompt) } : {}),
     ...(flags['turn-index'] !== undefined
       ? { turnIndex: parseInt(String(flags['turn-index']), 10) }
-      : {})
+      : {}),
+    ...(flags['follow-up-intent'] ? { followUpIntent: String(flags['follow-up-intent']) } : {}),
+    ...(sessionKey ? { sessionKey } : {})
   };
 
   try {
@@ -1833,7 +1839,7 @@ async function protocolAddProjectResource(args) {
       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`
+        `\nWarning: could not write .overlord/project.json: ${configError instanceof Error ? configError.message : configError}\n`
       );
     }
   }
@@ -2696,14 +2702,22 @@ update:
     --summary <text> or --summary-file <path|->
   Optional:
     --phase <status>          draft | execute | review | deliver | complete | blocked | cancelled
-    --event-type <type>       update | user_follow_up | alert
+    --event-type <type>       update | user_follow_up | alert | discussion_summary | decision
+    --begin-follow-up-work    Explicitly reopen a delivered/review ticket for execution
+    --follow-up-intent <mode> discussion | execution | pending_delivery
     --payload-json <json>     Additional structured payload, for example notifications
     --external-url <url|null> Store or clear a deep link to the live agent session
     --external-session-id <id|null>
     --change-rationales-json <json>
     --change-rationales-file <path>
   Notes:
-    Use phase=execute while actively working. user_follow_up is for verbatim human follow-up messages.
+    Use phase=execute while actively working. For delivered/review tickets, pass
+    --begin-follow-up-work before moving back to execute. user_follow_up is for
+    verbatim human follow-up messages; discussion_summary and decision record
+    important non-file follow-up outcomes. After a prior delivery, execution
+    updates, git snapshots, change rationales, or explicit pending_delivery
+    intent mark the objective as pending_delivery so redelivery is required
+    only when follow-up execution produced work.
     Pass --summary-file - to read the summary from stdin — avoids shell interpretation of backticks,
     quotes, or other special characters in the summary text.
 
@@ -2750,6 +2764,7 @@ hook-event:
   Optional:
     --prompt <text>
     --turn-index <n>
+    --follow-up-intent <mode> discussion | execution | pending_delivery
 
 read-context:
   Purpose:
@@ -3082,7 +3097,7 @@ Examples:
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --summary "Done"
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --summary "Done" --artifacts-file ./artifacts.json
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --payload-json '{"summary":"Done","artifacts":[{"type":"note","label":"Delivery","content":"..."}]}'
-  ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --payload-file ./deliver.json
+  ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --payload-file .overlord/tmp/deliver.json
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --payload-file -
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --summary "Done" --skip-file-change-check
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --summary "Done" --timeout 60000

package/bin/_cli/setup.mjs

@@ -208,7 +208,7 @@ If you receive a prompt with a specified ticket ID, adhere to the following. If
    \`\`\`bash
    ovld protocol deliver --session-key <sessionKey> --ticket-id $TICKET_ID --payload-file -
    \`\`\`
-   This avoids creating a scratch delivery file that needs cleanup. If your runtime cannot provide stdin directly, \`--payload-file ./deliver.json\` remains supported; treat that file as ephemeral scratch data, never commit it, and remove it after delivery.
+   This avoids creating a scratch delivery file that needs cleanup. If your runtime cannot provide stdin directly, \`--payload-file .overlord/tmp/deliver.json\` remains supported; treat that file as ephemeral scratch data under \`.overlord/tmp\`, never commit it, and remove it after delivery.
 
 ## Change Rationales
 
@@ -295,7 +295,7 @@ If you receive a prompt with a specified ticket ID, adhere to the following. If
      --artifacts-json '[{"type":"next_steps","label":"Next steps","content":"..."}]' \\\\
      --change-rationales-json '[{"label":"Short reviewer title","file_path":"path/to/file.ts","summary":"What changed.","why":"Why it changed.","impact":"Behavioral impact.","hunks":[{"header":"@@ -10,6 +10,14 @@"}]}]'
    \`\`\`
-   For larger delivery JSON, prefer \`--payload-file -\` and stream the full payload on stdin so no scratch file needs to be created or removed. If you use \`--payload-file\`, \`--artifacts-file\`, or \`--change-rationales-file\` with a real path, treat that file as ephemeral scratch data outside the repository and remove it after delivery. Do not leave delivery JSON checked into the worktree.
+   For larger delivery JSON, prefer \`--payload-file -\` and stream the full payload on stdin so no scratch file needs to be created or removed. If you use \`--payload-file\`, \`--artifacts-file\`, or \`--change-rationales-file\` with a real path, treat that file as ephemeral scratch data under \`.overlord/tmp\` and remove it after delivery. Do not leave delivery JSON checked into the worktree.
 
 ## Change Rationales
 
@@ -381,7 +381,7 @@ When done, deliver with artifacts and change rationales:
 \`\`\`bash
 ovld protocol deliver --session-key <sessionKey> --ticket-id $TICKET_ID --summary "Narrative: what you did, next steps." --artifacts-json '[{"type":"next_steps","label":"Next steps","content":"..."}]' --change-rationales-json '[{"label":"Short reviewer title","file_path":"path/to/file.ts","summary":"What changed.","why":"Why it changed.","impact":"Behavioral impact.","hunks":[{"header":"@@ -10,6 +10,14 @@"}]}]'
 \`\`\`
-Use \`--payload-json\` for compact inline delivery objects. For larger delivery JSON, prefer \`--payload-file -\` with stdin so no scratch file needs to be created or removed. If you use a JSON file for delivery transport, keep it ephemeral scratch data outside the repository and remove it after the protocol call.
+Use \`--payload-json\` for compact inline delivery objects. For larger delivery JSON, prefer \`--payload-file -\` with stdin so no scratch file needs to be created or removed. If you use a JSON file for delivery transport, keep it under \`.overlord/tmp\` and remove it after the protocol call.
 
 Rules:
 - Always attach first and deliver last.
@@ -1670,6 +1670,19 @@ function getPlatformUrl() {
   return process.env.OVERLORD_URL || 'http://localhost:3000';
 }
 
+function printAgentPermissionsDescription() {
+  console.log('Agent permissions pre-approve the `ovld protocol` commands your coding');
+  console.log('agent runs to drive Overlord tickets (attach, update, deliver, etc.) so');
+  console.log('you aren\'t prompted to approve each call mid-task. Without this, the');
+  console.log('agent stalls on permission prompts for every protocol step.');
+  console.log('');
+  console.log('Where each agent\'s permission is written:');
+  console.log('  • Claude Code — ./.claude/settings.local.json (this directory only)');
+  console.log('  • OpenCode    — ~/.config/opencode/opencode.json (global)');
+  console.log('  • Codex       — prints a one-time command to run inside Codex');
+  console.log('Each entry is plain JSON you can review or remove at any time.\n');
+}
+
 function installAgentPermissions(agents, platformUrl) {
   console.log(`\nInstalling agent permissions for: ${agents.join(', ')}`);
   console.log(`Platform URL: ${platformUrl}\n`);
@@ -1878,6 +1891,7 @@ export async function runSetupCommand(args) {
     if (agentsThatNeedPermissions.length > 0) {
       console.log('Agent plugins/connectors prepared successfully!\n');
 
+      printAgentPermissionsDescription();
       const shouldInstallPermissions = await askYesNo(
         'Would you like to configure agent permissions for Overlord protocol access?',
         true
@@ -1923,8 +1937,10 @@ export async function runSetupCommand(args) {
     );
 
     if (agentsThatNeedPermissions.length > 0) {
+      console.log();
+      printAgentPermissionsDescription();
       const shouldInstallPermissions = await askYesNo(
-        '\nWould you like to configure agent permissions for Overlord protocol access?',
+        'Would you like to configure agent permissions for Overlord protocol access?',
         true
       );
 
@@ -1956,8 +1972,10 @@ export async function runSetupCommand(args) {
 
     // Offer permissions setup for single agent install too
     if (['claude', 'codex', 'opencode'].includes(agent)) {
+      console.log();
+      printAgentPermissionsDescription();
       const shouldInstallPermissions = await askYesNo(
-        '\nWould you like to configure agent permissions for Overlord protocol access?',
+        'Would you like to configure agent permissions for Overlord protocol access?',
         true
       );
 

package/package.json

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

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

@@ -327,7 +327,8 @@ const tools = [
   },
   {
     name: 'update',
-    description: 'Post an Overlord progress update or activity event.',
+    description:
+      'Post an Overlord progress update or activity event. Use begin_follow_up_work to explicitly reopen delivered/review tickets for follow-up execution.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -341,7 +342,15 @@ const tools = [
           type: 'string',
           enum: ['draft', 'execute', 'review', 'deliver', 'complete', 'blocked', 'cancelled']
         },
-        event_type: { type: 'string', enum: ['update', 'user_follow_up', 'alert'] },
+        event_type: {
+          type: 'string',
+          enum: ['update', 'user_follow_up', 'alert', 'discussion_summary', 'decision']
+        },
+        begin_follow_up_work: { type: 'boolean' },
+        follow_up_intent: {
+          type: 'string',
+          enum: ['discussion', 'execution', 'pending_delivery']
+        },
         external_url: { type: ['string', 'null'] },
         external_session_id: { type: ['string', 'null'] },
         payload: { type: 'object' },
@@ -355,6 +364,8 @@ const tools = [
       summary: args.summary,
       phase: args.phase,
       'event-type': args.event_type,
+      ...(args.begin_follow_up_work ? { 'begin-follow-up-work': true } : {}),
+      'follow-up-intent': args.follow_up_intent,
       'external-url': args.external_url,
       'external-session-id': args.external_session_id,
       'payload-json': args.payload,
@@ -394,7 +405,7 @@ const tools = [
   {
     name: 'record_hook_event',
     description:
-      'Record a hook lifecycle event for a ticket without requiring a session key. Stop is reserved for future lifecycle hooks.',
+      "Record a hook lifecycle event for a ticket. Use hookType='Stop' with a session_key to check whether delivery is needed after a turn ends.",
     inputSchema: {
       type: 'object',
       properties: {
@@ -404,7 +415,16 @@ const tools = [
           description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.'
         },
         prompt: { type: 'string' },
-        turn_index: { type: 'number' }
+        turn_index: { type: 'number' },
+        follow_up_intent: {
+          type: 'string',
+          enum: ['discussion', 'execution', 'pending_delivery']
+        },
+        session_key: {
+          type: 'string',
+          description:
+            'Optional session key for Stop hooks. When provided, the response includes deliveryStatus indicating whether delivery is needed.'
+        }
       },
       required: ['hook_type', 'ticket_id']
     },
@@ -412,7 +432,9 @@ const tools = [
       'hook-type': args.hook_type,
       'ticket-id': args.ticket_id,
       prompt: args.prompt,
-      'turn-index': args.turn_index
+      'turn-index': args.turn_index,
+      'follow-up-intent': args.follow_up_intent,
+      'session-key': args.session_key
     }),
     subcommand: 'hook-event'
   },
@@ -760,6 +782,10 @@ const tools = [
         device_platform: {
           type: 'string',
           description: 'e.g. darwin, linux, win32.'
+        },
+        device_port: {
+          type: 'integer',
+          description: 'SSH port for placeholder reconciliation when multiple targets share the same host.'
         }
       },
       required: ['device_fingerprint']
@@ -771,7 +797,8 @@ const tools = [
         : {}),
       ...(typeof args.device_platform === 'string' && args.device_platform.trim().length > 0
         ? { 'device-platform': args.device_platform }
-        : {})
+        : {}),
+      ...(typeof args.device_port === 'number' ? { 'device-port': args.device_port } : {})
     }),
     subcommand: 'get-device'
   },
@@ -833,7 +860,11 @@ const tools = [
         label: { type: 'string' },
         is_primary: { type: 'boolean' },
         device_hostname: { type: 'string' },
-        device_platform: { type: 'string' }
+        device_platform: { type: 'string' },
+        device_port: {
+          type: 'integer',
+          description: 'SSH port for placeholder reconciliation when multiple targets share the same host.'
+        }
       },
       required: ['project_id', 'device_fingerprint']
     },
@@ -850,7 +881,8 @@ const tools = [
         : {}),
       ...(typeof args.device_platform === 'string' && args.device_platform.trim().length > 0
         ? { 'device-platform': args.device_platform }
-        : {})
+        : {}),
+      ...(typeof args.device_port === 'number' ? { 'device-port': args.device_port } : {})
     }),
     subcommand: 'add-project-resource'
   },
@@ -885,6 +917,40 @@ const tools = [
     }),
     subcommand: 'update-project-resource'
   },
+  {
+    name: 'request_approval_gate',
+    description:
+      'Flip the next queued future objective on this ticket to require manual human approval before it runs. Use sparingly — only when your current work surfaced a question, risk, or decision a human must make before the next objective auto-launches.',
+    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',
+          description:
+            'Why a human must approve before the next objective runs. Rendered in the awaiting-approval banner verbatim.'
+        },
+        objective_id: {
+          type: 'string',
+          description: 'Optional UUID of a specific future objective to gate. Defaults to the next.'
+        }
+      },
+      required: ['session_key', 'ticket_id', 'reason']
+    },
+    toCliFlags: args => ({
+      'session-key': args.session_key,
+      'ticket-id': args.ticket_id,
+      reason: args.reason,
+      ...(typeof args.objective_id === 'string' && args.objective_id.trim().length > 0
+        ? { 'objective-id': args.objective_id }
+        : {})
+    }),
+    subcommand: 'request-approval-gate'
+  },
   {
     name: 'request_execution',
     description:
@@ -1190,7 +1256,7 @@ async function handleRequest(message) {
       },
       serverInfo: {
         name: 'overlord',
-        version: '0.1.0'
+        version: '0.1.1'
       },
       instructions:
         'Use these tools to drive Overlord ticket workflows through the installed ovld CLI. Names mirror hosted MCP tools (attach, update, deliver, get_device, list_project_resources, …). Session tools need attach/connect. Devices are scoped to organization + user + fingerprint — call get_device before add_project_resource.'

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

@@ -15,7 +15,7 @@ Use this mode when the prompt already contains a ticket ID or explicitly says th
 2. Keep the returned `session.sessionKey` for all follow-up calls.
 3. Treat the Overlord ticket prompt as authoritative for the objective, constraints, and delivery target.
 4. Post updates while working with `ovld protocol update --phase execute`.
-5. Follow-up messages after the initial ticket are captured automatically by the installed `UserPromptSubmit` hook. Do not post `user_follow_up` manually unless the hook is unavailable.
+5. Follow-up messages after the initial ticket are captured automatically by the installed `UserPromptSubmit` hook and stay in discussion intent while the ticket is in review. Do not post `user_follow_up` manually unless the hook is unavailable.
 6. If blocked, call `ovld protocol ask` and stop.
 7. Deliver last with `ovld protocol deliver`, including `changeRationales` for each meaningful behavioral file change.
 
@@ -60,6 +60,14 @@ Event types:
 - `update` for standard progress updates
 - `user_follow_up` for human follow-up messages after the initial ticket when the automatic hook is unavailable
 - `alert` for warnings or non-blocking issues
+- `discussion_summary` for important discussion outcomes that should remain visible on the ticket
+- `decision` for explicit non-file decisions made during follow-up discussion
+
+Post-delivery follow-up modes:
+
+- User follow-up messages default to `discussion` intent while the ticket is in review.
+- Use `ovld protocol update --begin-follow-up-work --follow-up-intent execution --summary "Beginning follow-up work."` before moving a delivered/review ticket back to execution.
+- Use `--follow-up-intent pending_delivery` when implementation is complete but final delivery is still being prepared.
 
 Ask when blocked:
 
@@ -77,7 +85,7 @@ ovld protocol deliver --session-key <sessionKey> \
   --change-rationales-json '[{"label":"Short reviewer title","file_path":"path/to/file.ts","summary":"What changed.","why":"Why it changed.","impact":"Behavioral impact.","hunks":[{"header":"@@ -10,6 +10,14 @@"}]}]'
 ```
 
-Use `--payload-json` when the full delivery object fits comfortably inline. For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed. If the summary contains special characters, use `--summary-file -` and pipe via a single-quoted heredoc (`<<'EOF'`) to prevent shell expansion. If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data outside the repository and remove it after delivery.
+Use `--payload-json` when the full delivery object fits comfortably inline. For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed. If the summary contains special characters, use `--summary-file -` and pipe via a single-quoted heredoc (`<<'EOF'`) to prevent shell expansion. If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data under `.overlord/tmp` and remove it after delivery.
 
 Revert an objective:
 
@@ -190,15 +198,15 @@ When you need a project ID for a protocol command and the ticket prompt did not
 
 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`.
+3. If working-directory resolution returns nothing, read `.overlord/project.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. `projectId` (hosted MCP) or `project_id` (local shim) if explicitly provided or found in the ticket/context.
-2. Read `overlord.json` from the directory the user is accessing and pass its project id as `projectId` / `project_id`.
+2. Read `.overlord/project.json` from the directory the user is accessing and pass its project id as `projectId` / `project_id`.
 3. As a last resort, try `workingDirectory` / `working_directory` resolution. If a device fingerprint is available, include `deviceFingerprint` / `device_fingerprint`.
 
-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.
+If `.overlord/project.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.
 
 ### Devices and checkout paths
 
@@ -256,12 +264,16 @@ This keeps the ticket feed readable while preserving the full document in versio
 - Always attach first and always deliver last once you are on a ticket.
 - Use `ovld protocol` commands and the plugin's slash commands instead of ad hoc scripts.
 - Do not invent protocol subcommands. Use `ovld protocol help` when unsure.
+- After delivery, answer ordinary questions and clarifications in discussion mode; only begin follow-up execution when the user explicitly asks for file or code changes.
+- When explicit follow-up implementation starts on a delivered/review ticket, call `ovld protocol update --begin-follow-up-work --follow-up-intent execution --summary "Beginning follow-up work."` before code changes or `--phase execute`.
+- During follow-up execution, post progress updates and record change rationales for each file modified, the same as during initial execution.
+- Record important non-file decisions with `--event-type decision` or `--event-type discussion_summary`.
 - The `summary` in deliver is what the PM reads first, so write it as a narrative, not a command list.
 - When a summary or question contains backticks, `$vars`, or other shell-special characters, always use `--summary-file -` (or `--question-file -`) with a single-quoted heredoc (`<<'EOF'`). Never retry by stripping or escaping content — pipe stdin instead.
 - Use `write-context` for facts a future agent session should know.
 - 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`, `--organization-id <id>` is optional — use it only when you want to set a different default organization than the CLI would choose automatically.
 - 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.
+- Delivery is the concluding step. After delivering, stop implementation work unless the user explicitly asks for follow-up execution; once follow-up execution is complete, deliver again.
 
-<!-- version: 0.1.2 -->
+<!-- version: 0.1.5 -->

package/plugins/claude/hooks/hooks.json

@@ -21,6 +21,17 @@
           }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/stop-hook.sh"
+          }
+        ]
+      }
     ]
   }
 }

package/plugins/claude/scripts/stop-hook.sh

@@ -0,0 +1,78 @@
+#!/bin/bash
+# Overlord Stop hook — fires when the agent's turn ends.
+# Checks whether the session has pending delivery work and outputs
+# guidance if delivery is needed. Does not force delivery.
+
+BODY=$(cat -)
+OVERLORD_BASE_URL="${CLAUDE_PLUGIN_OPTION_OVERLORD_URL:-$OVERLORD_URL}"
+OVERLORD_TOKEN="${CLAUDE_PLUGIN_OPTION_AGENT_TOKEN:-${CLAUDE_PLUGIN_OPTION_OVERLORD_ACCESS_TOKEN:-$OVERLORD_ACCESS_TOKEN}}"
+OVERLORD_LOCAL_SECRET="${OVERLORD_LOCAL_SECRET:-}"
+LOG_DIR="${HOME:-}/.ovld/logs"
+LOG_FILE="${LOG_DIR}/stop-hook.log"
+
+log_hook() {
+  mkdir -p "$LOG_DIR" 2>/dev/null || return 0
+  printf '%s [stop] %s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" "$1" >>"$LOG_FILE" 2>/dev/null || true
+}
+
+if [ -z "$OVERLORD_BASE_URL" ] || [ -z "$OVERLORD_TOKEN" ] || [ -z "${TICKET_ID:-}" ]; then
+  log_hook "missing required env, skipping"
+  exit 0
+fi
+
+SESSION_KEY=$(python3 -c "
+import base64, json, os, tempfile
+cwd = os.getcwd().encode()
+encoded = base64.urlsafe_b64encode(cwd).decode().rstrip('=')
+session_file = os.path.join(tempfile.gettempdir(), f'.overlord-session-{encoded}')
+try:
+    with open(session_file) as f:
+        data = json.load(f)
+        print(data.get('sessionKey', ''))
+except Exception:
+    print('')
+" 2>/dev/null)
+
+if [ -z "$SESSION_KEY" ]; then
+  log_hook "no persisted session key, skipping delivery check"
+  exit 0
+fi
+
+PAYLOAD="{\"hookType\":\"Stop\",\"ticketId\":\"$TICKET_ID\",\"sessionKey\":\"$SESSION_KEY\"}"
+
+log_hook "checking delivery status session_key=${SESSION_KEY:0:8}..."
+
+RESPONSE_FILE=$(mktemp "${TMPDIR:-/tmp}/overlord-stop-hook.XXXXXX")
+HTTP_CODE=$(curl -sS -m 5 -o "$RESPONSE_FILE" -w "%{http_code}" \
+  -X POST "$OVERLORD_BASE_URL/api/protocol/hook-event" \
+  -H "Authorization: Bearer $OVERLORD_TOKEN" \
+  -H "X-Overlord-Local-Secret: $OVERLORD_LOCAL_SECRET" \
+  -H "Content-Type: application/json" \
+  -d "$PAYLOAD")
+CURL_EXIT=$?
+
+if [ "$CURL_EXIT" -eq 0 ] && [ -f "$RESPONSE_FILE" ]; then
+  GUIDANCE=$(python3 -c "
+import json, sys
+try:
+    with open(sys.argv[1]) as f:
+        data = json.load(f)
+    status = data.get('deliveryStatus')
+    if status and status.get('needed'):
+        print(status.get('reason', 'Pending delivery work detected.'))
+except Exception:
+    pass
+" "$RESPONSE_FILE" 2>/dev/null)
+
+  if [ -n "$GUIDANCE" ]; then
+    log_hook "delivery needed, outputting guidance"
+    echo "[Overlord] $GUIDANCE"
+  else
+    log_hook "no delivery needed"
+  fi
+else
+  log_hook "hook-event POST failed exit=$CURL_EXIT http_status=${HTTP_CODE:-none}"
+fi
+
+rm -f "$RESPONSE_FILE"
+exit 0

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

@@ -15,7 +15,7 @@ Use this mode when the prompt already contains a ticket ID or explicitly says th
 2. The attach response prints JSON to stdout containing `session.sessionKey`. The CLI also persists this key automatically so subsequent `ovld protocol` commands in the same working directory resolve it without `--session-key`. If auto-resolution fails, pass `--session-key <sessionKey>` explicitly on every subsequent call.
 3. Treat the Overlord ticket prompt as authoritative for the objective, constraints, and delivery target.
 4. Post updates while working: `ovld protocol update --session-key <sessionKey> --ticket-id <ticket_id> --summary "..." --phase execute`.
-5. Follow-up messages after the initial ticket are captured automatically by the installed `UserPromptSubmit` hook. Do not post `user_follow_up` manually unless the hook is unavailable.
+5. Follow-up messages after the initial ticket are captured automatically by the installed `UserPromptSubmit` hook and stay in discussion intent while the ticket is in review. Do not post `user_follow_up` manually unless the hook is unavailable.
 6. If blocked, call `ovld protocol ask --session-key <sessionKey> --ticket-id <ticket_id> --question "..."` and stop.
 7. Deliver last with `ovld protocol deliver --session-key <sessionKey> --ticket-id <ticket_id> --summary "..."`, including `changeRationales` for each meaningful behavioral file change.
 
@@ -93,13 +93,17 @@ For the `record-change-rationales` command and full payload shape with optional
 - Use `ovld protocol` commands and the plugin's slash commands instead of ad hoc scripts.
 - Do not invent protocol subcommands. Use `ovld protocol help` when unsure.
 - Include at least one progress update before delivering.
+- After delivery, answer ordinary questions and clarifications in discussion mode; only begin follow-up execution when the user explicitly asks for file or code changes.
+- When explicit follow-up implementation starts on a delivered/review ticket, call `ovld protocol update --begin-follow-up-work --follow-up-intent execution --summary "Beginning follow-up work."` before code changes or `--phase execute`.
+- During follow-up execution, post progress updates and record change rationales for each file modified, the same as during initial execution.
+- Record important non-file decisions with `--event-type decision` or `--event-type discussion_summary`.
 - The `summary` in deliver is what the PM reads first, so write it as a narrative, not a command list.
 - When a summary or question contains backticks, `$vars`, or other shell-special characters, always use `--summary-file -` (or `--question-file -`) with a single-quoted heredoc (`<<'EOF'`). Never retry by stripping or escaping content — pipe stdin instead. See [reference/shell-escaping.md](reference/shell-escaping.md).
 - Use `write-context` for facts a future agent session should know.
 - 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`, `--organization-id <id>` is optional — use it only when you want to set a different default organization than the CLI would choose automatically.
 - 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.
+- Delivery is the concluding step. After delivering, stop implementation work unless the user explicitly asks for follow-up execution; once follow-up execution is complete, deliver again.
 
 ## Reference
 
@@ -109,5 +113,5 @@ For the `record-change-rationales` command and full payload shape with optional
 - [reference/context.md](reference/context.md) — Shared state, attachments, and large artifact policy
 - [reference/shell-escaping.md](reference/shell-escaping.md) — Heredoc stdin piping for special characters in summaries and payloads
 
-<!-- version: 0.5.6 -->
+<!-- version: 0.5.8 -->
 

package/plugins/claude/skills/overlord-ticket/reference/cli.md

@@ -31,6 +31,14 @@ Event types:
 - `update` for standard progress updates
 - `user_follow_up` — only when the `UserPromptSubmit` hook is unavailable; the hook normally posts follow-ups to the activity feed
 - `alert` for warnings or non-blocking issues
+- `discussion_summary` for important discussion outcomes that should remain visible on the ticket
+- `decision` for explicit non-file decisions made during follow-up discussion
+
+Post-delivery follow-up modes:
+
+- User follow-up messages default to `discussion` intent while the ticket is in review.
+- Use `ovld protocol update --begin-follow-up-work --follow-up-intent execution --summary "Beginning follow-up work."` before moving a delivered/review ticket back to execution.
+- Use `--follow-up-intent pending_delivery` when implementation is complete but final delivery is still being prepared.
 
 ## Ask
 
@@ -48,7 +56,7 @@ ovld protocol deliver --session-key <sessionKey> \
   --change-rationales-json '[{"label":"Short reviewer title","file_path":"path/to/file.ts","summary":"What changed.","why":"Why it changed.","impact":"Behavioral impact.","hunks":[{"header":"@@ -10,6 +10,14 @@"}]}]'
 ```
 
-Use `--payload-json` when the full delivery object fits comfortably inline. For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed. If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data outside the repository and remove it after delivery.
+Use `--payload-json` when the full delivery object fits comfortably inline. For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed. If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data under `.overlord/tmp` and remove it after delivery.
 
 Ordinary deliver artifacts should use `next_steps`, `test_results`, `migration`, `note`, `url`, or `decision`.
 
@@ -132,13 +140,13 @@ When you need a project ID for a protocol command and the ticket prompt did not
 
 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`.
+3. If working-directory resolution returns nothing, read `.overlord/project.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. `projectId` (hosted MCP) or `project_id` (local shim) if explicitly provided or found in the ticket/context.
-2. Read `overlord.json` from the directory the user is accessing and pass its project id as `projectId` / `project_id`.
+2. Read `.overlord/project.json` from the directory the user is accessing and pass its project id as `projectId` / `project_id`.
 3. As a last resort, try `workingDirectory` / `working_directory` resolution. If a device fingerprint is available, include `deviceFingerprint` / `device_fingerprint`.
 
-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.
+If `.overlord/project.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.
 

package/plugins/claude/skills/overlord-ticket/reference/shell-escaping.md

@@ -12,5 +12,5 @@ Use `--payload-json` when the full delivery object fits comfortably inline. For
 
 If the summary contains special characters, use `--summary-file -` and pipe via a single-quoted heredoc (`<<'EOF'`) to prevent shell expansion.
 
-If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data outside the repository and remove it after delivery.
+If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data under `.overlord/tmp` and remove it after delivery.
 

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

@@ -15,7 +15,7 @@ Use this mode when the prompt already contains a ticket ID or explicitly says th
 2. The attach response prints JSON to stdout containing `session.sessionKey`. The CLI also persists this key automatically so subsequent `ovld protocol` commands in the same working directory resolve it without `--session-key`. If auto-resolution fails, pass `--session-key <sessionKey>` explicitly on every subsequent call.
 3. Treat the Overlord ticket prompt as authoritative for the objective, constraints, and delivery target.
 4. Post updates while working: `ovld protocol update --session-key <sessionKey> --ticket-id <ticket_id> --summary "..." --phase execute`.
-5. Follow-up messages after the initial ticket are captured automatically by the installed Cursor `beforeSubmitPrompt` hook (see `~/.cursor/hooks.json`). Do not post `user_follow_up` manually unless the hook is unavailable.
+5. Follow-up messages after the initial ticket are captured automatically by the installed Cursor `beforeSubmitPrompt` hook (see `~/.cursor/hooks.json`) and stay in discussion intent while the ticket is in review. Do not post `user_follow_up` manually unless the hook is unavailable.
 6. If blocked, call `ovld protocol ask --session-key <sessionKey> --ticket-id <ticket_id> --question "..."` and stop.
 7. Deliver last with `ovld protocol deliver --session-key <sessionKey> --ticket-id <ticket_id> --summary "..."`, including `changeRationales` for each meaningful behavioral file change.
 
@@ -93,13 +93,17 @@ For the `record-change-rationales` command and full payload shape with optional
 - Use `ovld protocol` commands, the plugin commands, and the MCP tool instead of ad hoc scripts.
 - Do not invent protocol subcommands. Use `ovld protocol help` when unsure.
 - Include at least one progress update before delivering.
+- After delivery, answer ordinary questions and clarifications in discussion mode; only begin follow-up execution when the user explicitly asks for file or code changes.
+- When explicit follow-up implementation starts on a delivered/review ticket, call `ovld protocol update --begin-follow-up-work --follow-up-intent execution --summary "Beginning follow-up work."` before code changes or `--phase execute`.
+- During follow-up execution, post progress updates and record change rationales for each file modified, the same as during initial execution.
+- Record important non-file decisions with `--event-type decision` or `--event-type discussion_summary`.
 - The `summary` in deliver is what the PM reads first, so write it as a narrative, not a command list.
 - When a summary or question contains backticks, `$vars`, or other shell-special characters, always use `--summary-file -` (or `--question-file -`) with a single-quoted heredoc (`<<'EOF'`). Never retry by stripping or escaping content — pipe stdin instead. See [reference/shell-escaping.md](reference/shell-escaping.md).
 - Use `write-context` for facts a future agent session should know.
 - 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`, `--organization-id <id>` is optional — use it only when you want to set a different default organization than the CLI would choose automatically.
 - 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.
+- Delivery is the concluding step. After delivering, stop implementation work unless the user explicitly asks for follow-up execution; once follow-up execution is complete, deliver again.
 
 ## Reference
 
@@ -109,5 +113,5 @@ For the `record-change-rationales` command and full payload shape with optional
 - [reference/context.md](reference/context.md) — Shared state, attachments, and large artifact policy
 - [reference/shell-escaping.md](reference/shell-escaping.md) — Heredoc stdin piping for special characters in summaries and payloads
 
-<!-- version: 0.5.6 -->
+<!-- version: 0.5.8 -->
 

package/plugins/cursor/skills/overlord-ticket/reference/cli.md

@@ -31,6 +31,14 @@ Event types:
 - `update` for standard progress updates
 - `user_follow_up` — only when the Cursor `beforeSubmitPrompt` hook (see `~/.cursor/hooks.json`) is unavailable; the hook normally posts follow-ups to the activity feed
 - `alert` for warnings or non-blocking issues
+- `discussion_summary` for important discussion outcomes that should remain visible on the ticket
+- `decision` for explicit non-file decisions made during follow-up discussion
+
+Post-delivery follow-up modes:
+
+- User follow-up messages default to `discussion` intent while the ticket is in review.
+- Use `ovld protocol update --begin-follow-up-work --follow-up-intent execution --summary "Beginning follow-up work."` before moving a delivered/review ticket back to execution.
+- Use `--follow-up-intent pending_delivery` when implementation is complete but final delivery is still being prepared.
 
 ## Ask
 
@@ -48,7 +56,7 @@ ovld protocol deliver --session-key <sessionKey> \
   --change-rationales-json '[{"label":"Short reviewer title","file_path":"path/to/file.ts","summary":"What changed.","why":"Why it changed.","impact":"Behavioral impact.","hunks":[{"header":"@@ -10,6 +10,14 @@"}]}]'
 ```
 
-Use `--payload-json` when the full delivery object fits comfortably inline. For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed. If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data outside the repository and remove it after delivery.
+Use `--payload-json` when the full delivery object fits comfortably inline. For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed. If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data under `.overlord/tmp` and remove it after delivery.
 
 Ordinary deliver artifacts should use `next_steps`, `test_results`, `migration`, `note`, `url`, or `decision`.
 
@@ -132,13 +140,13 @@ When you need a project ID for a protocol command and the ticket prompt did not
 
 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`.
+3. If working-directory resolution returns nothing, read `.overlord/project.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. `projectId` (hosted MCP) or `project_id` (local shim) if explicitly provided or found in the ticket/context.
-2. Read `overlord.json` from the directory the user is accessing and pass its project id as `projectId` / `project_id`.
+2. Read `.overlord/project.json` from the directory the user is accessing and pass its project id as `projectId` / `project_id`.
 3. As a last resort, try `workingDirectory` / `working_directory` resolution. If a device fingerprint is available, include `deviceFingerprint` / `device_fingerprint`.
 
-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.
+If `.overlord/project.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.
 

package/plugins/cursor/skills/overlord-ticket/reference/shell-escaping.md

@@ -12,5 +12,5 @@ Use `--payload-json` when the full delivery object fits comfortably inline. For
 
 If the summary contains special characters, use `--summary-file -` and pipe via a single-quoted heredoc (`<<'EOF'`) to prevent shell expansion.
 
-If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data outside the repository and remove it after delivery.
+If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data under `.overlord/tmp` and remove it after delivery.
 

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

@@ -327,7 +327,8 @@ const tools = [
   },
   {
     name: 'update',
-    description: 'Post an Overlord progress update or activity event.',
+    description:
+      'Post an Overlord progress update or activity event. Use begin_follow_up_work to explicitly reopen delivered/review tickets for follow-up execution.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -341,7 +342,15 @@ const tools = [
           type: 'string',
           enum: ['draft', 'execute', 'review', 'deliver', 'complete', 'blocked', 'cancelled']
         },
-        event_type: { type: 'string', enum: ['update', 'user_follow_up', 'alert'] },
+        event_type: {
+          type: 'string',
+          enum: ['update', 'user_follow_up', 'alert', 'discussion_summary', 'decision']
+        },
+        begin_follow_up_work: { type: 'boolean' },
+        follow_up_intent: {
+          type: 'string',
+          enum: ['discussion', 'execution', 'pending_delivery']
+        },
         external_url: { type: ['string', 'null'] },
         external_session_id: { type: ['string', 'null'] },
         payload: { type: 'object' },
@@ -355,6 +364,8 @@ const tools = [
       summary: args.summary,
       phase: args.phase,
       'event-type': args.event_type,
+      ...(args.begin_follow_up_work ? { 'begin-follow-up-work': true } : {}),
+      'follow-up-intent': args.follow_up_intent,
       'external-url': args.external_url,
       'external-session-id': args.external_session_id,
       'payload-json': args.payload,
@@ -394,7 +405,7 @@ const tools = [
   {
     name: 'record_hook_event',
     description:
-      'Record a hook lifecycle event for a ticket without requiring a session key. Stop is reserved for future lifecycle hooks.',
+      "Record a hook lifecycle event for a ticket. Use hookType='Stop' with a session_key to check whether delivery is needed after a turn ends.",
     inputSchema: {
       type: 'object',
       properties: {
@@ -404,7 +415,16 @@ const tools = [
           description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.'
         },
         prompt: { type: 'string' },
-        turn_index: { type: 'number' }
+        turn_index: { type: 'number' },
+        follow_up_intent: {
+          type: 'string',
+          enum: ['discussion', 'execution', 'pending_delivery']
+        },
+        session_key: {
+          type: 'string',
+          description:
+            'Optional session key for Stop hooks. When provided, the response includes deliveryStatus indicating whether delivery is needed.'
+        }
       },
       required: ['hook_type', 'ticket_id']
     },
@@ -412,7 +432,9 @@ const tools = [
       'hook-type': args.hook_type,
       'ticket-id': args.ticket_id,
       prompt: args.prompt,
-      'turn-index': args.turn_index
+      'turn-index': args.turn_index,
+      'follow-up-intent': args.follow_up_intent,
+      'session-key': args.session_key
     }),
     subcommand: 'hook-event'
   },
@@ -1197,7 +1219,7 @@ async function handleRequest(message) {
       },
       serverInfo: {
         name: 'overlord',
-        version: '0.1.5'
+        version: '0.1.6'
       },
       instructions:
         'Use these tools to drive Overlord ticket workflows through the installed ovld CLI. Names mirror hosted MCP tools (attach, update, deliver, get_device, list_project_resources, …). Session tools need attach/connect. Devices are scoped to organization + user + fingerprint — call get_device before add_project_resource.'

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

@@ -15,7 +15,7 @@ Use this mode when the prompt already contains a ticket ID or explicitly says th
 2. The attach response prints JSON to stdout containing `session.sessionKey`. The CLI also persists this key automatically so subsequent `ovld protocol` commands in the same working directory resolve it without `--session-key`. If auto-resolution fails, pass `--session-key <sessionKey>` explicitly on every subsequent call.
 3. Treat the Overlord ticket prompt as authoritative for the objective, constraints, and delivery target.
 4. Post updates while working: `ovld protocol update --session-key <sessionKey> --ticket-id <ticket_id> --summary "..." --phase execute`.
-5. Follow-up messages after the initial ticket are captured automatically by the installed `UserPromptSubmit` hook. Do not post `user_follow_up` manually unless the hook is unavailable.
+5. Follow-up messages after the initial ticket are captured automatically by the installed `UserPromptSubmit` hook and stay in discussion intent while the ticket is in review. Do not post `user_follow_up` manually unless the hook is unavailable.
 6. If blocked, call `ovld protocol ask --session-key <sessionKey> --ticket-id <ticket_id> --question "..."` and stop.
 7. Deliver last with `ovld protocol deliver --session-key <sessionKey> --ticket-id <ticket_id> --summary "..."`, including `changeRationales` for each meaningful behavioral file change.
 
@@ -93,6 +93,10 @@ For the `record-change-rationales` command and full payload shape with optional
 - Use `ovld protocol` commands and the plugin's MCP tools instead of ad hoc scripts.
 - Do not invent protocol subcommands. Use `ovld protocol help` when unsure.
 - Include at least one progress update before delivering.
+- After delivery, answer ordinary questions and clarifications in discussion mode; only begin follow-up execution when the user explicitly asks for file or code changes.
+- When explicit follow-up implementation starts on a delivered/review ticket, call `ovld protocol update --begin-follow-up-work --follow-up-intent execution --summary "Beginning follow-up work."` before code changes or `--phase execute`.
+- During follow-up execution, post progress updates and record change rationales for each file modified, the same as during initial execution.
+- Record important non-file decisions with `--event-type decision` or `--event-type discussion_summary`.
 - The `summary` in deliver is what the PM reads first, so write it as a narrative, not a command list.
 - When a summary or question contains backticks, `$vars`, or other shell-special characters, always use `--summary-file -` (or `--question-file -`) with a single-quoted heredoc (`<<'EOF'`). Never retry by stripping or escaping content — pipe stdin instead. See [reference/shell-escaping.md](reference/shell-escaping.md).
 - Use `write-context` for facts a future agent session should know.
@@ -100,7 +104,7 @@ For the `record-change-rationales` command and full payload shape with optional
 - If you must run `ovld auth login`, `--organization-id <id>` is optional — use it only when you want to set a different default organization than the CLI would choose automatically.
 - Do not add or commit changes unless the user explicitly asks you to commit.
 - Do not create or rely on a local Codex `AGENTS.md` bundle for Overlord.
-- Delivery is the concluding step. After delivering, stop unless the user follows up or the ticket is reopened.
+- Delivery is the concluding step. After delivering, stop implementation work unless the user explicitly asks for follow-up execution; once follow-up execution is complete, deliver again.
 
 ## Reference
 
@@ -110,5 +114,5 @@ For the `record-change-rationales` command and full payload shape with optional
 - [reference/context.md](reference/context.md) — Shared state, attachments, and large artifact policy
 - [reference/shell-escaping.md](reference/shell-escaping.md) — Heredoc stdin piping for special characters in summaries and payloads
 
-<!-- version: 0.5.6 -->
+<!-- version: 0.5.8 -->
 

package/plugins/overlord/skills/overlord-ticket/reference/cli.md

@@ -31,6 +31,14 @@ Event types:
 - `update` for standard progress updates
 - `user_follow_up` — only when the `UserPromptSubmit` hook is unavailable; the hook normally posts follow-ups to the activity feed
 - `alert` for warnings or non-blocking issues
+- `discussion_summary` for important discussion outcomes that should remain visible on the ticket
+- `decision` for explicit non-file decisions made during follow-up discussion
+
+Post-delivery follow-up modes:
+
+- User follow-up messages default to `discussion` intent while the ticket is in review.
+- Use `ovld protocol update --begin-follow-up-work --follow-up-intent execution --summary "Beginning follow-up work."` before moving a delivered/review ticket back to execution.
+- Use `--follow-up-intent pending_delivery` when implementation is complete but final delivery is still being prepared.
 
 ## Ask
 
@@ -48,7 +56,7 @@ ovld protocol deliver --session-key <sessionKey> \
   --change-rationales-json '[{"label":"Short reviewer title","file_path":"path/to/file.ts","summary":"What changed.","why":"Why it changed.","impact":"Behavioral impact.","hunks":[{"header":"@@ -10,6 +10,14 @@"}]}]'
 ```
 
-Use `--payload-json` when the full delivery object fits comfortably inline. For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed. If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data outside the repository and remove it after delivery.
+Use `--payload-json` when the full delivery object fits comfortably inline. For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed. If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data under `.overlord/tmp` and remove it after delivery.
 
 Ordinary deliver artifacts should use `next_steps`, `test_results`, `migration`, `note`, `url`, or `decision`.
 
@@ -132,13 +140,13 @@ When you need a project ID for a protocol command and the ticket prompt did not
 
 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`.
+3. If working-directory resolution returns nothing, read `.overlord/project.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. `projectId` (hosted MCP) or `project_id` (local shim) if explicitly provided or found in the ticket/context.
-2. Read `overlord.json` from the directory the user is accessing and pass its project id as `projectId` / `project_id`.
+2. Read `.overlord/project.json` from the directory the user is accessing and pass its project id as `projectId` / `project_id`.
 3. As a last resort, try `workingDirectory` / `working_directory` resolution. If a device fingerprint is available, include `deviceFingerprint` / `device_fingerprint`.
 
-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.
+If `.overlord/project.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.
 

package/plugins/overlord/skills/overlord-ticket/reference/shell-escaping.md

@@ -12,5 +12,5 @@ Use `--payload-json` when the full delivery object fits comfortably inline. For
 
 If the summary contains special characters, use `--summary-file -` and pipe via a single-quoted heredoc (`<<'EOF'`) to prevent shell expansion.
 
-If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data outside the repository and remove it after delivery.
+If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data under `.overlord/tmp` and remove it after delivery.