overlord-cli 0.2605131058.0 → 0.2605150751.0

package/README.md

@@ -117,6 +117,7 @@ Agents can find docs here: https://www.ovld.ai/docs/for-agents
 - `search-tickets` - find tickets by keyword, status, project, creator, or update date
 - `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
 - `record-change-rationales` - persist structured change rationales without a normal progress update
 - `ask` - post a blocking question and move the ticket to review
@@ -130,6 +131,8 @@ Agents can find docs here: https://www.ovld.ai/docs/for-agents
 - `attachment-download-url` - get a signed download URL for an existing objective attachment
 - `attachment-upload-file` - prepare, upload, and finalize a local objective attachment in one command
 
+Use `create` for future work you want to track, `prompt` for work that should start immediately, and `record-work` for work that was already completed in chat and now needs a review ticket plus feed post.
+
 `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|->`.
 
 ## License

package/bin/_cli/protocol.mjs

@@ -1570,6 +1570,34 @@ async function protocolPrompt(args) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// discuss-objective (mark a draft objective as submitted)
+// ---------------------------------------------------------------------------
+
+async function protocolDiscussObjective(args) {
+  const flags = parseFlags(args);
+  const ticketId = requireFlag(flags, 'ticket-id', process.env.TICKET_ID);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags, ticketId);
+  const timeoutMs = resolveTimeout(flags);
+
+  const body = {
+    ticketId,
+    ...(flags['objective-id'] ? { objectiveId: String(flags['objective-id']) } : {})
+  };
+
+  const data = await apiPost(
+    platformUrl,
+    bearerToken,
+    localSecret,
+    organizationId,
+    '/api/protocol/discuss-objective',
+    body,
+    timeoutMs
+  );
+  console.log(JSON.stringify(data, null, 2));
+}
+
 // ---------------------------------------------------------------------------
 // create (create follow-up ticket draft only)
 // ---------------------------------------------------------------------------
@@ -1654,6 +1682,120 @@ async function protocolCreateTicket(args) {
   console.log(JSON.stringify(data, null, 2));
 }
 
+// ---------------------------------------------------------------------------
+// record-work (one-shot: create ticket in review + completed objective + feed post)
+// ---------------------------------------------------------------------------
+
+async function protocolRecordWork(args) {
+  const flags = parseFlags(args);
+
+  if (flags['payload-file'] && flags['payload-json']) {
+    throw new Error('Use either --payload-file or --payload-json, not both');
+  }
+  const payload = flags['payload-file']
+    ? await readJsonFileOrStdin(String(flags['payload-file']), '--payload-file')
+    : flags['payload-json']
+      ? parseJsonFlag('--payload-json', flags['payload-json'])
+      : null;
+
+  if (payload && (flags.summary || flags['summary-file'])) {
+    throw new Error('Use either payload input or --summary/--summary-file, not both');
+  }
+  if (payload && (flags.objective || flags['objective-file'])) {
+    throw new Error('Use either payload input or --objective/--objective-file, not both');
+  }
+
+  const objective = payload
+    ? (() => {
+        const value = payload.objective;
+        if (typeof value !== 'string' || !value.trim()) {
+          throw new Error('payload input must include a non-empty objective');
+        }
+        return value;
+      })()
+    : flags['objective-file']
+      ? await readTextFileOrStdin(String(flags['objective-file']), '--objective-file')
+      : requireFlag(flags, 'objective', undefined);
+
+  const summary = payload
+    ? (() => {
+        const value = payload.summary;
+        if (typeof value !== 'string' || !value.trim()) {
+          throw new Error('payload input must include a non-empty summary');
+        }
+        return value;
+      })()
+    : flags['summary-file']
+      ? await readTextFileOrStdin(String(flags['summary-file']), '--summary-file')
+      : requireFlag(flags, 'summary', undefined);
+
+  let artifacts = payload?.artifacts ?? [];
+  if (payload && (flags['artifacts-file'] || flags['artifacts-json'])) {
+    throw new Error('Use either payload input or artifact flags, not both');
+  }
+  if (flags['artifacts-file']) {
+    artifacts = await readJsonFileOrStdin(String(flags['artifacts-file']), '--artifacts-file');
+  } else if (flags['artifacts-json']) {
+    artifacts = parseJsonFlag('--artifacts-json', flags['artifacts-json']);
+  }
+
+  if (payload && (flags['change-rationales-file'] || flags['change-rationales-json'])) {
+    throw new Error('Use either payload input or change-rationale flags, not both');
+  }
+  const changeRationales = payload?.changeRationales ?? (await resolveChangeRationales(flags));
+
+  // record-work has no live session, but the same git-changed-files guard
+  // helps catch missing rationales. Apply the same opt-out semantics as deliver.
+  validateDeliverFileChanges(flags, changeRationales);
+
+  const personal = Boolean(flags.personal);
+  const workingDirectory =
+    flags['working-directory'] ?? (!flags['project-id'] && !personal ? process.cwd() : undefined);
+
+  const agentIdentifier = resolveProtocolAgentIdentifier(flags);
+  const modelIdentifier = resolveProtocolModelIdentifier(flags);
+
+  const body = {
+    objective,
+    summary,
+    artifacts,
+    changeRationales,
+    agentIdentifier,
+    connectionMethod: String(flags.method ?? 'cli'),
+    metadata: await resolveProtocolMetadata(flags, { cwd: process.cwd() }),
+    ...(flags.title ? { title: String(flags.title) } : {}),
+    ...(flags.priority ? { priority: String(flags.priority) } : {}),
+    ...(flags['project-id'] ? { projectId: String(flags['project-id']) } : {}),
+    ...(personal ? { personal: true } : {}),
+    ...(workingDirectory ? { workingDirectory: String(workingDirectory) } : {}),
+    ...(flags['acceptance-criteria']
+      ? { acceptanceCriteria: String(flags['acceptance-criteria']) }
+      : {}),
+    ...(flags['available-tools'] ? { availableTools: String(flags['available-tools']) } : {}),
+    delegate: resolveProtocolTicketDelegate(flags, modelIdentifier, agentIdentifier)
+  };
+
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags);
+  const timeoutMs = resolveTimeout(flags);
+
+  const data = await apiPost(
+    platformUrl,
+    bearerToken,
+    localSecret,
+    organizationId,
+    '/api/protocol/record-work',
+    body,
+    timeoutMs
+  );
+  console.log(JSON.stringify(data, null, 2));
+
+  const ticketId = data.ticket?.ticket_id ?? data.ticket?.id ?? data.ticket?.ticketId;
+  if (ticketId) {
+    process.stderr.write(`\nTICKET_ID=${ticketId}\n`);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // search-tickets (find tickets by query/status/project/created_by/dates)
 // ---------------------------------------------------------------------------
@@ -1761,8 +1903,10 @@ Subcommands:
   connect                   Start a lightweight session without full context
   load-context              Read ticket context without creating a session
   search-tickets            Find tickets by keyword, status, project, creator, or update date
+  discuss-objective          Mark a draft objective as submitted (ready for review/execution)
   create                    Create a draft ticket without attaching (follow-up or standalone)
   prompt                    Create a ticket and attach to it immediately
+  record-work               Record completed-from-chat work as a ticket in review + feed post (no attach)
   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
@@ -1998,6 +2142,16 @@ prompt:
   Returns:
     New ticket/session JSON plus SESSION_KEY and TICKET_ID on stderr when available
 
+discuss-objective:
+  Purpose:
+    Mark the latest draft objective on a ticket as "submitted", indicating the objective
+    has been discussed and is ready for review or execution. Does NOT start execution —
+    use \`attach\` to begin execution.
+  Required:
+    --ticket-id <ticket_id>
+  Optional:
+    --objective-id <id>       Target a specific draft objective by UUID
+
 create:
   Purpose:
     Create a draft ticket without attaching to it.
@@ -2024,6 +2178,45 @@ create:
   Notes:
     Standalone create auto-discovers the project from the current working directory unless --personal is set.
     Follow-up create requires both --session-key and --ticket-id.
+    Use create for future work. If the work is already complete and only needs to be recorded,
+    use \`record-work\` instead.
+
+record-work:
+  Purpose:
+    Record work the agent already completed in a chat as a ticket in \`review\` status
+    with a completed objective, then trigger the feed-post generator. No session is
+    left open — use this INSTEAD OF \`create\` + \`attach\` + \`deliver\` for "log what we
+    just did" flows. Do NOT use this for in-progress work; use \`prompt\` for that.
+  Required:
+    --objective <text> or --objective-file <path|->   What was asked / what was done
+    --summary   <text> or --summary-file   <path|->   Narrative for feed post + reviewer
+    or: --payload-json <json>
+    or: --payload-file <path|-> containing { objective, summary, artifacts, changeRationales }
+  Optional:
+    --title <text>            Auto-derived from objective if omitted
+    --priority <level>        low | medium | high | urgent
+    --project-id <id>         Skip cwd resolution and use this project explicitly
+    --working-directory <path> Override cwd for project resolution
+    --personal                Create a private ticket when no project should be associated
+    --artifacts-json <json>
+    --artifacts-file <path|->
+    --change-rationales-json <json>
+    --change-rationales-file <path|->
+    --skip-file-change-check  Bypass local git vs changeRationales validation
+    --acceptance-criteria <text>
+    --available-tools <text>
+    --delegate <model>
+    --agent <identifier>
+    --model <identifier>
+  Notes:
+    Project resolution mirrors \`prompt\`: if --project-id is not set and --personal is not used,
+    the CLI sends cwd as workingDirectory and the API matches it against your configured
+    project_user.local_working_directory rows. If no match, the API returns 400 — re-run with
+    --project-id <id> or --personal.
+    Use this for completed-from-chat work. If you still need to execute the work, use \`create\`
+    for a draft ticket or \`prompt\` to create and start execution immediately.
+    In a git workspace, record-work validates that changed files are represented by
+    changeRationales unless --skip-file-change-check is set.
 
 attachment-list:
   Required:
@@ -2089,6 +2282,8 @@ Examples:
   ovld protocol connect --ticket-id 1:899
   ovld protocol load-context --ticket-id 1:899
   ovld protocol search-tickets --query "auth refactor" --status next-up,execute --limit 10
+  ovld protocol discuss-objective --ticket-id 1:899
+  ovld protocol discuss-objective --ticket-id 1:899 --objective-id <objective-uuid>
   ovld protocol create --agent codex --objective "Capture follow-up work from this repo"
   ovld protocol create --agent codex --session-key <key> --ticket-id <ticket_id> --objective "Capture follow-up work"
   ovld protocol prompt --agent codex --objective "Implement user auth" --priority high
@@ -2110,6 +2305,10 @@ Examples:
   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
+  ovld protocol record-work --objective "User asked for X; I did Y" --summary "What I did and why" --change-rationales-json '[...]'
+  ovld protocol record-work --payload-file - <<'EOF'
+    {"objective":"...","summary":"...","artifacts":[...],"changeRationales":[...]}
+EOF
 `);
     return;
   }
