@foundation0/api 1.0.0

package/projects.ts

@@ -0,0 +1,2690 @@
+import fs from 'node:fs/promises'
+import fsSync from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { setActiveLink } from './agents'
+import {
+  parseTaskGraphFromMarkdown as parseTaskGraphFromMarkdownScript,
+  type TaskGraphParseResult,
+  type TaskGraphTask,
+} from './taskgraph-parser'
+import {
+  createGitServiceApi,
+  resolveProjectRepoIdentity,
+  type GitServiceApi,
+  type GitServiceApiExecutionResult,
+  type GitServiceApiMethod,
+  syncIssueDependencies as syncIssueDependenciesViaApi,
+} from './git'
+
+type ProjectGenerateOptions = {
+  input?: string
+  out?: string
+  dryRun: boolean
+  manifest: boolean
+  prune: boolean
+  verbose: boolean
+}
+
+export type ProjectGenerateResult = {
+  projectName: string
+  inputPath: string
+  outRoot: string
+  files: number
+  created: number
+  updated: number
+  unchanged: number
+  dryRun: boolean
+}
+
+type MonolithFile = {
+  relPath: string
+  content: string
+  sha256: string
+  bytes: number
+  meta?: {
+    spec_id?: string
+    title?: string
+    source?: string
+    source_version?: string
+    source_anchor?: string
+  }
+}
+
+type ProjectSyncTaskResult = {
+  projectName: string
+  tracksPath: string
+  owner: string
+  repo: string
+  totalTasks: number
+  created: number
+  updated: number
+  skipped: number
+  dryRun: boolean
+  truncated: boolean
+}
+
+type ProjectClearIssuesOptions = {
+  owner?: string
+  repo?: string
+  state: 'open' | 'closed' | 'all'
+  dryRun: boolean
+  force: boolean
+  verbose: boolean
+}
+
+type ProjectClearIssuesResult = {
+  projectName: string
+  owner: string
+  repo: string
+  state: 'open' | 'closed' | 'all'
+  total: number
+  deleted: number
+  dryRun: boolean
+}
+
+type ProjectSyncTaskOptions = {
+  tracks?: string
+  owner?: string
+  repo?: string
+  labels: string[]
+  prefix: string
+  dryRun: boolean
+  max?: number
+  maxBodyLength?: number
+  requestTimeoutMs?: number
+  throttleMs?: number
+  skipDependencies?: boolean
+  verbose?: boolean
+}
+
+type GitTaskIssueState = 'open' | 'closed' | 'all'
+
+type ProjectGitTaskQueryOptions = {
+  owner?: string
+  repo?: string
+  state?: GitTaskIssueState
+  taskOnly?: boolean
+}
+
+type ProjectWriteGitTaskOptions = {
+  owner?: string
+  repo?: string
+  createIfMissing?: boolean
+  title?: string
+  body?: string
+  labels?: string[]
+  state?: 'open' | 'closed'
+  taskDependencies?: string[]
+  taskSignature?: string
+}
+
+export type ProjectGitTaskRecord = {
+  number: number
+  title: string
+  taskId: string | null
+  taskSignature: string | null
+  body: string
+  state: string
+  labels: string[]
+  taskDependenciesFromPayload: string[]
+  taskDependenciesFromBody: string[]
+}
+
+export type ProjectFetchGitTasksResult = {
+  projectName: string
+  owner: string
+  repo: string
+  state: GitTaskIssueState
+  taskOnly: boolean
+  total: number
+  tasks: ProjectGitTaskRecord[]
+}
+
+export type ProjectReadGitTaskResult = {
+  projectName: string
+  owner: string
+  repo: string
+  issueNumber: number
+  issue: ProjectGitTaskRecord
+  foundBy: 'number' | 'taskId'
+  searchScope: GitTaskIssueState
+}
+
+export type ProjectWriteGitTaskResult = {
+  projectName: string
+  owner: string
+  repo: string
+  action: 'created' | 'updated'
+  issueNumber: number
+  issue: ProjectGitTaskRecord
+}
+
+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']
+const PROJECT_DOC_SUBDIRS = ['docs', 'spec'] as const
+const PROJECT_ARCHIVE_DIR_NAME = '_archive'
+const ACTIVE_DOC_EXTENSION_MARKER_RE = /^(.+)\.active\.([^.]+)$/i
+const VERSIONED_DOC_RE = new RegExp(`^(.+)\\.(${VERSION_RE_CORE})\\.([^.]+)$`)
+const TASK_HASH_LENGTH = 8
+const ISSUE_LIST_PAGE_SIZE = 100
+const resolveGiteaHost = (): string => {
+  const host = process.env.GITEA_HOST ?? process.env.F0_GITEA_HOST
+  if (!host) {
+    throw new Error('No Gitea host configured. Set GITEA_HOST or F0_GITEA_HOST.')
+  }
+  return host
+}
+const TASK_ID_RE = /^TASK-[0-9]{3}[A-Za-z0-9]*$/
+const TASK_TITLE_RE = /^\[([^\]]+)\]\s+(TASK-[0-9]{3}[A-Za-z0-9]*)\s*(?:\s*\[([0-9a-fA-F]{8})\])?/
+const DEPENDENCY_TOKEN_RE = /TASK-[0-9]{3}[A-Za-z0-9]*/g
+const DEFAULT_TRACKS_CANDIDATES = [
+  path.join('spec', 'tracks.md'),
+  path.join('spec', '07_roadmap', 'tracks.md'),
+] as const
+const PROJECTS_DIRECTORY = 'projects'
+
+type ProjectDocsCandidateKind = 'active' | 'plain' | 'versioned'
+
+type ProjectDocsCandidate = {
+  sourcePath: string
+  kind: ProjectDocsCandidateKind
+  version: string | null
+}
+
+function resolveProjectsRoot(processRoot: string): string {
+  return path.join(processRoot, PROJECTS_DIRECTORY)
+}
+
+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` +
+    `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` +
+    `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`
+}
+
+export function resolveProjectRoot(projectName: string, processRoot: string = process.cwd()): string {
+  if (!projectName || projectName.trim().length === 0) {
+    throw new Error('project-name is required.')
+  }
+
+  const normalized = projectName.trim().replace(/[\\/]+/g, path.sep)
+  if (normalized === '.' || normalized === '..' || normalized.includes(path.sep + '..') || normalized.includes('..')) {
+    throw new Error('project-name may not include path traversal.')
+  }
+
+  const projectRoot = path.join(resolveProjectsRoot(processRoot), normalized)
+  if (!existsDir(projectRoot)) {
+    throw new Error(`Project folder not found: ${projectRoot}`)
+  }
+
+  return projectRoot
+}
+
+export function listProjects(processRoot: string = process.cwd()): string[] {
+  const projectsRoot = resolveProjectsRoot(processRoot)
+  if (!existsDir(projectsRoot)) {
+    return []
+  }
+
+  return fsSync
+    .readdirSync(projectsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .filter((entry) => {
+      const docsPath = path.join(projectsRoot, entry.name, 'docs')
+      return existsDir(docsPath)
+    })
+    .map((entry) => entry.name)
+    .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
+}
+
+type ProjectVersionedFileSpec = {
+  parts: string[]
+  base: string
+  version: string | null
+  ext: string | null
+}
+
+function buildProjectDocsCatalog(projectRoot: string): Map<string, ProjectDocsCandidate> {
+  const catalog = new Map<string, ProjectDocsCandidate>()
+
+  for (const section of PROJECT_DOC_SUBDIRS) {
+    const sectionRoot = path.join(projectRoot, section)
+    if (!existsDir(sectionRoot)) {
+      continue
+    }
+    collectProjectDocs(sectionRoot, section, '', catalog)
+  }
+
+  return catalog
+}
+
+function collectProjectDocs(
+  baseDir: string,
+  section: string,
+  relativeDir: string,
+  catalog: Map<string, ProjectDocsCandidate>
+): void {
+  const entries = fsSync.readdirSync(baseDir, { withFileTypes: true })
+
+  for (const entry of entries) {
+    if (entry.name.toLowerCase() === PROJECT_ARCHIVE_DIR_NAME) {
+      continue
+    }
+
+    const childAbsolute = path.join(baseDir, entry.name)
+    if (entry.isDirectory()) {
+      const nextRelative = relativeDir ? `${relativeDir}/${entry.name}` : entry.name
+      collectProjectDocs(childAbsolute, section, nextRelative, catalog)
+      continue
+    }
+
+    if (!entry.isFile() && !entry.isSymbolicLink()) {
+      continue
+    }
+
+    const isActiveCandidate = entry.isSymbolicLink()
+    const simpleName = simplifyDocsFileName(entry.name, isActiveCandidate)
+    if (!simpleName) {
+      continue
+    }
+
+    const logicalPath = relativeDir
+      ? `${section}/${relativeDir}/${simpleName}`
+      : `${section}/${simpleName}`
+
+    const candidate = buildDocsCandidate(entry.name, childAbsolute, isActiveCandidate)
+    const existing = catalog.get(logicalPath)
+    if (!existing || shouldReplaceDocsCandidate(existing, candidate)) {
+      catalog.set(logicalPath, candidate)
+    }
+  }
+}
+
+function buildDocsCandidate(fileName: string, sourcePath: string, isSymlink: boolean): ProjectDocsCandidate {
+  const activeMatch = isSymlink ? fileName.match(ACTIVE_DOC_EXTENSION_MARKER_RE) : null
+  if (activeMatch) {
+    return {
+      sourcePath,
+      kind: 'active',
+      version: null,
+    }
+  }
+
+  const versionedMatch = fileName.match(VERSIONED_DOC_RE)
+  if (versionedMatch) {
+    return {
+      sourcePath,
+      kind: 'versioned',
+      version: versionedMatch[2],
+    }
+  }
+
+  return {
+    sourcePath,
+    kind: 'plain',
+    version: null,
+  }
+}
+
+function simplifyDocsFileName(fileName: string, isSymlink: boolean): string | null {
+  const activeMatch = isSymlink ? fileName.match(ACTIVE_DOC_EXTENSION_MARKER_RE) : null
+  if (activeMatch) {
+    return `${activeMatch[1]}.${activeMatch[2]}`
+  }
+
+  const versionedMatch = fileName.match(VERSIONED_DOC_RE)
+  if (versionedMatch) {
+    return `${versionedMatch[1]}.${versionedMatch[3]}`
+  }
+
+  return fileName
+}
+
+function docsCandidatePriority(kind: ProjectDocsCandidateKind): number {
+  if (kind === 'active') return 0
+  if (kind === 'plain') return 1
+  return 2
+}
+
+function shouldReplaceDocsCandidate(
+  current: ProjectDocsCandidate,
+  incoming: ProjectDocsCandidate
+): boolean {
+  const currentPriority = docsCandidatePriority(current.kind)
+  const incomingPriority = docsCandidatePriority(incoming.kind)
+
+  if (incomingPriority < currentPriority) return true
+  if (incomingPriority > currentPriority) return false
+
+  if (incoming.kind === 'versioned' && current.kind === 'versioned') {
+    if (!incoming.version || !current.version) {
+      return incoming.sourcePath.localeCompare(current.sourcePath) > 0
+    }
+
+    const versionCompare = compareVersions(current.version, incoming.version)
+    if (versionCompare < 0) return true
+    if (versionCompare === 0) {
+      return incoming.sourcePath.localeCompare(current.sourcePath) > 0
+    }
+  }
+
+  return false
+}
+
+function normalizeProjectDocRequest(requestPath: string): string {
+  const normalized = requestPath
+    .replace(/\\/g, '/')
+    .trim()
+
+  if (!normalized) {
+    throw new Error('doc-path is required.')
+  }
+
+  const trimmed = normalized.startsWith('/') ? normalized.slice(1) : normalized
+
+  const parts = trimmed.split('/').filter(Boolean)
+  if (parts.length === 0) {
+    throw new Error('doc-path is required.')
+  }
+
+  if (parts.some((part) => part === '.' || part === '..')) {
+    throw new Error(`Invalid doc-path: ${requestPath}`)
+  }
+
+  return trimmed
+}
+
+function resolveProjectDocPath(
+  catalog: Map<string, ProjectDocsCandidate>,
+  requestPath: string
+): string | null {
+  const exact = catalog.get(requestPath)
+  if (exact) {
+    return exact.sourcePath
+  }
+
+  const matches = Array.from(catalog).filter(([
+    candidatePath,
+  ]) => candidatePath === requestPath || candidatePath.endsWith(`/${requestPath}`))
+
+  if (matches.length === 1) {
+    return matches[0]?.[1]?.sourcePath ?? null
+  }
+
+  if (matches.length > 1) {
+    throw new Error(`Ambiguous doc-path: ${requestPath}`)
+  }
+
+  return null
+}
+
+export interface ProjectSetActiveResult {
+  projectName: string
+  sourceFile: string
+  activeFile: string
+  matchedFile: string
+  mode: 'symlink'
+}
+
+type PlanResolveOptions = {
+  requireActive?: boolean
+}
+
+export function resolveImplementationPlan(
+  projectRoot: string,
+  inputFile?: string,
+  options: PlanResolveOptions = {}
+): string {
+  const docsRoot = path.join(projectRoot, 'docs')
+  if (!existsDir(docsRoot)) {
+    throw new Error(`docs directory not found for project: ${projectRoot}`)
+  }
+
+  if (inputFile) {
+    const explicit = path.isAbsolute(inputFile) ? inputFile : path.join(docsRoot, inputFile)
+    const resolved = path.resolve(explicit)
+    if (!isSubPath(docsRoot, resolved)) {
+      throw new Error(`Input plan path must be within docs directory: ${inputFile}`)
+    }
+    if (!existsFile(explicit)) {
+      throw new Error(`Input plan file not found: ${explicit}`)
+    }
+    return resolved
+  }
+
+  const files = fsSync.readdirSync(docsRoot, { withFileTypes: true }).map((entry) => entry.name)
+
+  const active = files.find((file) => /^implementation[-_]?plan\.active\.[^.]+$/i.test(file))
+  if (active) {
+    return path.join(docsRoot, active)
+  }
+
+  if (options.requireActive) {
+    throw new Error(
+      'No active implementation plan file found: expected docs/implementation-plan.active.md (or .json/.txt/etc).'
+    )
+  }
+
+  const versioned = files.filter((file) => new RegExp(`^implementation[-_]plan\\.${VERSION_RE}\\.[^.]+$`, 'i').test(file))
+  if (versioned.length === 1) {
+    return path.join(docsRoot, versioned[0])
+  }
+  if (versioned.length > 1) {
+    throw new Error(
+      `Multiple versioned implementation plan files found: ${versioned.join(', ')}. Please use --input <path>.`
+    )
+  }
+
+  throw new Error('No implementation plan file found. Expected docs/implementation-plan.active.md or docs/implementation-plan.<ver>.md')
+}
+
+export async function generateSpec(
+  projectName: string,
+  options: Partial<ProjectGenerateOptions> = {},
+  processRoot: string = process.cwd()
+): Promise<ProjectGenerateResult> {
+  const projectRoot = resolveProjectRoot(projectName, processRoot)
+  const opts: ProjectGenerateOptions = {
+    input: options.input,
+    out: options.out,
+    dryRun: options.dryRun ?? false,
+    manifest: options.manifest ?? true,
+    prune: options.prune ?? false,
+    verbose: options.verbose ?? false,
+  }
+
+  const inputAbs = path.resolve(
+    resolveImplementationPlan(projectRoot, opts.input, { requireActive: !opts.input })
+  )
+  const outRoot = opts.out ? path.resolve(projectRoot, opts.out) : projectRoot
+
+  const inputContents = await readTextIfExists(inputAbs)
+  if (inputContents === null) {
+    throw new Error(`Input monolith file not found: ${inputAbs}`)
+  }
+
+  if (inputContents.trim().length === 0) {
+    throw new Error(`Input monolith is empty: ${inputAbs}`)
+  }
+
+  const files = parseMonolith(inputContents)
+  files.sort((a, b) => a.relPath.localeCompare(b.relPath))
+
+  const manifestRel = 'spec/.spec-manifest.json'
+  const manifestAbs = path.resolve(outRoot, manifestRel)
+
+  if (opts.prune && !opts.dryRun) {
+    const previous = await loadPreviousManifest(manifestAbs)
+    if (previous?.files) {
+      const now = new Set(files.map((file) => file.relPath))
+      const toDelete = previous.files
+        .map((entry) => entry?.path)
+        .filter((value): value is string => Boolean(value))
+        .map((entryPath) => normalizeRelPath(entryPath))
+        .filter((entryPath) => !now.has(entryPath))
+
+      for (const relPath of toDelete) {
+        const absolute = path.resolve(outRoot, relPath)
+        assertWithinOutRoot(outRoot, absolute)
+        try {
+          await fs.rm(absolute, { force: true })
+          if (opts.verbose) {
+            // eslint-disable-next-line no-console
+            console.log(`pruned ${relPath}`)
+          }
+        } catch {
+          // ignore
+        }
+      }
+    }
+  }
+
+  let created = 0
+  let updated = 0
+  let unchanged = 0
+
+  for (const file of files) {
+    const outPath = path.resolve(outRoot, file.relPath)
+    assertWithinOutRoot(outRoot, outPath)
+
+    if (opts.dryRun) {
+      // eslint-disable-next-line no-console
+      console.log(`[dry-run] would write ${file.relPath} (${file.bytes} bytes)`)
+      continue
+    }
+
+    await fs.mkdir(path.dirname(outPath), { recursive: true })
+    const status = await writeIfChanged(outPath, file.content)
+    if (status === 'created') created += 1
+    if (status === 'updated') updated += 1
+    if (status === 'unchanged') unchanged += 1
+
+    if (opts.verbose) {
+      // eslint-disable-next-line no-console
+      console.log(`${status.padEnd(9)} ${file.relPath}`)
+    }
+  }
+
+  if (opts.manifest && !opts.dryRun) {
+    const manifest = {
+      generated_at: new Date().toISOString(),
+      source_monolith: path.relative(process.cwd(), inputAbs) || inputAbs,
+      out_root: path.relative(process.cwd(), outRoot) || outRoot,
+      file_count: files.length,
+      total_bytes: files.reduce((sum, file) => sum + file.bytes, 0),
+      files: files.map((file) => ({
+        path: file.relPath,
+        sha256: file.sha256,
+        bytes: file.bytes,
+        spec_id: file.meta?.spec_id ?? null,
+        title: file.meta?.title ?? null,
+        source_anchor: file.meta?.source_anchor ?? null,
+      })),
+    }
+
+    await fs.mkdir(path.dirname(manifestAbs), { recursive: true })
+    await fs.writeFile(manifestAbs, JSON.stringify(manifest, null, 2) + '\n')
+  }
+
+  return {
+    projectName,
+    inputPath: inputAbs,
+    outRoot,
+    files: files.length,
+    created,
+    updated,
+    unchanged,
+    dryRun: opts.dryRun,
+  }
+}
+
+function parseGenerateArgs(argv: string[]): {
+  command: 'generate-spec' | 'list'
+  setActive: boolean
+  target?: string
+  latest: boolean
+  options: Partial<ProjectGenerateOptions>
+  requestedGenerateSpec: boolean
+  unknownFlags: string[]
+} {
+  const result: {
+    command: 'generate-spec' | 'list'
+    setActive: boolean
+    target?: string
+    latest: boolean
+    options: Partial<ProjectGenerateOptions>
+    requestedGenerateSpec: boolean
+    unknownFlags: string[]
+  } = {
+    options: {},
+    requestedGenerateSpec: false,
+    unknownFlags: [],
+    command: 'generate-spec',
+    setActive: false,
+    latest: false,
+  }
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+
+    if (!arg.startsWith('--')) {
+      if (!result.target) {
+        result.target = arg
+      } else {
+        result.unknownFlags.push(arg)
+      }
+      continue
+    }
+
+    if (arg === '--generate-spec') {
+      result.command = 'generate-spec'
+      result.requestedGenerateSpec = true
+      continue
+    }
+    if (arg === '--set-active') {
+      result.setActive = true
+      continue
+    }
+    if (arg === '--latest') {
+      result.latest = true
+      continue
+    }
+
+    if (arg === '--list') {
+      result.command = 'list'
+      continue
+    }
+
+    if (arg === '--input') {
+      const value = argv[i + 1]
+      if (!value) {
+        throw new Error('Missing value for --input')
+      }
+      result.options.input = value
+      i += 1
+      continue
+    }
+
+    if (arg === '--out') {
+      const value = argv[i + 1]
+      if (!value) {
+        throw new Error('Missing value for --out')
+      }
+      result.options.out = value
+      i += 1
+      continue
+    }
+
+    if (arg === '--dry-run') {
+      result.options.dryRun = true
+      continue
+    }
+
+    if (arg === '--prune') {
+      result.options.prune = true
+      continue
+    }
+
+    if (arg === '--manifest') {
+      result.options.manifest = true
+      continue
+    }
+
+    if (arg === '--no-manifest') {
+      result.options.manifest = false
+      continue
+    }
+
+    if (arg === '--verbose') {
+      result.options.verbose = true
+      continue
+    }
+
+    if (arg === '--') {
+      continue
+    }
+
+    result.unknownFlags.push(arg)
+  }
+
+  return result
+}
+
+function parseSyncTasksArgs(argv: string[]): {
+  options: Omit<ProjectSyncTaskOptions, 'tracks'>
+  tracks?: string
+  unknownFlags: string[]
+} {
+  const options: Omit<ProjectSyncTaskOptions, 'tracks'> = {
+    labels: [],
+    prefix: '[TASK]',
+    dryRun: false,
+    requestTimeoutMs: 60_000,
+    throttleMs: 0,
+    skipDependencies: false,
+    verbose: false,
+  }
+  const result: {
+    options: Omit<ProjectSyncTaskOptions, 'tracks'>
+    tracks?: string
+    unknownFlags: string[]
+  } = {
+    options,
+    unknownFlags: [],
+  }
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+
+    if (!arg.startsWith('--')) {
+      if (!result.tracks && !arg.startsWith('sync-tasks')) {
+        result.tracks = arg
+      } else {
+        result.unknownFlags.push(arg)
+      }
+      continue
+    }
+
+    if (arg === '--dry-run') {
+      options.dryRun = true
+      continue
+    }
+
+    if (arg === '--owner') {
+      const value = argv[i + 1]
+      if (!value) {
+        throw new Error('Missing value for --owner')
+      }
+      options.owner = value
+      i += 1
+      continue
+    }
+
+    if (arg === '--repo') {
+      const value = argv[i + 1]
+      if (!value) {
+        throw new Error('Missing value for --repo')
+      }
+      options.repo = value
+      i += 1
+      continue
+    }
+
+    if (arg === '--label') {
+      const value = argv[i + 1]
+      if (!value) {
+        throw new Error('Missing value for --label')
+      }
+      options.labels.push(value)
+      i += 1
+      continue
+    }
+
+    if (arg === '--prefix') {
+      const value = argv[i + 1]
+      if (!value) {
+        throw new Error('Missing value for --prefix')
+      }
+      options.prefix = value
+      i += 1
+      continue
+    }
+
+    if (arg === '--max-body') {
+      const value = Number(argv[i + 1])
+      if (!Number.isFinite(value) || value <= 0 || Math.floor(value) !== value) {
+        throw new Error(`Invalid --max-body value: ${argv[i + 1]}`)
+      }
+      options.maxBodyLength = value
+      i += 1
+      continue
+    }
+
+    if (arg === '--max') {
+      const value = Number(argv[i + 1])
+      if (!Number.isFinite(value) || value <= 0 || Math.floor(value) !== value) {
+        throw new Error(`Invalid --max value: ${argv[i + 1]}`)
+      }
+      options.max = value
+      i += 1
+      continue
+    }
+
+    if (arg === '--request-timeout-ms') {
+      const value = Number(argv[i + 1])
+      if (!Number.isFinite(value) || value <= 0 || Math.floor(value) !== value) {
+        throw new Error(`Invalid --request-timeout-ms value: ${argv[i + 1]}`)
+      }
+      options.requestTimeoutMs = value
+      i += 1
+      continue
+    }
+
+    if (arg === '--throttle-ms') {
+      const value = Number(argv[i + 1])
+      if (!Number.isFinite(value) || value < 0 || Math.floor(value) !== value) {
+        throw new Error(`Invalid --throttle-ms value: ${argv[i + 1]}`)
+      }
+      options.throttleMs = value
+      i += 1
+      continue
+    }
+
+    if (arg === '--skip-dependencies') {
+      options.skipDependencies = true
+      continue
+    }
+
+    if (arg === '--tracks') {
+      const value = argv[i + 1]
+      if (!value) {
+        throw new Error('Missing value for --tracks')
+      }
+      result.tracks = value
+      i += 1
+      continue
+    }
+
+    if (arg === '--verbose') {
+      options.verbose = true
+      continue
+    }
+
+    result.unknownFlags.push(arg)
+  }
+
+  return result
+}
+
+function parseClearIssuesArgs(argv: string[]): {
+  options: ProjectClearIssuesOptions
+  unknownFlags: string[]
+} {
+  const options: ProjectClearIssuesOptions = {
+    state: 'all',
+    dryRun: false,
+    force: false,
+    verbose: false,
+  }
+
+  const result: {
+    options: ProjectClearIssuesOptions
+    unknownFlags: string[]
+  } = {
+    options,
+    unknownFlags: [],
+  }
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+
+    if (arg === '--dry-run') {
+      options.dryRun = true
+      continue
+    }
+
+    if (arg === '--force') {
+      options.force = true
+      continue
+    }
+
+    if (arg === '--verbose') {
+      options.verbose = true
+      continue
+    }
+
+    if (arg === '--state') {
+      const value = argv[i + 1]
+      if (!value) {
+        throw new Error('Missing value for --state')
+      }
+      if (value !== 'open' && value !== 'closed' && value !== 'all') {
+        throw new Error(`Invalid value for --state: ${value}`)
+      }
+      options.state = value
+      i += 1
+      continue
+    }
+
+    if (arg === '--owner') {
+      const value = argv[i + 1]
+      if (!value) {
+        throw new Error('Missing value for --owner')
+      }
+      options.owner = value
+      i += 1
+      continue
+    }
+
+    if (arg === '--repo') {
+      const value = argv[i + 1]
+      if (!value) {
+        throw new Error('Missing value for --repo')
+      }
+      options.repo = value
+      i += 1
+      continue
+    }
+
+    if (arg.startsWith('--')) {
+      result.unknownFlags.push(arg)
+      continue
+    }
+
+    result.unknownFlags.push(arg)
+  }
+
+  return result
+}
+
+function resolveGitIdentityFromProject(projectRoot: string): { owner: string; repo: string } {
+  const resolved = resolveProjectRepoIdentity(projectRoot)
+  if (!resolved) {
+    throw new Error(
+      `Could not resolve project git identity from ${path.join(projectRoot, 'code', '.git', 'config')} or ${path.join(projectRoot, '.git', 'config')}`
+    )
+  }
+  return resolved
+}
+
+function resolveTracksPath(projectRoot: string, input?: string): string {
+  if (input) {
+    if (path.isAbsolute(input)) {
+      if (!existsFile(input)) {
+        throw new Error(`tracks file not found: ${input}`)
+      }
+      return input
+    }
+
+    const relative = input.startsWith('/') || input.startsWith('\\') ? input.slice(1) : input
+    const candidate = path.join(projectRoot, relative)
+    if (!existsFile(candidate)) {
+      throw new Error(`tracks file not found: ${input}`)
+    }
+    return candidate
+  }
+
+  for (const candidate of DEFAULT_TRACKS_CANDIDATES) {
+    const absolute = path.join(projectRoot, candidate)
+    if (existsFile(absolute)) {
+      return absolute
+    }
+  }
+
+  throw new Error(
+    `Could not locate tracks file. Checked: ${DEFAULT_TRACKS_CANDIDATES.map((candidate) => path.join(projectRoot, candidate)).join(', ')}`
+  )
+}
+
+function normalizeTaskDependencies(value: string): string[] {
+  const normalized = value
+    .split(',')
+    .map((raw) => raw.trim())
+    .filter(Boolean)
+    .filter((raw) => TASK_ID_RE.test(raw))
+  const seen = new Set<string>()
+  const deduped: string[] = []
+
+  for (const item of normalized) {
+    const canonical = item.toUpperCase()
+    if (seen.has(canonical)) {
+      continue
+    }
+    seen.add(canonical)
+    deduped.push(canonical)
+  }
+
+  return deduped
+}
+
+function parseDependencyCell(value: string): string[] {
+  const found = value.match(DEPENDENCY_TOKEN_RE)
+  if (!found) {
+    return []
+  }
+  return normalizeTaskDependencies(found.join(','))
+}
+
+function parseTaskGraphFromMarkdownForProjects(
+  markdown: string,
+  log?: (message: string) => void
+): TaskGraphParseResult {
+  try {
+    log?.('Parsing tracks using script taskgraph parser.')
+    return parseTaskGraphFromMarkdownScript(markdown)
+  } catch {
+    log?.('Script taskgraph parser did not match; trying table fallback parser.')
+    const rows = parseTaskGraphFromTableRows(markdown)
+    if (rows.length === 0) {
+      throw new Error('No parseable taskgraph found in markdown.')
+    }
+    return buildTaskGraphFromRows(rows)
+  }
+}
+
+function parseTaskGraphFromTableRows(markdown: string): Array<{ id: string; desc: string; deps: string[]; lineNo: number }> {
+  const rows: Array<{ id: string; desc: string; deps: string[]; lineNo: number }> = []
+  const lines = markdown.replace(/\r/g, '').split('\n')
+  let tableHasHeader = false
+  let depIndex = -1
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i].trim()
+    if (!line.startsWith('|') || !line.endsWith('|')) {
+      if (tableHasHeader && line.length === 0) {
+        tableHasHeader = false
+        depIndex = -1
+      }
+      continue
+    }
+
+    const cells = line
+      .slice(1, -1)
+      .split('|')
+      .map((value) => value.trim())
+      .filter((value) => value.length > 0)
+
+    if (cells.length < 3) {
+      continue
+    }
+
+    const isSeparator = cells.every((cell) => /^:?[-\s]+:?$/.test(cell))
+    if (isSeparator) {
+      continue
+    }
+
+    const hasTaskHeader = cells[0].toUpperCase().includes('TASK') && cells[0].toUpperCase().includes('ID')
+    const hasDescriptionHeader = cells[1].toUpperCase().includes('DESCRIPTION')
+
+    if (hasTaskHeader && hasDescriptionHeader) {
+      tableHasHeader = true
+      const depsHeaderIndex = cells.findIndex((cell) => cell.toUpperCase().includes('DEPEND'))
+      depIndex = depsHeaderIndex >= 0 ? depsHeaderIndex : -1
+      continue
+    }
+
+    if (!tableHasHeader) {
+      continue
+    }
+
+    const taskId = cells[0].trim().toUpperCase()
+    if (!TASK_ID_RE.test(taskId)) {
+      continue
+    }
+
+    const desc = cells[1]?.trim() ?? ''
+    const depCell = depIndex >= 0 ? cells[depIndex] ?? '' : ''
+    const dependencies = parseDependencyCell(depCell)
+
+    rows.push({ id: taskId, desc, deps: dependencies, lineNo: i + 1 })
+  }
+
+  return rows
+}
+
+function buildTaskGraphFromRows(rows: Array<{ id: string; desc: string; deps: string[]; lineNo: number }>): TaskGraphParseResult {
+  const byId = new Map<string, TaskGraphTask>()
+
+  for (const row of rows) {
+    if (!row.desc) {
+      throw new Error(`Empty description in tracks table at line ${row.lineNo}`)
+    }
+    if (TASK_ID_RE.test(row.id) === false) {
+      continue
+    }
+    const normalizedDeps = row.deps.filter((dependency) => dependency !== row.id)
+    if (normalizedDeps.length !== row.deps.length) {
+      throw new Error(`Task '${row.id}' cannot depend on itself`)
+    }
+    if (new Set(normalizedDeps).size !== normalizedDeps.length) {
+      throw new Error(`Duplicate dependencies for '${row.id}' at line ${row.lineNo}`)
+    }
+
+    const task: TaskGraphTask = {
+      id: row.id as TaskGraphTask['id'],
+      desc: row.desc,
+      deps: normalizedDeps as TaskGraphTask['deps'],
+    }
+    byId.set(task.id, task)
+  }
+
+  const tasks = [...byId.values()]
+
+  const inDeg = new Map<string, number>()
+  const adj = new Map<string, string[]>()
+  for (const task of tasks) {
+    const effectiveDeps = task.deps.filter((dependency) => byId.has(dependency))
+    inDeg.set(task.id, effectiveDeps.length)
+    adj.set(task.id, [])
+  }
+
+  for (const task of tasks) {
+    for (const dep of task.deps.filter((dependency) => byId.has(dependency))) {
+      adj.get(dep)?.push(task.id)
+    }
+  }
+
+  const ready = [...inDeg.entries()]
+    .filter(([, degree]) => degree === 0)
+    .map(([id]) => id)
+    .sort()
+
+  const topo: string[] = []
+  while (ready.length > 0) {
+    const id = ready.shift()
+    if (!id) {
+      break
+    }
+
+    topo.push(id)
+    for (const downstream of adj.get(id) ?? []) {
+      const degree = (inDeg.get(downstream) ?? 0) - 1
+      inDeg.set(downstream, degree)
+      if (degree === 0) {
+        ready.push(downstream)
+        ready.sort()
+      }
+    }
+  }
+
+  if (topo.length !== tasks.length) {
+    const remaining = [...inDeg.entries()].filter(([, degree]) => degree > 0).map(([id]) => id).sort()
+    throw new Error(`Dependency cycle detected among: ${remaining.join(',')}`)
+  }
+
+  const byIdObject: Record<string, TaskGraphTask> = {}
+  for (const [id, task] of byId.entries()) {
+    byIdObject[id] = task
+  }
+
+  return {
+    version: 'TASKGRAPH-V1',
+    tasks,
+    byId: byIdObject,
+    topo,
+  }
+}
+
+function computeTaskHash(task: TaskGraphTask): string {
+  const payload = `${task.id}|${task.desc}|${task.deps.join(',')}`
+  return crypto
+    .createHash('sha256')
+    .update(payload, 'utf8')
+    .digest('hex')
+    .slice(0, TASK_HASH_LENGTH)
+}
+
+function buildIssuePayloadFromTask(
+  task: TaskGraphTask,
+  index: number,
+  total: number,
+  options: Pick<ProjectSyncTaskOptions, 'prefix' | 'maxBodyLength' | 'labels'>
+) {
+  const shortHash = computeTaskHash(task)
+  const deps = task.deps.length === 0 ? 'None' : task.deps.join(', ')
+  const body = [
+    `# ${task.id}`,
+    '',
+    `- Topological index: ${index + 1} / ${total}`,
+    `- Dependencies: ${deps}`,
+    '',
+    '## Description',
+    task.desc,
+  ].join('\n')
+
+  return {
+    title: `${options.prefix} ${task.id} [${shortHash}]`,
+    body: options.maxBodyLength ? body.slice(0, options.maxBodyLength) : body,
+    labels: [...new Set(options.labels)],
+    task_id: task.id,
+    task_dependencies: task.deps,
+    task_signature: shortHash,
+  }
+}
+
+function resolveIssueApiMethod(api: GitServiceApi, feature: 'create' | 'edit' | 'list' | 'delete' | 'view'): GitServiceApiMethod {
+  const issuesNamespace = api['issue']
+  if (!issuesNamespace || typeof issuesNamespace !== 'object') {
+    throw new Error('Git service API does not expose issue namespace')
+  }
+
+  const method = (issuesNamespace as {
+    create?: unknown
+    edit?: unknown
+    list?: unknown
+    delete?: unknown
+    view?: unknown
+  })[feature]
+  if (typeof method !== 'function') {
+    throw new Error(`Git service API does not expose issue.${feature}`)
+  }
+
+  return method as GitServiceApiMethod
+}
+
+type ProjectGitTaskIdentifier = {
+  type: 'number' | 'taskId'
+  value: number | string
+}
+
+function parseGitTaskReference(taskRef: string): ProjectGitTaskIdentifier {
+  const trimmed = taskRef.trim()
+  if (!trimmed) {
+    throw new Error('Task reference is required.')
+  }
+
+  const numeric = trimmed.match(/^([1-9]\d*)$/)
+  if (numeric?.[1]) {
+    return { type: 'number', value: Number(numeric[1]) }
+  }
+
+  const taskId = trimmed.toUpperCase()
+  if (!TASK_ID_RE.test(taskId)) {
+    throw new Error(`Invalid task reference: ${taskRef}`)
+  }
+
+  return { type: 'taskId', value: taskId }
+}
+
+function normalizeIssueLabels(raw: unknown): string[] {
+  if (!Array.isArray(raw)) {
+    return []
+  }
+
+  const labels = raw
+    .map((item) => {
+      if (typeof item === 'string') return item.trim()
+      if (item && typeof item === 'object' && 'name' in item && typeof (item as { name?: unknown }).name === 'string') {
+        return (item as { name: string }).name.trim()
+      }
+
+      return ''
+    })
+    .filter((value): value is string => value.length > 0)
+
+  return [...new Set(labels)]
+}
+
+function parseTaskDependencyList(raw: unknown): string[] {
+  if (Array.isArray(raw)) {
+    return [...new Set(
+      raw
+        .map((item) => (typeof item === 'string' ? item.trim().toUpperCase() : ''))
+        .filter((value): value is string => value.length > 0 && TASK_ID_RE.test(value)),
+    )]
+  }
+
+  if (typeof raw === 'string') {
+    return [...new Set(
+      normalizeTaskDependencies(raw).map((value) => value.toUpperCase()).filter((value) => TASK_ID_RE.test(value)),
+    )]
+  }
+
+  return []
+}
+
+function normalizeTaskId(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null
+  }
+
+  const normalized = value.trim().toUpperCase()
+  return TASK_ID_RE.test(normalized) ? normalized : null
+}
+
+function normalizeTaskSignature(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null
+  }
+
+  const normalized = value.trim()
+  return /^[0-9a-fA-F]{8}$/.test(normalized) ? normalized.toUpperCase() : null
+}
+
+function buildGitTaskPayload(ref: ProjectGitTaskIdentifier, options: ProjectWriteGitTaskOptions): Record<string, unknown> {
+  const payload: Record<string, unknown> = {}
+
+  if (typeof options.title === 'string') payload.title = options.title
+  if (typeof options.body === 'string') payload.body = options.body
+  if (options.labels) payload.labels = options.labels
+  if (options.state) payload.state = options.state
+  if (options.taskDependencies) payload.task_dependencies = options.taskDependencies
+  if (options.taskSignature) payload.task_signature = options.taskSignature
+
+  if (ref.type === 'taskId' && payload.title === undefined) {
+    payload.title = `[TASK] ${ref.value}`
+  }
+
+  return payload
+}
+
+function toProjectGitTaskRecord(issue: GitIssueLike): ProjectGitTaskRecord | null {
+  const raw = issue as Record<string, unknown>
+
+  const issueNumber = Number(raw.number)
+  if (!Number.isInteger(issueNumber) || issueNumber <= 0) return null
+
+  const title = typeof raw.title === 'string' ? raw.title : `Task #${issueNumber}`
+  const body = typeof raw.body === 'string' ? raw.body : ''
+  const parsedTitle = parseIssueTaskIdFromTitle(title)
+  const parsedBody = body ? parseIssueTaskIdFromBody(body) : null
+  const taskIdFromPayload = normalizeTaskId(raw.task_id)
+  const signatureFromPayload = normalizeTaskSignature(raw.task_signature)
+
+  return {
+    number: issueNumber,
+    title,
+    taskId: taskIdFromPayload ?? parsedTitle?.taskId ?? parsedBody?.taskId ?? null,
+    taskSignature: signatureFromPayload ?? parsedTitle?.hash ?? parsedBody?.hash ?? null,
+    body,
+    state: typeof raw.state === 'string' ? raw.state : 'unknown',
+    labels: normalizeIssueLabels(raw.labels),
+    taskDependenciesFromPayload: parseTaskDependencyList(raw.task_dependencies),
+    taskDependenciesFromBody: body ? parseIssueDependenciesFromBody(body) : [],
+  }
+}
+
+function resolveProjectGitRepository(
+  projectName: string,
+  processRoot: string,
+  options: { owner?: string; repo?: string },
+): { owner: string; repo: string } {
+  const projectRoot = resolveProjectRoot(projectName, processRoot)
+  const resolved = resolveGitIdentityFromProject(projectRoot)
+  const fallbackOwner = process.env.GITEA_TEST_OWNER || process.env.GITEA_OWNER
+  const fallbackRepo = process.env.GITEA_TEST_REPO || process.env.GITEA_REPO
+
+  const owner = options.owner ?? resolved?.owner ?? fallbackOwner
+  const repo = options.repo ?? resolved?.repo ?? fallbackRepo
+
+  if (!owner || !repo) {
+    throw new Error(
+      `Could not resolve project git identity from ${path.join(projectRoot, 'code', '.git', 'config')} or ${path.join(projectRoot, '.git', 'config')} and no owner/repo defaults are configured. Pass --owner and --repo (or set GITEA_TEST_OWNER and GITEA_TEST_REPO).`
+    )
+  }
+
+  return {
+    owner,
+    repo,
+  }
+}
+
+function parseIssueTaskIdFromTitle(title: string): { taskId: string; hash?: string } | null {
+  const normalizedTitle = title.trim().toUpperCase()
+  const match = normalizedTitle.match(TASK_TITLE_RE)
+  if (match && match[1] && match[2]) {
+    return {
+      taskId: match[2],
+      hash: match[3],
+    }
+  }
+
+  const fallbackMatch = normalizedTitle.match(/^(?:\[[^\]]+\]\s*)?(TASK-[0-9]{3}[A-Za-z0-9]*)/)
+  if (!fallbackMatch?.[1]) {
+    return null
+  }
+
+  return {
+    taskId: fallbackMatch[1],
+  }
+}
+
+function parseIssueTaskIdFromBody(body: string): { taskId: string; hash?: string } | null {
+  const firstLine = body
+    .replace(/\r/g, '')
+    .split('\n')
+    .map((line) => line.trim())
+    .find((line) => line.length > 0)
+
+  if (!firstLine) {
+    return null
+  }
+
+  const normalized = firstLine.toUpperCase().replace(/^#\s*/, '')
+  const match = normalized.match(/^(TASK-[0-9]{3}[A-Za-z0-9]*)(?:\s+\[([0-9A-F]{8})\])?/)
+  if (!match?.[1]) {
+    return null
+  }
+
+  return {
+    taskId: match[1],
+    hash: match[2],
+  }
+}
+
+function parseIssueDependenciesFromBody(body: string): string[] {
+  const match = body.match(/^\s*-\s*Dependencies:\s*(.+)$/im)
+  if (!match || !match[1]) {
+    return []
+  }
+
+  const text = match[1].trim()
+  if (!text || /^none$/i.test(text)) {
+    return []
+  }
+
+  return normalizeTaskDependencies(text.replace(/`/g, ','))
+}
+
+type GitIssueLike = {
+  title?: unknown
+  number?: unknown
+  task_id?: unknown
+  task_signature?: unknown
+  state?: unknown
+  labels?: unknown
+  task_dependencies?: unknown
+  body?: unknown
+}
+
+async function fetchAllIssues(
+  issueList: GitServiceApiMethod,
+  owner: string,
+  repo: string,
+  state: 'open' | 'closed' | 'all',
+  projectName: string,
+  log?: (message: string) => void
+): Promise<GitIssueLike[]> {
+  const allIssues: GitIssueLike[] = []
+  let page = 1
+
+  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 },
+    })
+
+    if (!listResult.ok) {
+      throw new Error(
+        `Failed to list ${state} 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} (page ${page})`)
+    }
+
+    const batch = listResult.body as GitIssueLike[]
+    allIssues.push(...batch)
+    log?.(`Loaded page ${page} with ${batch.length} ${state} issues for ${owner}/${repo}.`)
+
+    if (batch.length === 0) {
+      break
+    }
+    page += 1
+  }
+
+  log?.(`Loaded ${allIssues.length} ${state} issues in ${owner}/${repo} across pages.`)
+  return allIssues
+}
+
+function issueDependenciesMatches(taskDeps: string[], issue: ProjectSyncIssueRecord): boolean {
+  const fromBody = issue.dependenciesFromBody
+  if (fromBody) {
+    return areDependencyListsEqual(fromBody, taskDeps)
+  }
+
+  if (issue.dependenciesFromPayload) {
+    return areDependencyListsEqual(issue.dependenciesFromPayload, taskDeps)
+  }
+
+  return taskDeps.length === 0
+}
+
+function areDependencyListsEqual(left: string[], right: string[]): boolean {
+  const normalize = (value: string[]) => {
+    const uniq = [...new Set(value.map((item) => item.toUpperCase()))].sort()
+    return uniq.join(',')
+  }
+
+  return normalize(left) === normalize(right)
+}
+
+type ProjectSyncIssueRecord = {
+  number: number
+  title: string
+  hash: string
+  rawHash: string | null
+  state: string
+  dependenciesFromPayload: string[] | null
+  dependenciesFromBody: string[] | null
+}
+
+function buildIssueNumberFromPayload(payload: unknown): number | null {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return null
+  }
+
+  const number = Number((payload as { number?: unknown }).number)
+  if (Number.isInteger(number) && number > 0) {
+    return number
+  }
+  return null
+}
+
+function indexExistingTaskIssues(rawBody: unknown, projectName: string): Map<string, ProjectSyncIssueRecord[]> {
+  if (!Array.isArray(rawBody)) {
+    throw new Error(`Expected array from issue.list for ${projectName}`)
+  }
+
+  const byTask = new Map<string, ProjectSyncIssueRecord[]>()
+  for (const issue of rawBody as Array<Record<string, unknown>>) {
+    const parsedIssue = toProjectGitTaskRecord(issue)
+    if (!parsedIssue || !parsedIssue.taskId) {
+      continue
+    }
+
+    const taskId = parsedIssue.taskId
+    const issueHash = parsedIssue.taskSignature
+
+    const existing = byTask.get(taskId) ?? []
+    existing.push({
+      number: parsedIssue.number,
+      title: parsedIssue.title,
+      hash: issueHash ?? '',
+      rawHash: issueHash ?? null,
+      state: parsedIssue.state,
+      dependenciesFromPayload: parsedIssue.taskDependenciesFromPayload.length === 0 ? null : parsedIssue.taskDependenciesFromPayload,
+      dependenciesFromBody: parsedIssue.body ? parsedIssue.taskDependenciesFromBody : null,
+    })
+    byTask.set(taskId, existing)
+  }
+
+  for (const [, existing] of byTask) {
+    existing.sort((left, right) => {
+      const leftOpen = left.state === 'open'
+      const rightOpen = right.state === 'open'
+
+      if (leftOpen && !rightOpen) return -1
+      if (!leftOpen && rightOpen) return 1
+      return 0
+    })
+  }
+
+  return byTask
+}
+
+function hasSyncMatch(existing: ProjectSyncIssueRecord, task: TaskGraphTask): boolean {
+  const expectedHash = computeTaskHash(task)
+  if (!existing.rawHash || existing.rawHash.toLowerCase() !== expectedHash.toLowerCase()) {
+    return false
+  }
+
+  return issueDependenciesMatches(task.deps, existing)
+}
+
+function pickTaskIssueMatch(
+  issues: ProjectSyncIssueRecord[],
+  task: TaskGraphTask
+): { issue: ProjectSyncIssueRecord; isMatch: boolean } | null {
+  const matched = issues.find((issue) => hasSyncMatch(issue, task))
+  if (matched) {
+    return { issue: matched, isMatch: true }
+  }
+
+  if (issues.length === 0) {
+    return null
+  }
+
+  const openIssue = issues.find((issue) => issue.state === 'open')
+  return { issue: openIssue ?? issues[0], isMatch: false }
+}
+
+function pickBestMatchFromTasks(issues: ProjectGitTaskRecord[]): ProjectGitTaskRecord | null {
+  if (issues.length === 0) {
+    return null
+  }
+
+  const openIssue = issues.find((issue) => issue.state === 'open')
+  if (openIssue) {
+    return openIssue
+  }
+
+  return issues.sort((a, b) => a.number - b.number)[0] ?? null
+}
+
+export async function fetchGitTasks(
+  projectName: string,
+  options: Partial<ProjectGitTaskQueryOptions> = {},
+  processRoot: string = process.cwd()
+): Promise<ProjectFetchGitTasksResult> {
+  const { owner, repo } = resolveProjectGitRepository(projectName, processRoot, options)
+  const state: GitTaskIssueState = options.state ?? 'open'
+  const taskOnly = options.taskOnly ?? true
+
+  const git = createGitServiceApi({
+    config: {
+      platform: 'GITEA',
+      giteaHost: resolveGiteaHost(),
+      giteaToken: process.env.GITEA_TOKEN,
+    },
+    defaultOwner: owner,
+    defaultRepo: repo,
+  })
+  const issueList = resolveIssueApiMethod(git, 'list')
+  const issues = await fetchAllIssues(issueList, owner, repo, state, projectName)
+  const tasks = issues
+    .map((issue) => toProjectGitTaskRecord(issue))
+    .filter((issue): issue is ProjectGitTaskRecord => {
+      if (!issue) return false
+      return !taskOnly || Boolean(issue.taskId)
+    })
+
+  return {
+    projectName,
+    owner,
+    repo,
+    state,
+    taskOnly,
+    total: tasks.length,
+    tasks,
+  }
+}
+
+export async function readGitTask(
+  projectName: string,
+  taskRef: string,
+  options: Partial<ProjectGitTaskQueryOptions> = {},
+  processRoot: string = process.cwd()
+): Promise<ProjectReadGitTaskResult> {
+  const parsedRef = parseGitTaskReference(taskRef)
+  const state: GitTaskIssueState = options.state ?? 'all'
+  const { owner, repo } = resolveProjectGitRepository(projectName, processRoot, options)
+
+  const git = createGitServiceApi({
+    config: {
+      platform: 'GITEA',
+      giteaHost: resolveGiteaHost(),
+      giteaToken: process.env.GITEA_TOKEN,
+    },
+    defaultOwner: owner,
+    defaultRepo: repo,
+  })
+
+  if (parsedRef.type === 'number') {
+    const issueView = resolveIssueApiMethod(git, 'view')
+    const result = await issueView(owner, repo, parsedRef.value) as GitServiceApiExecutionResult<GitIssueLike>
+
+    if (!result.ok) {
+      throw new Error(`Failed to read issue #${parsedRef.value} for ${owner}/${repo}: status=${result.status} url=${result.request.url}`)
+    }
+
+    const issue = toProjectGitTaskRecord(result.body)
+    if (!issue) {
+      throw new Error(`Read issue payload invalid for ${owner}/${repo} issue #${parsedRef.value}`)
+    }
+
+    return {
+      projectName,
+      owner,
+      repo,
+      issueNumber: issue.number,
+      issue,
+      foundBy: 'number',
+      searchScope: state,
+    }
+  }
+
+  const issueList = resolveIssueApiMethod(git, 'list')
+  const issues = await fetchAllIssues(issueList, owner, repo, state, projectName)
+  const match = issues
+    .map((issue) => toProjectGitTaskRecord(issue))
+    .find((task) => task?.taskId === parsedRef.value)
+
+  if (!match) {
+    throw new Error(`Task ${parsedRef.value} not found in ${owner}/${repo}`)
+  }
+
+  return {
+    projectName,
+    owner,
+    repo,
+    issueNumber: match.number,
+    issue: match,
+    foundBy: 'taskId',
+    searchScope: state,
+  }
+}
+
+export async function writeGitTask(
+  projectName: string,
+  taskRef: string,
+  options: Partial<ProjectWriteGitTaskOptions> = {},
+  processRoot: string = process.cwd()
+): Promise<ProjectWriteGitTaskResult> {
+  const parsedRef = parseGitTaskReference(taskRef)
+  const { owner, repo } = resolveProjectGitRepository(projectName, processRoot, options)
+  const payload = buildGitTaskPayload(parsedRef, options as ProjectWriteGitTaskOptions)
+
+  if (Object.keys(payload).length === 0) {
+    throw new Error('Nothing to write. Provide at least one writable field (title, body, labels, state, taskDependencies, or taskSignature).')
+  }
+
+  const git = createGitServiceApi({
+    config: {
+      platform: 'GITEA',
+      giteaHost: resolveGiteaHost(),
+      giteaToken: process.env.GITEA_TOKEN,
+    },
+    defaultOwner: owner,
+    defaultRepo: repo,
+  })
+
+  const issueList = resolveIssueApiMethod(git, 'list')
+  const issueEdit = resolveIssueApiMethod(git, 'edit')
+  const issueCreate = resolveIssueApiMethod(git, 'create')
+
+  let issueNumber: number | null = null
+  if (parsedRef.type === 'number') {
+    issueNumber = parsedRef.value
+  } else {
+    const issues = await fetchAllIssues(issueList, owner, repo, 'all', projectName)
+    const matchingIssues = issues
+      .map((issue) => toProjectGitTaskRecord(issue))
+      .filter((task): task is ProjectGitTaskRecord => Boolean(task?.taskId === parsedRef.value))
+    const match = pickBestMatchFromTasks(matchingIssues)
+
+    if (match) {
+      issueNumber = match.number
+    } else if (!options.createIfMissing) {
+      throw new Error(`Task ${parsedRef.value} not found for ${owner}/${repo}. Pass createIfMissing:true to create it.`)
+    }
+  }
+
+  if (!issueNumber) {
+    const createResult = await issueCreate(owner, repo, payload)
+    if (!createResult.ok) {
+      throw new Error(`Failed to create task in ${owner}/${repo}: status=${createResult.status} url=${createResult.request.url}`)
+    }
+
+    const issue = toProjectGitTaskRecord(createResult.body as GitIssueLike)
+    if (!issue) {
+      throw new Error(`Create task response invalid for ${owner}/${repo}`)
+    }
+
+    return {
+      projectName,
+      owner,
+      repo,
+      action: 'created',
+      issueNumber: issue.number,
+      issue,
+    }
+  }
+
+  const updateResult = await issueEdit(owner, repo, issueNumber, payload)
+  if (!updateResult.ok) {
+    throw new Error(`Failed to update issue #${issueNumber} for ${owner}/${repo}: status=${updateResult.status} url=${updateResult.request.url}`)
+  }
+
+  const issue = toProjectGitTaskRecord(updateResult.body as GitIssueLike)
+  if (!issue) {
+    throw new Error(`Update task response invalid for ${owner}/${repo} issue #${issueNumber}`)
+  }
+
+  return {
+    projectName,
+    owner,
+    repo,
+    action: 'updated',
+    issueNumber: issue.number,
+    issue,
+  }
+}
+
+export async function syncTasks(
+  projectName: string,
+  options: Partial<ProjectSyncTaskOptions> = {},
+  processRoot: string = process.cwd()
+): Promise<ProjectSyncTaskResult> {
+  const projectRoot = resolveProjectRoot(projectName, processRoot)
+  const tracksPath = resolveTracksPath(projectRoot, options.tracks)
+  const resolved = options.owner && options.repo
+    ? { owner: options.owner, repo: options.repo }
+    : resolveGitIdentityFromProject(projectRoot)
+
+  const owner = options.owner ?? resolved.owner
+  const repo = options.repo ?? resolved.repo
+  const syncOptions: ProjectSyncTaskOptions = {
+    labels: options.labels ?? [],
+    prefix: options.prefix ?? '[TASK]',
+    dryRun: options.dryRun ?? false,
+    max: options.max,
+    maxBodyLength: options.maxBodyLength,
+    requestTimeoutMs: options.requestTimeoutMs,
+    throttleMs: options.throttleMs,
+    skipDependencies: options.skipDependencies,
+    owner,
+    repo,
+    verbose: options.verbose ?? false,
+  }
+  const log = syncOptions.verbose
+    ? (message: string) => {
+        process.stderr.write(`[f0 projects ${projectName}] ${message}\n`)
+      }
+    : null
+
+  const previousTimeoutEnv = process.env.F0_GIT_REQUEST_TIMEOUT_MS
+  if (syncOptions.requestTimeoutMs) {
+    process.env.F0_GIT_REQUEST_TIMEOUT_MS = String(syncOptions.requestTimeoutMs)
+  }
+
+  log?.(`Resolved project root: ${projectRoot}`)
+  log?.(`Resolved tracks file: ${tracksPath}`)
+  log?.(`Using issue destination: ${owner}/${repo}`)
+  log?.(`HTTP request timeout: ${syncOptions.requestTimeoutMs ?? 'default'}`)
+  log?.(`HTTP throttle: ${syncOptions.throttleMs ?? 0}ms`)
+  log?.(`Dependency sync: ${syncOptions.skipDependencies ? 'skipped' : 'enabled'}`)
+  const markdown = await fs.readFile(tracksPath, 'utf8')
+  log?.(`Loaded tracks content (${markdown.length} chars).`)
+  const graph = parseTaskGraphFromMarkdownForProjects(markdown, (message) => log?.(message))
+  const topo = graph.topo
+  const total = graph.topo.length
+  const ordered = topo.map((taskId) => graph.byId[taskId]).filter((value): value is TaskGraphTask => Boolean(value))
+  const selected = syncOptions.max ? ordered.slice(0, syncOptions.max) : ordered
+  log?.(`Parsed ${total} tasks from tracks. ${selected.length} selected for sync.`)
+  if (selected.length === 0) {
+    log?.('No tasks selected for sync. Nothing to do.')
+  }
+
+  const truncated = syncOptions.max ? total > selected.length : false
+
+  const git = createGitServiceApi({
+    config: {
+      platform: 'GITEA',
+      giteaHost: resolveGiteaHost(),
+      giteaToken: process.env.GITEA_TOKEN,
+    },
+    defaultOwner: owner,
+    defaultRepo: repo,
+    ...(syncOptions.requestTimeoutMs ? { requestTimeoutMs: syncOptions.requestTimeoutMs } : {}),
+    ...(log ? { log: (message: string) => log(message) } : {}),
+  })
+
+  const issueList = resolveIssueApiMethod(git, 'list')
+  const issueCreate = resolveIssueApiMethod(git, 'create')
+  const issueEdit = resolveIssueApiMethod(git, 'edit')
+
+  const allIssues = await fetchAllIssues(issueList, owner, repo, 'all', projectName, log)
+  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}.`)
+  let created = 0
+  let updated = 0
+  let unchanged = 0
+  const issueNumbersByTask = new Map<string, number>()
+  const host = resolveGiteaHost()
+  const token = process.env.GITEA_TOKEN
+  const dependencyStats = {
+    added: 0,
+    removed: 0,
+    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}`
+    const payload = buildIssuePayloadFromTask(task, i, selected.length, syncOptions)
+    const byId = existing.get(task.id)
+    const selection = byId ? pickTaskIssueMatch(byId, task) : null
+    const targetIssue = selection?.issue
+
+    if (selection?.isMatch) {
+      issueNumbersByTask.set(task.id, targetIssue.number)
+      unchanged += 1
+      log?.(`${marker} unchanged`)
+      continue
+    }
+
+    if (selection) {
+      issueNumbersByTask.set(task.id, targetIssue.number)
+      updated += 1
+      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,
+          },
+        }) as GitServiceApiExecutionResult
+
+        if (!updatedResult.ok) {
+          throw new Error(
+            `Failed to update issue ${targetIssue.number} for ${owner}/${repo}: status=${updatedResult.status} url=${updatedResult.request.url}`
+          )
+        }
+
+        if (syncOptions.throttleMs && syncOptions.throttleMs > 0) {
+          await sleep(syncOptions.throttleMs)
+        }
+      }
+      continue
+    }
+
+    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)}`
+        )
+      }
+      issueNumbersByTask.set(task.id, issueNumber)
+
+      log?.(`${marker} created #${issueNumber}`)
+
+      if (syncOptions.throttleMs && syncOptions.throttleMs > 0) {
+        await sleep(syncOptions.throttleMs)
+      }
+    } else {
+      issueNumbersByTask.set(task.id, 0)
+    }
+    created += 1
+  }
+
+  if (syncOptions.skipDependencies) {
+    if (previousTimeoutEnv === undefined) {
+      delete process.env.F0_GIT_REQUEST_TIMEOUT_MS
+    } else {
+      process.env.F0_GIT_REQUEST_TIMEOUT_MS = previousTimeoutEnv
+    }
+
+    return {
+      projectName,
+      tracksPath,
+      owner,
+      repo,
+      totalTasks: total,
+      created,
+      updated,
+      skipped: unchanged,
+      dryRun: syncOptions.dryRun,
+      truncated,
+    }
+  }
+
+  for (let i = 0; i < selected.length; i += 1) {
+    const task = selected[i]
+    const issueNumber = issueNumbersByTask.get(task.id)
+    if (!issueNumber) {
+      log?.(`[${i + 1}/${selected.length}] ${task.id} has no issue number; skipping dependency sync`)
+      continue
+    }
+
+    const missingDependencies = task.deps.filter((dep) => !issueNumbersByTask.has(dep))
+    if (missingDependencies.length > 0) {
+      log?.(`Issue #${issueNumber} (task ${task.id}) skipped dependency(s): ${missingDependencies.join(', ')} not synced/open`)
+    }
+
+    const desiredDependencyIssues = task.deps
+      .map((dep) => issueNumbersByTask.get(dep))
+      .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
+    )
+    dependencyStats.added += syncResult.added
+    dependencyStats.removed += syncResult.removed
+    dependencyStats.unchanged += syncResult.unchanged
+
+    if (syncOptions.throttleMs && syncOptions.throttleMs > 0) {
+      await sleep(syncOptions.throttleMs)
+    }
+  }
+
+  if (dependencyStats.added > 0 || dependencyStats.removed > 0) {
+    log?.(`Dependency sync summary: +${dependencyStats.added} -${dependencyStats.removed}`)
+  }
+
+  if (previousTimeoutEnv === undefined) {
+    delete process.env.F0_GIT_REQUEST_TIMEOUT_MS
+  } else {
+    process.env.F0_GIT_REQUEST_TIMEOUT_MS = previousTimeoutEnv
+  }
+
+  return {
+    projectName,
+    tracksPath,
+    owner,
+    repo,
+    totalTasks: total,
+    created,
+    updated,
+    skipped: unchanged,
+    dryRun: syncOptions.dryRun,
+    truncated,
+  }
+}
+
+export async function clearIssues(
+  projectName: string,
+  options: Partial<ProjectClearIssuesOptions> = {},
+  processRoot: string = process.cwd()
+): Promise<ProjectClearIssuesResult> {
+  const projectRoot = resolveProjectRoot(projectName, processRoot)
+  const resolved = options.owner && options.repo
+    ? { owner: options.owner, repo: options.repo }
+    : resolveGitIdentityFromProject(projectRoot)
+
+  const owner = options.owner ?? resolved.owner
+  const repo = options.repo ?? resolved.repo
+  const clearOptions: ProjectClearIssuesOptions = {
+    state: options.state ?? 'all',
+    dryRun: options.dryRun ?? false,
+    force: options.force ?? false,
+    verbose: options.verbose ?? false,
+    owner,
+    repo,
+  }
+
+  if (!clearOptions.dryRun && !clearOptions.force) {
+    throw new Error('Refusing to delete issues without --force. Re-run with --dry-run for preview.')
+  }
+
+  const log = clearOptions.verbose
+    ? (message: string) => {
+        process.stderr.write(`[f0 projects ${projectName}] ${message}\n`)
+      }
+    : null
+
+  log?.(`Resolved project root: ${projectRoot}`)
+  log?.(`Using issue destination: ${owner}/${repo}`)
+
+  const git = createGitServiceApi({
+    config: {
+      platform: 'GITEA',
+      giteaHost: resolveGiteaHost(),
+      giteaToken: process.env.GITEA_TOKEN,
+    },
+    defaultOwner: owner,
+    defaultRepo: repo,
+  })
+
+  const issueList = resolveIssueApiMethod(git, 'list')
+  const issueDelete = resolveIssueApiMethod(git, 'delete')
+
+  const requestedStates: Array<'open' | 'closed' | 'all'> = clearOptions.state === 'all'
+    ? ['open', 'closed']
+    : [clearOptions.state]
+
+  const issueBatches = await Promise.all(
+    requestedStates.map((state) => fetchAllIssues(issueList, owner, repo, state, projectName, log))
+  )
+  const issueByNumber = new Map<number, GitIssueLike>()
+
+  for (const batch of issueBatches) {
+    for (const issue of batch) {
+      const number = Number((issue as Record<string, unknown>).number)
+      if (!Number.isFinite(number) || number <= 0) {
+        continue
+      }
+      issueByNumber.set(number, issue)
+    }
+  }
+
+  const issues = Array.from(issueByNumber.values())
+  log?.(`Found ${issues.length} issues to process.`)
+
+  let deleted = 0
+  for (const issue of issues) {
+    const issueNumber = Number((issue as Record<string, unknown>).number)
+    if (!Number.isFinite(issueNumber) || issueNumber <= 0) {
+      continue
+    }
+
+    log?.(`Deleting #${issueNumber}`)
+    if (clearOptions.dryRun) {
+      continue
+    }
+
+    const deleteResult = await issueDelete(owner, repo, issueNumber, { yes: true }) as GitServiceApiExecutionResult
+    if (!deleteResult.ok) {
+      throw new Error(
+        `Failed to delete issue ${issueNumber} for ${owner}/${repo}: status=${deleteResult.status} url=${deleteResult.request.url}`
+      )
+    }
+
+    deleted += 1
+  }
+
+  return {
+    projectName,
+    owner,
+    repo,
+    state: clearOptions.state,
+    total: issues.length,
+    deleted,
+    dryRun: clearOptions.dryRun,
+  }
+}
+
+export async function main(argv: string[], processRoot: string = process.cwd()): Promise<string> {
+  if (
+    argv.length === 0 ||
+    argv.includes('--help') ||
+    argv.includes('-h')
+  ) {
+    return usage()
+  }
+
+  const [scope, maybeProject, maybeTarget, ...rest] = argv
+  const listMode = scope === 'projects' && maybeProject === '--list'
+
+  if (scope !== 'projects') {
+    throw new Error('Expected command `projects` as first positional argument.')
+  }
+
+  if (listMode) {
+    const unknownFlags = rest.filter(Boolean)
+    if (unknownFlags.length > 0) {
+      throw new Error(`Unknown flags: ${unknownFlags.join(', ')}`)
+    }
+    return listProjects(processRoot).join('\n')
+  }
+
+  const projectName = maybeProject
+  if (!projectName) {
+    throw new Error('Missing required arguments: <project-name>.')
+  }
+
+  if (maybeTarget === 'sync-tasks') {
+    const parsedSync = parseSyncTasksArgs(rest)
+    if (parsedSync.unknownFlags.length > 0) {
+      throw new Error(`Unknown flags: ${parsedSync.unknownFlags.join(', ')}`)
+    }
+
+    const result = await syncTasks(projectName, { ...parsedSync.options, tracks: parsedSync.tracks }, processRoot)
+    const dryRun = result.dryRun ? ' [dry-run]' : ''
+    const truncated = result.truncated ? ' (truncated)' : ''
+    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') {
+    const parsedClear = parseClearIssuesArgs(rest)
+    if (parsedClear.unknownFlags.length > 0) {
+      throw new Error(`Unknown flags: ${parsedClear.unknownFlags.join(', ')}`)
+    }
+
+    const result = await clearIssues(projectName, parsedClear.options, processRoot)
+    const dryRun = result.dryRun ? ' [dry-run]' : ''
+    return `${CLI_NAME}: clear-issues for ${result.projectName}${dryRun} (${result.owner}/${result.repo}, state=${result.state}) total=${result.total}, deleted=${result.deleted}`
+  }
+
+  const parsed = parseGenerateArgs(maybeTarget ? [maybeTarget, ...rest] : rest)
+  if (parsed.command === 'list') {
+    throw new Error('`--list` can only be used without a project name.')
+  }
+
+  if (parsed.setActive) {
+    if (parsed.requestedGenerateSpec) {
+      throw new Error('`--set-active` cannot be combined with `--generate-spec`.')
+    }
+
+    if (parsed.target === undefined) {
+      throw new Error('Missing required arguments: <project-name> and <file-path>.')
+    }
+    if (parsed.unknownFlags.length > 0) {
+      throw new Error(`Unknown flags: ${parsed.unknownFlags.join(', ')}`)
+    }
+    const optionFlags = Object.keys(parsed.options)
+    if (optionFlags.length > 0) {
+      throw new Error(`Unknown flags: --${optionFlags.join(', --')}`)
+    }
+
+    const result = setActive(projectName, parsed.target, processRoot, { latest: parsed.latest })
+    const matchedFileName = path.basename(result.sourceFile).toLowerCase()
+    const isImplementationPlan = /^implementation[-_]?plan(?:\.[^.]+)*$/i.test(matchedFileName)
+    if (!isImplementationPlan) {
+      return `[${CLI_NAME}] set active: ${result.matchedFile} -> ${path.basename(result.activeFile)} (${result.mode})`
+    }
+
+    const generated = await generateSpec(projectName, { input: result.sourceFile }, processRoot)
+    const dryRun = generated.dryRun ? ' [dry-run]' : ''
+    return `[${CLI_NAME}] set active: ${result.matchedFile} -> ${path.basename(result.activeFile)} (${result.mode})` +
+      `\n${CLI_NAME}: generated ${generated.files} spec files for ${generated.projectName}${dryRun} from ${path.relative(processRoot, generated.inputPath)}`
+  }
+
+  if (!parsed.requestedGenerateSpec) {
+    throw new Error('`--generate-spec` is required.')
+  }
+  if (parsed.target !== undefined) {
+    throw new Error(`Unknown argument: ${parsed.target}`)
+  }
+
+  if (parsed.unknownFlags.length > 0) {
+    throw new Error(`Unknown flags: ${parsed.unknownFlags.join(', ')}`)
+  }
+
+  const result = await generateSpec(projectName, parsed.options, processRoot)
+  const dryRun = result.dryRun ? ' [dry-run]' : ''
+
+  return `${CLI_NAME}: generated ${result.files} spec files for ${result.projectName}${dryRun} from ${path.relative(processRoot, result.inputPath)}`
+}
+
+export function parseProjectTargetSpec(spec: string): ProjectVersionedFileSpec {
+  if (!spec || typeof spec !== 'string') {
+    throw new Error('file-path is required.')
+  }
+
+  const normalized = spec.replace(/\\/g, '/').trim()
+  if (!normalized.startsWith('/')) {
+    throw new Error('file-path must start with a leading slash, e.g. /implementation-plan.v0.0.1')
+  }
+
+  const body = normalized.slice(1).replace(/^docs\//, '')
+  if (!body) {
+    throw new Error('file-path is empty.')
+  }
+
+  const parts = body.split('/').filter(Boolean)
+  if (parts.length === 0) {
+    throw new Error('file-path must include a file name, for example /implementation-plan.v0.0.1')
+  }
+
+  const file = parts.pop()
+  if (!file) {
+    throw new Error('file-path must include a file name, for example /implementation-plan.v0.0.1')
+  }
+
+  const withExt = file.match(new RegExp(`^(.+)\\.(${VERSION_RE})\\.([A-Za-z][A-Za-z0-9_-]*)$`))
+  const withoutExt = file.match(new RegExp(`^(.+)\\.(${VERSION_RE})$`))
+  if (withExt) {
+    return {
+      parts,
+      base: withExt[1],
+      version: withExt[2],
+      ext: withExt[3],
+    }
+  }
+  if (withoutExt) {
+    return {
+      parts,
+      base: withoutExt[1],
+      version: withoutExt[2],
+      ext: null,
+    }
+  }
+
+  return {
+    parts,
+    base: file,
+    version: null,
+    ext: null,
+  }
+}
+
+function parseVersion(version: string): number[] {
+  const clean = version.replace(/^v/, '')
+  return clean.split('.').filter(Boolean).map((part) => Number.parseInt(part, 10))
+}
+
+function compareVersions(left: string, right: string): number {
+  const a = parseVersion(left)
+  const b = parseVersion(right)
+  const size = Math.max(a.length, b.length)
+
+  for (let i = 0; i < size; i += 1) {
+    const leftValue = a[i] ?? 0
+    const rightValue = b[i] ?? 0
+    if (leftValue > rightValue) return 1
+    if (leftValue < rightValue) return -1
+  }
+
+  return 0
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+function findLatestVersionedFile(targetDir: string, base: string, ext: string | null): string | null {
+  const fileEntries = fsSync
+    .readdirSync(targetDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name)
+
+  const safeBase = escapeRegExp(base)
+  const regex = new RegExp(`^${safeBase}\\.(${VERSION_RE_CORE})\\.([^.]+)$`)
+  const matches = fileEntries
+    .map((entry) => {
+      const match = entry.match(regex)
+      if (!match) return null
+
+      const version = match[1]
+      const detectedExt = `.${match[2]}`
+      if (ext && detectedExt !== `.${ext}`) {
+        return null
+      }
+
+      return { entry, version, detectedExt }
+    })
+    .filter((value): value is { entry: string; version: string; detectedExt: string } => value !== null)
+
+  if (matches.length === 0) return null
+
+  matches.sort((a, b) => compareVersions(a.version, b.version))
+  const latestVersion = matches[matches.length - 1].version
+  const sameVersion = matches
+    .filter((item) => compareVersions(item.version, latestVersion) === 0)
+    .map((item) => item.entry)
+    .sort()
+
+  if (sameVersion.length <= 1) {
+    return sameVersion[0]
+  }
+
+  for (const extName of ACTIVE_EXT_PRIORITY) {
+    const preferred = sameVersion.find((entryName) => entryName.endsWith(extName))
+    if (preferred) {
+      return preferred
+    }
+  }
+
+  return sameVersion.sort()[0]
+}
+
+export function resolveProjectTargetFile(
+  targetDir: string,
+  spec: ProjectVersionedFileSpec,
+  options: { latest?: boolean } = {}
+): string | null {
+  const entries = fsSync
+    .readdirSync(targetDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name)
+
+  if (!spec.version) {
+    if (!options.latest) {
+      return null
+    }
+    return findLatestVersionedFile(targetDir, spec.base, null)
+  }
+
+  if (spec.ext) {
+    const exact = `${spec.base}.${spec.version}.${spec.ext}`
+    if (entries.includes(exact)) {
+      return exact
+    }
+    return null
+  }
+
+  const prefix = `${spec.base}.${spec.version}.`
+  const candidates = entries.filter((entry) => entry.startsWith(prefix))
+  if (candidates.length === 0) {
+    return null
+  }
+
+  for (const ext of ACTIVE_EXT_PRIORITY) {
+    const matched = candidates.find((entry) => entry.endsWith(ext))
+    if (matched) {
+      return matched
+    }
+  }
+
+  return candidates.sort()[0]
+}
+
+export function setActive(
+  projectName: string,
+  target: string,
+  processRoot: string = process.cwd(),
+  options: { latest?: boolean } = {}
+): ProjectSetActiveResult {
+  const projectRoot = resolveProjectRoot(projectName, processRoot)
+  const docsRoot = path.join(projectRoot, 'docs')
+  const spec = parseProjectTargetSpec(target)
+  const targetDir = path.join(docsRoot, ...spec.parts)
+  if (!existsDir(docsRoot)) {
+    throw new Error(`Docs directory not found for project: ${projectRoot}`)
+  }
+
+  if (!existsDir(targetDir)) {
+    throw new Error(`Target folder not found: ${targetDir}`)
+  }
+
+  const matchedFile = resolveProjectTargetFile(targetDir, spec, options)
+  if (!matchedFile && !spec.version && options.latest) {
+    throw new Error(`No files found for /${spec.parts.join('/')}/${spec.base}`)
+  }
+  if (!matchedFile) {
+    if (!spec.version && !options.latest) {
+      throw new Error(
+        `Version missing for /${spec.parts.join('/')}/${spec.base}. Use --latest to select the latest version.`
+      )
+    }
+    const extensionHint = spec.ext ? `.${spec.ext}` : ' with any extension'
+    throw new Error(
+      `Versioned file not found for /${spec.parts.join('/')}/${spec.base}.${spec.version}${extensionHint}`
+    )
+  }
+
+  const sourceFile = path.join(targetDir, matchedFile)
+  const activeFile = path.join(targetDir, `${spec.base}.active${path.extname(matchedFile)}`)
+  const mode = setActiveLink(sourceFile, activeFile)
+
+  return {
+    projectName,
+    sourceFile,
+    activeFile,
+    matchedFile,
+    mode,
+  }
+}
+
+function parseMonolith(monolith: string): MonolithFile[] {
+  const hasBeginMarker = /BEGIN(?:\s|_)FILE:/.test(monolith)
+  const hasEndMarker = /END(?:\s|_)FILE:/.test(monolith)
+  if (!hasBeginMarker || !hasEndMarker) {
+    throw new Error(
+      'Monolith does not appear to contain BEGIN/END markers (expected BEGIN FILE/END FILE or BEGIN_FILE/END_FILE).'
+    )
+  }
+
+  const re =
+    /<!--\s*BEGIN(?:\s|_)FILE:\s*(.+?)\s*-->\s*\r?\n([\s\S]*?)\r?\n<!--\s*END(?:\s|_)FILE:\s*\1\s*-->/g
+
+  const entries: MonolithFile[] = []
+  const seen = new Set<string>()
+
+  let match: RegExpExecArray | null
+  while ((match = re.exec(monolith)) !== null) {
+    const relPath = normalizeRelPath(match[1])
+
+    if (seen.has(relPath)) {
+      throw new Error(`Duplicate file path in monolith: ${relPath}`)
+    }
+
+    const raw = match[2]
+    const content = raw.endsWith('\n') ? raw : `${raw}\n`
+    const bytes = Buffer.byteLength(content, 'utf8')
+    const sha256 = sha256Hex(content)
+
+    entries.push({
+      relPath,
+      content,
+      sha256,
+      bytes,
+      meta: extractTopMetadataBlock(content),
+    })
+
+    seen.add(relPath)
+  }
+
+  if (entries.length === 0) {
+    throw new Error('No files found. Expected matching BEGIN/END FILE markers in monolith.')
+  }
+
+  return entries
+}
+
+function normalizeRelPath(relPath: string): string {
+  const p = relPath.trim()
+  if (p.length === 0) {
+    throw new Error('Empty path in BEGIN FILE marker')
+  }
+  if (path.isAbsolute(p)) {
+    throw new Error(`Absolute paths are not allowed: ${p}`)
+  }
+
+  const normalized = p.replace(/\\/g, '/')
+  const parts = normalized.split('/')
+  for (const part of parts) {
+    if (part === '..') {
+      throw new Error(`Path traversal is not allowed: ${p}`)
+    }
+    if (part === '') {
+      throw new Error(`Empty path segment is not allowed: ${p}`)
+    }
+  }
+
+  return normalized
+}
+
+function extractTopMetadataBlock(content: string): MonolithFile['meta'] {
+  const match = content.match(/^\s*<!--\s*\n([\s\S]*?)\n-->\s*\n/m)
+  if (!match) return undefined
+
+  const lines = match[1]
+  const meta: NonNullable<MonolithFile['meta']> = {}
+
+  for (const line of lines.split(/\r?\n/)) {
+    const parsed = line.match(/^\s*([a-zA-Z0-9_]+)\s*:\s*(.*?)\s*$/)
+    if (!parsed) continue
+
+    const key = parsed[1]
+    const value = parsed[2]
+    if (key === 'spec_id') meta.spec_id = value
+    if (key === 'title') meta.title = value
+    if (key === 'source') meta.source = value
+    if (key === 'source_version') meta.source_version = value
+    if (key === 'source_anchor') meta.source_anchor = value
+  }
+
+  return Object.keys(meta).length === 0 ? undefined : meta
+}
+
+async function readTextIfExists(filePath: string): Promise<string | null> {
+  try {
+    return await fs.readFile(filePath, 'utf8')
+  } catch (error: any) {
+    if (error?.code === 'ENOENT') {
+      return null
+    }
+    throw error
+  }
+}
+
+async function writeIfChanged(filePath: string, content: string): Promise<'created' | 'updated' | 'unchanged'> {
+  const existing = await readTextIfExists(filePath)
+  if (existing === null) {
+    await fs.writeFile(filePath, content, 'utf8')
+    return 'created'
+  }
+
+  if (existing === content) return 'unchanged'
+  await fs.writeFile(filePath, content, 'utf8')
+  return 'updated'
+}
+
+async function loadPreviousManifest(manifestAbs: string): Promise<{ files: Array<{ path: string }> } | null> {
+  const manifestRaw = await readTextIfExists(manifestAbs)
+  if (!manifestRaw) return null
+
+  try {
+    const parsed = JSON.parse(manifestRaw)
+    if (!parsed || typeof parsed !== 'object') return null
+    if (!Array.isArray((parsed as any).files)) return null
+    return parsed as { files: Array<{ path: string }> }
+  } catch {
+    return null
+  }
+}
+
+function sha256Hex(value: string): string {
+  return crypto.createHash('sha256').update(value, 'utf8').digest('hex')
+}
+
+function assertWithinOutRoot(outRoot: string, candidate: string): void {
+  const rel = path.relative(path.resolve(outRoot), path.resolve(candidate))
+  if (rel === '' || (!rel.startsWith(`..${path.sep}`) && rel !== '..')) {
+    return
+  }
+  throw new Error(`Refusing to write outside project root. outRoot=${outRoot} candidate=${candidate}`)
+}
+
+function isSubPath(parent: string, child: string): boolean {
+  const resolvedParent = path.resolve(parent)
+  const resolvedChild = path.resolve(child)
+
+  const parentRoot = path.parse(resolvedParent).root.toLowerCase()
+  const childRoot = path.parse(resolvedChild).root.toLowerCase()
+  if (parentRoot !== childRoot) {
+    return false
+  }
+
+  const relative = path.relative(path.resolve(parent), path.resolve(child))
+  if (relative === '' || relative === '.') {
+    return true
+  }
+  return !relative.startsWith(`..${path.sep}`) && relative !== '..'
+}
+
+function existsDir(input: string): boolean {
+  try {
+    return fsSync.statSync(input).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+function existsFile(input: string): boolean {
+  try {
+    return fsSync.statSync(input).isFile()
+  } catch {
+    return false
+  }
+}