overlord-cli 0.2605241101.0 → 0.2605241431.0

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

@@ -1839,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`
       );
     }
   }
@@ -3097,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.

package/package.json

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

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

@@ -85,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:
 
@@ -198,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
 
@@ -276,4 +276,4 @@ This keeps the ticket feed readable while preserving the full document in versio
 - Do not add or commit changes unless the user explicitly asks you to commit.
 - Delivery is the concluding step. After delivering, stop implementation work unless the user explicitly asks for follow-up execution; once follow-up execution is complete, deliver again.
 
-<!-- version: 0.1.4 -->
+<!-- version: 0.1.5 -->

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

@@ -56,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`.
 
@@ -140,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/reference/cli.md

@@ -56,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`.
 
@@ -140,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/skills/overlord-ticket/reference/cli.md

@@ -56,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`.
 
@@ -140,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.