@@ -2138,6 +2337,10 @@ Examples:
     await protocolSearchTickets(args);
     return;
   }
+  if (subcommand === 'discuss-objective') {
+    await protocolDiscussObjective(args);
+    return;
+  }
   if (subcommand === 'create' || subcommand === 'create-ticket') {
     await protocolCreateTicket(args);
     return;
@@ -2146,6 +2349,10 @@ Examples:
     await protocolPrompt(args);
     return;
   }
+  if (subcommand === 'record-work') {
+    await protocolRecordWork(args);
+    return;
+  }
   if (subcommand === 'attachment-list') {
     await protocolAttachmentList(args);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord-cli",
-  "version": "0.2605131058.0",
+  "version": "0.2605150751.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.0",
+  "version": "0.2.1",
   "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/scripts/user-prompt-submit-hook.sh

@@ -9,6 +9,23 @@ 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:-}"
+HOOK_NAME="claude"
+LOG_DIR="${HOME:-}/.ovld/logs"
+LOG_FILE="${LOG_DIR}/user-prompt-submit-hook.log"
+
+log_hook() {
+  mkdir -p "$LOG_DIR" 2>/dev/null || return 0
+  printf '%s [%s] %s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" "$HOOK_NAME" "$1" >>"$LOG_FILE" 2>/dev/null || true
+}
+
+PROMPT_LEN=$(printf '%s' "$BODY" | python3 -c "import json,sys; print(len((json.load(sys.stdin).get('prompt') or '').strip()))" 2>/dev/null || echo "0")
+SESSION_ID=$(printf '%s' "$BODY" | python3 -c "import json,sys; print(json.load(sys.stdin).get('session_id') or 'unknown')" 2>/dev/null || echo "unknown")
+log_hook "received submit session_id=$SESSION_ID prompt_len=$PROMPT_LEN ticket_present=$([ -n "${TICKET_ID:-}" ] && echo yes || echo no)"
+
+if [ -z "$OVERLORD_BASE_URL" ] || [ -z "$OVERLORD_TOKEN" ] || [ -z "${TICKET_ID:-}" ]; then
+  log_hook "missing required env base_url=$([ -n "$OVERLORD_BASE_URL" ] && echo yes || echo no) token=$([ -n "$OVERLORD_TOKEN" ] && echo yes || echo no) ticket=$([ -n "${TICKET_ID:-}" ] && echo yes || echo no)"
+  exit 0
+fi
 
 if [ -n "$OVERLORD_BASE_URL" ] && [ -n "$OVERLORD_TOKEN" ] && [ -n "$TICKET_ID" ]; then
   PAYLOAD=$(
@@ -48,16 +65,31 @@ tid = os.environ.get('TICKET_ID', '')
 print(json.dumps({'hookType': 'UserPromptSubmit', 'ticketId': tid, 'prompt': text, 'turnIndex': turn_index}))
 " 2>/dev/null
   )
