agentic-dev 0.2.22 → 0.2.24

package/dist/lib/orchestration-assets.js

@@ -21,6 +21,7 @@ on:
   push:
     paths:
       - "sdd/02_plan/**"
+      - "sdd/99_toolchain/01_automation/github-project-kit/**"
       - ".agentic-dev/orchestration.json"
       - ".agentic-dev/runtime/**"
   workflow_dispatch:
@@ -31,6 +32,7 @@ jobs:
     permissions:
       contents: read
       issues: write
+      pull-requests: write
       repository-projects: write
     steps:
       - name: Checkout
@@ -41,9 +43,25 @@ jobs:
         with:
           node-version: "22"
 
-      - name: Start orchestration server
+      - name: Resolve orchestration GitHub auth
         env:
-          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+          AGENTIC_GITHUB_TOKEN_SECRET: \${{ secrets.AGENTIC_GITHUB_TOKEN }}
+          FALLBACK_GITHUB_TOKEN: \${{ github.token }}
+        run: |
+          TOKEN="$AGENTIC_GITHUB_TOKEN_SECRET"
+          if [ -z "$TOKEN" ]; then
+            TOKEN="$FALLBACK_GITHUB_TOKEN"
+          fi
+          if [ -z "$TOKEN" ]; then
+            echo "No GitHub token available for orchestration" >&2
+            exit 1
+          fi
+          echo "::add-mask::$TOKEN"
+          echo "AGENTIC_GITHUB_TOKEN=$TOKEN" >> "$GITHUB_ENV"
+          echo "GH_TOKEN=$TOKEN" >> "$GITHUB_ENV"
+          echo "GITHUB_TOKEN=$TOKEN" >> "$GITHUB_ENV"
+
+      - name: Start orchestration server
         run: |
           npx --yes tsx .agentic-dev/runtime/server.ts > /tmp/agentic-orchestration.log 2>&1 &
           echo $! > /tmp/agentic-orchestration.pid
@@ -60,29 +78,20 @@ jobs:
         run: curl -fsS -X POST http://127.0.0.1:4310/sync/ir
 
       - name: Sync GitHub project tasks
-        env:
-          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
         run: curl -fsS -X POST http://127.0.0.1:4310/sync/tasks
 
       - name: Plan multi-agent queue
-        env:
-          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
         run: curl -fsS -X POST http://127.0.0.1:4310/queue/plan
 
       - name: Build dispatch plan
-        env:
-          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
         run: curl -fsS -X POST http://127.0.0.1:4310/queue/dispatch
 
       - name: Execute dispatch queue
         env:
-          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
           AGENTIC_AGENT_TIMEOUT_MS: "30000"
         run: curl -fsS -X POST http://127.0.0.1:4310/queue/execute
 
       - name: Close completed tasks
-        env:
-          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
         run: curl -fsS -X POST http://127.0.0.1:4310/tasks/close
 
       - name: Stop orchestration server
@@ -125,12 +134,97 @@ export function orchestrationConfig() {
   return readJson(path.resolve(".agentic-dev/orchestration.json"), {});
 }
 
