@k0t0vich/meta-agents-template 0.1.3 → 0.1.4

package/template/.meta-agents/prompts/mr-review-agent.md

@@ -0,0 +1,26 @@
+Role: MR Review Agent
+Goal: выполнить обязательный pre-merge review gate для MR/PR с фокусом на task linkage, PRD evidence и соответствие Git Flow Lite.
+
+When to run:
+- после `COMMIT_BY_NAME` и `push`;
+- до merge в целевую ветку (`develop` для feature, `main` для release/hotfix).
+
+Output format:
+1. MR context (branch/base/PR/commit scope).
+2. Task linkage summary.
+3. PRD evidence summary (в PR body и/или изменённых markdown-артефактах).
+4. Critical findings.
+5. Risks.
+6. Recommendation: `PASS_CANDIDATE`/`FAIL`.
+
+Rules:
+- финальный `PASS_CONFIRMED` только после явного `MR Review Approved: yes` от пользователя;
+- при `FAIL` merge блокируется;
+- для `feature/*` target branch обязан быть `develop`;
+- для `release/*|hotfix/*` target branch обязан быть `main`;
+- в отчёте обязательно фиксировать task refs и состояние PRD evidence.
+
+Tooling:
+- `npm run meta:mr-review`
+- `npm run meta:mr-review-approve`
+- или `npm run meta:ops -- --command RUN_MR_REVIEW_GATE --payload '{...}'`

package/template/.meta-agents/prompts/reviewer-judge.md

@@ -2,6 +2,8 @@ Role: Reviewer/Judge Agent
 Goal: независимая приёмка по критериям и обязательный pre-commit review gate.
 Output format: что сделано, критические замечания, потенциальные риски, рекомендация PASS_CANDIDATE/FAIL.
 Rule: финальный PASS_CONFIRMED только после явного `Review Approved: yes` от пользователя.
+Handoff rule: после pre-commit PASS_CONFIRMED задача передаётся в `MR Review Agent` для pre-merge gate.
 Status rule: перед review gate задача должна быть в статусе `REVIEW`; статус `READY` выставляется только после `PASS_CONFIRMED`.
-Delivery rule: `READY` требует commit+push; `DONE` требует интеграцию в `main`; `PUBLISH` только после фактической публикации.
+Delivery rule: `READY` требует commit+push на `feature/*|release/*|hotfix/*` (или `codex/*` эквиваленты) и PR в целевую ветку; `DONE` требует интеграцию в `main` и back-merge в `develop` для `release/*|hotfix/*`; `PUBLISH` только после фактической публикации.
+Branch rule: при несоответствии ветки Git Flow Lite (`main`, `develop`, `feature/*`, `release/*`, `hotfix/*`, `codex/*`) review gate должен сигнализировать FAIL.
 Output: accepted/rejected + findings.

package/template/.meta-agents/prompts/status-agent.md

@@ -0,0 +1,27 @@
+Role: Status Agent
+Goal: выдавать короткий и точный статус-срез проекта по запросам вида `статус`, `что в процессе`, `процесс`, `где мы`.
+
+Routing rule:
+- Если запрос про текущее состояние/прогресс без явной команды реализации, выбирается `Status Agent`.
+
+Data source priority:
+1. locked tracker provider (`.meta-agents/config/project-context.yaml` + `trackers.yaml`).
+2. Для `github`: GitHub tracker snapshot (через `gh`) — источник истины.
+3. Для `local`: `tasks/*` — источник истины.
+4. Git (`branch`, uncommitted changes) всегда включается.
+
+Output format (обязательный):
+1. Trackers used (locked provider + доступные providers).
+2. Current sprint.
+3. Current task in progress.
+4. Branch context (`branch`, `branch type`, `branch task ref`, `task/branch alignment`).
+5. Git working tree summary (modified/staged, untracked, ahead/behind).
+6. Короткая сводка рисков/неопределённостей.
+
+Tooling:
+- Основной путь: `npm run meta:status`.
+- Для machine-readable вывода можно использовать `npm run meta:status -- --json`.
+- Для веточного preflight по конкретной задаче: `npm run meta:task-start -- --task <TASK-ID|#issue> --slug <slug>`.
+
+Rule:
+- В `github` режиме локальные `tasks/*` не считать авторитетным источником по умолчанию; рассматривать только как cache/legacy artifacts.

package/template/.meta-agents/scripts/run-mr-review-gate.mjs