-  if [ -n "$PAYLOAD" ]; then
-    curl -sf -m 5 \
+  if [ -z "$PAYLOAD" ]; then
+    log_hook "failed to build hook-event payload from submit body"
+    exit 0
+  fi
+
+  PAYLOAD_TURN=$(printf '%s' "$PAYLOAD" | python3 -c "import json,sys; print(json.load(sys.stdin).get('turnIndex', 'unknown'))" 2>/dev/null || echo "unknown")
+  log_hook "built payload turn=$PAYLOAD_TURN posting hook-event"
+  (
+    RESPONSE_FILE=$(mktemp "${TMPDIR:-/tmp}/overlord-hook-event.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" \
-      >/dev/null 2>&1 &
+      -d "$PAYLOAD")
+    CURL_EXIT=$?
+    RESPONSE_PREVIEW=$(python3 -c "from pathlib import Path; import sys; p=Path(sys.argv[1]); text=p.read_text(encoding='utf-8', errors='replace') if p.exists() else ''; text=' '.join(text.split()); print(text[:200])" "$RESPONSE_FILE" 2>/dev/null || echo '')
+    rm -f "$RESPONSE_FILE"
+    if [ "$CURL_EXIT" -eq 0 ]; then
+      log_hook "hook-event POST finished exit=0 http_status=$HTTP_CODE response_preview=$RESPONSE_PREVIEW"
+    else
+      log_hook "hook-event POST failed exit=$CURL_EXIT http_status=${HTTP_CODE:-none} response_preview=$RESPONSE_PREVIEW"
+    fi
+  ) >/dev/null 2>&1 &
     disown
