Ticket artifacts are being saved to project .ai/ instead of ~/.ai

[williamthorsen]

Problem

The MCP init_run tool (packages/mcp/src/tools/init-run.ts:67) hardcodes the artifact base directory as join(projectRoot, '.ai', ...), which places run artifacts at <projectDir>/.ai/ instead of the documented default ~/.ai/.

The artifact conventions (artifact-conventions.md) specify a preference cascade for resolving the base directory:

1. artifacts.base_dir from <projectRoot>/.agents/preferences.yaml
2. artifacts.base_dir from ~/.agents/preferences.yaml
3. Default: ~/.ai

All non-MCP skills (save-artifact, save-plan, review-change) and the orchestrate skill's fallback path correctly follow this cascade. The MCP init_run tool is the only code path that ignores it.

Proposed solution

Implement the preference cascade directly in the MCP server so that init_run resolves the artifact base directory from preferences files automatically. Add an optional baseDir parameter as an explicit override for testing and advanced callers.

Key changes:

• Add js-yaml dependency to the MCP package
• Create resolve-base-dir.ts utility implementing the preference cascade
• Update init_run to call the resolver instead of hardcoding the path
• Add baseDir to the MCP tool schema
• Update tests, orchestrate skill docs, and artifact conventions

Acceptance criteria

• init_run defaults to ~/.ai when no preferences are set and no baseDir is passed
• init_run reads artifacts.base_dir from project-level .agents/preferences.yaml
• init_run falls back to global ~/.agents/preferences.yaml when project-level is absent
• Relative base_dir values are resolved from projectRoot
• Explicit baseDir parameter overrides the preference cascade
• All existing MCP tests pass (updated with explicit baseDir for self-containment)
• New resolve-base-dir tests cover the full cascade
• pnpm run check passes at root

[williamthorsen]

Implementation plan

Context

Issue #163: The MCP init_run tool hardcodes join(projectRoot, '.ai', ...) to construct the run directory path. This places artifacts at <projectDir>/.ai/ instead of the documented default ~/.ai/. The artifact conventions document specifies a preference cascade that defaults to ~/.ai, and all non-MCP skills (save-artifact, save-plan, review-change) correctly follow this cascade. The MCP tool is the outlier.

Approach

Implement the preference cascade directly in the MCP server so that init_run resolves the artifact base directory automatically from preferences files, falling back to ~/.ai. Also accept an optional baseDir parameter as an explicit override (useful for testing and advanced callers).

Resolution cascade (matching artifact-conventions.md):

1. Explicit baseDir parameter (if provided)
2. artifacts.base_dir from <projectRoot>/.agents/preferences.yaml
3. artifacts.base_dir from ~/.agents/preferences.yaml
4. Default: ~/.ai
5. If the resolved value is relative, resolve from projectRoot. If absolute, use as-is.

Step 1: Add js-yaml dependency to MCP package

File: packages/mcp/package.json

• Add "js-yaml": "4.1.1" to dependencies (matches existing version in root and agents packages)
• Add "@types/js-yaml": "4.0.9" to devDependencies (following agents package pattern)
• Run pnpm install

Step 2: Create preference resolution utility

File: packages/mcp/src/tools/resolve-base-dir.ts (new)

Create a utility function:

import { readFile } from 'node:fs/promises';
import { homedir } from 'node:os';
import { isAbsolute, join, resolve } from 'node:path';
import yaml from 'js-yaml';

const DEFAULT_BASE_DIR = join(homedir(), '.ai');

/**
 * Resolve the artifact base directory using the preference cascade:
 * 1. Explicit baseDir (if provided)
 * 2. artifacts.base_dir from <projectRoot>/.agents/preferences.yaml
 * 3. artifacts.base_dir from ~/.agents/preferences.yaml
 * 4. Default: ~/.ai
 * Relative paths are resolved from projectRoot.
 */
