@foundation0/api 1.1.1 → 1.1.3

package/projects.ts

@@ -94,6 +94,9 @@ type ProjectSyncTaskOptions = {
   maxBodyLength?: number
   requestTimeoutMs?: number
   throttleMs?: number
+  retryMax?: number
+  retryBaseDelayMs?: number
+  retryMaxDelayMs?: number
   skipDependencies?: boolean
   verbose?: boolean
 }
@@ -119,6 +122,14 @@ type ProjectWriteGitTaskOptions = {
   taskSignature?: string
 }
 
+type ProjectCreateGitIssueOptions = {
+  owner?: string
+  repo?: string
+  title: string
+  body?: string
+  labels?: string[]
+}
+
 export type ProjectGitTaskRecord = {
   number: number
   title: string
@@ -160,7 +171,90 @@ export type ProjectWriteGitTaskResult = {
   issue: ProjectGitTaskRecord
 }
 
-const CLI_NAME = 'example'
+export type ProjectGitIssueRecord = {
+  number: number
+  title: string
+  body: string
+  state: string
+  labels: string[]
+}
+
+export type ProjectCreateGitIssueResult = {
+  projectName: string
+  owner: string
+  repo: string
+  issueNumber: number
+  issue: ProjectGitIssueRecord
+}
+
+type ProjectSearchTargetSection = 'docs' | 'spec'
+
+type ProjectSearchOptions = {
+  projectName?: string
+  owner?: string
+  repo?: string
+  ref?: string
+  branch?: string
+  sha?: string
+  source?: 'local' | 'gitea' | 'auto'
+  remote?: boolean
+  processRoot?: string
+  cacheDir?: string
+  refresh?: boolean
+  args?: unknown[]
+}
+
+type RgLikeSearchQuery = {
+  patterns: string[]
+  paths: string[]
+  lineNumber: boolean
+  withFilename: boolean
+  noFilename: boolean
+  ignoreCase: boolean
+  caseSensitive: boolean
+  smartCase: boolean
+  fixedStrings: boolean
+  wordRegexp: boolean
+  maxCount: number | null
+  countOnly: boolean
+  filesWithMatches: boolean
+  filesWithoutMatch: boolean
+  onlyMatching: boolean
+  includeHidden: boolean
+  globs: string[]
+}
+
+type RgLikeCompiledPattern = {
+  test: RegExp
+  global: RegExp
+}
+
+type RgLikeSearchExecutionResult = {
+  filesSearched: number
+  filesMatched: number
+  matchedLines: number
+  matchedSegments: number
+  outputLines: string[]
+}
+
+export type ProjectSearchResult = {
+  projectName: string
+  owner: string | null
+  repo: string | null
+  section: ProjectSearchTargetSection
+  ref: string | null
+  source: 'gitea' | 'local'
+  cacheDir: string
+  cacheRefreshed: boolean
+  args: string[]
+  filesSearched: number
+  filesMatched: number
+  matchedLines: number
+  matchedSegments: number
+  output: string
+}
+
+const CLI_NAME = 'f0'
 const VERSION_RE = 'v?\\d+(?:\\.\\d+){2,}'
 const VERSION_RE_CORE = `(?:${VERSION_RE})`
 const ACTIVE_EXT_PRIORITY = ['.md', '.json', '.yaml', '.yml', '.ts', '.js', '.txt']
@@ -185,6 +279,8 @@ const DEFAULT_TRACKS_CANDIDATES = [
   path.join('spec', '07_roadmap', 'tracks.md'),
 ] as const
 const PROJECTS_DIRECTORY = 'projects'
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
 
 type ProjectDocsCandidateKind = 'active' | 'plain' | 'versioned'
 
@@ -199,10 +295,10 @@ function resolveProjectsRoot(processRoot: string): string {
 }
 
 export function usage(): string {
-  return `Usage:\n  ${CLI_NAME} projects <project-name> --generate-spec\n  ${CLI_NAME} projects <project-name> <file-path> --set-active\n  ${CLI_NAME} projects --list\n  ${CLI_NAME} projects <project-name> sync-tasks\n  ${CLI_NAME} projects <project-name> clear-issues\n\n` +
-    `Examples:\n  ${CLI_NAME} projects index --generate-spec\n  ${CLI_NAME} projects index /implementation-plan.v0.0.1 --set-active\n  ${CLI_NAME} projects index /implementation-plan --set-active --latest\n  ${CLI_NAME} projects index sync-tasks\n  ${CLI_NAME} projects index sync-tasks --verbose\n  ${CLI_NAME} projects index sync-tasks --request-timeout-ms 60000 --throttle-ms 250\n  ${CLI_NAME} projects index sync-tasks --skip-dependencies\n  ${CLI_NAME} projects index clear-issues --dry-run\n  ${CLI_NAME} projects index clear-issues --force\n  ${CLI_NAME} projects index clear-issues --state all --force\n  ${CLI_NAME} projects --list\n\n` +
+  return `Usage:\n  ${CLI_NAME} projects <project-name> --generate-spec\n  ${CLI_NAME} projects <project-name> <file-path> --set-active\n  ${CLI_NAME} projects <project-name> --sync-tasks (alias: --sync-issues)\n  ${CLI_NAME} projects <project-name> --clear-issues\n  ${CLI_NAME} projects --list\n\n` +
+    `Examples:\n  ${CLI_NAME} projects index --generate-spec\n  ${CLI_NAME} projects index /implementation-plan.v0.0.1 --set-active\n  ${CLI_NAME} projects index /implementation-plan --set-active --latest\n  ${CLI_NAME} projects index sync-tasks\n  ${CLI_NAME} projects index sync-tasks --verbose\n  ${CLI_NAME} projects index sync-tasks --request-timeout-ms 60000 --throttle-ms 250\n  ${CLI_NAME} projects index sync-tasks --retry 5 --retry-base-delay-ms 500\n  ${CLI_NAME} projects index sync-tasks --skip-dependencies\n  ${CLI_NAME} projects index clear-issues --dry-run\n  ${CLI_NAME} projects index clear-issues --force\n  ${CLI_NAME} projects index clear-issues --state all --force\n  ${CLI_NAME} projects --list\n\n` +
     `file-path is relative to the project root (leading slash required).\n` +
-    `Sync-tasks flags: --verbose --max --max-body --request-timeout-ms --throttle-ms --skip-dependencies --owner --repo --label --prefix --tracks.\n` +
+    `Sync-tasks flags: --verbose --max --max-body --request-timeout-ms --throttle-ms --retry --retry-base-delay-ms --retry-max-delay-ms --no-retry --skip-dependencies --owner --repo --label --prefix --tracks.\n` +
     `Use --verbose with clear-issues to print each deletion.\n` +
     `Use --latest to resolve /file-name to the latest version.\n` +
     `The active file created is [file].active.<ext>.\n`
@@ -243,32 +339,1152 @@ export function listProjects(processRoot: string = process.cwd()): string[] {
     .sort((a, b) => a.localeCompare(b))
 }
 
-export function listProjectDocs(projectName: string, processRoot: string = process.cwd()): string[] {
-  const projectRoot = resolveProjectRoot(projectName, processRoot)
-  const candidates = buildProjectDocsCatalog(projectRoot)
-  return Array.from(candidates.keys()).sort((a, b) => a.localeCompare(b))
+export function listProjectDocs(projectName: string, processRoot: string = process.cwd()): string[] {
+  const projectRoot = resolveProjectRoot(projectName, processRoot)
+  const candidates = buildProjectDocsCatalog(projectRoot)
+  return Array.from(candidates.keys()).sort((a, b) => a.localeCompare(b))
+}
+
+export async function readProjectDoc(
+  projectName: string,
+  requestPath: string,
+  processRoot: string = process.cwd()
+): Promise<string> {
+  const projectRoot = resolveProjectRoot(projectName, processRoot)
+  const catalog = buildProjectDocsCatalog(projectRoot)
+  const normalized = normalizeProjectDocRequest(requestPath)
+  const sourcePath = resolveProjectDocPath(catalog, normalized)
+
+  if (!sourcePath) {
+    throw new Error(`Doc file not found: ${requestPath}`)
+  }
+
+  const content = await readTextIfExists(sourcePath)
+  if (content === null) {
+    throw new Error(`Doc file not found: ${requestPath}`)
+  }
+
+  return content
+}
+
+export async function searchDocs(projectName: string, ...rawArgs: unknown[]): Promise<ProjectSearchResult> {
+  return searchProjectSection(projectName, 'docs', rawArgs)
+}
+
+export async function searchSpecs(projectName: string, ...rawArgs: unknown[]): Promise<ProjectSearchResult> {
+  return searchProjectSection(projectName, 'spec', rawArgs)
+}
+
+async function searchProjectSection(
+  projectNameInput: unknown,
+  section: ProjectSearchTargetSection,
+  rawArgs: unknown[]
+): Promise<ProjectSearchResult> {
+  const seedOptions = isRecord(projectNameInput) ? projectNameInput : {}
+  const { rgArgs, options } = parseProjectSearchInvocationWithSeed(rawArgs, seedOptions)
+  const processRoot = parseStringOption(options.processRoot) ?? process.cwd()
+  const positionalProjectName = typeof projectNameInput === 'string' ? projectNameInput.trim() : ''
+  const optionProjectName = parseStringOption(options.projectName) ?? ''
+  const sourcePreference = parseSearchSourceOption(options.source, options.remote)
+
+  if (!positionalProjectName && !optionProjectName) {
+    throw new Error('Missing project name. Pass it as first arg or options.projectName.')
+  }
+
+  let projectName = positionalProjectName || optionProjectName
+  let projectRoot: string | null = null
+
+  if (positionalProjectName && optionProjectName && positionalProjectName !== optionProjectName) {
+    const resolvedPositional = tryResolveProjectRoot(positionalProjectName, processRoot)
+    const resolvedOption = tryResolveProjectRoot(optionProjectName, processRoot)
+
+    if (!resolvedPositional && resolvedOption) {
+      projectName = optionProjectName
+      projectRoot = resolvedOption
+    } else if (resolvedPositional && !resolvedOption) {
+      projectName = positionalProjectName
+      projectRoot = resolvedPositional
+    } else if (!resolvedPositional && !resolvedOption) {
+      throw new Error(
+        `Could not resolve project-name from positional "${positionalProjectName}" or options.projectName "${optionProjectName}".`,
+      )
+    } else {
+      throw new Error(
+        `Conflicting project names: positional "${positionalProjectName}" and options.projectName "${optionProjectName}". Use one.`,
+      )
+    }
+  }
+
+  if (!projectRoot) {
+    projectRoot = resolveProjectRoot(projectName, processRoot)
+  }
+
+  const ownerFromOptions = parseStringOption(options.owner)
+  const repoFromOptions = parseStringOption(options.repo)
+  const resolvedIdentity = (!ownerFromOptions || !repoFromOptions)
+    ? tryResolveGitIdentityFromProject(projectRoot)
+    : null
+  const owner = ownerFromOptions ?? resolvedIdentity?.owner ?? null
+  const repo = repoFromOptions ?? resolvedIdentity?.repo ?? null
+  const ref = parseStringOption(options.ref) ?? parseStringOption(options.branch) ?? parseStringOption(options.sha) ?? null
+
+  const cacheRoot = resolveProjectSearchCacheRoot({
+    processRoot,
+    projectName,
+    owner: owner ?? 'unknown-owner',
+    repo: repo ?? 'unknown-repo',
+    section,
+    ref,
+    cacheDir: parseStringOption(options.cacheDir),
+  })
+
+  const cacheSync = await syncProjectSearchCache({
+    owner,
+    repo,
+    projectRoot,
+    section,
+    ref,
+    cacheRoot,
+    sourcePreference,
+    refresh: parseBooleanOption(options.refresh),
+  })
+
+  const query = parseRgLikeQueryArgs(rgArgs)
+  const searchResult = await executeRgLikeSearch(cacheRoot, query)
+
+  return {
+    projectName,
+    owner,
+    repo,
+    section,
+    ref,
+    source: cacheSync.source,
+    cacheDir: cacheRoot,
+    cacheRefreshed: cacheSync.refreshed,
+    args: rgArgs,
+    filesSearched: searchResult.filesSearched,
+    filesMatched: searchResult.filesMatched,
+    matchedLines: searchResult.matchedLines,
+    matchedSegments: searchResult.matchedSegments,
+    output: searchResult.outputLines.join('\n'),
+  }
+}
+
+function parseProjectSearchInvocation(rawArgs: unknown[]): { rgArgs: string[]; options: ProjectSearchOptions } {
+  return parseProjectSearchInvocationWithSeed(rawArgs, {})
+}
+
+function parseProjectSearchInvocationWithSeed(
+  rawArgs: unknown[],
+  seedOptions: Record<string, unknown>,
+): { rgArgs: string[]; options: ProjectSearchOptions } {
+  const options: Record<string, unknown> = { ...seedOptions }
+  let rgArgs: string[] = []
+
+  if (rawArgs.length > 0) {
+    const maybeOptions = rawArgs[rawArgs.length - 1]
+    if (isRecord(maybeOptions)) {
+      rgArgs = rawArgs.slice(0, -1).map((value) => String(value))
+      for (const [key, value] of Object.entries(maybeOptions)) {
+        options[key] = value
+      }
+    } else {
+      rgArgs = rawArgs.map((value) => String(value))
+    }
+  }
+
+  if (rgArgs.length === 0 && Array.isArray(options.args)) {
+    rgArgs = options.args.map((value) => String(value))
+  }
+
+  return {
+    rgArgs,
+    options: options as ProjectSearchOptions,
+  }
+}
+
+function parseStringOption(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null
+  }
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : null
+}
+
+function parseBooleanOption(value: unknown): boolean {
+  return value === true || value === 1 || value === '1' || value === 'true' || value === 'yes' || value === 'on'
+}
+
+function tryResolveProjectRoot(projectName: string, processRoot: string): string | null {
+  try {
+    return resolveProjectRoot(projectName, processRoot)
+  } catch {
+    return null
+  }
+}
+
+function tryResolveGitIdentityFromProject(projectRoot: string): { owner: string; repo: string } | null {
+  try {
+    return resolveGitIdentityFromProject(projectRoot)
+  } catch {
+    return null
+  }
+}
+
+function resolveProjectSearchCacheRoot(input: {
+  processRoot: string
+  projectName: string
+  owner: string
+  repo: string
+  section: ProjectSearchTargetSection
+  ref: string | null
+  cacheDir: string | null
+}): string {
+  if (input.cacheDir) {
+    return path.resolve(input.cacheDir)
+  }
+
+  const refToken = input.ref ?? 'HEAD'
+  const refHash = crypto.createHash('sha256').update(refToken).digest('hex').slice(0, 12)
+  const ownerToken = input.owner.replace(/[^a-zA-Z0-9_.-]+/g, '_')
+  const repoToken = input.repo.replace(/[^a-zA-Z0-9_.-]+/g, '_')
+  const projectToken = input.projectName.replace(/[^a-zA-Z0-9_.-]+/g, '_')
+
+  return path.join(
+    input.processRoot,
+    '.cache',
+    'project-search',
+    projectToken,
+    ownerToken,
+    repoToken,
+    input.section,
+    refHash,
+  )
+}
+
+async function syncProjectSearchCache(input: {
+  owner: string | null
+  repo: string | null
+  projectRoot: string
+  section: ProjectSearchTargetSection
+  ref: string | null
+  cacheRoot: string
+  sourcePreference: 'local' | 'gitea' | 'auto'
+  refresh: boolean
+}): Promise<{ refreshed: boolean; source: 'gitea' | 'local' }> {
+  const manifestPath = path.join(input.cacheRoot, '.search-cache.json')
+  const localSectionRoot = path.join(input.projectRoot, input.section)
+  const localAvailable = existsDir(localSectionRoot)
+
+  if (!input.refresh && existsFile(manifestPath)) {
+    const existingSource = (await readCacheSource(manifestPath)) ?? 'local'
+
+    // Prefer local if available unless the caller explicitly forces remote.
+    if (existingSource === 'gitea' && input.sourcePreference !== 'gitea' && localAvailable) {
+      // fall through and refresh to local
+    } else if (existingSource === 'local' && input.sourcePreference === 'gitea') {
+      // fall through and refresh to remote
+    } else {
+      return { refreshed: false, source: existingSource }
+    }
+  }
+
+  await fs.rm(input.cacheRoot, { recursive: true, force: true })
+  await fs.mkdir(input.cacheRoot, { recursive: true })
+
+  const canUseRemote = Boolean(input.owner && input.repo) && canResolveGiteaHost()
+  const shouldUseRemote = (() => {
+    if (input.sourcePreference === 'gitea') return true
+    if (input.sourcePreference === 'local') return false
+    // auto: local-first, remote only if local isn't available
+    return !localAvailable
+  })()
+
+  if (shouldUseRemote) {
+    if (!canUseRemote) {
+      const missing = [
+        !input.owner ? 'owner' : null,
+        !input.repo ? 'repo' : null,
+        !canResolveGiteaHost() ? 'GITEA_HOST' : null,
+      ].filter((value): value is string => Boolean(value))
+      throw new Error(`Remote search requested but missing: ${missing.join(', ')}`)
+    }
+
+    const git = createGitServiceApi({
+      config: {
+        platform: 'GITEA',
+        giteaHost: resolveGiteaHost(),
+        giteaToken: process.env.GITEA_TOKEN,
+      },
+      defaultOwner: input.owner ?? undefined,
+      defaultRepo: input.repo ?? undefined,
+    })
+
+    const listContents = resolveRepoContentsApiMethod(git, 'list')
+    const viewContents = resolveRepoContentsApiMethod(git, 'view')
+
+    const remoteFiles = await collectRepoSectionFiles(listContents, input.owner as string, input.repo as string, input.section, input.ref)
+    for (const remotePath of remoteFiles) {
+      const relative = stripSectionPrefix(remotePath, input.section)
+      if (!relative) {
+        continue
+      }
+      const content = await loadRepoFileContent(viewContents, input.owner as string, input.repo as string, remotePath, input.ref)
+      const outPath = path.join(input.cacheRoot, relative)
+      await fs.mkdir(path.dirname(outPath), { recursive: true })
+      await fs.writeFile(outPath, content, 'utf8')
+    }
+
+    await fs.writeFile(
+      manifestPath,
+      JSON.stringify(
+        {
+          source: 'gitea',
+          owner: input.owner,
+          repo: input.repo,
+          section: input.section,
+          ref: input.ref,
+          fileCount: remoteFiles.length,
+          updatedAt: new Date().toISOString(),
+        },
+        null,
+        2,
+      ) + '\n',
+      'utf8',
+    )
+
+    return { refreshed: true, source: 'gitea' }
+  }
+
+  if (!localAvailable) {
+    throw new Error(`Section directory not found in project: ${localSectionRoot}`)
+  }
+
+  const copied = await copyProjectSectionToCache(localSectionRoot, input.cacheRoot)
+
+  await fs.writeFile(
+    manifestPath,
+    JSON.stringify(
+      {
+        source: 'local',
+        owner: input.owner,
+        repo: input.repo,
+        section: input.section,
+        ref: input.ref,
+        fileCount: copied,
+        updatedAt: new Date().toISOString(),
+      },
+      null,
+      2,
+    ) + '\n',
+    'utf8',
+  )
+
+  return { refreshed: true, source: 'local' }
+}
+
+function parseSearchSourceOption(value: unknown, remoteFlag: unknown): 'local' | 'gitea' | 'auto' {
+  if (parseBooleanOption(remoteFlag)) {
+    return 'gitea'
+  }
+  const normalized = parseStringOption(value)?.toLowerCase()
+  if (!normalized) return 'auto'
+  if (normalized === 'local') return 'local'
+  if (normalized === 'gitea' || normalized === 'remote') return 'gitea'
+  if (normalized === 'auto') return 'auto'
+  throw new Error(`Invalid search source: ${normalized}. Expected "local", "gitea", or "auto".`)
+}
+
+function canResolveGiteaHost(): boolean {
+  return Boolean(process.env.GITEA_HOST ?? process.env.EXAMPLE_GITEA_HOST)
+}
+
+async function readCacheSource(manifestPath: string): Promise<'gitea' | 'local' | null> {
+  try {
+    const raw = await fs.readFile(manifestPath, 'utf8')
+    const parsed = JSON.parse(raw)
+    const source = (parsed as any)?.source
+    if (source === 'gitea' || source === 'local') {
+      return source
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+async function copyProjectSectionToCache(sectionRoot: string, cacheRoot: string): Promise<number> {
+  let copied = 0
+  const queue: Array<{ from: string; rel: string }> = [{ from: sectionRoot, rel: '' }]
+
+  while (queue.length > 0) {
+    const current = queue.shift()
+    if (!current) {
+      continue
+    }
+
+    const entries = await fs.readdir(current.from, { withFileTypes: true })
+    for (const entry of entries) {
+      if (entry.name.toLowerCase() === PROJECT_ARCHIVE_DIR_NAME) {
+        continue
+      }
+
+      const fromPath = path.join(current.from, entry.name)
+      const relPath = current.rel ? `${current.rel}/${entry.name}` : entry.name
+      const outPath = path.join(cacheRoot, relPath)
+
+      if (entry.isDirectory()) {
+        queue.push({ from: fromPath, rel: relPath })
+        continue
+      }
+
+      if (!entry.isFile() && !entry.isSymbolicLink()) {
+        continue
+      }
+
+      const content = await readTextIfExists(fromPath)
+      if (content === null) {
+        continue
+      }
+      await fs.mkdir(path.dirname(outPath), { recursive: true })
+      await fs.writeFile(outPath, content, 'utf8')
+      copied += 1
+    }
+  }
+
+  return copied
+}
+
+function resolveRepoContentsApiMethod(api: GitServiceApi, action: 'list' | 'view'): GitServiceApiMethod {
+  const repoNamespace = api.repo
+  if (!repoNamespace || typeof repoNamespace !== 'object') {
+    throw new Error('Git service API does not expose repo namespace')
+  }
+
+  const contentsNamespace = (repoNamespace as Record<string, unknown>).contents
+  if (!contentsNamespace || typeof contentsNamespace !== 'object') {
+    throw new Error('Git service API does not expose repo.contents namespace')
+  }
+
+  const method = (contentsNamespace as Record<string, unknown>)[action]
+  if (typeof method !== 'function') {
+    throw new Error(`Git service API does not expose repo.contents.${action}`)
+  }
+
+  return method as GitServiceApiMethod
+}
+
+function buildRepoContentsQueryOptions(ref: string | null): Record<string, unknown> | null {
+  if (!ref) {
+    return null
+  }
+
+  return {
+    query: {
+      ref,
+    },
+  }
+}
+
+async function collectRepoSectionFiles(
+  listContents: GitServiceApiMethod,
+  owner: string,
+  repo: string,
+  section: ProjectSearchTargetSection,
+  ref: string | null,
+): Promise<string[]> {
+  const discovered = new Set<string>()
+  const queue: string[] = [section]
+  const queryOptions = buildRepoContentsQueryOptions(ref)
+
+  while (queue.length > 0) {
+    const current = queue.shift()
+    if (!current) {
+      continue
+    }
+
+    const args: unknown[] = [owner, repo, current]
+    if (queryOptions) {
+      args.push(queryOptions)
+    }
+
+    const result = await listContents(...args)
+    if (!result.ok) {
+      throw new Error(
+        `Failed to list repo contents at ${current} (${owner}/${repo}). status=${result.status}`,
+      )
+    }
+
+    const entries = normalizeRepoContentsEntries(result.body, current)
+    for (const entry of entries) {
+      if (entry.type === 'dir') {
+        queue.push(entry.path)
+        continue
+      }
+
+      if (entry.type === 'file') {
+        discovered.add(entry.path)
+      }
+    }
+  }
+
+  return Array.from(discovered).sort((left, right) => left.localeCompare(right))
+}
+
+function normalizeRepoContentsEntries(
+  body: unknown,
+  currentPath: string,
+): Array<{ path: string; type: 'file' | 'dir' | 'other' }> {
+  const entries = Array.isArray(body) ? body : [body]
+  const normalized: Array<{ path: string; type: 'file' | 'dir' | 'other' }> = []
+
+  for (const entry of entries) {
+    if (!isRecord(entry)) {
+      continue
+    }
+
+    const rawType = typeof entry.type === 'string' ? entry.type.toLowerCase() : 'other'
+    const type = rawType === 'dir' || rawType === 'file' ? rawType : 'other'
+    const explicitPath = typeof entry.path === 'string' && entry.path.trim().length > 0
+      ? entry.path.trim().replace(/\\/g, '/')
+      : null
+    const explicitName = typeof entry.name === 'string' && entry.name.trim().length > 0
+      ? entry.name.trim()
+      : null
+    const resolvedPath = explicitPath
+      ?? (explicitName ? `${currentPath.replace(/\\/g, '/')}/${explicitName}` : null)
+
+    if (!resolvedPath) {
+      continue
+    }
+
+    normalized.push({
+      path: resolvedPath,
+      type,
+    })
+  }
+
+  return normalized
+}
+
+function stripSectionPrefix(remotePath: string, section: ProjectSearchTargetSection): string {
+  const normalized = remotePath.replace(/\\/g, '/')
+  if (normalized === section) {
+    return ''
+  }
+  if (normalized.startsWith(`${section}/`)) {
+    return normalized.slice(section.length + 1)
+  }
+  return ''
+}
+
+async function loadRepoFileContent(
+  viewContents: GitServiceApiMethod,
+  owner: string,
+  repo: string,
+  remotePath: string,
+  ref: string | null,
+): Promise<string> {
+  const args: unknown[] = [owner, repo, remotePath]
+  const queryOptions = buildRepoContentsQueryOptions(ref)
+  if (queryOptions) {
+    args.push(queryOptions)
+  }
+
+  const result = await viewContents(...args)
+  if (!result.ok) {
+    throw new Error(
+      `Failed to read repo file ${remotePath} (${owner}/${repo}). status=${result.status}`,
+    )
+  }
+
+  const content = extractRepoFileContent(result.body)
+  if (content === null) {
+    throw new Error(`Repo response for ${remotePath} did not contain textual file content.`)
+  }
+
+  return content
+}
+
+function extractRepoFileContent(body: unknown): string | null {
+  if (!isRecord(body)) {
+    return null
+  }
+
+  if (typeof body.content !== 'string') {
+    return null
+  }
+
+  const raw = body.content
+  const encoding = typeof body.encoding === 'string' ? body.encoding.toLowerCase() : ''
+
+  if (encoding === 'base64') {
+    try {
+      return Buffer.from(raw.replace(/\s+/g, ''), 'base64').toString('utf8')
+    } catch {
+      return null
+    }
+  }
+
+  return raw
+}
+
+function parseRgLikeQueryArgs(args: string[]): RgLikeSearchQuery {
+  const query: RgLikeSearchQuery = {
+    patterns: [],
+    paths: [],
+    lineNumber: true,
+    withFilename: false,
+    noFilename: false,
+    ignoreCase: false,
+    caseSensitive: false,
+    smartCase: false,
+    fixedStrings: false,
+    wordRegexp: false,
+    maxCount: null,
+    countOnly: false,
+    filesWithMatches: false,
+    filesWithoutMatch: false,
+    onlyMatching: false,
+    includeHidden: false,
+    globs: [],
+  }
+
+  const positionals: string[] = []
+  let stopOptionParsing = false
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]
+    if (!stopOptionParsing && arg === '--') {
+      stopOptionParsing = true
+      continue
+    }
+
+    if (!stopOptionParsing && arg.startsWith('--')) {
+      const consumed = parseRgLikeLongOption(arg, args[i + 1], query)
+      if (consumed) {
+        i += 1
+      }
+      continue
+    }
+
+    if (!stopOptionParsing && arg.startsWith('-') && arg !== '-') {
+      const consumed = parseRgLikeShortOption(arg, args[i + 1], query)
+      if (consumed) {
+        i += 1
+      }
+      continue
+    }
+
+    positionals.push(arg)
+  }
+
+  if (query.patterns.length === 0) {
+    const positionalPattern = positionals.shift()
+    if (!positionalPattern) {
+      throw new Error('Missing search pattern. Usage mirrors rg: PATTERN [PATH ...]')
+    }
+    query.patterns.push(positionalPattern)
+  }
+
+  query.paths = positionals.length > 0 ? positionals : ['.']
+
+  if (query.filesWithMatches && query.filesWithoutMatch) {
+    throw new Error('Cannot combine --files-with-matches and --files-without-match.')
+  }
+
+  return query
+}
+
+function parseRgLikeLongOption(option: string, next: string | undefined, query: RgLikeSearchQuery): boolean {
+  const equalsIndex = option.indexOf('=')
+  const name = equalsIndex >= 0 ? option.slice(0, equalsIndex) : option
+  const inlineValue = equalsIndex >= 0 ? option.slice(equalsIndex + 1) : null
+
+  const readValue = (): string => {
+    const value = inlineValue ?? next
+    if (value === undefined || value === null || value.length === 0) {
+      throw new Error(`Missing value for ${name}`)
+    }
+    return value
+  }
+
+  switch (name) {
+    case '--ignore-case':
+      query.ignoreCase = true
+      return false
+    case '--case-sensitive':
+      query.caseSensitive = true
+      return false
+    case '--smart-case':
+      query.smartCase = true
+      return false
+    case '--fixed-strings':
+      query.fixedStrings = true
+      return false
+    case '--word-regexp':
+      query.wordRegexp = true
+      return false
+    case '--line-number':
+      query.lineNumber = true
+      return false
+    case '--with-filename':
+      query.withFilename = true
+      return false
+    case '--no-filename':
+      query.noFilename = true
+      return false
+    case '--count':
+      query.countOnly = true
+      return false
+    case '--files-with-matches':
+      query.filesWithMatches = true
+      return false
+    case '--files-without-match':
+      query.filesWithoutMatch = true
+      return false
+    case '--only-matching':
+      query.onlyMatching = true
+      return false
+    case '--hidden':
+      query.includeHidden = true
+      return false
+    case '--no-ignore':
+      return false
+    case '--glob': {
+      query.globs.push(readValue())
+      return inlineValue === null
+    }
+    case '--regexp': {
+      query.patterns.push(readValue())
+      return inlineValue === null
+    }
+    case '--max-count': {
+      const value = readValue()
+      const parsed = Number.parseInt(value, 10)
+      if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new Error(`Invalid value for --max-count: ${value}`)
+      }
+      query.maxCount = parsed
+      return inlineValue === null
+    }
+    default:
+      throw new Error(`Unsupported rg option: ${name}`)
+  }
+}
+
+function parseRgLikeShortOption(option: string, next: string | undefined, query: RgLikeSearchQuery): boolean {
+  const cluster = option.slice(1)
+  if (!cluster) {
+    return false
+  }
+
+  const valueFlags = new Set(['m', 'g', 'e'])
+  let consumedNext = false
+
+  for (let i = 0; i < cluster.length; i += 1) {
+    const token = cluster[i]
+
+    if (valueFlags.has(token)) {
+      const inline = cluster.slice(i + 1)
+      const value = inline.length > 0 ? inline : next
+      if (!value) {
+        throw new Error(`Missing value for -${token}`)
+      }
+
+      if (token === 'm') {
+        const parsed = Number.parseInt(value, 10)
+        if (!Number.isFinite(parsed) || parsed < 0) {
+          throw new Error(`Invalid value for -m: ${value}`)
+        }
+        query.maxCount = parsed
+      } else if (token === 'g') {
+        query.globs.push(value)
+      } else if (token === 'e') {
+        query.patterns.push(value)
+      }
+
+      consumedNext = inline.length === 0
+      break
+    }
+
+    switch (token) {
+      case 'i':
+        query.ignoreCase = true
+        break
+      case 's':
+        query.caseSensitive = true
+        break
+      case 'S':
+        query.smartCase = true
+        break
+      case 'F':
+        query.fixedStrings = true
+        break
+      case 'w':
+        query.wordRegexp = true
+        break
+      case 'n':
+        query.lineNumber = true
+        break
+      case 'H':
+        query.withFilename = true
+        break
+      case 'h':
+        query.noFilename = true
+        break
+      case 'c':
+        query.countOnly = true
+        break
+      case 'l':
+        query.filesWithMatches = true
+        break
+      case 'L':
+        query.filesWithoutMatch = true
+        break
+      case 'o':
+        query.onlyMatching = true
+        break
+      default:
+        throw new Error(`Unsupported rg option: -${token}`)
+    }
+  }
+
+  return consumedNext
+}
+
+async function executeRgLikeSearch(
+  cacheRoot: string,
+  query: RgLikeSearchQuery,
+): Promise<RgLikeSearchExecutionResult> {
+  const files = await collectSearchFiles(cacheRoot, query)
+  const compiledPatterns = compileRgLikePatterns(query)
+  const outputLines: string[] = []
+  const multipleFiles = query.withFilename || files.length > 1
+
+  let filesMatched = 0
+  let matchedLines = 0
+  let matchedSegments = 0
+
+  for (const filePath of files) {
+    const relativePath = path.relative(cacheRoot, filePath).replace(/\\/g, '/')
+    const content = await fs.readFile(filePath, 'utf8')
+    const normalized = content.replace(/\r/g, '')
+    const lines = normalized.split('\n')
+    if (lines.length > 0 && lines[lines.length - 1] === '') {
+      lines.pop()
+    }
+
+    let fileMatchedLines = 0
+    let fileMatchedSegments = 0
+    const fileLineOutputs: string[] = []
+
+    for (let index = 0; index < lines.length; index += 1) {
+      const lineText = lines[index] ?? ''
+      const matches = matchLineWithPatterns(lineText, compiledPatterns)
+      if (matches.length === 0) {
+        continue
+      }
+
+      fileMatchedLines += 1
+      fileMatchedSegments += matches.length
+
+      if (!query.countOnly && !query.filesWithMatches && !query.filesWithoutMatch) {
+        if (query.onlyMatching) {
+          for (const matchText of matches) {
+            fileLineOutputs.push(formatSearchOutputLine({
+              filePath: relativePath,
+              includeFilePath: multipleFiles && !query.noFilename,
+              lineNumber: index + 1,
+              includeLineNumber: query.lineNumber,
+              text: matchText,
+            }))
+          }
+        } else {
+          fileLineOutputs.push(formatSearchOutputLine({
+            filePath: relativePath,
+            includeFilePath: multipleFiles && !query.noFilename,
+            lineNumber: index + 1,
+            includeLineNumber: query.lineNumber,
+            text: lineText,
+          }))
+        }
+      }
+
+      if (query.maxCount !== null && fileMatchedLines >= query.maxCount) {
+        break
+      }
+    }
+
+    matchedLines += fileMatchedLines
+    matchedSegments += fileMatchedSegments
+
+    if (query.filesWithoutMatch) {
+      if (fileMatchedLines === 0) {
+        outputLines.push(relativePath)
+      }
+      continue
+    }
+
+    if (fileMatchedLines > 0) {
+      filesMatched += 1
+    }
+
+    if (query.filesWithMatches) {
+      if (fileMatchedLines > 0) {
+        outputLines.push(relativePath)
+      }
+      continue
+    }
+
+    if (query.countOnly) {
+      const includeFilePath = multipleFiles && !query.noFilename
+      outputLines.push(includeFilePath ? `${relativePath}:${fileMatchedLines}` : String(fileMatchedLines))
+      continue
+    }
+
+    outputLines.push(...fileLineOutputs)
+  }
+
+  return {
+    filesSearched: files.length,
+    filesMatched,
+    matchedLines,
+    matchedSegments,
+    outputLines,
+  }
+}
+
+function formatSearchOutputLine(input: {
+  filePath: string
+  includeFilePath: boolean
+  lineNumber: number
+  includeLineNumber: boolean
+  text: string
+}): string {
+  const prefixParts: string[] = []
+  if (input.includeFilePath) {
+    prefixParts.push(input.filePath)
+  }
+  if (input.includeLineNumber) {
+    prefixParts.push(String(input.lineNumber))
+  }
+  if (prefixParts.length === 0) {
+    return input.text
+  }
+  return `${prefixParts.join(':')}:${input.text}`
+}
+
+function matchLineWithPatterns(line: string, patterns: RgLikeCompiledPattern[]): string[] {
+  const collected: string[] = []
+
+  for (const pattern of patterns) {
+    if (!pattern.test.test(line)) {
+      continue
+    }
+
+    pattern.global.lastIndex = 0
+    let match: RegExpExecArray | null = null
+    while ((match = pattern.global.exec(line)) !== null) {
+      collected.push(match[0] ?? '')
+      if ((match[0] ?? '').length === 0) {
+        pattern.global.lastIndex += 1
+      }
+    }
+  }
+
+  return collected
+}
+
+function compileRgLikePatterns(query: RgLikeSearchQuery): RgLikeCompiledPattern[] {
+  return query.patterns.map((pattern) => {
+    const source = query.fixedStrings ? escapeRegExp(pattern) : pattern
+    const wrappedSource = query.wordRegexp ? `\\b(?:${source})\\b` : source
+    const flags = resolveRgLikePatternFlags(pattern, query)
+
+    try {
+      return {
+        test: new RegExp(wrappedSource, flags),
+        global: new RegExp(wrappedSource, `${flags}g`),
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      throw new Error(`Invalid search pattern "${pattern}": ${message}`)
+    }
+  })
+}
+
+function resolveRgLikePatternFlags(pattern: string, query: RgLikeSearchQuery): string {
+  if (query.caseSensitive) {
+    return ''
+  }
+  if (query.ignoreCase) {
+    return 'i'
+  }
+  if (query.smartCase) {
+    return /[A-Z]/.test(pattern) ? '' : 'i'
+  }
+  return ''
+}
+
+type CompiledSearchGlob = {
+  raw: string
+  negate: boolean
+  regex: RegExp
+  basenameOnly: boolean
+}
+
+async function collectSearchFiles(cacheRoot: string, query: RgLikeSearchQuery): Promise<string[]> {
+  const compiledGlobs = compileSearchGlobs(query.globs)
+  const files = new Set<string>()
+
+  for (const requested of query.paths) {
+    const normalized = requested === '.' ? '' : requested.replace(/\\/g, '/')
+    const candidate = path.resolve(cacheRoot, normalized)
+    if (!isSubPath(cacheRoot, candidate)) {
+      throw new Error(`Path escapes cache root: ${requested}`)
+    }
+
+    let stats: fsSync.Stats
+    try {
+      stats = await fs.stat(candidate)
+    } catch {
+      throw new Error(`Path not found in cached section: ${requested}`)
+    }
+
+    if (stats.isDirectory()) {
+      await collectFilesFromDirectory(cacheRoot, candidate, query.includeHidden, compiledGlobs, files)
+      continue
+    }
+
+    if (stats.isFile() && shouldIncludeFile(cacheRoot, candidate, query.includeHidden, compiledGlobs)) {
+      files.add(candidate)
+    }
+  }
+
+  return Array.from(files).sort((left, right) => left.localeCompare(right))
+}
+
+async function collectFilesFromDirectory(
+  cacheRoot: string,
+  directory: string,
+  includeHidden: boolean,
+  globs: CompiledSearchGlob[],
+  files: Set<string>,
+): Promise<void> {
+  const entries = await fs.readdir(directory, { withFileTypes: true })
+
+  for (const entry of entries) {
+    if (entry.name === PROJECT_ARCHIVE_DIR_NAME) {
+      continue
+    }
+
+    if (!includeHidden && entry.name.startsWith('.')) {
+      continue
+    }
+
+    const absolute = path.join(directory, entry.name)
+    if (entry.isDirectory()) {
+      await collectFilesFromDirectory(cacheRoot, absolute, includeHidden, globs, files)
+      continue
+    }
+
+    if (entry.isFile() && shouldIncludeFile(cacheRoot, absolute, includeHidden, globs)) {
+      files.add(absolute)
+    }
+  }
+}
+
+function shouldIncludeFile(
+  cacheRoot: string,
+  filePath: string,
+  includeHidden: boolean,
+  globs: CompiledSearchGlob[],
+): boolean {
+  const relative = path.relative(cacheRoot, filePath).replace(/\\/g, '/')
+  if (!includeHidden && relative.split('/').some((segment) => segment.startsWith('.'))) {
+    return false
+  }
+
+  return matchesSearchGlobs(relative, globs)
+}
+
+function compileSearchGlobs(globs: string[]): CompiledSearchGlob[] {
+  return globs
+    .map((raw) => raw.trim())
+    .filter((raw) => raw.length > 0)
+    .map((raw) => {
+      const negate = raw.startsWith('!')
+      const normalized = (negate ? raw.slice(1) : raw).replace(/\\/g, '/')
+      const basenameOnly = !normalized.includes('/')
+
+      return {
+        raw,
+        negate,
+        regex: globToRegExp(normalized),
+        basenameOnly,
+      }
+    })
+}
+
+function matchesSearchGlobs(relativePath: string, globs: CompiledSearchGlob[]): boolean {
+  if (globs.length === 0) {
+    return true
+  }
+
+  const includeGlobs = globs.filter((glob) => !glob.negate)
+  const excludeGlobs = globs.filter((glob) => glob.negate)
+  const fileName = relativePath.split('/').pop() ?? relativePath
+
+  const matchesGlob = (glob: CompiledSearchGlob): boolean => {
+    if (glob.basenameOnly) {
+      return glob.regex.test(fileName)
+    }
+    return glob.regex.test(relativePath)
+  }
+
+  if (includeGlobs.length > 0 && !includeGlobs.some((glob) => matchesGlob(glob))) {
+    return false
+  }
+
+  if (excludeGlobs.some((glob) => matchesGlob(glob))) {
+    return false
+  }
+
+  return true
 }
 
-export async function readProjectDoc(
-  projectName: string,
-  requestPath: string,
-  processRoot: string = process.cwd()
-): Promise<string> {
-  const projectRoot = resolveProjectRoot(projectName, processRoot)
-  const catalog = buildProjectDocsCatalog(projectRoot)
-  const normalized = normalizeProjectDocRequest(requestPath)
-  const sourcePath = resolveProjectDocPath(catalog, normalized)
+function globToRegExp(glob: string): RegExp {
+  let index = 0
+  let source = '^'
 
-  if (!sourcePath) {
-    throw new Error(`Doc file not found: ${requestPath}`)
-  }
+  while (index < glob.length) {
+    const char = glob[index]
 
-  const content = await readTextIfExists(sourcePath)
-  if (content === null) {
-    throw new Error(`Doc file not found: ${requestPath}`)
+    if (char === '*') {
+      const next = glob[index + 1]
+      if (next === '*') {
+        source += '.*'
+        index += 2
+        continue
+      }
+      source += '[^/]*'
+      index += 1
+      continue
+    }
+
+    if (char === '?') {
+      source += '[^/]'
+      index += 1
+      continue
+    }
+
+    source += escapeRegExp(char)
+    index += 1
   }
 
-  return content
+  source += '$'
+  return new RegExp(source)
 }
 
 type ProjectVersionedFileSpec = {
@@ -754,7 +1970,10 @@ function parseSyncTasksArgs(argv: string[]): {
     prefix: '[TASK]',
     dryRun: false,
     requestTimeoutMs: 60_000,
-    throttleMs: 0,
+    throttleMs: 200,
+    retryMax: 5,
+    retryBaseDelayMs: 500,
+    retryMaxDelayMs: 10_000,
     skipDependencies: false,
     verbose: false,
   }
@@ -864,6 +2083,41 @@ function parseSyncTasksArgs(argv: string[]): {
       continue
     }
 
+    if (arg === '--retry') {
+      const value = Number(argv[i + 1])
+      if (!Number.isFinite(value) || value < 0 || Math.floor(value) !== value) {
+        throw new Error(`Invalid --retry value: ${argv[i + 1]}`)
+      }
+      options.retryMax = value
+      i += 1
+      continue
+    }
+
+    if (arg === '--retry-base-delay-ms') {
+      const value = Number(argv[i + 1])
+      if (!Number.isFinite(value) || value < 0 || Math.floor(value) !== value) {
+        throw new Error(`Invalid --retry-base-delay-ms value: ${argv[i + 1]}`)
+      }
+      options.retryBaseDelayMs = value
+      i += 1
+      continue
+    }
+
+    if (arg === '--retry-max-delay-ms') {
+      const value = Number(argv[i + 1])
+      if (!Number.isFinite(value) || value < 0 || Math.floor(value) !== value) {
+        throw new Error(`Invalid --retry-max-delay-ms value: ${argv[i + 1]}`)
+      }
+      options.retryMaxDelayMs = value
+      i += 1
+      continue
+    }
+
+    if (arg === '--no-retry') {
+      options.retryMax = 0
+      continue
+    }
+
     if (arg === '--skip-dependencies') {
       options.skipDependencies = true
       continue
@@ -1378,6 +2632,21 @@ function toProjectGitTaskRecord(issue: GitIssueLike): ProjectGitTaskRecord | nul
   }
 }
 
+function toProjectGitIssueRecord(issue: GitIssueLike): ProjectGitIssueRecord | null {
+  const raw = issue as Record<string, unknown>
+
+  const issueNumber = Number(raw.number)
+  if (!Number.isInteger(issueNumber) || issueNumber <= 0) return null
+
+  return {
+    number: issueNumber,
+    title: typeof raw.title === 'string' ? raw.title : `Issue #${issueNumber}`,
+    body: typeof raw.body === 'string' ? raw.body : '',
+    state: typeof raw.state === 'string' ? raw.state : 'unknown',
+    labels: normalizeIssueLabels(raw.labels),
+  }
+}
+
 function resolveProjectGitRepository(
   projectName: string,
   processRoot: string,
@@ -1471,24 +2740,141 @@ type GitIssueLike = {
   body?: unknown
 }
 
+type NetworkRetryOptions = {
+  maxRetries: number
+  baseDelayMs: number
+  maxDelayMs: number
+  retryOnStatuses: ReadonlySet<number>
+}
+
+const DEFAULT_RETRYABLE_HTTP_STATUSES = new Set<number>([408, 425, 429, 500, 502, 503, 504])
+
+function resolveNetworkRetryOptions(options: {
+  retryMax?: number
+  retryBaseDelayMs?: number
+  retryMaxDelayMs?: number
+}): NetworkRetryOptions {
+  const maxRetries = Number.isFinite(options.retryMax) ? Math.max(0, Math.floor(options.retryMax ?? 0)) : 0
+  const baseDelayMs = Number.isFinite(options.retryBaseDelayMs) ? Math.max(0, Math.floor(options.retryBaseDelayMs ?? 0)) : 0
+  const maxDelayMs = Number.isFinite(options.retryMaxDelayMs) ? Math.max(0, Math.floor(options.retryMaxDelayMs ?? 0)) : 0
+
+  return {
+    maxRetries,
+    baseDelayMs,
+    maxDelayMs,
+    retryOnStatuses: DEFAULT_RETRYABLE_HTTP_STATUSES,
+  }
+}
+
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
+
+function retryDelayMs(retryNumber: number, baseDelayMs: number, maxDelayMs: number): number {
+  if (retryNumber <= 0) {
+    return 0
+  }
+
+  const exponent = Math.max(0, retryNumber - 1)
+  const raw = baseDelayMs * (2 ** exponent)
+  const capped = maxDelayMs > 0 ? Math.min(raw, maxDelayMs) : raw
+  const jitter = 0.5 + Math.random()
+  return Math.max(0, Math.floor(capped * jitter))
+}
+
+function isRetryableError(error: unknown, retryOnStatuses: ReadonlySet<number>): boolean {
+  if (!(error instanceof Error)) {
+    return false
+  }
+
+  const message = String(error.message ?? '').toLowerCase()
+  const statusMatch = message.match(/status\\s*=\\s*(\\d{3})/)
+  if (statusMatch) {
+    const status = Number(statusMatch[1])
+    if (Number.isInteger(status) && retryOnStatuses.has(status)) {
+      return true
+    }
+  }
+
+  if (message.includes('request timed out')) return true
+  if (message.includes('timeout')) return true
+  if (message.includes('fetch failed')) return true
+  if (message.includes('network')) return true
+  if (message.includes('socket')) return true
+  if (message.includes('econnreset')) return true
+  if (message.includes('econnrefused')) return true
+  if (message.includes('enotfound')) return true
+  if (message.includes('eai_again')) return true
+  if (message.includes('tls')) return true
+
+  return false
+}
+
+async function withRetry<T>(
+  label: string,
+  operation: () => Promise<T>,
+  retry: NetworkRetryOptions,
+  log: ((message: string) => void) | null,
+  shouldRetryValue?: (value: T) => string | null,
+): Promise<T> {
+  const maxAttempts = Math.max(1, retry.maxRetries + 1)
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      const value = await operation()
+      const retryReason = shouldRetryValue ? shouldRetryValue(value) : null
+      if (retryReason && attempt < maxAttempts) {
+        const delay = retryDelayMs(attempt, retry.baseDelayMs, retry.maxDelayMs)
+        log?.(`${label}: retrying (attempt ${attempt}/${maxAttempts}) reason=${retryReason} delay=${delay}ms`)
+        if (delay > 0) await sleep(delay)
+        continue
+      }
+      return value
+    } catch (error) {
+      if (attempt >= maxAttempts || !isRetryableError(error, retry.retryOnStatuses)) {
+        throw error
+      }
+
+      const delay = retryDelayMs(attempt, retry.baseDelayMs, retry.maxDelayMs)
+      const message = error instanceof Error ? error.message : String(error)
+      log?.(`${label}: retrying (attempt ${attempt}/${maxAttempts}) error=${message} delay=${delay}ms`)
+      if (delay > 0) await sleep(delay)
+    }
+  }
+
+  // Unreachable, but keeps TS happy.
+  throw new Error(`${label}: retry loop exhausted`)
+}
+
 async function fetchAllIssues(
   issueList: GitServiceApiMethod,
   owner: string,
   repo: string,
   state: 'open' | 'closed' | 'all',
   projectName: string,
-  log?: (message: string) => void
+  log?: (message: string) => void,
+  requestOptions?: { retry?: NetworkRetryOptions; throttleMs?: number },
 ): Promise<GitIssueLike[]> {
   const allIssues: GitIssueLike[] = []
   let page = 1
+  const retry = requestOptions?.retry ?? resolveNetworkRetryOptions({ retryMax: 0, retryBaseDelayMs: 0, retryMaxDelayMs: 0 })
+  const throttleMs = requestOptions?.throttleMs ?? 0
 
   while (true) {
     log?.(`Listing ${state} issues page ${page} for ${owner}/${repo}...`)
-    const listResult = await issueList(owner, repo, {
-      state,
-      limit: ISSUE_LIST_PAGE_SIZE,
-      query: { page },
-    })
+    const listResult = await withRetry(
+      `issue.list ${owner}/${repo} state=${state} page=${page}`,
+      () => issueList(owner, repo, {
+        state,
+        limit: ISSUE_LIST_PAGE_SIZE,
+        query: { page },
+      }),
+      retry,
+      log ?? null,
+      (result) => {
+        const response = result as GitServiceApiExecutionResult
+        if (response.ok) return null
+        return retry.retryOnStatuses.has(response.status) ? `status=${response.status}` : null
+      },
+    )
 
     if (!listResult.ok) {
       throw new Error(
@@ -1508,12 +2894,205 @@ async function fetchAllIssues(
       break
     }
     page += 1
+
+    if (throttleMs > 0) {
+      await sleep(throttleMs)
+    }
   }
 
   log?.(`Loaded ${allIssues.length} ${state} issues in ${owner}/${repo} across pages.`)
   return allIssues
 }
 
+async function findIssueNumberByTaskId(
+  issueList: GitServiceApiMethod,
+  owner: string,
+  repo: string,
+  taskId: string,
+  projectName: string,
+  retry: NetworkRetryOptions,
+  throttleMs: number,
+  log: ((message: string) => void) | null,
+): Promise<number | null> {
+  let page = 1
+
+  while (true) {
+    const listResult = await withRetry(
+      `issue.list (lookup ${taskId}) ${owner}/${repo} page=${page}`,
+      () => issueList(owner, repo, {
+        state: 'open',
+        limit: ISSUE_LIST_PAGE_SIZE,
+        query: { page },
+      }),
+      retry,
+      log,
+      (result) => {
+        const response = result as GitServiceApiExecutionResult
+        if (response.ok) return null
+        return retry.retryOnStatuses.has(response.status) ? `status=${response.status}` : null
+      },
+    )
+
+    if (!listResult.ok) {
+      throw new Error(
+        `Failed to list open issues for ${owner}/${repo}: status=${listResult.status} url=${listResult.request.url}`
+      )
+    }
+
+    if (!Array.isArray(listResult.body)) {
+      throw new Error(`Expected array from issue.list for ${projectName} (open issues lookup, page ${page})`)
+    }
+
+    const batch = listResult.body as GitIssueLike[]
+    for (const issue of batch) {
+      const record = toProjectGitTaskRecord(issue)
+      if (record?.taskId === taskId) {
+        return record.number
+      }
+    }
+
+    if (batch.length === 0) {
+      break
+    }
+    page += 1
+
+    if (throttleMs > 0) {
+      await sleep(throttleMs)
+    }
+  }
+
+  return null
+}
+
+async function findIssueNumberByTaskIdEventually(
+  issueList: GitServiceApiMethod,
+  owner: string,
+  repo: string,
+  taskId: string,
+  projectName: string,
+  retry: NetworkRetryOptions,
+  throttleMs: number,
+  log: ((message: string) => void) | null,
+  attempts: number,
+  delayMs: number,
+): Promise<number | null> {
+  const totalAttempts = Math.max(1, Math.floor(attempts))
+
+  for (let i = 0; i < totalAttempts; i += 1) {
+    const existing = await findIssueNumberByTaskId(issueList, owner, repo, taskId, projectName, retry, throttleMs, log)
+    if (existing) {
+      return existing
+    }
+    if (i < totalAttempts - 1 && delayMs > 0) {
+      await sleep(delayMs)
+    }
+  }
+
+  return null
+}
+
+async function createTaskIssueNumberWithRetry(
+  issueCreate: GitServiceApiMethod,
+  issueList: GitServiceApiMethod,
+  owner: string,
+  repo: string,
+  taskId: string,
+  payload: Record<string, unknown>,
+  projectName: string,
+  retry: NetworkRetryOptions,
+  throttleMs: number,
+  log: ((message: string) => void) | null,
+): Promise<number> {
+  const maxAttempts = Math.max(1, retry.maxRetries + 1)
+  const verifyDelayMs = retry.baseDelayMs > 0 ? Math.min(500, retry.baseDelayMs) : 0
+  const verifyBudgetMs = retry.maxDelayMs > 0 ? Math.min(10_000, retry.maxDelayMs) : 0
+  const verifyAttempts = verifyDelayMs > 0 ? Math.max(1, Math.ceil(verifyBudgetMs / verifyDelayMs)) : 1
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      const createResult = await issueCreate(owner, repo, { data: payload }) as GitServiceApiExecutionResult
+
+      if (createResult.ok) {
+        const issueNumber = buildIssueNumberFromPayload(createResult.body)
+        if (issueNumber === null) {
+          throw new Error(
+            `Created issue response for ${taskId} in ${owner}/${repo} is invalid: ${JSON.stringify(createResult.body)}`
+          )
+        }
+        return issueNumber
+      }
+
+      const shouldRetry = retry.retryOnStatuses.has(createResult.status) && attempt < maxAttempts
+      if (!shouldRetry) {
+        const bodySummary = (() => {
+          try {
+            if (typeof createResult.body === 'string') {
+              return createResult.body.slice(0, 500)
+            }
+            return JSON.stringify(createResult.body)?.slice(0, 500) ?? String(createResult.body)
+          } catch {
+            return String(createResult.body)
+          }
+        })()
+        throw new Error(
+          `Failed to create issue for ${taskId} in ${owner}/${repo}: status=${createResult.status} url=${createResult.request.url} body=${bodySummary}`
+        )
+      }
+
+      log?.(`Create issue for ${taskId}: retryable response status=${createResult.status}; checking if issue already exists...`)
+      const existing = await findIssueNumberByTaskIdEventually(
+        issueList,
+        owner,
+        repo,
+        taskId,
+        projectName,
+        retry,
+        throttleMs,
+        log,
+        verifyAttempts,
+        verifyDelayMs,
+      )
+      if (existing) {
+        log?.(`Create issue for ${taskId}: found existing issue #${existing} after failure; continuing.`)
+        return existing
+      }
+
+      const delay = retryDelayMs(attempt, retry.baseDelayMs, retry.maxDelayMs)
+      log?.(`Create issue for ${taskId}: retrying (attempt ${attempt}/${maxAttempts}) delay=${delay}ms`)
+      if (delay > 0) await sleep(delay)
+    } catch (error) {
+      if (attempt >= maxAttempts || !isRetryableError(error, retry.retryOnStatuses)) {
+        throw error
+      }
+
+      const message = error instanceof Error ? error.message : String(error)
+      log?.(`Create issue for ${taskId}: retryable error (${message}); checking if issue already exists...`)
+      const existing = await findIssueNumberByTaskIdEventually(
+        issueList,
+        owner,
+        repo,
+        taskId,
+        projectName,
+        retry,
+        throttleMs,
+        log,
+        verifyAttempts,
+        verifyDelayMs,
+      )
+      if (existing) {
+        log?.(`Create issue for ${taskId}: found existing issue #${existing} after error; continuing.`)
+        return existing
+      }
+
+      const delay = retryDelayMs(attempt, retry.baseDelayMs, retry.maxDelayMs)
+      log?.(`Create issue for ${taskId}: retrying (attempt ${attempt}/${maxAttempts}) delay=${delay}ms`)
+      if (delay > 0) await sleep(delay)
+    }
+  }
+
+  throw new Error(`Create issue for ${taskId}: retry loop exhausted`)
+}
+
 function issueDependenciesMatches(taskDeps: string[], issue: ProjectSyncIssueRecord): boolean {
   const fromBody = issue.dependenciesFromBody
   if (fromBody) {
@@ -1788,9 +3367,21 @@ export async function writeGitTask(
   }
 
   if (!issueNumber) {
-    const createResult = await issueCreate(owner, repo, payload)
+    const createResult = await issueCreate(owner, repo, { data: payload })
     if (!createResult.ok) {
-      throw new Error(`Failed to create task in ${owner}/${repo}: status=${createResult.status} url=${createResult.request.url}`)
+      const bodySummary = (() => {
+        try {
+          if (typeof createResult.body === 'string') {
+            return createResult.body.slice(0, 500)
+          }
+          return JSON.stringify(createResult.body)?.slice(0, 500) ?? String(createResult.body)
+        } catch {
+          return String(createResult.body)
+        }
+      })()
+      throw new Error(
+        `Failed to create task in ${owner}/${repo}: status=${createResult.status} url=${createResult.request.url} body=${bodySummary}`
+      )
     }
 
     const issue = toProjectGitTaskRecord(createResult.body as GitIssueLike)
@@ -1808,9 +3399,21 @@ export async function writeGitTask(
     }
   }
 
-  const updateResult = await issueEdit(owner, repo, issueNumber, payload)
+  const updateResult = await issueEdit(owner, repo, issueNumber, { data: payload })
   if (!updateResult.ok) {
-    throw new Error(`Failed to update issue #${issueNumber} for ${owner}/${repo}: status=${updateResult.status} url=${updateResult.request.url}`)
+    const bodySummary = (() => {
+      try {
+        if (typeof updateResult.body === 'string') {
+          return updateResult.body.slice(0, 500)
+        }
+        return JSON.stringify(updateResult.body)?.slice(0, 500) ?? String(updateResult.body)
+      } catch {
+        return String(updateResult.body)
+      }
+    })()
+    throw new Error(
+      `Failed to update issue #${issueNumber} for ${owner}/${repo}: status=${updateResult.status} url=${updateResult.request.url} body=${bodySummary}`
+    )
   }
 
   const issue = toProjectGitTaskRecord(updateResult.body as GitIssueLike)
@@ -1828,6 +3431,63 @@ export async function writeGitTask(
   }
 }
 
+export async function createGitIssue(
+  projectName: string,
+  options: ProjectCreateGitIssueOptions,
+  processRoot: string = process.cwd()
+): Promise<ProjectCreateGitIssueResult> {
+  const { owner, repo } = resolveProjectGitRepository(projectName, processRoot, options)
+  const title = typeof options.title === 'string' ? options.title.trim() : ''
+  if (!title) {
+    throw new Error('Issue title is required.')
+  }
+
+  const payload: Record<string, unknown> = { title }
+  if (typeof options.body === 'string') payload.body = options.body
+  if (options.labels) payload.labels = options.labels
+
+  const git = createGitServiceApi({
+    config: {
+      platform: 'GITEA',
+      giteaHost: resolveGiteaHost(),
+      giteaToken: process.env.GITEA_TOKEN,
+    },
+    defaultOwner: owner,
+    defaultRepo: repo,
+  })
+
+  const issueCreate = resolveIssueApiMethod(git, 'create')
+  const createResult = await issueCreate(owner, repo, { data: payload })
+  if (!createResult.ok) {
+    const bodySummary = (() => {
+      try {
+        if (typeof createResult.body === 'string') {
+          return createResult.body.slice(0, 500)
+        }
+        return JSON.stringify(createResult.body)?.slice(0, 500) ?? String(createResult.body)
+      } catch {
+        return String(createResult.body)
+      }
+    })()
+    throw new Error(
+      `Failed to create issue in ${owner}/${repo}: status=${createResult.status} url=${createResult.request.url} body=${bodySummary}`
+    )
+  }
+
+  const issue = toProjectGitIssueRecord(createResult.body as GitIssueLike)
+  if (!issue) {
+    throw new Error(`Create issue response invalid for ${owner}/${repo}`)
+  }
+
+  return {
+    projectName,
+    owner,
+    repo,
+    issueNumber: issue.number,
+    issue,
+  }
+}
+
 export async function syncTasks(
   projectName: string,
   options: Partial<ProjectSyncTaskOptions> = {},
@@ -1847,8 +3507,11 @@ export async function syncTasks(
     dryRun: options.dryRun ?? false,
     max: options.max,
     maxBodyLength: options.maxBodyLength,
-    requestTimeoutMs: options.requestTimeoutMs,
-    throttleMs: options.throttleMs,
+    requestTimeoutMs: options.requestTimeoutMs ?? 60_000,
+    throttleMs: options.throttleMs ?? 200,
+    retryMax: options.retryMax ?? 5,
+    retryBaseDelayMs: options.retryBaseDelayMs ?? 500,
+    retryMaxDelayMs: options.retryMaxDelayMs ?? 10_000,
     skipDependencies: options.skipDependencies,
     owner,
     repo,
@@ -1869,7 +3532,9 @@ export async function syncTasks(
   log?.(`Resolved tracks file: ${tracksPath}`)
   log?.(`Using issue destination: ${owner}/${repo}`)
   log?.(`HTTP request timeout: ${syncOptions.requestTimeoutMs ?? 'default'}`)
+  log?.(`HTTP transport: ${(process.env.EXAMPLE_GIT_HTTP_TRANSPORT ?? '').trim() || '(auto)'}`)
   log?.(`HTTP throttle: ${syncOptions.throttleMs ?? 0}ms`)
+  log?.(`HTTP retry: max=${syncOptions.retryMax ?? 0} baseDelayMs=${syncOptions.retryBaseDelayMs ?? 0} maxDelayMs=${syncOptions.retryMaxDelayMs ?? 0}`)
   log?.(`Dependency sync: ${syncOptions.skipDependencies ? 'skipped' : 'enabled'}`)
   const markdown = await fs.readFile(tracksPath, 'utf8')
   log?.(`Loaded tracks content (${markdown.length} chars).`)
@@ -1900,8 +3565,10 @@ export async function syncTasks(
   const issueList = resolveIssueApiMethod(git, 'list')
   const issueCreate = resolveIssueApiMethod(git, 'create')
   const issueEdit = resolveIssueApiMethod(git, 'edit')
+  const issueView = resolveIssueApiMethod(git, 'view')
 
-  const allIssues = await fetchAllIssues(issueList, owner, repo, 'all', projectName, log)
+  const retry = resolveNetworkRetryOptions(syncOptions)
+  const allIssues = await fetchAllIssues(issueList, owner, repo, 'all', projectName, log, { retry, throttleMs: syncOptions.throttleMs ?? 0 })
   const existing = indexExistingTaskIssues(allIssues, projectName)
   const indexedIssueCount = [...existing.values()].reduce((acc, bucket) => acc + bucket.length, 0)
   log?.(`Loaded ${indexedIssueCount} task-like issues in ${owner}/${repo}.`)
@@ -1917,9 +3584,6 @@ export async function syncTasks(
     unchanged: 0,
   }
 
-  const sleep = (ms: number) =>
-    new Promise<void>((resolve) => setTimeout(resolve, ms))
-
   for (let i = 0; i < selected.length; i += 1) {
     const task = selected[i]
     const marker = `[${i + 1}/${selected.length}] ${task.id}`
@@ -1941,17 +3605,55 @@ export async function syncTasks(
       log?.(`${marker} updating #${targetIssue.number}`)
       if (!syncOptions.dryRun) {
         log?.(`${marker} sending update request...`)
-        const updatedResult = await issueEdit(owner, repo, targetIssue.number, {
-          data: {
-            title: payload.title,
-            body: payload.body,
-            labels: payload.labels,
-            task_id: payload.task_id,
-            task_dependencies: payload.task_dependencies,
+        const updatedResult = await withRetry(
+          `${marker} issue.edit #${targetIssue.number}`,
+          () => issueEdit(owner, repo, targetIssue.number, {
+            data: {
+              title: payload.title,
+              body: payload.body,
+              labels: payload.labels,
+              task_id: payload.task_id,
+              task_dependencies: payload.task_dependencies,
+            },
+          }) as Promise<GitServiceApiExecutionResult>,
+          retry,
+          log,
+          (result) => {
+            if (result.ok) return null
+            return retry.retryOnStatuses.has(result.status) ? `status=${result.status}` : null
           },
-        }) as GitServiceApiExecutionResult
+        )
 
         if (!updatedResult.ok) {
+          const isTimeoutOrRetryable = retry.retryOnStatuses.has(updatedResult.status)
+          if (isTimeoutOrRetryable) {
+            try {
+              const viewResult = await withRetry(
+                `${marker} issue.view #${targetIssue.number}`,
+                () => issueView(owner, repo, targetIssue.number) as Promise<GitServiceApiExecutionResult<GitIssueLike>>,
+                retry,
+                log,
+                (result) => {
+                  if (result.ok) return null
+                  return retry.retryOnStatuses.has(result.status) ? `status=${result.status}` : null
+                },
+              )
+
+              if (viewResult.ok) {
+                const record = toProjectGitTaskRecord(viewResult.body as GitIssueLike)
+                const expectedHash = computeTaskHash(task)
+                const depsMatch = areDependencyListsEqual(task.deps, record?.taskDependenciesFromPayload ?? [])
+                const signatureMatch = record?.taskSignature?.toLowerCase() === expectedHash.toLowerCase()
+                if (signatureMatch && depsMatch) {
+                  log?.(`${marker} update likely succeeded (verified after retryable failure)`)
+                  continue
+                }
+              }
+            } catch {
+              // best effort
+            }
+          }
+
           throw new Error(
             `Failed to update issue ${targetIssue.number} for ${owner}/${repo}: status=${updatedResult.status} url=${updatedResult.request.url}`
           )
@@ -1966,45 +3668,25 @@ export async function syncTasks(
 
     log?.(`${marker} creating new task issue`)
     if (!syncOptions.dryRun) {
-      let createdResult: GitServiceApiExecutionResult
-      try {
-        log?.(`${marker} sending create request...`)
-        createdResult = await issueCreate(owner, repo, {
-          data: {
-            title: payload.title,
-            body: payload.body,
-            labels: payload.labels,
-            task_id: payload.task_id,
-            task_dependencies: payload.task_dependencies,
-          },
-        }) as GitServiceApiExecutionResult
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error)
-        throw new Error(`Failed to create issue for ${task.id} in ${owner}/${repo}: ${message}`)
-      }
-
-      if (!createdResult.ok) {
-        const bodySummary = (() => {
-          try {
-            if (typeof createdResult.body === 'string') {
-              return createdResult.body.slice(0, 500)
-            }
-            return JSON.stringify(createdResult.body)?.slice(0, 500) ?? String(createdResult.body)
-          } catch {
-            return String(createdResult.body)
-          }
-        })()
-        throw new Error(
-          `Failed to create issue for ${task.id} in ${owner}/${repo}: status=${createdResult.status} url=${createdResult.request.url} body=${bodySummary}`
-        )
-      }
-
-      const issueNumber = buildIssueNumberFromPayload(createdResult.body)
-      if (issueNumber === null) {
-        throw new Error(
-          `Created issue response for ${task.id} in ${owner}/${repo} is invalid: ${JSON.stringify(createdResult.body)}`
-        )
-      }
+      log?.(`${marker} sending create request...`)
+      const issueNumber = await createTaskIssueNumberWithRetry(
+        issueCreate,
+        issueList,
+        owner,
+        repo,
+        task.id,
+        {
+          title: payload.title,
+          body: payload.body,
+          labels: payload.labels,
+          task_id: payload.task_id,
+          task_dependencies: payload.task_dependencies,
+        },
+        projectName,
+        retry,
+        syncOptions.throttleMs ?? 0,
+        log,
+      )
       issueNumbersByTask.set(task.id, issueNumber)
 
       log?.(`${marker} created #${issueNumber}`)
@@ -2057,15 +3739,20 @@ export async function syncTasks(
       .filter((value): value is number => value !== undefined && value > 0)
 
     log?.(`Issue #${issueNumber}: syncing dependencies (${desiredDependencyIssues.length} desired)...`)
-    const syncResult = await syncIssueDependenciesViaApi(
-      owner,
-      repo,
-      issueNumber,
-      desiredDependencyIssues,
-      host,
-      token,
-      syncOptions.dryRun,
-      log
+    const syncResult = await withRetry(
+      `issue.dependencies ${owner}/${repo} #${issueNumber}`,
+      () => syncIssueDependenciesViaApi(
+        owner,
+        repo,
+        issueNumber,
+        desiredDependencyIssues,
+        host,
+        token,
+        syncOptions.dryRun,
+        log
+      ),
+      retry,
+      log,
     )
     dependencyStats.added += syncResult.added
     dependencyStats.removed += syncResult.removed
@@ -2231,7 +3918,12 @@ export async function main(argv: string[], processRoot: string = process.cwd()):
     throw new Error('Missing required arguments: <project-name>.')
   }
 
-  if (maybeTarget === 'sync-tasks') {
+  if (
+    maybeTarget === 'sync-tasks' ||
+    maybeTarget === '--sync-tasks' ||
+    maybeTarget === 'sync-issues' ||
+    maybeTarget === '--sync-issues'
+  ) {
     const parsedSync = parseSyncTasksArgs(rest)
     if (parsedSync.unknownFlags.length > 0) {
       throw new Error(`Unknown flags: ${parsedSync.unknownFlags.join(', ')}`)
@@ -2243,7 +3935,7 @@ export async function main(argv: string[], processRoot: string = process.cwd()):
     return `${CLI_NAME}: synced ${result.totalTasks} tasks for ${result.projectName}${dryRun} from ${path.relative(processRoot, result.tracksPath)}${truncated} (created ${result.created}, updated ${result.updated}, skipped ${result.skipped})`
   }
 
-  if (maybeTarget === 'clear-issues') {
+  if (maybeTarget === 'clear-issues' || maybeTarget === '--clear-issues') {
     const parsedClear = parseClearIssuesArgs(rest)
     if (parsedClear.unknownFlags.length > 0) {
       throw new Error(`Unknown flags: ${parsedClear.unknownFlags.join(', ')}`)