-  fi
 fi
 
 exit 0

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

@@ -84,7 +84,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 tickets. Only use `/overlord:prompt` or `ovld protocol prompt --agent claude-code --objective "..."` when the user explicitly asks to create and execute 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>`.
@@ -93,6 +93,46 @@ Use this mode when the conversation starts normally and the user asks Claude to
 7. If you need other lifecycle commands or flags, run `ovld protocol help` and use the real subcommand list instead of guessing.
 8. Once you attach to a ticket, switch back to Mode 1 and follow the full ticket lifecycle.
 
+## Recording Completed Work From Chat
+
+Use this when the user has had a working conversation with the agent (no Overlord ticket attached) and now wants to record the outcome as a ticket — both for review and to publish a feed post about it. This is **distinct from `create` and from `deliver`**:
+
+- `create` makes a draft ticket for *future* work; nothing happens yet.
+- `prompt` creates a ticket and starts an execution session.
+- `deliver` concludes an *attached* session; the ticket already exists.
+- `record-work` creates the ticket *and* completes the objective *and* triggers the feed-post generator in a single call, with no session left open.
+
+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.
+
+The hosted MCP tool name is `record_work` (snake_case). It accepts the same fields as the CLI but in camelCase JSON. Use `record_work` over the `create_ticket` + `attach` + `deliver` sequence whenever the work is already done.
+
 ## Change Rationales
 
 Always include `changeRationales` when delivering. Optionally include them on updates during long-running work.
@@ -160,10 +200,20 @@ 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.
 
+## 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.**
+
+- Save to a meaningful path in the repository (e.g., `ai/feature-plans/my-feature.md` for feature plans, `docs/decisions/my-decision.md` for architecture decision records).
+- Commit the file as part of the ticket's work so it appears in `changeRationales`.
+- In the delivery, include a `note` or `decision` artifact with a concise summary and the repository file path — not the full document content.
+
+This keeps the ticket feed readable while preserving the full document in version control where it can be reviewed, diffed, and referenced later.
+
 ## Defaults And Notes
 
 - API requires `agentIdentifier` and `connectionMethod` on attach/connect/prompt. The CLI defaults them to `claude-code`/`cli`; the MCP tool defaults to `mcp`. Override with `--agent` / `--method` when calling from a different runtime.
-- 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`, …). 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`).
+- 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.
@@ -182,4 +232,4 @@ The `attach` and `load-context` responses already include `attachments` and `obj
 - 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.9 -->