export async function resolveBaseDir(projectRoot: string, baseDir?: string): Promise<string> {
  if (baseDir !== undefined) {
    return isAbsolute(baseDir) ? baseDir : resolve(projectRoot, baseDir);
  }

  const candidates = [
    join(projectRoot, '.agents', 'preferences.yaml'),
    join(homedir(), '.agents', 'preferences.yaml'),
  ];

  for (const filePath of candidates) {
    const value = await readBaseDirFromYaml(filePath);
    if (value !== undefined) {
      return isAbsolute(value) ? value : resolve(projectRoot, value);
    }
  }

  return DEFAULT_BASE_DIR;
}

async function readBaseDirFromYaml(filePath: string): Promise<string | undefined> {
  try {
    const content = await readFile(filePath, 'utf8');
    const parsed: unknown = yaml.load(content);
    if (parsed !== null && typeof parsed === 'object' && 'artifacts' in parsed) {
      const artifacts: unknown = (parsed as Record<string, unknown>).artifacts;
      if (artifacts !== null && typeof artifacts === 'object' && 'base_dir' in artifacts) {
        const baseDir: unknown = (artifacts as Record<string, unknown>).base_dir;
        if (typeof baseDir === 'string' && baseDir !== '') {
          return baseDir;
        }
      }
    }
  } catch {
    // File doesn't exist or isn't valid YAML — skip silently
  }
  return undefined;
}

Step 3: Update init_run to use the resolver

File: packages/mcp/src/tools/init-run.ts

• Add baseDir?: string | undefined to InitRunInput

• Import resolveBaseDir from ./resolve-base-dir.js

• Replace the hardcoded path construction:

  // Before (line 67):
  const runDir = join(projectRoot, '.ai', 'projects', projectSlug, 'tickets', resolvedTicketId, runId);
  
  // After:
  const artifactBase = await resolveBaseDir(projectRoot, baseDir);
  const runDir = join(artifactBase, 'projects', projectSlug, 'tickets', resolvedTicketId, runId);

• Update JSDoc to document the new behavior

Step 4: Update MCP server schema

File: packages/mcp/src/server.ts

• Add baseDir: z.string().optional() to the init_run tool's inputSchema

Step 5: Update tests

File: packages/mcp/src/tools/__tests__/resolve-base-dir.test.ts (new)

Test the preference cascade:

• Returns ~/.ai when no preferences files exist
• Reads artifacts.base_dir from project-level preferences
• Reads artifacts.base_dir from global preferences
• Project-level preference takes priority over global
• Resolves relative paths from project root
• Uses absolute paths as-is
• Explicit baseDir parameter overrides preferences
• Handles malformed YAML gracefully (skips silently)
• Handles missing artifacts key (skips silently)

File: packages/mcp/src/tools/__tests__/init-run.test.ts

• Update existing tests to pass baseDir explicitly (pointing to temp dir) so they remain self-contained and don't write to ~/.ai/
• Add test: when baseDir is not provided and no preferences exist, runDir is under ~/.ai/

File: packages/mcp/src/tools/__tests__/lifecycle.test.ts

• Pass baseDir explicitly to the initRun call so the test remains self-contained

Step 6: Update orchestrate skill documentation

File: packages/agents/content/skills/orchestrate/SKILL.md

• In the "Run initialization" section, note that init_run resolves the base directory from preferences automatically (no need for the skill to pass baseDir)
• The fallback path (lines 187-196, for when MCP is unavailable) already resolves {base-dir} correctly; no changes needed there

Step 7: Update artifact conventions v3 layout example

File: packages/agents/content/skills/_data/artifact-conventions.md

• Line 489: Change {projectRoot}/.ai/projects/{projectSlug}/... to {base_dir}/projects/{projectSlug}/... for consistency with the rest of the document

Verification

1. pnpm run ws test in packages/mcp/ — all tests pass (including new resolve-base-dir tests)
2. pnpm run ws typecheck in packages/mcp/ — no type errors
3. pnpm run ws lint in packages/mcp/ — no lint errors
4. pnpm run check at root — full project check passes

[williamthorsen]

Insight from run 20260304-073605Z: MCP init_run was the sole code path bypassing the documented preference cascade — all non-MCP skills (save-artifact, save-plan, review-change) and the orchestrate skill's fallback path already resolved {base-dir} correctly. This fix brings MCP into alignment with the rest of the system.