+export function githubAuthEnv() {
+  const env = { ...process.env };
+  const token = String(env.AGENTIC_GITHUB_TOKEN || env.GH_TOKEN || env.GITHUB_TOKEN || "").trim();
+  if (token) {
+    env.AGENTIC_GITHUB_TOKEN = env.AGENTIC_GITHUB_TOKEN || token;
+    env.GH_TOKEN = token;
+    env.GITHUB_TOKEN = token;
+  }
+  return env;
+}
+
+export function projectContractPath() {
+  return path.resolve("sdd/99_toolchain/01_automation/github-project-kit/project-contract.json");
+}
+
+export function roleMapPath() {
+  return path.resolve("sdd/99_toolchain/01_automation/github-project-kit/role-map.json");
+}
+
+export function loadProjectContract() {
+  return readJson(projectContractPath(), null);
+}
+
+export function loadRoleMap() {
+  return readJson(roleMapPath(), { roles: [] });
+}
+
+export function artifactContractPath() {
+  return path.resolve("sdd/99_toolchain/01_automation/github-project-kit/artifact-contract.json");
+}
+
+export function loadArtifactContract() {
+  return readJson(artifactContractPath(), null);
+}
+
+export function taskCatalogPath() {
+  const contract = loadArtifactContract();
+  return path.resolve(
+    String(contract?.outputs?.task_catalog || "sdd/99_toolchain/01_automation/github-project-kit/task-catalog.json"),
+  );
+}
+
+export function taskSyncStatePath() {
+  const contract = loadArtifactContract();
+  return path.resolve(
+    String(contract?.outputs?.task_sync_state || "sdd/99_toolchain/01_automation/github-project-kit/task-sync-state.json"),
+  );
+}
+
+export function loadTaskCatalog() {
+  return readJson(taskCatalogPath(), { tasks: [] });
+}
+
+export function loadTaskSyncState() {
+  return readJson(taskSyncStatePath(), { issues: {} });
+}
+
+export function hasProjectContract() {
+  const contract = loadProjectContract();
+  return Boolean(contract && contract.project_id && contract.project_number && contract.repository);
+}
+
+export function hasArtifactBacklogKit() {
+  return Boolean(
+    hasProjectContract() &&
+      fs.existsSync(artifactContractPath()) &&
+      fs.existsSync(path.resolve("scripts/agentic-core/artifact_backlog.py")),
+  );
+}
+
+export function runArtifactBacklog() {
+  const output = execFileSync("python3", ["scripts/agentic-core/artifact_backlog.py", "run", "--repo-root", "."], {
+    encoding: "utf-8",
+    env: githubAuthEnv(),
+  }).trim();
+  return output ? JSON.parse(output) : {};
+}
+
 export function ghJson(args) {
-  return JSON.parse(execFileSync("gh", args, { encoding: "utf-8" }));
+  const output = execFileSync("gh", args, {
+    encoding: "utf-8",
+    env: githubAuthEnv(),
+  }).trim();
+  return output ? JSON.parse(output) : {};
 }
 
 export function gh(args) {
-  return execFileSync("gh", args, { encoding: "utf-8" }).trim();
+  return execFileSync("gh", args, {
+    encoding: "utf-8",
+    env: githubAuthEnv(),
+  }).trim();
 }
 
 export function loadTaskIr() {
@@ -153,6 +247,30 @@ export function loadExecutionJournal() {
   return readJson(generatedPath("execution-journal.json"), { executions: [] });
 }
 
+export function issueUrl(repository, issueNumber) {
+  return "https://github.com/" + String(repository || "") + "/issues/" + String(issueNumber || "");
+}
+
+export function issueNumberFromUrl(url) {
+  const match = String(url || "").match(/\\/issues\\/(\\d+)$/);
+  return match ? Number(match[1]) : null;
+}
+
+export function normalizeTaskStatus(status) {
+  return String(status || "").trim().toLowerCase() === "closed" ? "closed" : "open";
+}
+
+export function classifyAgent(title) {
+  const lower = String(title || "").toLowerCase();
+  if (lower.includes("api") || lower.includes("contract")) return "api";
+  if (lower.includes("screen") || lower.includes("ui")) return "ui";
+  if (lower.includes("verify") || lower.includes("test") || lower.includes("proof")) return "quality";
+  if (lower.includes("workflow") || lower.includes("project") || lower.includes("github")) return "gitops";
+  if (lower.includes("arch") || lower.includes("boundary") || lower.includes("structure")) return "architecture";
+  if (lower.includes("plan") || lower.includes("spec")) return "specs";
+  return "runtime";
+}
+
 export function normalizeProviderProfile(profile) {
   const normalized = String(profile || "").trim().toLowerCase();
   switch (normalized) {
@@ -174,6 +292,217 @@ export function normalizeProviderProfile(profile) {
       return normalized;
   }
 }
+
+export function pickProvider(title, providers) {
+  const normalizedProviders = (Array.isArray(providers) ? providers : []).map(normalizeProviderProfile);
+  const lower = String(title || "").toLowerCase();
+  if (lower.includes("verify") || lower.includes("test")) {
+    return (
+      normalizedProviders.find((provider) => provider === "claude-cli" || provider === "anthropic-api") ||
+      normalizedProviders[0] ||
+      "claude-cli"
+    );
+  }
+  if (lower.includes("api") || lower.includes("contract")) {
+    return (
+      normalizedProviders.find((provider) => provider === "openai-api" || provider === "anthropic-api") ||
+      normalizedProviders[0] ||
+      "openai-api"
+    );
+  }
+  return (
+    normalizedProviders.find((provider) => provider === "codex-cli" || provider === "openai-api") ||
+    normalizedProviders[0] ||
+    "codex-cli"
+  );
+}
+
+export function roleEntry(roleMap, roleId) {
+  const roles = Array.isArray(roleMap?.roles) ? roleMap.roles : [];
+  return roles.find((entry) => String(entry?.id || "") === String(roleId || "")) || null;
+}
+
+export function resolveAgentRole(roleMap, preferredRole) {
+  const normalized = String(preferredRole || "").trim() || "runtime";
+  if (roleEntry(roleMap, normalized)) return normalized;
+  if (roleEntry(roleMap, "runtime")) return "runtime";
+  return normalized;
+}
+
+export function taskIssueMarker(taskId) {
+  return "<!-- agentic-task-key: " + String(taskId || "") + " -->";
+}
+
+export function taskIssueTitle(task) {
+  return "[agentic-task] " + String(task?.id || "") + " " + String(task?.title || "");
+}
+
+export function taskIssueBody(task, assignedAgent) {
+  return [
+    taskIssueMarker(task.id),
+    "<!-- agentic-task-meta " +
+      JSON.stringify({
+        id: String(task?.id || ""),
+        title: String(task?.title || ""),
+        source: String(task?.source || ""),
+        status: normalizeTaskStatus(task?.status),
+        agent_role: String(assignedAgent || "") || null,
+      }) +
+      " -->",
+    "agent_role: " + String(assignedAgent || ""),
+    "SDD source: " + String(task?.source || ""),
+    "",
+    "Managed by agentic-dev orchestration.",
+  ].join("\\n");
+}
+
+export function findIssueForTask(issues, taskId) {
+  return (
+    (Array.isArray(issues) ? issues : []).find((issue) => {
+      const body = String(issue?.body || "");
+      const title = String(issue?.title || "");
+      return body.includes(taskIssueMarker(taskId)) || title.startsWith("[agentic-task] " + taskId + " ");
+    }) || null
+  );
+}
+
+export function projectContractAvailable(contract) {
+  return Boolean(
+    contract &&
+      contract.project_id &&
+      contract.project_number &&
+      contract.owner &&
+      contract.repository,
+  );
+}
+
+export function projectItemIndex(contract) {
+  if (!projectContractAvailable(contract)) {
+    return new Map();
+  }
+  const payload = ghJson([
+    "project",
+    "item-list",
+    String(contract.project_number),
+    "--owner",
+    String(contract.owner),
+    "--limit",
+    "200",
+    "--format",
+    "json",
+  ]);
+  const index = new Map();
+  for (const item of Array.isArray(payload?.items) ? payload.items : []) {
+    const content = item?.content || {};
+    if (content.type === "Issue" && typeof content.number === "number") {
+      index.set(content.number, item);
+    }
+  }
+  return index;
+}
+
+export function ensureProjectItem(contract, issueNumber, itemIndex) {
+  if (!projectContractAvailable(contract)) {
+    return null;
+  }
+  const existing = itemIndex?.get(issueNumber);
+  if (existing) {
+    return existing;
+  }
+  const payload = ghJson([
+    "project",
+    "item-add",
+    String(contract.project_number),
+    "--owner",
+    String(contract.owner),
+    "--url",
+    issueUrl(contract.repository, issueNumber),
+    "--format",
+    "json",
+  ]);
+  if (!payload?.id) {
+    throw new Error("unable to add project item for issue #" + String(issueNumber));
+  }
+  const added = {
+    id: String(payload.id),
+    content: {
+      type: String(payload.type || "Issue"),
+      number: Number(issueNumber),
+    },
+  };
+  if (itemIndex) {
+    itemIndex.set(Number(issueNumber), added);
+  }
+  return added;
+}
+
+export function setProjectStatus(contract, itemId, statusKey) {
+  const fieldId = String(contract?.fields?.status?.id || "");
+  const optionId = String(contract?.fields?.status?.options?.[statusKey] || "");
+  const projectId = String(contract?.project_id || "");
+  if (!itemId || !fieldId || !optionId || !projectId) {
+    return false;
+  }
+  gh([
+    "project",
+    "item-edit",
+    "--id",
+    String(itemId),
+    "--project-id",
+    projectId,
+    "--field-id",
+    fieldId,
+    "--single-select-option-id",
+    optionId,
+  ]);
+  return true;
+}
+
+export function setProjectText(contract, itemId, fieldId, text) {
+  const projectId = String(contract?.project_id || "");
+  if (!itemId || !fieldId || !projectId) {
+    return false;
+  }
+  gh([
+    "project",
+    "item-edit",
+    "--id",
+    String(itemId),
+    "--project-id",
+    projectId,
+    "--field-id",
+    String(fieldId),
+    "--text",
+    String(text || ""),
+  ]);
+  return true;
+}
+
+export function setProjectAgentRole(contract, itemId, agentRole) {
+  return setProjectText(contract, itemId, String(contract?.fields?.agent_role?.id || ""), String(agentRole || ""));
+}
+
+export function buildProjectLogComment(contract, payload = {}) {
+  const lines = [String(contract?.structured_comment_prefix || "<!-- agentic-project-log -->")];
+  if (payload.agent_role) lines.push("agent_role: " + String(payload.agent_role));
+  if (payload.status) lines.push("status: " + String(payload.status));
+  if (payload.branch) lines.push("branch: " + String(payload.branch));
+  if (payload.summary) lines.push("summary: " + String(payload.summary));
+  if (payload.next) lines.push("next: " + String(payload.next));
+  return lines.join("\\n");
+}
+
+export function parseTaskMeta(body) {
+  const match = String(body || "").match(/<!-- agentic-task-meta\\s*([\\s\\S]*?)\\s*-->/);
+  if (!match) {
+    return {};
+  }
+  try {
+    return JSON.parse(match[1]);
+  } catch {
+    return {};
+  }
+}
 `;
 }
 function sddToIrScript() {
@@ -182,13 +511,30 @@ import fs from "node:fs";
 import path from "node:path";
 import { generatedPath, writeJson } from "./runtime-lib.ts";
 
+const IGNORED_FILE_NAMES = new Set(["README.md", "INDEX.md"]);
+const IGNORED_DIRECTORY_NAMES = new Set(["templates", "99_generated"]);
+
+function shouldIncludeFile(file) {
+  const baseName = path.basename(file);
+  if (IGNORED_FILE_NAMES.has(baseName) || baseName.startsWith("_")) {
+    return false;
+  }
+  const relativePath = path.relative(planRoot, file);
+  const segments = relativePath.split(path.sep).filter(Boolean);
+  return !segments.some((segment) => IGNORED_DIRECTORY_NAMES.has(segment));
+}
+
 function walk(root) {
   if (!fs.existsSync(root)) return [];
   const files = [];
   for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
     const full = path.join(root, entry.name);
-    if (entry.isDirectory()) files.push(...walk(full));
-    else if (entry.name.endsWith(".md")) files.push(full);
+    if (entry.isDirectory()) {
+      if (IGNORED_DIRECTORY_NAMES.has(entry.name)) continue;
+      files.push(...walk(full));
+    } else if (entry.name.endsWith(".md") && shouldIncludeFile(full)) {
+      files.push(full);
+    }
   }
   return files;
 }
@@ -220,120 +566,323 @@ console.log(\`tasks=\${tasks.length}\`);
 }
 function syncProjectTasksScript() {
     return `#!/usr/bin/env node
-import { gh, ghJson, loadTaskIr, orchestrationConfig, writeJson, generatedPath } from "./runtime-lib.ts";
+import {
+  artifactContractPath,
+  ensureProjectItem,
+  findIssueForTask,
+  generatedPath,
+  gh,
+  ghJson,
+  hasArtifactBacklogKit,
+  issueNumberFromUrl,
+  issueUrl,
+  loadArtifactContract,
+  loadProjectContract,
+  loadRoleMap,
+  loadTaskCatalog,
+  loadTaskSyncState,
+  loadTaskIr,
+  normalizeTaskStatus,
+  orchestrationConfig,
+  parseTaskMeta,
+  projectContractAvailable,
+  projectContractPath,
+  projectItemIndex,
+  resolveAgentRole,
+  roleMapPath,
+  runArtifactBacklog,
+  setProjectAgentRole,
+  setProjectStatus,
+  taskIssueBody,
+  taskIssueTitle,
+  classifyAgent,
+  writeJson,
+} from "./runtime-lib.ts";
 
 const orchestration = orchestrationConfig();
+const repository = orchestration?.github?.repository?.slug;
+if (!repository) {
+  throw new Error("github repository slug is not configured in .agentic-dev/orchestration.json");
+}
+
 const taskIr = loadTaskIr();
-const existingIssues = ghJson([
-  "issue",
-  "list",
-  "--repo",
-  orchestration.github.repository.slug,
-  "--state",
-  "all",
-  "--limit",
-  "200",
-  "--json",
-  "number,title,state",
-]);
-const syncResult = { created: [], closed: [], tasks: [] };
+const artifactContract = loadArtifactContract();
+const projectContract = loadProjectContract();
+const roleMap = loadRoleMap();
+function loadIssues() {
+  const payload = ghJson([
+    "issue",
+    "list",
+    "--repo",
+    repository,
+    "--state",
+    "all",
+    "--limit",
+    "200",
+    "--json",
+    "number,title,state,body,url",
+  ]);
+  return Array.isArray(payload) ? payload : [];
+}
 
-for (const task of taskIr.tasks) {
-  const issueTitle = \`[agentic-task] \${task.id} \${task.title}\`;
-  const found = existingIssues.find((issue) =>
-    issue.title.startsWith(\`[agentic-task] \${task.id} \`),
-  );
-  if (!found && task.status === "open") {
-    const url = gh([
-      "issue",
-      "create",
-      "--repo",
-      orchestration.github.repository.slug,
-      "--title",
-      issueTitle,
-      "--body",
-      \`SDD source: \${task.source}\\n\\nManaged by agentic-dev orchestration.\`,
-    ]);
-    syncResult.created.push({ id: task.id, title: task.title, issue_url: url });
+let existingIssues = loadIssues();
+let itemIndex = projectContractAvailable(projectContract) ? projectItemIndex(projectContract) : new Map();
+const syncResult = {
+  mode: "checklist",
+  artifact_backlog: null,
+  created: [],
+  updated: [],
+  reopened: [],
+  closed: [],
+  warnings: [],
+  project: {
+    enabled: projectContractAvailable(projectContract),
+    contract_path: projectContractAvailable(projectContract) ? projectContractPath() : null,
+    artifact_contract_path: artifactContract ? artifactContractPath() : null,
+    role_map_path: roleMapPath(),
+  },
+  tasks: [],
+};
+
+if (hasArtifactBacklogKit()) {
+  syncResult.mode = "artifact-backlog";
+  syncResult.artifact_backlog = runArtifactBacklog();
+  existingIssues = loadIssues();
+  itemIndex = projectContractAvailable(projectContract) ? projectItemIndex(projectContract) : new Map();
+
+  const catalog = loadTaskCatalog();
+  const syncState = loadTaskSyncState();
+  const catalogTasks = Array.isArray(catalog?.tasks) ? catalog.tasks : [];
+
+  for (const task of catalogTasks) {
+    const meta = parseTaskMeta(task.body);
+    const assignedAgent = resolveAgentRole(
+      roleMap,
+      String(task.agent_role || meta.agent_role || classifyAgent(task.title)),
+    );
+    const syncedIssue = syncState?.issues?.[task.key];
+    const mappedIssueNumber =
+      syncedIssue && typeof syncedIssue.number === "number" ? Number(syncedIssue.number) : null;
+    const found =
+      (mappedIssueNumber
+        ? existingIssues.find((issue) => Number(issue?.number) === mappedIssueNumber)
+        : null) ||
+      findIssueForTask(existingIssues, task.key);
+    const taskStatus = normalizeTaskStatus(found?.state === "CLOSED" ? "closed" : "open");
+    const issueNumber = found?.number ?? mappedIssueNumber ?? null;
+    const issueLink = found?.url || (issueNumber ? issueUrl(repository, issueNumber) : null);
+
+    let projectItemId = null;
+    let projectStatus = null;
+    if (issueNumber && projectContractAvailable(projectContract)) {
+      try {
+        const item = ensureProjectItem(projectContract, Number(issueNumber), itemIndex);
+        projectItemId = item?.id || null;
+        if (projectItemId) {
+          setProjectAgentRole(projectContract, projectItemId, assignedAgent);
+          projectStatus = taskStatus === "closed" ? "done" : "todo";
+          setProjectStatus(projectContract, projectItemId, projectStatus);
+        }
+      } catch (error) {
+        syncResult.warnings.push({
+          id: task.key,
+          scope: "artifact-project-sync",
+          message: String(error?.message || error),
+        });
+      }
+    }
+
+    syncResult.tasks.push({
+      id: task.key,
+      title: task.title,
+      source:
+        Array.isArray(meta.source_refs) && meta.source_refs.length > 0
+          ? String(meta.source_refs[0])
+          : "artifact:" + String(task.artifact_type || "task"),
+      status: taskStatus,
+      agent_role: assignedAgent,
+      issue_number: issueNumber,
+      issue_url: issueLink,
+      project_item_id: projectItemId,
+      project_status: projectStatus,
+      project_enabled: projectContractAvailable(projectContract),
+      task_origin: "artifact-backlog",
+      artifact_type: task.artifact_type || null,
+      source_refs: Array.isArray(meta.source_refs) ? meta.source_refs : [],
+      suggested_commands: Array.isArray(meta.suggested_commands) ? meta.suggested_commands : [],
+      target_paths_hint: Array.isArray(meta.target_paths_hint) ? meta.target_paths_hint : [],
+      priority: task.priority || null,
+      size: task.size || null,
+    });
+  }
+}
+
+if (syncResult.tasks.length === 0) {
+  syncResult.mode = "checklist";
+
+  for (const task of taskIr.tasks) {
+    const assignedAgent = resolveAgentRole(roleMap, classifyAgent(task.title));
+    const issueTitle = taskIssueTitle(task);
+    const issueBody = taskIssueBody(task, assignedAgent);
+    const taskStatus = normalizeTaskStatus(task.status);
+
+    let found = findIssueForTask(existingIssues, task.id);
+    let issueNumber = found?.number ?? null;
+    let issueLink = found?.url || (issueNumber ? issueUrl(repository, issueNumber) : null);
+
+    if (!found && taskStatus === "open") {
+      const createdUrl = gh([
+        "issue",
+        "create",
+        "--repo",
+        repository,
+        "--title",
+        issueTitle,
+        "--body",
+        issueBody,
+      ]);
+      issueNumber = issueNumberFromUrl(createdUrl);
+      issueLink = createdUrl || (issueNumber ? issueUrl(repository, issueNumber) : null);
+      found = {
+        number: issueNumber,
+        title: issueTitle,
+        state: "OPEN",
+        body: issueBody,
+        url: issueLink,
+      };
+      existingIssues.push(found);
+      syncResult.created.push({
+        id: task.id,
+        title: task.title,
+        issue_number: issueNumber,
+        issue_url: issueLink,
+      });
+    }
+
+    if (found && taskStatus === "open" && found.state === "CLOSED") {
+      gh([
+        "issue",
+        "reopen",
+        String(found.number),
+        "--repo",
+        repository,
+      ]);
+      found.state = "OPEN";
+      syncResult.reopened.push({ id: task.id, issue_number: found.number });
+    }
+
+    if (found && (String(found.title || "") !== issueTitle || String(found.body || "") !== issueBody)) {
+      gh([
+        "issue",
+        "edit",
+        String(found.number),
+        "--repo",
+        repository,
+        "--title",
+        issueTitle,
+        "--body",
+        issueBody,
+      ]);
+      found.title = issueTitle;
+      found.body = issueBody;
+      syncResult.updated.push({ id: task.id, issue_number: found.number });
+    }
+
+    if (found && taskStatus === "closed" && found.state !== "CLOSED") {
+      gh([
+        "issue",
+        "close",
+        String(found.number),
+        "--repo",
+        repository,
+        "--comment",
+        "Closed from SDD task IR.",
+      ]);
+      found.state = "CLOSED";
+      syncResult.closed.push({ id: task.id, issue_number: found.number });
+    }
+
+    issueNumber = found?.number ?? issueNumber ?? null;
+    issueLink = found?.url || issueLink || (issueNumber ? issueUrl(repository, issueNumber) : null);
+
+    let projectItemId = null;
+    let projectStatus = null;
+    if (issueNumber && projectContractAvailable(projectContract)) {
+      try {
+        const item = ensureProjectItem(projectContract, Number(issueNumber), itemIndex);
+        projectItemId = item?.id || null;
+        if (projectItemId) {
+          setProjectAgentRole(projectContract, projectItemId, assignedAgent);
+          projectStatus = taskStatus === "closed" ? "done" : "todo";
+          setProjectStatus(projectContract, projectItemId, projectStatus);
+        }
+      } catch (error) {
+        syncResult.warnings.push({
+          id: task.id,
+          scope: "project-sync",
+          message: String(error?.message || error),
+        });
+      }
+    }
+
+    syncResult.tasks.push({
+      id: task.id,
+      title: task.title,
+      source: task.source,
+      status: taskStatus,
+      agent_role: assignedAgent,
+      issue_number: issueNumber,
+      issue_url: issueLink,
+      project_item_id: projectItemId,
+      project_status: projectStatus,
+      project_enabled: projectContractAvailable(projectContract),
+      task_origin: "checklist",
+    });
   }
-  if (found && task.status === "closed" && found.state !== "CLOSED") {
-    gh([
-      "issue",
-      "close",
-      String(found.number),
-      "--repo",
-      orchestration.github.repository.slug,
-      "--comment",
-      "Closed from SDD task IR.",
-    ]);
-    syncResult.closed.push({ id: task.id, issue_number: found.number });
-  }
-
-  syncResult.tasks.push({
-    id: task.id,
-    title: task.title,
-    source: task.source,
-    status: task.status,
-    issue_number: found?.number ?? null,
-    issue_url: found
-      ? \`https://github.com/\${orchestration.github.repository.slug}/issues/\${found.number}\`
-      : null,
-  });
 }
 
 writeJson(generatedPath("task-sync.json"), syncResult);
-writeJson(generatedPath("task-index.json"), { tasks: syncResult.tasks });
-console.log(\`synced_tasks=\${taskIr.tasks.length}\`);
+writeJson(generatedPath("task-index.json"), {
+  generated_at: new Date().toISOString(),
+  project: syncResult.project,
+  tasks: syncResult.tasks,
+});
+console.log(\`sync_mode=\${syncResult.mode}\`);
+console.log(\`synced_tasks=\${syncResult.tasks.length}\`);
 `;
 }
 function runQueueScript() {
     return `#!/usr/bin/env node
-import { generatedPath, loadTaskIr, normalizeProviderProfile, orchestrationConfig, writeJson } from "./runtime-lib.ts";
+import {
+  classifyAgent,
+  generatedPath,
+  loadTaskIndex,
+  loadTaskIr,
+  normalizeTaskStatus,
+  orchestrationConfig,
+  pickProvider,
+  writeJson,
+} from "./runtime-lib.ts";
 
 const orchestration = orchestrationConfig();
-const taskIr = loadTaskIr();
-
-function classifyAgent(title) {
-  const lower = title.toLowerCase();
-  if (lower.includes("api") || lower.includes("contract")) return "api";
-  if (lower.includes("screen") || lower.includes("ui")) return "ui";
-  if (lower.includes("verify") || lower.includes("test") || lower.includes("proof")) return "quality";
-  if (lower.includes("workflow") || lower.includes("project") || lower.includes("github")) return "gitops";
-  if (lower.includes("arch") || lower.includes("boundary") || lower.includes("structure")) return "architecture";
-  if (lower.includes("plan") || lower.includes("spec")) return "specs";
-  return "runtime";
-}
-
-function pickProvider(title) {
-  const providers = (Array.isArray(orchestration.providers) ? orchestration.providers : []).map(normalizeProviderProfile);
-  const lower = title.toLowerCase();
-  if (lower.includes("verify") || lower.includes("test")) {
-    return (
-      providers.find((provider) => provider === "claude-cli" || provider === "anthropic-api") ||
-      providers[0] ||
-      "claude-cli"
-    );
-  }
-  if (lower.includes("api") || lower.includes("contract")) {
-    return (
-      providers.find((provider) => provider === "openai-api" || provider === "anthropic-api") ||
-      providers[0] ||
-      "openai-api"
-    );
-  }
-  return (
-    providers.find((provider) => provider === "codex-cli" || provider === "openai-api") ||
-    providers[0] ||
-    "codex-cli"
-  );
-}
+const taskIndex = loadTaskIndex();
+const indexedTasks = Array.isArray(taskIndex.tasks) ? taskIndex.tasks : [];
+const tasks = indexedTasks.length > 0 ? indexedTasks : loadTaskIr().tasks;
 
-const openTasks = taskIr.tasks.filter((task) => task.status === "open");
-const queue = openTasks.map((task) => ({
-  ...task,
-  assigned_agent: classifyAgent(task.title),
-  preferred_provider: pickProvider(task.title),
-}));
+const queue = tasks
+  .filter((task) => normalizeTaskStatus(task.status) === "open")
+  .map((task) => {
+    const assignedAgent = String(task.agent_role || classifyAgent(task.title));
+    return {
+      ...task,
+      assigned_agent: assignedAgent,
+      agent_role: assignedAgent,
+      preferred_provider: pickProvider(task.title, orchestration.providers),
+      project_item_id: task.project_item_id ?? null,
+      project_status: task.project_status ?? null,
+      project_enabled: Boolean(task.project_enabled),
+    };
+  });
 
 const outputPath = generatedPath("agent-queue.json");
 writeJson(outputPath, { providers: orchestration.providers, queue });
@@ -343,19 +892,32 @@ console.log(\`queued=\${queue.length}\`);
 }
 function dispatchQueueScript() {
     return `#!/usr/bin/env node
-import { generatedPath, loadQueue, orchestrationConfig, writeJson } from "./runtime-lib.ts";
+import { generatedPath, loadProjectContract, loadQueue, orchestrationConfig, writeJson } from "./runtime-lib.ts";
 
 const orchestration = orchestrationConfig();
+const projectContract = loadProjectContract();
 const queuePayload = loadQueue();
 
 const dispatch = queuePayload.queue.map((task) => ({
   task_id: task.id,
   title: task.title,
   source: task.source,
+  source_refs: Array.isArray(task.source_refs) ? task.source_refs : [],
+  suggested_commands: Array.isArray(task.suggested_commands) ? task.suggested_commands : [],
+  target_paths_hint: Array.isArray(task.target_paths_hint) ? task.target_paths_hint : [],
+  priority: task.priority ?? null,
+  size: task.size ?? null,
+  task_origin: task.task_origin || "checklist",
   assigned_agent: task.assigned_agent,
+  agent_role: task.agent_role || task.assigned_agent,
   provider: task.preferred_provider,
   repository: orchestration.github.repository.slug,
-  project_title: orchestration.github.project.title,
+  project_title: orchestration.github.project.title || projectContract?.project_title || "",
+  issue_number: task.issue_number ?? null,
+  issue_url: task.issue_url ?? null,
+  project_item_id: task.project_item_id ?? null,
+  project_status: task.project_status ?? null,
+  project_enabled: Boolean(task.project_enabled),
   execution_state: "planned",
 }));
 
@@ -373,11 +935,24 @@ function dispatchExecutorScript() {
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
-import { generatedPath, loadDispatchPlan, loadTaskIndex, normalizeProviderProfile, orchestrationConfig, writeJson } from "./runtime-lib.ts";
+import {
+  buildProjectLogComment,
+  generatedPath,
+  githubAuthEnv,
+  loadDispatchPlan,
+  loadProjectContract,
+  loadTaskIndex,
+  normalizeProviderProfile,
+  orchestrationConfig,
+  setProjectAgentRole,
+  setProjectStatus,
+  writeJson,
+} from "./runtime-lib.ts";
 
 const orchestration = orchestrationConfig();
 const dispatchPlan = loadDispatchPlan();
 const taskIndex = loadTaskIndex();
+const projectContract = loadProjectContract();
 const executionDir = generatedPath("executions");
 const commandTimeoutMs = Number(process.env.AGENTIC_AGENT_TIMEOUT_MS || 30000);
 fs.mkdirSync(executionDir, { recursive: true });
@@ -391,17 +966,45 @@ function commentOnIssue(issueNumber, body) {
   return spawnSync(
     "gh",
     ["issue", "comment", String(issueNumber), "--repo", orchestration.github.repository.slug, "--body", body],
-    { encoding: "utf-8" },
+    { encoding: "utf-8", env: githubAuthEnv() },
   );
 }
 
+function updateProjectState(record, statusKey) {
+  if (!projectContract || !record.project_item_id) return false;
+  try {
+    setProjectAgentRole(projectContract, record.project_item_id, record.agent_role || record.assigned_agent);
+    setProjectStatus(projectContract, record.project_item_id, statusKey);
+    record.project_status = statusKey;
+    return true;
+  } catch (error) {
+    record.warnings.push("project_status_update_failed: " + String(error?.message || error));
+    return false;
+  }
+}
+
 function buildPrompt(item, taskMeta) {
   return [
     \`You are the \${item.assigned_agent} agent working inside repository \${item.repository}.\`,
     \`GitHub Project: \${item.project_title}\`,
     \`Task id: \${item.task_id}\`,
     \`Task title: \${item.title}\`,
+    item.agent_role ? \`Agent role: \${item.agent_role}\` : "",
+    item.task_origin ? \`Task origin: \${item.task_origin}\` : "",
+    item.priority ? \`Priority: \${item.priority}\` : "",
+    item.size ? \`Size: \${item.size}\` : "",
+    item.project_item_id ? \`Project item id: \${item.project_item_id}\` : "",
+    item.project_status ? \`Current project status: \${item.project_status}\` : "",
     taskMeta?.source ? \`SDD source: \${taskMeta.source}\` : "",
+    Array.isArray(item.source_refs) && item.source_refs.length > 0
+      ? \`Source refs: \${item.source_refs.join(", ")}\`
+      : "",
+    Array.isArray(item.target_paths_hint) && item.target_paths_hint.length > 0
+      ? \`Target paths hint: \${item.target_paths_hint.join(", ")}\`
+      : "",
+    Array.isArray(item.suggested_commands) && item.suggested_commands.length > 0
+      ? \`Suggested commands: \${item.suggested_commands.join(", ")}\`
+      : "",
     "Follow the repository SDD workflow.",
     "Implement the task directly in the working tree when changes are required.",
     "Run relevant verification for the task.",
@@ -550,59 +1153,90 @@ async function runProvider(provider, prompt) {
 const executions = [];
 
 async function main() {
-for (const item of dispatchPlan.dispatch) {
-  const taskMeta = taskIndex.tasks.find((task) => task.id === item.task_id) || {};
-  const executionPath = path.join(executionDir, \`\${item.task_id}.json\`);
-  const prompt = buildPrompt(item, taskMeta);
-  const startedAt = new Date().toISOString();
-
-  const record = {
-    ...item,
-    issue_number: taskMeta.issue_number ?? null,
-    issue_url: taskMeta.issue_url ?? null,
-    started_at: startedAt,
-    completed_at: null,
-    prompt_path: path.relative(process.cwd(), executionPath.replace(/\\.json$/, ".prompt.txt")),
-    execution_artifact: path.relative(process.cwd(), executionPath),
-    adapter: "pending",
-    execution_state: "running",
-    exit_code: null,
-    stdout: "",
-    stderr: "",
-  };
+  for (const item of dispatchPlan.dispatch) {
+    const taskMeta = taskIndex.tasks.find((task) => task.id === item.task_id) || {};
+    const executionPath = path.join(executionDir, \`\${item.task_id}.json\`);
+    const prompt = buildPrompt(item, taskMeta);
+    const startedAt = new Date().toISOString();
+
+    const record = {
+      ...item,
+      issue_number: item.issue_number ?? taskMeta.issue_number ?? null,
+      issue_url: item.issue_url ?? taskMeta.issue_url ?? null,
+      project_item_id: item.project_item_id ?? taskMeta.project_item_id ?? null,
+      project_status: item.project_status ?? taskMeta.project_status ?? null,
+      agent_role: String(item.agent_role || taskMeta.agent_role || item.assigned_agent || ""),
+      task_origin: item.task_origin || taskMeta.task_origin || "checklist",
+      source_refs: Array.isArray(item.source_refs) ? item.source_refs : [],
+      suggested_commands: Array.isArray(item.suggested_commands) ? item.suggested_commands : [],
+      target_paths_hint: Array.isArray(item.target_paths_hint) ? item.target_paths_hint : [],
+      priority: item.priority ?? null,
+      size: item.size ?? null,
+      started_at: startedAt,
+      completed_at: null,
+      prompt_path: path.relative(process.cwd(), executionPath.replace(/\\.json$/, ".prompt.txt")),
+      execution_artifact: path.relative(process.cwd(), executionPath),
+      adapter: "pending",
+      execution_state: "running",
+      exit_code: null,
+      stdout: "",
+      stderr: "",
+      warnings: [],
+    };
 
-  fs.writeFileSync(executionPath.replace(/\\.json$/, ".prompt.txt"), prompt + "\\n");
-  const live = await runProvider(String(item.provider || ""), prompt);
-  record.provider = normalizeProviderProfile(String(item.provider || ""));
-  record.adapter = live.adapter;
-  record.exit_code = live.result.status ?? null;
-  record.stdout = String(live.result.stdout || "");
-  record.stderr = String(live.result.stderr || "");
-  record.execution_state = live.result.status === 0 ? "completed" : "failed";
-  record.completed_at = new Date().toISOString();
-
-  if (record.issue_number) {
-    const comment = [
-      "Agentic-dev dispatch execution result",
-      \`Task: \${record.task_id}\`,
-      \`Provider: \${record.provider}\`,
-      \`Adapter: \${record.adapter}\`,
-      \`State: \${record.execution_state}\`,
-      \`Execution artifact: \${record.execution_artifact}\`,
-    ].join("\\n");
-    commentOnIssue(record.issue_number, comment);
-  }
-
-  fs.writeFileSync(executionPath, JSON.stringify(record, null, 2) + "\\n");
-  executions.push(record);
-}
-
-writeJson(generatedPath("execution-journal.json"), {
-  generated_at: new Date().toISOString(),
-  executions,
-});
-console.log(\`executed=\${executions.length}\`);
-console.log(\`execution_journal=\${generatedPath("execution-journal.json")}\`);
+    updateProjectState(record, "in_progress");
+    fs.writeFileSync(executionPath.replace(/\\.json$/, ".prompt.txt"), prompt + "\\n");
+
+    const live = await runProvider(String(item.provider || ""), prompt);
+    record.provider = normalizeProviderProfile(String(item.provider || ""));
+    record.adapter = live.adapter;
+    record.exit_code = live.result.status ?? null;
+    record.stdout = String(live.result.stdout || "");
+    record.stderr = String(live.result.stderr || "");
+    record.execution_state = live.result.status === 0 ? "completed" : "failed";
+    record.completed_at = new Date().toISOString();
+
+    if (record.execution_state === "completed") {
+      updateProjectState(record, "in_review");
+    } else if (record.project_item_id) {
+      updateProjectState(record, "todo");
+    }
+
+    if (record.issue_number) {
+      const comment = projectContract
+        ? buildProjectLogComment(projectContract, {
+            agent_role: record.agent_role,
+            status: record.execution_state === "completed" ? "in_review" : "in_progress",
+            summary:
+              "Dispatch finished via " +
+              String(record.provider || "") +
+              " (" +
+              String(record.adapter || "") +
+              "), state=" +
+              String(record.execution_state || ""),
+            next: record.execution_state === "completed" ? "quality" : "retry-or-manual-follow-up",
+          })
+        : [
+            "Agentic-dev dispatch execution result",
+            \`Task: \${record.task_id}\`,
+            \`Provider: \${record.provider}\`,
+            \`Adapter: \${record.adapter}\`,
+            \`State: \${record.execution_state}\`,
+            \`Execution artifact: \${record.execution_artifact}\`,
+          ].join("\\n");
+      commentOnIssue(record.issue_number, comment);
+    }
+
+    fs.writeFileSync(executionPath, JSON.stringify(record, null, 2) + "\\n");
+    executions.push(record);
+  }
+
+  writeJson(generatedPath("execution-journal.json"), {
+    generated_at: new Date().toISOString(),
+    executions,
+  });
+  console.log(\`executed=\${executions.length}\`);
+  console.log(\`execution_journal=\${generatedPath("execution-journal.json")}\`);
 }
 
 main().catch((error) => {
@@ -613,11 +1247,22 @@ main().catch((error) => {
 }
 function closeTasksScript() {
     return `#!/usr/bin/env node
-import { gh, ghJson, generatedPath, loadExecutionJournal, orchestrationConfig, writeJson } from "./runtime-lib.ts";
+import {
+  generatedPath,
+  gh,
+  ghJson,
+  loadExecutionJournal,
+  loadProjectContract,
+  orchestrationConfig,
+  setProjectAgentRole,
+  setProjectStatus,
+  writeJson,
+} from "./runtime-lib.ts";
 
 const orchestration = orchestrationConfig();
 const executionJournal = loadExecutionJournal();
-const issues = ghJson([
+const projectContract = loadProjectContract();
+const issuesPayload = ghJson([
   "issue",
   "list",
   "--repo",
@@ -627,34 +1272,50 @@ const issues = ghJson([
   "--limit",
   "200",
   "--json",
-  "number,title",
+  "number",
 ]);
-const closed = [];
-
-const successfulTaskIds = new Set(
-  executionJournal.executions
-    .filter((execution) => execution.execution_state === "completed")
-    .map((execution) => execution.task_id),
+const openIssueNumbers = new Set(
+  (Array.isArray(issuesPayload) ? issuesPayload : []).map((issue) => issue.number),
 );
+const closed = [];
+const warnings = [];
+
+for (const execution of executionJournal.executions.filter((entry) => entry.execution_state === "completed")) {
+  if (projectContract && execution.project_item_id) {
+    try {
+      setProjectAgentRole(projectContract, execution.project_item_id, execution.agent_role || execution.assigned_agent);
+      setProjectStatus(projectContract, execution.project_item_id, "done");
+    } catch (error) {
+      warnings.push({
+        id: execution.task_id,
+        scope: "project-close",
+        message: String(error?.message || error),
+      });
+    }
+  }
 
-for (const issue of issues) {
-  const match = issue.title.match(/^\\[agentic-task\\] ([^ ]+) /);
-  if (!match) continue;
-  if (!successfulTaskIds.has(match[1])) continue;
-  gh([
-    "issue",
-    "close",
-    String(issue.number),
-    "--repo",
-    orchestration.github.repository.slug,
-    "--comment",
-    "Closed from SDD orchestration close pass.",
-  ]);
-  closed.push({ id: match[1], issue_number: issue.number });
+  if (!execution.issue_number) continue;
+  if (openIssueNumbers.has(execution.issue_number)) {
+    gh([
+      "issue",
+      "close",
+      String(execution.issue_number),
+      "--repo",
+      orchestration.github.repository.slug,
+      "--comment",
+      "Closed from SDD orchestration close pass.",
+    ]);
+  }
+  closed.push({
+    id: execution.task_id,
+    issue_number: execution.issue_number,
+    project_item_id: execution.project_item_id ?? null,
+    project_status: execution.project_item_id ? "done" : null,
+  });
 }
 
-writeJson(generatedPath("closed-tasks.json"), { closed });
-console.log(\`closed_candidates=\${successfulTaskIds.size}\`);
+writeJson(generatedPath("closed-tasks.json"), { closed, warnings });
+console.log(\`closed_candidates=\${closed.length}\`);
 `;
 }
 function serverScript() {