+<!-- version: 0.4.10 -->

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

@@ -68,7 +68,7 @@ ovld protocol deliver --session-key <sessionKey> \
 1. If the user wants to create tickets (and does not ask to start execution), use `/create` or run `ovld protocol create --agent cursor --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 tickets. Only use `/prompt` or `ovld protocol prompt --agent cursor --objective "..."` when the user explicitly asks to create and execute immediately.
+2. Default to `create` for new draft tickets. Only use `/prompt` or `ovld protocol prompt --agent cursor --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.
 3. If the user already has a ticket ID and only wants to inspect it, use `/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 `/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 `/attach` or run `ovld protocol attach --ticket-id <ticket_id>`.
@@ -76,6 +76,10 @@ ovld protocol deliver --session-key <sessionKey> \
 7. If you need other lifecycle commands or flags, run `ovld protocol help` and use the real subcommand list instead of guessing.
 8. Once you attach to a ticket, switch back to Mode 1 and follow the full ticket lifecycle.
 
+## Recording Completed Work From Chat
+
+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.
+
 ## Change Rationales
 
 Always include `changeRationales` when delivering. Optionally include them on updates during long-running work.
@@ -134,10 +138,20 @@ Objective attachment uploads also expose two-step variants — `attachment-prepa
 
 "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.**
+
+- Save to a meaningful path in the repository (e.g., `ai/feature-plans/my-feature.md` for feature plans, `docs/decisions/my-decision.md` for architecture decision records).
+- Commit the file as part of the ticket's work so it appears in `changeRationales`.
+- In the delivery, include a `note` or `decision` artifact with a concise summary and the repository file path — not the full document content.
+
+This keeps the ticket feed readable while preserving the full document in version control where it can be reviewed, diffed, and referenced later.
+
 ## Defaults And Notes
 
 - The Overlord API requires `agentIdentifier` and `connectionMethod` on attach/connect/prompt, but the CLI defaults them to `cursor`/`cli` (override with `--agent` / `--method`). The MCP tools default to `mcp`.
-- The Cursor local MCP stub exposes `attach`, `update`, and `deliver` only (same names as the hosted Overlord MCP core set).
+- The Cursor plugin ships the shared local `overlord-mcp.mjs` shim. Treat its tool list as the source of truth; it includes `record_work` alongside the core lifecycle tools.
 - `permission-request` is invoked by the installed permission hook; agents normally do not call it directly.
 - The `record_change_rationales` MCP tool and `ovld protocol record-change-rationales` CLI both write to the same `file_changes` table; pick whichever fits your runtime.
 
@@ -152,4 +166,4 @@ Objective attachment uploads also expose two-step variants — `attachment-prepa
 - 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.
 - Delivery is the concluding step. After delivering, stop unless the user follows up or the ticket is reopened.
 
