@k0t0vich/meta-agents-template 0.1.3 → 0.1.4

package/template/.meta-agents/scripts/tracker-gateway.mjs

@@ -0,0 +1,199 @@
+import process from "node:process";
+import { execFileSync } from "node:child_process";
+import { resolveTrackerForCommand } from "./tracker/provider-lock.mjs";
+
+const COMMAND_MAP = {
+  CREATE_TASK: "createTask",
+  PREPARE_TASK_BRANCH: "__prepareTaskBranch",
+  RUN_MR_REVIEW_GATE: "__runMrReviewGate",
+  SET_STATUS: "setStatus",
+  COMMIT_BY_NAME: "commitByName",
+  ASSIGN_SPRINT: "assignSprint",
+};
+
+function printHelp() {
+  console.log("TrackerGateway CLI");
+  console.log("");
+  console.log("Usage:");
+  console.log(
+    "  npm run meta:ops -- --command CREATE_TASK|PREPARE_TASK_BRANCH|RUN_MR_REVIEW_GATE|SET_STATUS|COMMIT_BY_NAME|ASSIGN_SPRINT [--tracker github|mcp|local|custom] [--payload '{\"k\":\"v\"}']",
+  );
+  console.log("");
+  console.log("Rules:");
+  console.log("  - If --tracker is passed, it must match locked project tracker provider.");
+  console.log(
+    "  - Locked provider is resolved from .meta-agents/config/project-context.yaml and trackers.yaml.",
+  );
+}
+
+function runTaskBranchRouter(payload) {
+  const args = [".meta-agents/scripts/task-branch-router.mjs"];
+  if (payload.task) {
+    args.push("--task", String(payload.task));
+  }
+  if (payload.slug) {
+    args.push("--slug", String(payload.slug));
+  }
+  if (payload.kind) {
+    args.push("--kind", String(payload.kind));
+  }
+  if (payload.base) {
+    args.push("--base", String(payload.base));
+  }
+  if (payload.apply) {
+    args.push("--apply");
+  }
+  if (payload.allowDirty) {
+    args.push("--allow-dirty");
+  }
+  if (payload.allowAhead) {
+    args.push("--allow-ahead");
+  }
+  if (payload.json) {
+    args.push("--json");
+  }
+
+  const output = execFileSync("node", args, {
+    cwd: process.cwd(),
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (output.trim()) {
+    console.log(output.trim());
+  }
+}
+
+function runMrReviewGate(payload) {
+  const args = [".meta-agents/scripts/run-mr-review-gate.mjs"];
+  if (payload.pr) {
+    args.push("--pr", String(payload.pr));
+  }
+  if (payload.base) {
+    args.push("--base", String(payload.base));
+  }
+  if (payload.approve) {
+    args.push("--approve", "yes");
+  }
+  if (payload.json) {
+    args.push("--json");
+  }
+
+  const output = execFileSync("node", args, {
+    cwd: process.cwd(),
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (output.trim()) {
+    console.log(output.trim());
+  }
+}
+
+function parseArgs(argv) {
+  const options = {
+    command: "",
+    tracker: "",
+    payloadRaw: "",
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+      continue;
+    }
+    if (arg === "--command") {
+      options.command = (argv[i + 1] || "").trim().toUpperCase();
+      i += 1;
+      continue;
+    }
+    if (arg === "--tracker") {
+      options.tracker = (argv[i + 1] || "").trim().toLowerCase();
+      i += 1;
+      continue;
+    }
+    if (arg === "--payload") {
+      options.payloadRaw = argv[i + 1] || "";
+      i += 1;
+      continue;
+    }
+  }
+
+  return options;
+}
+
+function parsePayload(payloadRaw) {
+  if (!payloadRaw) {
+    return {};
+  }
+  try {
+    const payload = JSON.parse(payloadRaw);
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+      throw new Error("payload must be a JSON object");
+    }
+    return payload;
+  } catch (error) {
+    throw new Error(`invalid --payload JSON: ${error.message}`);
+  }
+}
+
+async function loadAdapter(provider) {
+  try {
+    return await import(`./tracker/${provider}.mjs`);
+  } catch (error) {
+    throw new Error(`failed to load tracker adapter '${provider}': ${error.message}`);
+  }
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  if (!options.command) {
+    throw new Error("missing --command");
+  }
+
+  const adapterMethod = COMMAND_MAP[options.command];
+  if (!adapterMethod) {
+    throw new Error(
+      `unsupported --command '${options.command}'. Allowed: ${Object.keys(COMMAND_MAP).join(", ")}`,
+    );
+  }
+
+  const payload = parsePayload(options.payloadRaw);
+  const trackerProvider = resolveTrackerForCommand({
+    requestedTracker: options.tracker,
+    cwd: process.cwd(),
+  });
+
+  if (adapterMethod === "__prepareTaskBranch") {
+    runTaskBranchRouter(payload);
+    console.log(`TrackerGateway PASS: ${options.command} via tracker '${trackerProvider}'.`);
+    return;
+  }
+  if (adapterMethod === "__runMrReviewGate") {
+    runMrReviewGate(payload);
+    console.log(`TrackerGateway PASS: ${options.command} via tracker '${trackerProvider}'.`);
+    return;
+  }
+
+  const adapter = await loadAdapter(trackerProvider);
+  const operation = adapter[adapterMethod];
+
+  if (typeof operation !== "function") {
+    throw new Error(
+      `tracker adapter '${trackerProvider}' does not export '${adapterMethod}' operation`,
+    );
+  }
+
+  await operation(payload);
+  console.log(`TrackerGateway PASS: ${options.command} via tracker '${trackerProvider}'.`);
+}
+
+main().catch((error) => {
+  console.error(`TrackerGateway FAIL: ${error.message}`);
+  process.exit(1);
+});

package/template/.meta-agents/scripts/verify-branch-strategy.mjs

@@ -0,0 +1,103 @@
+import { execFileSync } from "node:child_process";
+import process from "node:process";
+
+const BRANCH_PATTERNS = [
+  { type: "main", regex: /^main$/ },
+  { type: "develop", regex: /^develop$/ },
+  { type: "feature", regex: /^feature\/.+/ },
+  { type: "release", regex: /^release\/.+/ },
+  { type: "hotfix", regex: /^hotfix\/.+/ },
+  { type: "feature", regex: /^codex\/feature\/.+/ },
+  { type: "release", regex: /^codex\/release\/.+/ },
+  { type: "hotfix", regex: /^codex\/hotfix\/.+/ },
+];
+
+function git(args, allowFailure = false) {
+  try {
+    return execFileSync("git", args, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+  } catch (error) {
+    if (allowFailure) {
+      return "";
+    }
+    throw error;
+  }
+}
+
+function detectBranch() {
+  const direct = git(["rev-parse", "--abbrev-ref", "HEAD"], true);
+  if (direct && direct !== "HEAD") {
+    return direct;
+  }
+
+  const status = git(["status", "--short", "--branch"], true);
+  const header = status.split("\n")[0] || "";
+
+  const noCommitsMatch = header.match(/^##\s+No commits yet on\s+(.+)$/);
+  if (noCommitsMatch) {
+    return noCommitsMatch[1].trim();
+  }
+
+  const branchMatch = header.match(/^##\s+([^\.\s]+)(?:\.\.\.[^\s]+)?/);
+  if (branchMatch) {
+    return branchMatch[1].trim();
+  }
+
+  return "";
+}
+
+function parseArgs(argv) {
+  const options = {
+    noMain: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === "--no-main") {
+      options.noMain = true;
+    }
+  }
+
+  return options;
+}
+
+function classify(branch) {
+  for (const pattern of BRANCH_PATTERNS) {
+    if (pattern.regex.test(branch)) {
+      return pattern.type;
+    }
+  }
+  return "unknown";
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const branch = detectBranch();
+
+  if (!branch) {
+    console.error("Branch strategy FAIL: cannot detect current git branch.");
+    process.exit(1);
+  }
+
+  const type = classify(branch);
+  if (type === "unknown") {
+    console.error(`Branch strategy FAIL: branch '${branch}' is not allowed by Git Flow Lite.`);
+    console.error("Allowed: main, develop, feature/*, release/*, hotfix/*");
+    process.exit(1);
+  }
+
+  if (options.noMain && type === "main") {
+    console.error("Branch strategy FAIL: direct operation on main is blocked by --no-main.");
+    process.exit(1);
+  }
+
+  console.log(`Branch strategy PASS: branch='${branch}', type='${type}'.`);
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(`Branch strategy FAIL: ${error.message}`);
+  process.exit(1);
+}

package/template/.meta-agents/scripts/verify-commit-link.mjs

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { resolveTrackerForCommand } from "./tracker/provider-lock.mjs";
 
 function readLastCommitSubject(ref = "HEAD") {
   const output = execFileSync("git", ["log", "-1", "--pretty=%s", ref], { encoding: "utf8" });
@@ -12,7 +13,7 @@ function validateMessage(message) {
 }
 
 function parseArgs(argv) {
-  const args = { message: "", ref: "HEAD" };
+  const args = { message: "", ref: "HEAD", tracker: "" };
   for (let i = 0; i < argv.length; i += 1) {
     if (argv[i] === "--message") {
       args.message = argv[i + 1] || "";
@@ -24,27 +25,40 @@ function parseArgs(argv) {
       i += 1;
       continue;
     }
+    if (argv[i] === "--tracker") {
+      args.tracker = argv[i + 1] || "";
+      i += 1;
+      continue;
+    }
   }
   return args;
 }
 
 function main() {
-  const options = parseArgs(process.argv.slice(2));
-  const message = options.message || readLastCommitSubject(options.ref);
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    const trackerProvider = resolveTrackerForCommand({
+      requestedTracker: options.tracker,
+      cwd: process.cwd(),
+    });
+    const message = options.message || readLastCommitSubject(options.ref);
 
-  if (!message) {
-    console.error("Commit link FAIL: empty commit message.");
-    process.exit(1);
-  }
+    if (!message) {
+      console.error("Commit link FAIL: empty commit message.");
+      process.exit(1);
+    }
+
+    if (!validateMessage(message)) {
+      console.error("Commit link FAIL: message must contain TASK-ID or #issue.");
+      console.error(`Message: ${message}`);
+      process.exit(1);
+    }
 
-  if (!validateMessage(message)) {
-    console.error("Commit link FAIL: message must contain TASK-ID or #issue.");
-    console.error(`Message: ${message}`);
+    console.log(`Commit link PASS [tracker=${trackerProvider}]: ${message}`);
+  } catch (error) {
+    console.error(`Commit link FAIL: ${error.message}`);
     process.exit(1);
   }
-
-  console.log(`Commit link PASS: ${message}`);
 }
 
 main();
-

package/template/.meta-agents/scripts/verify-governance.mjs

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
+import { resolveLockedTrackerProvider } from "./tracker/provider-lock.mjs";
 
 const TASKS_DIR = path.resolve(process.cwd(), "tasks");
 const EXCLUDED_FILES = new Set(["backlog.md", "sprint-1.md", "task-status-log.md"]);
@@ -15,10 +16,14 @@ const REQUIRED_PATTERNS = [
 ];
 
 async function listTaskFiles() {
-  const entries = await fs.readdir(TASKS_DIR, { withFileTypes: true });
-  return entries
-    .filter((entry) => entry.isFile() && entry.name.endsWith(".md") && !EXCLUDED_FILES.has(entry.name))
-    .map((entry) => path.join(TASKS_DIR, entry.name));
+  try {
+    const entries = await fs.readdir(TASKS_DIR, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".md") && !EXCLUDED_FILES.has(entry.name))
+      .map((entry) => path.join(TASKS_DIR, entry.name));
+  } catch {
+    return null;
+  }
 }
 
 async function validateTask(filePath) {
@@ -35,19 +40,38 @@ async function validateTask(filePath) {
 }
 
 async function main() {
-  let taskFiles;
+  const args = process.argv.slice(2);
+  const validateLocalCache = args.includes("--validate-local-cache");
+
+  let trackerProvider = "";
   try {
-    taskFiles = await listTaskFiles();
-  } catch {
-    console.error("Governance FAIL: tasks directory not found.");
+    trackerProvider = resolveLockedTrackerProvider(process.cwd());
+  } catch (error) {
+    console.error(`Governance FAIL: ${error.message}`);
     process.exit(1);
   }
 
-  if (taskFiles.length === 0) {
-    console.error("Governance FAIL: no task markdown files found in tasks/.");
+  const taskFiles = await listTaskFiles();
+  const localTasksRequired = trackerProvider === "local" || validateLocalCache;
+
+  if (!localTasksRequired) {
+    const localCount = taskFiles ? taskFiles.length : 0;
+    console.log(
+      `Governance PASS: tracker provider '${trackerProvider}' is external; local task validation skipped (${localCount} file(s) in tasks/).`,
+    );
+    return;
+  }
+
+  if (taskFiles === null) {
+    console.error("Governance FAIL: tasks directory not found for local-task validation.");
     process.exit(1);
   }
 
+  if (taskFiles.length === 0) {
+    console.log(`Governance PASS: no local task files found, tracker provider '${trackerProvider}'.`);
+    return;
+  }
+
   let hasErrors = false;
   for (const filePath of taskFiles) {
     const failed = await validateTask(filePath);
@@ -64,11 +88,12 @@ async function main() {
     process.exit(1);
   }
 
-  console.log(`Governance PASS: checked ${taskFiles.length} task file(s).`);
+  console.log(
+    `Governance PASS: checked ${taskFiles.length} task file(s), tracker provider '${trackerProvider}'.`,
+  );
 }
 
 main().catch((error) => {
   console.error(`Governance FAIL: ${error.message}`);
   process.exit(1);
 });
-

package/template/.meta-agents/templates/agent-work-contract.md

@@ -10,5 +10,12 @@
 - Acceptance Criteria:
 - Failure/Escalation Rules:
 - Tracker Binding (task/status/sprint):
-- Git Strategy (main or feature branch + MR/PR):
+- Git Strategy (Git Flow Lite: feature/* -> develop, release/* -> main + back-merge, hotfix/* -> main + back-merge):
+- Branch Routing Preflight:
+  - Current Branch:
+  - Requested Task Type (atomic|feature|release|hotfix):
+  - Routing Decision (stay_on_current_branch|create_new_branch):
+  - Base Branch:
+  - Working Branch:
+  - User Dialogue Confirmed (yes/no):
 - Epic/Feature Linkage (for large features in GitHub tracker):

package/template/.meta-agents/templates/task-template.md

@@ -3,10 +3,16 @@
 - Task ID:
 - Short Name:
 - Owner Role:
+- Task Type: atomic (atomic|feature|release|hotfix)
 - Status: TODO (TODO -> IN_PROGRESS -> REVIEW -> READY -> DONE -> PUBLISH for release tasks)
 - Sprint:
 - Parent Epic (optional):
-- Git Strategy (main or feature branch + MR/PR):
+- Git Strategy (Git Flow Lite: feature/* -> develop, release/* -> main + back-merge, hotfix/* -> main + back-merge):
+- Branch Context:
+  - Current Branch:
+  - Branch Task Ref:
+  - Routing Decision (stay_on_current_branch|create_new_branch):
+  - Working Branch (target):
 
 ## PRD Step
 ### Описание

package/template/README.md

@@ -6,14 +6,23 @@
 - `agents.md`: роли, правила и жёсткие критерии приёмки;
 - `tracker-command-template.md`: команды управления задачами и спринтами;
 - `.meta-agents/`: конфигурация системы и шаблоны PRD/verification;
+- `.github/workflows/gitflow-lite-verify.yml`: branch-aware CI-проверки для Git Flow Lite;
 - `tasks/`: backlog/sprint/status-log.
 
+## Source of truth по tracker provider
+- Выбранный при `init` provider фиксируется в `.meta-agents/config/project-context.yaml`.
+- Он должен совпадать с `.meta-agents/config/trackers.yaml -> tracker_gateway.default`.
+- По умолчанию все операционные команды выполняются только через этот provider, пока пользователь явно не изменит конфиг.
+
 Отдельно включён `Governance Watchdog Agent`:
 - обязательный gate перед каждой командой;
 - техническая проверка PRD-структуры через `npm run meta:verify`.
 - обязательный review gate перед коммитом:
   - `npm run meta:review` (отчёт + рекомендация);
   - `npm run meta:review-approve` (финальный PASS только после подтверждения пользователя).
+- обязательный MR review gate перед merge:
+  - `npm run meta:mr-review` (сводный MR/PR анализ);
+  - `npm run meta:mr-review-approve` (финальный PASS только после подтверждения пользователя).
 
 ## Что спросит init
 1. Git режим: `github`, `local` или `skip`.
@@ -24,13 +33,15 @@
 1. Каждый шаг содержит: `Описание -> Проверяемость -> Что сделано`.
 2. Перед каждой задачей обязателен вывод `[Agent Auto-Select]` и `[Task Agent]`.
 3. Коммиты и закрытие задачи в `DONE` только после явного подтверждения пользователя.
-4. В single-branch режиме используется статусный цикл: `TODO -> IN_PROGRESS -> REVIEW -> READY -> DONE` (для релизных задач дополнительно `-> PUBLISH`).
+4. В режиме Git Flow Lite используется статусный цикл: `TODO -> IN_PROGRESS -> REVIEW -> READY -> DONE` (для релизных задач дополнительно `-> PUBLISH`).
 5. Без подтверждения пользователя максимум статуса: `REVIEW`; `READY` только после `RUN_REVIEW_GATE: PASS_CONFIRMED`.
-6. `READY` = коммит + push (в `main` или в ветку с открытым MR/PR); `DONE` = интеграция в `main`; `PUBLISH` = опубликовано в latest.
-7. Для больших фич (GitHub tracker) агент обязан предложить `feature issue` + `epic issue` и отдельную ветку.
-8. В GitHub epic оформляется как issue с label `type:epic`, а feature связывается с ним ссылкой (`type:feature`).
-9. Для релиза используется `Publishing Agent`: он создаёт release note с вошедшими задачами и переводит эти задачи в `PUBLISH`.
-10. Перед релизом `Publishing Agent` обязан обновить публичный `CHANGELOG.md`.
+6. Merge в целевую ветку разрешён только после `RUN_MR_REVIEW_GATE: PASS_CONFIRMED` и `MR Review Approved: yes`.
+7. Git Flow Lite ветки: `feature/* -> develop`, `release/* -> main` + back-merge в `develop`, `hotfix/* -> main` + back-merge в `develop`.
+8. `READY` = commit + push в `feature/*|release/*|hotfix/*` и открытый PR в целевую ветку; `DONE` = интеграция в `main` + back-merge (для release/hotfix); `PUBLISH` = опубликовано в latest.
+9. Для больших фич (GitHub tracker) агент обязан предложить `feature issue` + `epic issue` и отдельную ветку.
+10. В GitHub epic оформляется как issue с label `type:epic`, а feature связывается с ним ссылкой (`type:feature`).
+11. Для релиза используется `Publishing Agent`: он создаёт release note с вошедшими задачами и переводит эти задачи в `PUBLISH`.
+12. Перед релизом `Publishing Agent` обязан обновить публичный `CHANGELOG.md`.
 
 ## Команды
 Смотри `tracker-command-template.md`.
@@ -38,7 +49,33 @@
 Дополнительно:
 ```bash
 npm run meta:verify
+npm run meta:branch
+npm run meta:task-start -- --task 12 --slug api-redirect
 npm run meta:review
 npm run meta:review-approve
+npm run meta:mr-review
+npm run meta:mr-review-approve
 npm run meta:verify-link
+npm run meta:ops -- --command SET_STATUS --payload '{"task":"DEV-12","status":"IN_PROGRESS"}'
+npm run meta:ops -- --command PREPARE_TASK_BRANCH --payload '{"task":"12","slug":"api-redirect"}'
+npm run meta:status
 ```
+
+`meta:ops` принудительно валидирует tracker provider lock.
+Если передать `--tracker`, он обязан совпадать с зафиксированным provider проекта, иначе команда блокируется.
+`meta:branch` валидирует ветку по Git Flow Lite (`main`, `develop`, `feature/*`, `release/*`, `hotfix/*`).
+`meta:task-start` делает branch-routing preflight: сравнивает задачу с текущей веткой, показывает dirty/ahead блокеры и готовит маршрут (`stay_on_current_branch` или `create_new_branch`).
+`meta:task-start` также делает context-protection check для `agents.md` между текущей и базовой веткой и требует явного подтверждения при diff.
+`meta:mr-review` формирует сводный pre-merge отчёт по MR/PR, `meta:mr-review-approve` фиксирует финальный PASS после подтверждения пользователя.
+
+`meta:status` выдаёт сводный статус:
+- trackers used;
+- current sprint;
+- current task;
+- current branch context (type/task-ref/alignment);
+- git uncommitted summary;
+- короткая сводка.
+
+Важно:
+- в `github` режиме локальные `tasks/*` не считаются источником истины по умолчанию (только cache/legacy);
+- в `local` режиме `tasks/*` считаются источником истины.