@@ -0,0 +1,488 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { execFileSync } from "node:child_process";
+import { resolveTrackerForCommand } from "./tracker/provider-lock.mjs";
+
+const REQUIRED_PRD_SECTIONS = ["### Описание", "### Проверяемость", "### Что сделано"];
+
+function parseArgs(argv) {
+  const options = {
+    approve: false,
+    tracker: "",
+    pr: "",
+    base: "",
+    json: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--approve") {
+      const value = (argv[i + 1] || "").trim().toLowerCase();
+      options.approve = value === "yes" || value === "true" || value === "1";
+      i += 1;
+      continue;
+    }
+    if (arg === "--tracker") {
+      options.tracker = (argv[i + 1] || "").trim().toLowerCase();
+      i += 1;
+      continue;
+    }
+    if (arg === "--pr") {
+      options.pr = (argv[i + 1] || "").trim();
+      i += 1;
+      continue;
+    }
+    if (arg === "--base") {
+      options.base = (argv[i + 1] || "").trim();
+      i += 1;
+      continue;
+    }
+    if (arg === "--json") {
+      options.json = true;
+      continue;
+    }
+  }
+
+  return options;
+}
+
+function run(command, args, allowFailure = false) {
+  try {
+    return execFileSync(command, args, {
+      encoding: "utf8",
+      cwd: process.cwd(),
+      stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+  } catch (error) {
+    if (allowFailure) {
+      return "";
+    }
+    throw error;
+  }
+}
+
+function readJson(command, args, allowFailure = false) {
+  const raw = run(command, args, allowFailure);
+  if (!raw) {
+    return null;
+  }
+  return JSON.parse(raw);
+}
+
+function classifyBranch(branch) {
+  if (/^main$/.test(branch)) {
+    return "main";
+  }
+  if (/^develop$/.test(branch)) {
+    return "develop";
+  }
+  if (/^feature\/.+/.test(branch) || /^codex\/feature\/.+/.test(branch)) {
+    return "feature";
+  }
+  if (/^release\/.+/.test(branch) || /^codex\/release\/.+/.test(branch)) {
+    return "release";
+  }
+  if (/^hotfix\/.+/.test(branch) || /^codex\/hotfix\/.+/.test(branch)) {
+    return "hotfix";
+  }
+  return "unknown";
+}
+
+function defaultBaseByBranchType(branchType) {
+  if (branchType === "hotfix") {
+    return "main";
+  }
+  return "develop";
+}
+
+function extractTaskRefs(text) {
+  const source = String(text || "");
+  const refs = new Set();
+
+  const issueMatches = source.match(/#\d+/g) || [];
+  for (const ref of issueMatches) {
+    refs.add(ref);
+  }
+
+  const taskMatches = source.match(/\b[A-Z][A-Z0-9_]*-\d+\b/g) || [];
+  for (const ref of taskMatches) {
+    refs.add(ref.toUpperCase());
+  }
+
+  return refs;
+}
+
+function hasTestFiles(files) {
+  return files.some(
+    (file) =>
+      /(^|\/)(tests?|__tests__)\//i.test(file) ||
+      /\.(test|spec)\.[cm]?[jt]sx?$/i.test(file),
+  );
+}
+
+async function readPrdEvidenceFromFiles(files) {
+  const evidence = [];
+  for (const file of files) {
+    if (!file.endsWith(".md")) {
+      continue;
+    }
+
+    const abs = path.resolve(process.cwd(), file);
+    let content = "";
+    try {
+      content = await fs.readFile(abs, "utf8");
+    } catch {
+      continue;
+    }
+
+    const hasAll = REQUIRED_PRD_SECTIONS.every((section) => content.includes(section));
+    if (hasAll) {
+      evidence.push(`${file}: ${REQUIRED_PRD_SECTIONS.join(", ")}`);
+      continue;
+    }
+
+    const found = REQUIRED_PRD_SECTIONS.filter((section) => content.includes(section));
+    if (found.length > 0) {
+      evidence.push(`${file}: partial -> ${found.join(", ")}`);
+    }
+  }
+
+  return evidence;
+}
+
+function parseGitLog(range) {
+  const format = "%H%x1f%s%x1f%b%x1e";
+  const raw = run("git", ["log", `--pretty=format:${format}`, range], true);
+  if (!raw) {
+    return [];
+  }
+
+  return raw
+    .split("\x1e")
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .map((entry) => {
+      const parts = entry.split("\x1f");
+      return {
+        oid: parts[0] || "",
+        title: parts[1] || "",
+        body: parts.slice(2).join("\x1f") || "",
+      };
+    });
+}
+
+function ensureUnique(values) {
+  return Array.from(new Set(values.filter(Boolean)));
+}
+
+function collectLocalContext(options) {
+  const branch = run("git", ["rev-parse", "--abbrev-ref", "HEAD"], true) || "unknown";
+  const branchType = classifyBranch(branch);
+  const baseRef = options.base || defaultBaseByBranchType(branchType);
+  const range = `${baseRef}..HEAD`;
+  const commits = parseGitLog(range);
+  const files = run("git", ["diff", "--name-only", range], true)
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  return {
+    source: "git",
+    pr: {
+      number: options.pr || "",
+      title: "",
+      url: "",
+      state: "LOCAL",
+      baseRefName: baseRef,
+      headRefName: branch,
+      body: "",
+    },
+    branch,
+    branchType,
+    baseRefName: baseRef,
+    commits,
+    files,
+  };
+}
+
+function collectGithubContext(options) {
+  run("gh", ["--version"], false);
+  const authStatus = run("gh", ["auth", "status"], true);
+  if (!authStatus) {
+    throw new Error("gh auth status unavailable");
+  }
+
+  let prNumber = options.pr;
+  if (!prNumber) {
+    const self = readJson("gh", ["pr", "view", "--json", "number"], true);
+    prNumber = self?.number ? String(self.number) : "";
+  }
+
+  if (!prNumber) {
+    return null;
+  }
+
+  const pr = readJson("gh", [
+    "pr",
+    "view",
+    prNumber,
+    "--json",
+    "number,title,url,state,baseRefName,headRefName,body,commits,files",
+  ]);
+
+  const commits = (pr?.commits || []).map((commit) => ({
+    oid: commit.oid || "",
+    title: commit.messageHeadline || "",
+    body: commit.messageBody || "",
+  }));
+  const files = (pr?.files || []).map((file) => file.path).filter(Boolean);
+
+  return {
+    source: "github",
+    pr: {
+      number: String(pr?.number || ""),
+      title: pr?.title || "",
+      url: pr?.url || "",
+      state: pr?.state || "",
+      baseRefName: pr?.baseRefName || "",
+      headRefName: pr?.headRefName || "",
+      body: pr?.body || "",
+    },
+    branch: pr?.headRefName || run("git", ["rev-parse", "--abbrev-ref", "HEAD"], true) || "unknown",
+    branchType: classifyBranch(pr?.headRefName || ""),
+    baseRefName: pr?.baseRefName || "",
+    commits,
+    files,
+  };
+}
+
+function gatherTaskRefs(context) {
+  const refs = new Set();
+
+  for (const ref of extractTaskRefs(context.pr.title)) {
+    refs.add(ref);
+  }
+  for (const ref of extractTaskRefs(context.pr.body)) {
+    refs.add(ref);
+  }
+  for (const commit of context.commits) {
+    for (const ref of extractTaskRefs(`${commit.title}\n${commit.body}`)) {
+      refs.add(ref);
+    }
+  }
+
+  const branchIssue = String(context.branch || "").match(/(?:^|\/)(\d+)(?:-|$)/);
+  if (branchIssue) {
+    refs.add(`#${branchIssue[1]}`);
+  }
+
+  const branchTask = String(context.branch || "").match(/([A-Z][A-Z0-9_]*-\d+)/);
+  if (branchTask) {
+    refs.add(branchTask[1].toUpperCase());
+  }
+
+  return Array.from(refs);
+}
+
+function evaluateBranchPolicy(context, critical) {
+  const branchType = context.branchType;
+  if (branchType === "unknown" || branchType === "main") {
+    critical.push(`branch-policy -> unsupported merge flow branch '${context.branch}'`);
+    return;
+  }
+
+  if (branchType === "feature" && context.baseRefName !== "develop") {
+    critical.push(
+      `branch-policy -> feature branch '${context.branch}' must target develop, got '${context.baseRefName || "unknown"}'`,
+    );
+  }
+  if ((branchType === "release" || branchType === "hotfix") && context.baseRefName !== "main") {
+    critical.push(
+      `branch-policy -> ${branchType} branch '${context.branch}' must target main, got '${context.baseRefName || "unknown"}'`,
+    );
+  }
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  let trackerProvider = "";
+  try {
+    trackerProvider = resolveTrackerForCommand({
+      requestedTracker: options.tracker,
+      cwd: process.cwd(),
+    });
+  } catch (error) {
+    console.error(`MR Review Gate FAIL: ${error.message}`);
+    process.exit(1);
+  }
+
+  let context = null;
+  let sourceNote = "";
+
+  if (trackerProvider === "github") {
+    try {
+      context = collectGithubContext(options);
+      if (!context) {
+        sourceNote = "No PR found via GitHub; fallback to local git range analysis.";
+        context = collectLocalContext(options);
+      }
+    } catch (error) {
+      sourceNote = `GitHub PR query failed (${error.message}); fallback to local git range analysis.`;
+      context = collectLocalContext(options);
+    }
+  } else {
+    context = collectLocalContext(options);
+  }
+
+  if (!context) {
+    console.error("MR Review Gate FAIL: unable to collect MR context");
+    process.exit(1);
+  }
+
+  const critical = [];
+  const risks = [];
+
+  if (context.pr.state && context.pr.state !== "OPEN" && context.pr.state !== "LOCAL") {
+    critical.push(`pr-state -> expected OPEN/LOCAL, got '${context.pr.state}'`);
+  }
+
+  if (context.commits.length === 0) {
+    critical.push("mr-context -> no commits detected for review range");
+  }
+
+  evaluateBranchPolicy(context, critical);
+
+  const taskRefs = gatherTaskRefs(context);
+  if (taskRefs.length === 0) {
+    critical.push("task-linkage -> no task/issue references detected in PR/commits/branch");
+  }
+
+  const prdEvidence = await readPrdEvidenceFromFiles(context.files);
+  const prHasPrdSections = REQUIRED_PRD_SECTIONS.every((section) =>
+    String(context.pr.body || "").includes(section),
+  );
+  if (prdEvidence.length === 0 && !prHasPrdSections) {
+    critical.push(
+      "prd-evidence -> no PRD sections found in changed markdown files or PR body",
+    );
+  }
+
+  if (context.files.length > 0 && !hasTestFiles(context.files)) {
+    risks.push("Changes detected without explicit test files in MR diff.");
+  }
+
+  if (sourceNote) {
+    risks.push(sourceNote);
+  }
+
+  const report = {
+    trackerProvider,
+    source: context.source,
+    pr: context.pr,
+    branch: context.branch,
+    branchType: context.branchType,
+    baseRefName: context.baseRefName,
+    commitsCount: context.commits.length,
+    changedFilesCount: context.files.length,
+    taskRefs: ensureUnique(taskRefs),
+    prdEvidence: prHasPrdSections
+      ? ["PR body contains full PRD sections: Описание, Проверяемость, Что сделано", ...prdEvidence]
+      : prdEvidence,
+    critical,
+    risks,
+    recommendation: critical.length === 0 ? "PASS_CANDIDATE" : "FAIL",
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log("# MR Review Gate Report");
+    console.log("");
+    console.log("## MR Context");
+    console.log(`- tracker provider: ${trackerProvider}`);
+    console.log(`- source: ${report.source}`);
+    console.log(`- branch: ${report.branch} (${report.branchType})`);
+    console.log(`- base: ${report.baseRefName || "unknown"}`);
+    console.log(`- PR: ${report.pr.number || "not detected"} ${report.pr.title || ""}`.trim());
+    if (report.pr.url) {
+      console.log(`- PR url: ${report.pr.url}`);
+    }
+    console.log(`- commits: ${report.commitsCount}`);
+    console.log(`- changed files: ${report.changedFilesCount}`);
+
+    console.log("");
+    console.log("## Task Linkage");
+    if (report.taskRefs.length === 0) {
+      console.log("- none");
+    } else {
+      for (const ref of report.taskRefs) {
+        console.log(`- ${ref}`);
+      }
+    }
+
+    console.log("");
+    console.log("## PRD Evidence");
+    if (report.prdEvidence.length === 0) {
+      console.log("- none");
+    } else {
+      for (const item of report.prdEvidence.slice(0, 20)) {
+        console.log(`- ${item}`);
+      }
+    }
+
+    console.log("");
+    console.log("## Critical Findings");
+    if (report.critical.length === 0) {
+      console.log("- none");
+    } else {
+      for (const item of report.critical) {
+        console.log(`- ${item}`);
+      }
+    }
+
+    console.log("");
+    console.log("## Risks");
+    if (report.risks.length === 0) {
+      console.log("- none");
+    } else {
+      for (const item of report.risks) {
+        console.log(`- ${item}`);
+      }
+    }
+
+    console.log("");
+    console.log("## Recommendation");
+    console.log(`- ${report.recommendation}`);
+  }
+
+  if (report.critical.length > 0) {
+    if (!options.json) {
+      console.log("");
+      console.log("## Decision");
+      console.log("- FAIL");
+    }
+    process.exit(1);
+  }
+
+  if (!options.approve) {
+    if (!options.json) {
+      console.log("");
+      console.log("## Decision");
+      console.log("- PENDING_USER_CONFIRMATION");
+      console.log("- Требуется явное подтверждение пользователя: MR Review Approved = yes");
+    }
+    process.exit(2);
+  }
+
+  if (!options.json) {
+    console.log("");
+    console.log("## Decision");
+    console.log("- PASS_CONFIRMED");
+  }
+}
+
+main().catch((error) => {
+  console.error(`MR Review Gate FAIL: ${error.message}`);
+  process.exit(1);
+});

package/template/.meta-agents/scripts/run-review-gate.mjs

@@ -1,10 +1,12 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
+import { resolveTrackerForCommand } from "./tracker/provider-lock.mjs";
 
 function parseArgs(argv) {
   const options = {
     approve: false,
+    tracker: "",
   };
 
   for (let index = 0; index < argv.length; index += 1) {
@@ -13,6 +15,11 @@ function parseArgs(argv) {
       const value = (argv[index + 1] || "").trim().toLowerCase();
       options.approve = value === "yes" || value === "true" || value === "1";
       index += 1;
+      continue;
+    }
+    if (arg === "--tracker") {
+      options.tracker = (argv[index + 1] || "").trim().toLowerCase();
+      index += 1;
     }
   }
 
@@ -21,7 +28,10 @@ function parseArgs(argv) {
 
 function git(args, allowFailure = false) {
   try {
-    const output = execFileSync("git", args, { encoding: "utf8" });
+    const output = execFileSync("git", args, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
     return output.trim();
   } catch (error) {
     if (allowFailure) {
@@ -45,6 +55,25 @@ function matchTestFile(filePath) {
   return /(^|\/)(tests?|__tests__)\//i.test(filePath) || /\.(test|spec)\.[cm]?[jt]sx?$/i.test(filePath);
 }
 
+function classifyBranch(branch) {
+  if (/^main$/.test(branch)) {
+    return "main";
+  }
+  if (/^develop$/.test(branch)) {
+    return "develop";
+  }
+  if (/^feature\/.+/.test(branch) || /^codex\/feature\/.+/.test(branch)) {
+    return "feature";
+  }
+  if (/^release\/.+/.test(branch) || /^codex\/release\/.+/.test(branch)) {
+    return "release";
+  }
+  if (/^hotfix\/.+/.test(branch) || /^codex\/hotfix\/.+/.test(branch)) {
+    return "hotfix";
+  }
+  return "unknown";
+}
+
 async function scanMarkers(files) {
   const markers = [];
   // Match common marker formats while ignoring status arrows in workflow lines.
@@ -70,9 +99,22 @@ async function scanMarkers(files) {
 
 async function main() {
   const options = parseArgs(process.argv.slice(2));
+  let trackerProvider = "";
+  try {
+    trackerProvider = resolveTrackerForCommand({
+      requestedTracker: options.tracker,
+      cwd: process.cwd(),
+    });
+  } catch (error) {
+    console.error(`Review Gate FAIL: ${error.message}`);
+    process.exit(1);
+  }
+
   const stagedFiles = splitLines(git(["diff", "--cached", "--name-only"], true));
   const recentFiles = splitLines(git(["show", "--name-only", "--pretty=", "HEAD"], true));
   const files = stagedFiles.length > 0 ? stagedFiles : recentFiles;
+  const branch = git(["rev-parse", "--abbrev-ref", "HEAD"], true) || "unknown";
+  const branchType = classifyBranch(branch);
 
   if (files.length === 0) {
     console.log("Review Gate FAIL");
@@ -93,10 +135,21 @@ async function main() {
   if (sourceTouched && !testsTouched) {
     risks.push("Source/template changes detected without explicit test changes.");
   }
+  if (branchType === "develop") {
+    risks.push("Changes are on develop branch; prefer feature/release/hotfix branches for task-level work.");
+  }
+  if (branchType === "unknown") {
+    critical.push(`branch-policy -> unsupported branch '${branch}' for Git Flow Lite`);
+  }
+  if (branchType === "main") {
+    critical.push("branch-policy -> direct review/commit flow on main is blocked in Git Flow Lite");
+  }
 
   console.log("# Review Gate Report");
   console.log("");
   console.log("## Что сделано");
+  console.log(`- tracker provider: ${trackerProvider}`);
+  console.log(`- branch: ${branch} (${branchType})`);
   for (const file of files) {
     console.log(`- changed: ${file}`);
   }