-<!-- version: 0.4.9 -->
+<!-- version: 0.4.10 -->

package/plugins/overlord/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Chat-driven access to Overlord ticket protocol workflows with hook-driven activity capture.",
   "author": {
     "name": "Cooperativ",

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

@@ -393,6 +393,58 @@ const tools = [
       }),
     subcommand: 'deliver'
   },
+  {
+    name: 'record_work',
+    description:
+      'Record completed-from-chat work as a ticket in `review` status with a completed objective, then trigger feed-post generation. Use this INSTEAD OF create_ticket + attach + deliver for "log what we just did" flows. Project resolution mirrors `prompt`: if project_id is omitted, working_directory is matched against project_user.local_working_directory. When neither resolves, pass personal: true. Do not use for in-progress work.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        objective: {
+          type: 'string',
+          description: 'What was asked / what was done. Stored as a completed objective.'
+        },
+        summary: {
+          type: 'string',
+          description: 'Narrative for feed post + reviewer.'
+        },
+        title: { type: 'string' },
+        priority: { type: 'string', enum: ['low', 'medium', 'high', 'urgent'] },
+        project_id: { type: 'string' },
+        working_directory: { type: 'string' },
+        personal: { type: 'boolean' },
+        acceptance_criteria: { type: 'string' },
+        available_tools: { type: 'string' },
+        delegate: { type: 'string' },
+        artifacts: { type: 'array' },
+        change_rationales: { type: 'array' },
+        skip_file_change_check: { type: 'boolean' }
+      },
+      required: ['objective', 'summary']
+    },
+    toCliFlags: args => ({
+      'payload-file': '-',
+      title: args.title,
+      priority: args.priority,
+      'project-id': args.project_id,
+      'working-directory': args.working_directory,
+      personal: args.personal,
+      'acceptance-criteria': args.acceptance_criteria,
+      'available-tools': args.available_tools,
+      delegate: args.delegate,
+      'skip-file-change-check': args.skip_file_change_check
+    }),
+    toCliStdin: args =>
+      JSON.stringify({
+        objective: args.objective,
+        summary: args.summary,
+        ...(Array.isArray(args.artifacts) ? { artifacts: args.artifacts } : {}),
+        ...(Array.isArray(args.change_rationales)
+          ? { changeRationales: args.change_rationales }
+          : {})
+      }),
+    subcommand: 'record-work'
+  },
   {
     name: 'list_attachments',
     description:

package/plugins/overlord/scripts/user-prompt-submit-hook.sh

@@ -5,24 +5,55 @@ BODY=$(cat -)
 OVERLORD_BASE_URL="${OVERLORD_URL:-}"
 OVERLORD_TOKEN="${OVERLORD_ACCESS_TOKEN:-}"
 OVERLORD_LOCAL_SECRET="${OVERLORD_LOCAL_SECRET:-}"
+HOOK_NAME="codex"
+LOG_DIR="${HOME:-}/.ovld/logs"
+LOG_FILE="${LOG_DIR}/user-prompt-submit-hook.log"
+
+log_hook() {
+  mkdir -p "$LOG_DIR" 2>/dev/null || return 0
+  printf '%s [%s] %s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" "$HOOK_NAME" "$1" >>"$LOG_FILE" 2>/dev/null || true
+}
 
 TURN=$(printf '%s' "$BODY" | python3 -c "import json,sys; print(json.load(sys.stdin).get('turn_number', 0))" 2>/dev/null || echo "0")
+PROMPT_LEN=$(printf '%s' "$BODY" | python3 -c "import json,sys; print(len((json.load(sys.stdin).get('prompt') or '').strip()))" 2>/dev/null || echo "0")
+log_hook "received submit turn=$TURN prompt_len=$PROMPT_LEN ticket_present=$([ -n "${TICKET_ID:-}" ] && echo yes || echo no)"
 if [ "$TURN" = "0" ]; then
+  log_hook "skipping initial submit turn=0"
+  exit 0
+fi
+
+if [ -z "$OVERLORD_BASE_URL" ] || [ -z "$OVERLORD_TOKEN" ] || [ -z "${TICKET_ID:-}" ]; then
+  log_hook "missing required env base_url=$([ -n "$OVERLORD_BASE_URL" ] && echo yes || echo no) token=$([ -n "$OVERLORD_TOKEN" ] && echo yes || echo no) ticket=$([ -n "${TICKET_ID:-}" ] && echo yes || echo no)"
   exit 0
 fi
 
 if [ -n "$OVERLORD_BASE_URL" ] && [ -n "$OVERLORD_TOKEN" ] && [ -n "$TICKET_ID" ]; then
   PAYLOAD=$(printf '%s' "$BODY" | python3 -c "import json,sys; body=json.load(sys.stdin); print(json.dumps({'hookType': 'UserPromptSubmit', 'ticketId': __import__('os').environ['TICKET_ID'], 'prompt': body.get('prompt', ''), 'turnIndex': body.get('turn_number', 0)}))" 2>/dev/null || echo '')
-  if [ -n "$PAYLOAD" ]; then
-    curl -sf -m 5 \
+  if [ -z "$PAYLOAD" ]; then
+    log_hook "failed to build hook-event payload from submit body"
+    exit 0
+  fi
+
+  PAYLOAD_TURN=$(printf '%s' "$PAYLOAD" | python3 -c "import json,sys; print(json.load(sys.stdin).get('turnIndex', 'unknown'))" 2>/dev/null || echo "unknown")
+  log_hook "built payload turn=$PAYLOAD_TURN posting hook-event"
+  (
+    RESPONSE_FILE=$(mktemp "${TMPDIR:-/tmp}/overlord-hook-event.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" \
-      >/dev/null 2>&1 &
+      -d "$PAYLOAD")
+    CURL_EXIT=$?
+    RESPONSE_PREVIEW=$(python3 -c "from pathlib import Path; import sys; p=Path(sys.argv[1]); text=p.read_text(encoding='utf-8', errors='replace') if p.exists() else ''; text=' '.join(text.split()); print(text[:200])" "$RESPONSE_FILE" 2>/dev/null || echo '')
+    rm -f "$RESPONSE_FILE"
+    if [ "$CURL_EXIT" -eq 0 ]; then
+      log_hook "hook-event POST finished exit=0 http_status=$HTTP_CODE response_preview=$RESPONSE_PREVIEW"
+    else
+      log_hook "hook-event POST failed exit=$CURL_EXIT http_status=${HTTP_CODE:-none} response_preview=$RESPONSE_PREVIEW"
+    fi
+  ) >/dev/null 2>&1 &
     disown
-  fi
 fi
 
 exit 0

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

@@ -72,7 +72,7 @@ ovld protocol deliver --session-key <sessionKey> \
 1. If the user wants to create tickets (and does not ask to start execution), run `ovld protocol create --agent codex --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 tickets. Only use `ovld protocol prompt --agent codex --objective "..."` when the user explicitly asks to create and execute immediately.
+2. Default to `create` for new draft tickets. Only use `ovld protocol prompt --agent codex --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 wants to inspect an existing ticket without starting work, use `ovld protocol load-context --ticket-id <ticket_id>`.
 4. If the user wants to work an existing ticket, attach with `ovld protocol attach --ticket-id <ticket_id>` and then switch to Mode 1. Use `ovld protocol connect --ticket-id <ticket_id>` instead when you only need a session key without the full ticket payload.
@@ -105,6 +105,23 @@ Pass `--execution-target agent` or `--execution-target human` (default: `human`)
 
 When in doubt, ask yourself: _can this be done entirely inside a terminal or browser by an AI without human intervention?_ If yes → `agent`. If it requires a human to log in, decide, or act in the real world → `human`.
 
+## Recording Completed Work From Chat
+
+Use `ovld protocol record-work` (hosted MCP: `record_work`) when the user has done work directly in a chat (no attached ticket) and now wants to record it as a ticket *and* publish a feed post about it. Distinct from `create` (drafts future work), `prompt` (creates and starts execution), and `deliver` (concludes an attached session). `record-work` creates the ticket in `review` with a completed objective and triggers the feed-post generator atomically; no session is left open.
+
+```bash
+ovld protocol record-work --payload-file - <<'EOF'
+{
+  "objective": "User asked me to X; I did Y...",
+  "summary": "Narrative for feed post + reviewer.",
+  "artifacts": [...],
+  "changeRationales": [...]
+}
+EOF
+```
+
+Project resolution mirrors `prompt`/`create`: cwd is matched against `project_user.local_working_directory`. If no match, ask the user for `--project-id`; if the work is not tied to any project, pass `--personal`. In a git workspace, `record-work` validates uncommitted changes are represented by `changeRationales` unless `--skip-file-change-check` is set. Do NOT use for in-progress work.
+
 ## Change Rationales
 
 Always include `changeRationales` when delivering. Optionally include them on updates during long-running work.
@@ -139,10 +156,20 @@ 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.
 
+## 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.**
+
+- Save to a meaningful path in the repository (e.g., `ai/feature-plans/my-feature.md` for feature plans, `docs/decisions/my-decision.md` for architecture decision records).
+- Commit the file as part of the ticket's work so it appears in `changeRationales`.
+- In the delivery, include a `note` or `decision` artifact with a concise summary and the repository file path — not the full document content.
+
+This keeps the ticket feed readable while preserving the full document in version control where it can be reviewed, diffed, and referenced later.
+
 ## Defaults And Notes
 
 - API requires `agentIdentifier` and `connectionMethod` on attach/connect/prompt. The CLI defaults them to `codex`/`cli`; the hosted MCP defaults to `mcp`. Override with `--agent` / `--method` when calling from a different runtime.
-- Hosted MCP and the local `overlord-mcp.mjs` shim use the same **tool names** (\`attach\`, \`update\`, \`deliver\`, …). The shim uses **snake_case** JSON keys (\`ticket_id\`, \`session_key\`) that map to CLI flags; hosted MCP uses **camelCase** (\`ticketId\`, \`sessionKey\`) matching REST bodies.
+- Hosted MCP and the local `overlord-mcp.mjs` shim use the same **tool names** (\`attach\`, \`update\`, \`deliver\`, \`record_work\`, …). The shim uses **snake_case** JSON keys (\`ticket_id\`, \`session_key\`) that map to CLI flags; hosted MCP uses **camelCase** (\`ticketId\`, \`sessionKey\`) matching REST bodies.
 - `permission-request` is invoked by the local Codex plugin's permission rules; agents do not normally call it directly.
 - `record_change_rationales` (MCP) and `ovld protocol record-change-rationales` (CLI) both write to the `file_changes` table; the dedicated route is `POST /api/protocol/record-change-rationales`.
 - Objective attachment MCP tools use `<verb>_<noun>` names — `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.
@@ -158,4 +185,4 @@ The `attach` and `load-context` responses already include `attachments` and `obj
 - 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.9 -->
+<!-- version: 0.4.10 -->