@k0t0vich/meta-agents-template 0.1.11 → 0.1.12

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this package are documented in this file.
 
+## 0.1.12 - 2026-03-20
+
+### Added
+- Added hard docs-first law in canonical rules: no code before PRD + architecture + verification matrix.
+- Added explicit scope-control rule: if dialogue exits current task scope, agent must propose creating a task or finishing current one before coding.
+- Added mandatory verification matrix fields for task artifacts: `tests_unit`, `tests_system`, `tests_e2e_playwright`, `external_analysis`.
+
+### Changed
+- Upgraded `meta:ops` runtime flow to execute governance verification before operational commands.
+- Expanded GitHub issue body validation for `SET_STATUS -> IN_PROGRESS` and implementation gate to require `Architecture`, `Verification Plan`, and extended verification rows.
+- Updated governance prompts and templates to enforce docs-first execution discipline.
+
+### Fixed
+- Eliminated policy/runtime gap where code-stage commands could start without task-scoped docs-first validation.
+
 ## 0.1.11 - 2026-03-20
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k0t0vich/meta-agents-template",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Template system for verification-first agentic development",
   "type": "module",
   "bin": {

package/template/.meta-agents/config/system.yaml

@@ -62,6 +62,23 @@ system:
         - local
         - custom
       require_provider_consistency: true
+    coding_law:
+      no_code_before_prd_and_verification: true
+      required_before_coding:
+        - prd_description_complete
+        - architecture_documented
+        - verification_matrix_complete
+        - tests_unit_defined
+        - tests_system_defined
+        - tests_e2e_playwright_defined
+        - external_analysis_defined
+        - implementation_gate_passed
+    dialogue_scope_control:
+      enabled: true
+      if_request_out_of_scope:
+        - propose_create_task
+        - or_finish_current_task
+      code_actions_blocked_until_scope_resolved: true
     user_confirmation_required_for:
       - review_gate_pass
       - mr_review_gate_pass
@@ -173,8 +190,13 @@ system:
         - MARK_TASKS_PUBLISH
       minimum_checks:
         - prd_sections_complete
+        - architecture_documented
+        - verification_matrix_complete
+        - tests_unit_system_playwright_defined
+        - external_analysis_defined
         - acceptance_criteria_defined
         - user_confirmation_policy_respected
+        - no_code_before_prd
     review_gate:
       required_before_commit: true
       command: RUN_REVIEW_GATE
@@ -220,12 +242,19 @@ system:
   acceptance:
     hard_criteria:
       - prd_sections_complete
+      - architecture_documented_before_coding
       - auto_select_prefix_present
       - strict_checks_passed
       - statistical_thresholds_met
       - human_approvals_passed
+      - verification_matrix_contains_unit_tests
+      - verification_matrix_contains_system_tests
+      - verification_matrix_contains_e2e_playwright
+      - external_agent_analysis_completed_for_key_tasks
+      - no_code_changes_before_implementation_gate_pass
       - evidence_pack_complete
       - tracker_sync_complete
+      - out_of_scope_dialogue_requires_task_decision
       - branch_routing_dialog_completed
       - implementation_gate_passed
       - branch_routing_e2e_verified

package/template/.meta-agents/prompts/agile-manager.md

@@ -1,6 +1,7 @@
 Role: Agile Manager Agent
 Goal: управлять задачами и статусами через TrackerGateway.
 Commands: CREATE_TASK, SET_STATUS, COMMIT_BY_NAME, ASSIGN_SPRINT.
+Law: не начинать кодовые изменения до PASS по docs-first gate (`PRD + Architecture + Verification Plan + tests_unit/tests_system/tests_e2e_playwright/external_analysis`).
 Status semantics: READY = commit+push on feature/release/hotfix + open PR; DONE = integrated to main + back-merge to develop (release/hotfix); PUBLISH = published in latest version.
 Git Flow Lite rule: использовать `feature/* -> develop`, `release/* -> main` + back-merge, `hotfix/* -> main` + back-merge.
 Rule: для большой фичи в GitHub tracker сначала предложить связку `feature issue` + `epic issue` и выделенную ветку.
@@ -25,3 +26,5 @@ Task ref naming rule:
 Pre-merge rule:
 - после commit+push и открытия PR обязательно выполнить `RUN_MR_REVIEW_GATE`;
 - merge допускается только после `RUN_MR_REVIEW_GATE: PASS_CONFIRMED` и явного `MR Review Approved: yes` от пользователя.
+Scope rule:
+- если запрос уходит за границы текущей задачи, сначала предложить `CREATE_TASK` или завершение текущей задачи; до решения не переходить к коду.

package/template/.meta-agents/prompts/clarifier.md

@@ -1,6 +1,8 @@
 Role: Clarifier Agent
 Goal: выявить цель, ограничения, неоднозначности и критерии успеха.
+Law: никаких кодовых изменений до заполнения PRD, архитектуры и verification matrix (`tests_unit`, `tests_system`, `tests_e2e_playwright`, `external_analysis`).
 Rule: если задача классифицируется как большая фича, обязательно предложить создать `feature issue` и `epic issue` в GitHub tracker, а также отдельную ветку.
 Git rule: для задач реализации в Git Flow Lite по умолчанию выбирать `feature/<task-or-issue-id>-<slug>` (или `codex/feature/...`) от `develop`.
 Task granularity rule: если задача атомарная и относится к текущей feature-ветке, это фиксируется как `Task Type: atomic`, иначе создаётся отдельная рабочая ветка.
+Scope rule: если запрос вышел за рамки текущей задачи, сначала предложить завести новую задачу или завершить текущую; не переходить к коду до решения.
 Output: PRD Step с заполненными "Описание" и "Проверяемость".

package/template/.meta-agents/prompts/governance-watchdog.md

@@ -1,3 +1,5 @@
 Role: Governance Watchdog Agent
 Goal: блокировать выполнение команды, если не выполнены PRD/acceptance/user-confirmation требования.
 Rule: без PASS от governance gate команда не исполняется.
+Rule: перед началом кодирования обязателен docs-first PASS (`PRD + Architecture + Verification Plan + tests_unit/tests_system/tests_e2e_playwright/external_analysis`).
+Rule: если запрос вышел за рамки текущей задачи, агент обязан остановить кодовые действия и предложить `CREATE_TASK` или завершение текущей задачи.

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

@@ -2,6 +2,7 @@ Role: Reviewer/Judge Agent
 Goal: независимая приёмка по критериям и обязательный pre-commit review gate.
 Output format: что сделано, критические замечания, потенциальные риски, рекомендация PASS_CANDIDATE/FAIL.
 Rule: финальный PASS_CONFIRMED только после явного `Review Approved: yes` от пользователя.
+Rule: review обязан подтвердить docs-first дисциплину: код не начат до `PRD + Architecture + Verification Plan + tests_unit/tests_system/tests_e2e_playwright/external_analysis`.
 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 на `feature/*|release/*|hotfix/*` (или `codex/*` эквиваленты) и PR в целевую ветку; `DONE` требует интеграцию в `main` и back-merge в `develop` для `release/*|hotfix/*`; `PUBLISH` только после фактической публикации.

package/template/.meta-agents/prompts/verifier-designer.md

@@ -1,3 +1,4 @@
 Role: Verifier Designer Agent
 Goal: определить strict/statistical/human проверки.
+Rule: verification plan обязан включать `tests_unit`, `tests_system`, `tests_e2e_playwright` и `external_analysis`.
 Output: verification plan и evidence mapping.

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

@@ -3,6 +3,17 @@ import process from "node:process";
 
 const STATUS_LABELS = ["TODO", "IN_PROGRESS", "REVIEW", "READY", "BLOCKED", "DONE", "PUBLISH"];
 const REQUIRED_PRD_HEADINGS = ["### Описание", "### Проверяемость", "### Что сделано"];
+const REQUIRED_DOCUMENT_HEADINGS = ["## Architecture", "## Verification Plan"];
+const REQUIRED_VERIFIABILITY_ROWS = [
+  { key: "strict", label: "strict" },
+  { key: "statistical", label: "statistical" },
+  { key: "human", label: "human" },
+  { key: "architecture", label: "architecture" },
+  { key: "tests_unit", label: "tests_unit" },
+  { key: "tests_system", label: "tests_system" },
+  { key: "tests_e2e_playwright", label: "tests_e2e_playwright" },
+  { key: "external_analysis", label: "external_analysis" },
+];
 const STATUS_COLORS = {
   IN_PROGRESS: "FBCA04",
   REVIEW: "5319E7",
@@ -195,6 +206,11 @@ function buildVerifiability(payload = {}) {
   let strict = "";
   let statistical = "";
   let human = "";
+  let architecture = "";
+  let testsUnit = "";
+  let testsSystem = "";
+  let testsE2EPlaywright = "";
+  let externalAnalysis = "";
 
   if (structured && typeof structured === "object" && !Array.isArray(structured)) {
     strict = pickFirstNonEmpty(structured.strict, payload.strict, payload.verificationStrict);
@@ -204,6 +220,39 @@ function buildVerifiability(payload = {}) {
       payload.verificationStatistical,
     );
     human = pickFirstNonEmpty(structured.human, payload.human, payload.verificationHuman);
+    architecture = pickFirstNonEmpty(
+      structured.architecture,
+      payload.architecture,
+      payload.verificationArchitecture,
+    );
+    testsUnit = pickFirstNonEmpty(
+      structured.tests_unit,
+      structured.testsUnit,
+      payload.tests_unit,
+      payload.testsUnit,
+      payload.verificationTestsUnit,
+    );
+    testsSystem = pickFirstNonEmpty(
+      structured.tests_system,
+      structured.testsSystem,
+      payload.tests_system,
+      payload.testsSystem,
+      payload.verificationTestsSystem,
+    );
+    testsE2EPlaywright = pickFirstNonEmpty(
+      structured.tests_e2e_playwright,
+      structured.testsE2EPlaywright,
+      payload.tests_e2e_playwright,
+      payload.testsE2EPlaywright,
+      payload.verificationTestsE2EPlaywright,
+    );
+    externalAnalysis = pickFirstNonEmpty(
+      structured.external_analysis,
+      structured.externalAnalysis,
+      payload.external_analysis,
+      payload.externalAnalysis,
+      payload.verificationExternalAnalysis,
+    );
   } else {
     const flat = pickFirstNonEmpty(payload.verifiability, payload.verification);
     strict = pickFirstNonEmpty(
@@ -221,12 +270,48 @@ function buildVerifiability(payload = {}) {
       payload.verificationHuman,
       parsePrefixedValue(flat, "human"),
     );
+    architecture = pickFirstNonEmpty(
+      payload.architecture,
+      payload.verificationArchitecture,
+      parsePrefixedValue(flat, "architecture"),
+    );
+    testsUnit = pickFirstNonEmpty(
+      payload.tests_unit,
+      payload.testsUnit,
+      payload.verificationTestsUnit,
+      parsePrefixedValue(flat, "tests_unit"),
+    );
+    testsSystem = pickFirstNonEmpty(
+      payload.tests_system,
+      payload.testsSystem,
+      payload.verificationTestsSystem,
+      parsePrefixedValue(flat, "tests_system"),
+    );
+    testsE2EPlaywright = pickFirstNonEmpty(
+      payload.tests_e2e_playwright,
+      payload.testsE2EPlaywright,
+      payload.verificationTestsE2EPlaywright,
+      parsePrefixedValue(flat, "tests_e2e_playwright"),
+    );
+    externalAnalysis = pickFirstNonEmpty(
+      payload.external_analysis,
+      payload.externalAnalysis,
+      payload.verificationExternalAnalysis,
+      parsePrefixedValue(flat, "external_analysis"),
+    );
   }
 
   return {
     strict: strict || "schema/types/invariants defined",
     statistical: statistical || "N/A (provide measurable threshold if metric is applicable)",
     human: human || "manual review and acceptance by task owner",
+    architecture: architecture || "component contracts and constraints documented before coding",
+    tests_unit: testsUnit || "unit tests required for changed logic",
+    tests_system: testsSystem || "system/integration tests required for key flows",
+    tests_e2e_playwright:
+      testsE2EPlaywright || "Playwright e2e scenario required for critical user path",
+    external_analysis:
+      externalAnalysis || "independent analysis by another agent role for key decisions",
   };
 }
 
@@ -239,19 +324,20 @@ function validateVerifiabilitySection(body) {
     };
   }
 
-  const hasStrict = /(^|\n)\s*-\s*strict\s*:/i.test(section);
-  const hasStatistical = /(^|\n)\s*-\s*statistical\s*:/i.test(section);
-  const hasHuman = /(^|\n)\s*-\s*human\s*:/i.test(section);
   const reasons = [];
 
-  if (!hasStrict) {
-    reasons.push("missing 'strict:' row in verifiability");
-  }
-  if (!hasStatistical) {
-    reasons.push("missing 'statistical:' row in verifiability");
-  }
-  if (!hasHuman) {
-    reasons.push("missing 'human:' row in verifiability");
+  for (const row of REQUIRED_VERIFIABILITY_ROWS) {
+    const match = section.match(
+      new RegExp(`(^|\\n)\\s*-\\s*${row.key}\\s*:\\s*(.+)$`, "im"),
+    );
+    if (!match) {
+      reasons.push(`missing '${row.key}:' row in verifiability`);
+      continue;
+    }
+    const value = toNonEmptyString(match[2]);
+    if (!value) {
+      reasons.push(`row '${row.key}:' must not be empty`);
+    }
   }
 
   const statisticalMatch = section.match(/(^|\n)\s*-\s*statistical\s*:\s*(.+)$/im);
@@ -278,6 +364,11 @@ function validateIssueBodyForInProgress(body) {
       reasons.push(`missing required PRD heading '${heading}'`);
     }
   }
+  for (const heading of REQUIRED_DOCUMENT_HEADINGS) {
+    if (!String(body || "").includes(heading)) {
+      reasons.push(`missing required document heading '${heading}'`);
+    }
+  }
 
   const verifiabilityCheck = validateVerifiabilitySection(body);
   if (!verifiabilityCheck.ok) {
@@ -359,6 +450,14 @@ function renderCreateTaskBody(payload, labels) {
     "заполнить описание задачи",
   );
   const verifiability = buildVerifiability(payload);
+  const architecture = renderBulletedValue(
+    payload.architecture,
+    "описать архитектуру, контракты компонентов и ограничения до начала кодирования",
+  );
+  const verificationPlan = renderBulletedValue(
+    payload.verificationPlan,
+    "описать детальный план проверок (unit/system/e2e_playwright/external_analysis)",
+  );
   const doneBlock = renderBulletedValue(
     payload.done,
     "[ ] Не начато",
@@ -386,10 +485,21 @@ function renderCreateTaskBody(payload, labels) {
     `- strict: ${verifiability.strict}`,
     `- statistical: ${verifiability.statistical}`,
     `- human: ${verifiability.human}`,
+    `- architecture: ${verifiability.architecture}`,
+    `- tests_unit: ${verifiability.tests_unit}`,
+    `- tests_system: ${verifiability.tests_system}`,
+    `- tests_e2e_playwright: ${verifiability.tests_e2e_playwright}`,
+    `- external_analysis: ${verifiability.external_analysis}`,
     "",
     "### Что сделано",
     doneBlock,
     "",
+    "## Architecture",
+    architecture,
+    "",
+    "## Verification Plan",
+    verificationPlan,
+    "",
     "## Metadata",
     ...metadata,
   ].join("\n");

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

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 import { resolveTrackerForCommand } from "./tracker/provider-lock.mjs";
 
 const COMMAND_MAP = {
+  VERIFY_GOVERNANCE_GATE: "__verifyGovernanceGate",
   VERIFY_IMPLEMENTATION_GATE: "__verifyImplementationGate",
   CREATE_TASK: "createTask",
   PREPARE_TASK_BRANCH: "__prepareTaskBranch",
@@ -44,7 +45,7 @@ function printHelp() {
   console.log("");
   console.log("Usage:");
   console.log(
-    "  npm run meta:ops -- --command VERIFY_IMPLEMENTATION_GATE|CREATE_TASK|PREPARE_TASK_BRANCH|RUN_MR_REVIEW_GATE|SET_STATUS|COMMIT_BY_NAME|ASSIGN_SPRINT [--tracker github|mcp|local|custom] [--payload '{\"k\":\"v\"}']",
+    "  npm run meta:ops -- --command VERIFY_GOVERNANCE_GATE|VERIFY_IMPLEMENTATION_GATE|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:");
@@ -124,6 +125,21 @@ function runImplementationGate(payload, trackerProvider) {
   }
 }
 
+function runGovernanceGate(payload, trackerProvider, command) {
+  const args = [scriptPath("verify-governance.mjs"), "--tracker", trackerProvider, "--command", command];
+  if (payload.task) {
+    args.push("--task", String(payload.task));
+  }
+  if (payload.validateLocalCache) {
+    args.push("--validate-local-cache");
+  }
+
+  const output = runNodeScript(args);
+  if (output.trim()) {
+    console.log(output.trim());
+  }
+}
+
 function parseArgs(argv) {
   const options = {
     command: "",
@@ -204,6 +220,20 @@ async function main() {
     requestedTracker: options.tracker,
     cwd: process.cwd(),
   });
+  const governanceTaskRef =
+    payload.task || payload.issue || payload.taskId || payload.id || payload.pr || "";
+  const governanceCommand =
+    options.command === "SET_STATUS" && String(payload.status || "").toUpperCase() === "IN_PROGRESS"
+      ? "VERIFY_IMPLEMENTATION_GATE"
+      : options.command;
+
+  if (adapterMethod === "__verifyGovernanceGate") {
+    runGovernanceGate({ task: governanceTaskRef, validateLocalCache: payload.validateLocalCache }, trackerProvider, governanceCommand);
+    console.log(`TrackerGateway PASS: ${options.command} via tracker '${trackerProvider}'.`);
+    return;
+  }
+
+  runGovernanceGate({ task: governanceTaskRef, validateLocalCache: payload.validateLocalCache }, trackerProvider, governanceCommand);
 
   if (adapterMethod === "__prepareTaskBranch") {
     runTaskBranchRouter(payload);

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

@@ -1,20 +1,190 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
-import { resolveLockedTrackerProvider } from "./tracker/provider-lock.mjs";
+import { execFileSync } from "node:child_process";
+import { resolveTrackerForCommand } 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"]);
+const COMMANDS_REQUIRE_TASK_CONTEXT = new Set([
+  "PREPARE_TASK_BRANCH",
+  "VERIFY_IMPLEMENTATION_GATE",
+  "RUN_REVIEW_GATE",
+  "RUN_MR_REVIEW_GATE",
+  "COMMIT_BY_NAME",
+]);
 
 const REQUIRED_PATTERNS = [
   { label: "PRD section: Описание", regex: /^###\s+Описание/m },
   { label: "PRD section: Проверяемость", regex: /^###\s+Проверяемость/m },
   { label: "PRD section: Что сделано", regex: /^###\s+Что сделано/m },
+  { label: "Document section: Architecture", regex: /^##\s+Architecture/m },
+  { label: "Document section: Verification Plan", regex: /^##\s+Verification Plan/m },
   { label: "Verifiability strict", regex: /^\s*-\s*strict:/m },
   { label: "Verifiability statistical", regex: /^\s*-\s*statistical:/m },
   { label: "Verifiability human", regex: /^\s*-\s*human:/m },
+  { label: "Verifiability architecture", regex: /^\s*-\s*architecture:/m },
+  { label: "Verifiability tests_unit", regex: /^\s*-\s*tests_unit:/m },
+  { label: "Verifiability tests_system", regex: /^\s*-\s*tests_system:/m },
+  { label: "Verifiability tests_e2e_playwright", regex: /^\s*-\s*tests_e2e_playwright:/m },
+  { label: "Verifiability external_analysis", regex: /^\s*-\s*external_analysis:/m },
 ];
 
+const REQUIRED_PRD_HEADINGS = ["### Описание", "### Проверяемость", "### Что сделано"];
+const REQUIRED_DOCUMENT_HEADINGS = ["## Architecture", "## Verification Plan"];
+const REQUIRED_VERIFIABILITY_ROWS = [
+  "strict",
+  "statistical",
+  "human",
+  "architecture",
+  "tests_unit",
+  "tests_system",
+  "tests_e2e_playwright",
+  "external_analysis",
+];
+
+function parseArgs(argv) {
+  const options = {
+    validateLocalCache: false,
+    tracker: "",
+    command: "",
+    task: "",
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--validate-local-cache") {
+      options.validateLocalCache = true;
+      continue;
+    }
+    if (arg === "--tracker") {
+      options.tracker = (argv[i + 1] || "").trim().toLowerCase();
+      i += 1;
+      continue;
+    }
+    if (arg === "--command") {
+      options.command = (argv[i + 1] || "").trim().toUpperCase();
+      i += 1;
+      continue;
+    }
+    if (arg === "--task") {
+      options.task = (argv[i + 1] || "").trim();
+      i += 1;
+    }
+  }
+
+  return options;
+}
+
+function parseIssueNumber(value) {
+  const source = String(value || "").trim();
+  if (!source) {
+    return "";
+  }
+
+  const direct = source.match(/^#?(\d+)$/);
+  if (direct) {
+    return direct[1];
+  }
+
+  const issueToken = source.match(/(?:^|[\/\s])issue-(\d+)(?:-|$|\s)/i);
+  if (issueToken) {
+    return issueToken[1];
+  }
+
+  const githubUrl = source.match(/\/issues\/(\d+)(?:$|[/?#])/i);
+  if (githubUrl) {
+    return githubUrl[1];
+  }
+
+  const ref = source.match(/#(\d+)/);
+  if (ref) {
+    return ref[1];
+  }
+
+  return "";
+}
+
+function run(command, args, allowFailure = false) {
+  try {
+    return execFileSync(command, args, {
+      cwd: process.cwd(),
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+  } catch (error) {
+    if (allowFailure) {
+      return "";
+    }
+    const stderr = String(error?.stderr || "").trim();
+    const stdout = String(error?.stdout || "").trim();
+    throw new Error(`${command} ${args.join(" ")} failed: ${stderr || stdout || error.message}`);
+  }
+}
+
+function readJson(command, args, allowFailure = false) {
+  const raw = run(command, args, allowFailure);
+  if (!raw) {
+    return null;
+  }
+  return JSON.parse(raw);
+}
+
+function ensureGhReady() {
+  run("gh", ["--version"], false);
+  const auth = run("gh", ["auth", "status"], true);
+  if (!auth) {
+    throw new Error("gh is not authenticated. Run 'gh auth login' first.");
+  }
+}
+
+function extractSection(content, heading) {
+  const source = String(content || "");
+  if (!source || !heading) {
+    return "";
+  }
+  const escapedHeading = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const regex = new RegExp(`${escapedHeading}\\s*\\n([\\s\\S]*?)(?:\\n###\\s+|$)`, "i");
+  const match = source.match(regex);
+  return (match?.[1] || "").trim();
+}
+
+function validateIssueBody(content) {
+  const reasons = [];
+  for (const heading of REQUIRED_PRD_HEADINGS) {
+    if (!String(content || "").includes(heading)) {
+      reasons.push(`missing required PRD heading '${heading}'`);
+    }
+  }
+  for (const heading of REQUIRED_DOCUMENT_HEADINGS) {
+    if (!String(content || "").includes(heading)) {
+      reasons.push(`missing required document heading '${heading}'`);
+    }
+  }
+
+  const section = extractSection(content, "### Проверяемость");
+  if (!section) {
+    reasons.push("missing section '### Проверяемость'");
+    return reasons;
+  }
+
+  for (const key of REQUIRED_VERIFIABILITY_ROWS) {
+    const match = section.match(
+      new RegExp(`(^|\\n)\\s*-\\s*${key}\\s*:\\s*(.+)$`, "im"),
+    );
+    if (!match) {
+      reasons.push(`missing '${key}:' row in verifiability`);
+      continue;
+    }
+    const value = String(match[2] || "").trim();
+    if (!value) {
+      reasons.push(`row '${key}:' must not be empty`);
+    }
+  }
+
+  return reasons;
+}
+
 async function listTaskFiles() {
   try {
     const entries = await fs.readdir(TASKS_DIR, { withFileTypes: true });
@@ -39,22 +209,56 @@ async function validateTask(filePath) {
   return failed;
 }
 
-async function main() {
-  const args = process.argv.slice(2);
-  const validateLocalCache = args.includes("--validate-local-cache");
+function validateGithubTask(taskRef) {
+  const issueNumber = parseIssueNumber(taskRef);
+  if (!issueNumber) {
+    throw new Error("missing/invalid --task for governance command that requires task context");
+  }
 
-  let trackerProvider = "";
-  try {
-    trackerProvider = resolveLockedTrackerProvider(process.cwd());
-  } catch (error) {
-    console.error(`Governance FAIL: ${error.message}`);
-    process.exit(1);
+  ensureGhReady();
+  const issueData = readJson("gh", [
+    "issue",
+    "view",
+    issueNumber,
+    "--json",
+    "number,title,body,url",
+  ]);
+  const reasons = validateIssueBody(issueData?.body || "");
+  if (reasons.length > 0) {
+    throw new Error(`issue #${issueNumber} governance FAIL: ${reasons.join("; ")}`);
   }
 
+  return issueData;
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const trackerProvider = resolveTrackerForCommand({
+    requestedTracker: options.tracker,
+    cwd: process.cwd(),
+  });
+
   const taskFiles = await listTaskFiles();
-  const localTasksRequired = trackerProvider === "local" || validateLocalCache;
+  const localTasksRequired = trackerProvider === "local" || options.validateLocalCache;
+  const commandRequiresTask = COMMANDS_REQUIRE_TASK_CONTEXT.has(options.command);
+
+  if (commandRequiresTask && !options.task) {
+    console.error(
+      `Governance FAIL: command '${options.command}' requires explicit --task for docs-first validation.`,
+    );
+    process.exit(1);
+  }
 
   if (!localTasksRequired) {
+    if (trackerProvider === "github" && commandRequiresTask) {
+      const issueData = validateGithubTask(options.task);
+      const issueNumber = String(issueData?.number || parseIssueNumber(options.task));
+      console.log(
+        `Governance PASS: docs-first check passed for issue #${issueNumber} (command ${options.command}).`,
+      );
+      return;
+    }
+
     const localCount = taskFiles ? taskFiles.length : 0;
     console.log(
       `Governance PASS: tracker provider '${trackerProvider}' is external; local task validation skipped (${localCount} file(s) in tasks/).`,

package/template/.meta-agents/scripts/verify-implementation-gate.mjs

@@ -4,6 +4,17 @@ import { resolveTrackerForCommand } from "./tracker/provider-lock.mjs";
 
 const STATUS_LABELS = ["TODO", "IN_PROGRESS", "REVIEW", "READY", "BLOCKED", "DONE", "PUBLISH"];
 const REQUIRED_PRD_HEADINGS = ["### Описание", "### Проверяемость", "### Что сделано"];
+const REQUIRED_DOCUMENT_HEADINGS = ["## Architecture", "## Verification Plan"];
+const REQUIRED_VERIFIABILITY_ROWS = [
+  "strict",
+  "statistical",
+  "human",
+  "architecture",
+  "tests_unit",
+  "tests_system",
+  "tests_e2e_playwright",
+  "external_analysis",
+];
 const IMPLEMENTATION_BRANCH_TYPES = new Set(["feature", "release", "hotfix"]);
 
 function run(command, args, allowFailure = false) {
@@ -165,6 +176,11 @@ function validateIssueBody(issueBody) {
       blockers.push(`missing required PRD heading '${heading}'`);
     }
   }
+  for (const heading of REQUIRED_DOCUMENT_HEADINGS) {
+    if (!String(issueBody || "").includes(heading)) {
+      blockers.push(`missing required document heading '${heading}'`);
+    }
+  }
 
   const verifiability = extractSection(issueBody, "### Проверяемость");
   if (!verifiability) {
@@ -172,14 +188,18 @@ function validateIssueBody(issueBody) {
     return blockers;
   }
 
-  if (!/(^|\n)\s*-\s*strict\s*:/i.test(verifiability)) {
-    blockers.push("missing 'strict:' row in verifiability");
-  }
-  if (!/(^|\n)\s*-\s*statistical\s*:/i.test(verifiability)) {
-    blockers.push("missing 'statistical:' row in verifiability");
-  }
-  if (!/(^|\n)\s*-\s*human\s*:/i.test(verifiability)) {
-    blockers.push("missing 'human:' row in verifiability");
+  for (const key of REQUIRED_VERIFIABILITY_ROWS) {
+    const match = verifiability.match(
+      new RegExp(`(^|\\n)\\s*-\\s*${key}\\s*:\\s*(.+)$`, "im"),
+    );
+    if (!match) {
+      blockers.push(`missing '${key}:' row in verifiability`);
+      continue;
+    }
+    const value = String(match[2] || "").trim();
+    if (!value) {
+      blockers.push(`row '${key}:' must not be empty`);
+    }
   }
 
   const statisticalMatch = verifiability.match(/(^|\n)\s*-\s*statistical\s*:\s*(.+)$/im);
@@ -223,6 +243,9 @@ function buildNextSteps({ issueNumber, branchType, branchTaskRef }) {
   steps.push(
     `Ensure task is IN_PROGRESS: npm run meta:ops -- --command SET_STATUS --payload '{\"task\":\"#${issueNumber}\",\"status\":\"IN_PROGRESS\"}'`,
   );
+  steps.push(
+    "Complete docs-first gate: PRD + Architecture + Verification Plan + tests matrix (unit/system/e2e_playwright) + external analysis.",
+  );
   steps.push(
     `Run branch preflight: npm run meta:task-start -- --task \"#${issueNumber}\" --slug <slug> --kind feature`,
   );
@@ -251,7 +274,7 @@ function printHuman(report) {
   console.log("## Checks");
   console.log(`- issue: ${report.issue.number ? `#${report.issue.number}` : "not detected"}`);
   console.log(`- issue status: ${report.issue.status || "not detected"}`);
-  console.log(`- prd/verifiability: ${report.prdOk ? "PASS" : "FAIL"}`);
+  console.log(`- prd/architecture/verification matrix: ${report.prdOk ? "PASS" : "FAIL"}`);
   console.log(`- branch alignment: ${report.branchAligned ? "PASS" : "FAIL"}`);
 
   console.log("");

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

@@ -8,6 +8,10 @@
 - Required Outputs:
 - Required Evidence:
 - Acceptance Criteria:
+- Coding Start Gate (PASS required before any code edits):
+  - PRD Description complete
+  - Architecture documented
+  - Verification matrix complete (unit/system/e2e_playwright/external_analysis)
 - Failure/Escalation Rules:
 - Tracker Binding (task/status/sprint):
 - Git Strategy (Git Flow Lite: feature/* -> develop, release/* -> main + back-merge, hotfix/* -> main + back-merge):

package/template/.meta-agents/templates/evidence-pack.md

@@ -2,6 +2,10 @@
 
 - Task ID:
 - Build/Test artifacts:
+- Unit tests:
+- System tests:
+- Playwright e2e:
+- External agent analysis:
 - Eval metrics:
 - Trace/Logs:
 - Commit refs:

package/template/.meta-agents/templates/prd-step.md

@@ -3,10 +3,19 @@
 ### Описание
 - Что и зачем делаем на этапе.
 
+## Architecture
+- Контекст и ограничения архитектуры.
+- Контракты компонентов (вход/выход, инварианты).
+
 ### Проверяемость
 - strict:
 - statistical:
 - human:
+- architecture:
+- tests_unit:
+- tests_system:
+- tests_e2e_playwright:
+- external_analysis:
 - evidence:
 
 ### Что сделано

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

@@ -17,10 +17,19 @@
 ## PRD Step
 ### Описание
 -
+## Architecture
+- Контекст:
+- Компоненты/контракты:
+- Ограничения и инварианты:
 ### Проверяемость
 - strict:
 - statistical:
 - human:
+- architecture:
+- tests_unit:
+- tests_system:
+- tests_e2e_playwright:
+- external_analysis:
 ### Что сделано
 - [ ] Не начато
 
@@ -28,7 +37,11 @@
 -
 
 ## Evidence
--
+- Unit tests report:
+- System tests report:
+- Playwright e2e report:
+- External analysis report:
+- Tracker links:
 
 ## Progress Log
 - YYYY-MM-DD: created

package/template/.meta-agents/templates/verification-plan.md

@@ -3,13 +3,24 @@
 ## Scope
 -
 
-## Checks
-- strict:
-- statistical:
-- human:
+## Architecture Validation
+- архитектурные ограничения и инварианты зафиксированы
+- контракты компонентов проверяемы и трассируемы
+
+## Test Matrix
+- unit:
+- system:
+- e2e_playwright:
+
+## External Analysis
+- независимый агентный анализ по ключевым рискам и решениям
+- ссылки на отчеты/артефакты
 
 ## Metrics & Thresholds
--
+- statistical:
+
+## Human Approval
+- human:
 
 ## Evidence Mapping
 - criterion -> proof artifact

package/template/agents.md

@@ -26,6 +26,15 @@
 Правило запуска этапа:
 - если не заполнены `Описание` и `Проверяемость`, этап не стартует.
 
+## 2.1) Закон No-Code-Before-PRD
+До выполнения любых кодовых изменений (`write/edit/refactor/test-fix`) обязательно должны быть зафиксированы:
+- PRD с заполненными `Описание` и `Проверяемость`;
+- архитектурное решение (контекст, ограничения, контракты компонентов);
+- верификационная матрица минимум: `unit`, `system`, `e2e_playwright`, `external_analysis`;
+- evidence-план и критерии PASS/FAIL.
+
+Если любой пункт отсутствует, агент обязан остановить реализацию и сначала завершить PRD/архитектуру/проверки.
+
 ## 3) Роли агентов
 - `Chief of Staff Agent`: оркестрация цепочки, приоритеты, блокеры, эскалации.
 - `Status Agent`: сводный статус проекта (`tracker/sprint/task/git`) по запросам состояния.
@@ -92,6 +101,12 @@ Name: <agent role>
 - `statistical`: benchmark/метрики/judge score/пороговые значения.
 - `human`: review/approval в рискованных и неоднозначных точках.
 
+Минимальный обязательный набор перед стартом кодирования:
+- unit tests plan;
+- system tests plan;
+- e2e tests plan на Playwright;
+- независимый внешний анализ (другой агент/роль) по ключевым решениям и рискам.
+
 ## 7) AgentWorkContract
 Перед передачей задачи Executor-агенту фиксируется контракт:
 - scope;
@@ -205,18 +220,32 @@ Name: <agent role>
 23. Коммит следует формату `#issue-number <summary>` (issue ref в начале сообщения).
 24. Для branch routing собран e2e evidence по двум сценариям: `same feature` и `different feature`.
 25. Перед `--apply` подтверждена консистентность контекста `AGENTS.md` (fallback: `agents.md`) или явно подтверждён осознанный switch при diff.
+26. До любых кодовых правок заполнены архитектурные артефакты задачи (контекст, ограничения, контракты).
+27. В `Проверяемость` явно зафиксированы `tests_unit`, `tests_system`, `tests_e2e_playwright`.
+28. Для ключевых задач выполнен `external_analysis` (независимый агентный review) с evidence-ссылкой.
+29. Запуск кодирования разрешён только после `VERIFY_IMPLEMENTATION_GATE: PASS`.
+30. Если диалог уходит за рамки текущей задачи, агент сначала предлагает `CREATE_TASK` или возвращает диалог в рамки текущей задачи; кодирование до решения запрещено.
 
 Если хотя бы один критерий не выполнен, задача не принимается.
 
 ## 12) Verification-first gate
 Реализация не начинается, пока не определены:
 - acceptance criteria;
+- архитектура и контракты компонентов;
 - метрики и пороги;
 - инварианты и ограничения;
 - процедуры проверки;
+- test matrix (`unit`, `system`, `e2e_playwright`);
+- внешний независимый анализ по критическим зонам;
 - зоны неопределённости и правила эскалации;
 - способ фиксации в трекере.
 
+## 12.1) Контроль рамок задачи в диалоге
+Если пользовательский запрос выходит за рамки текущей задачи, агент обязан:
+1. Остановить кодовые действия.
+2. Предложить завести новую задачу (`CREATE_TASK`) или явно продолжить текущую.
+3. До фиксации решения продолжать только PRD/архитектурное/валидационное оформление.
+
 ## 13) Реакция на провал проверки
 Допустимые сценарии:
 - `retry` с корректировками;
@@ -226,4 +255,4 @@ Name: <agent role>
 - возврат статуса задачи в `IN_PROGRESS` или `BLOCKED`.
 
 ## 14) Главный инвариант
-Нельзя делегировать работу и нельзя закрывать задачу без формализованных критериев приёмки, PRD-блока `Проверяемость` и требуемых доказательств в трекере.
+Нельзя делегировать работу, писать код и закрывать задачу без формализованных критериев приёмки, PRD-блока `Проверяемость`, архитектурного описания и требуемых доказательств в трекере.

package/template/tracker-command-template.md

@@ -27,7 +27,7 @@ Name: Governance Watchdog Agent
 
 Governance Watchdog Agent: verify governance gate,
 task <#issue>,
-required checks "prd_sections_complete, acceptance_defined, user_confirmation_policy_respected",
+required checks "prd_sections_complete, architecture_documented, verification_matrix(unit/system/e2e_playwright/external_analysis), acceptance_defined, user_confirmation_policy_respected, no_code_before_prd",
 result PASS
 ```
 
@@ -41,6 +41,15 @@ result PASS
 - Если пользователь явно не запросил смену provider и конфиг не обновлён, команды выполняются только через `__DEFAULT_TRACKER__`.
 - CLI enforcement: `npm run meta:ops -- --command <COMMAND> [--tracker ...]` блокирует выполнение при mismatch provider.
 
+## 0.3) Жёсткий закон до начала кодирования
+Перед реализацией обязателен порядок:
+1. `Описание`.
+2. `Архитектура`.
+3. `Проверяемость` (включая `tests_unit`, `tests_system`, `tests_e2e_playwright`, `external_analysis`).
+4. `VERIFY_IMPLEMENTATION_GATE: PASS`.
+
+До пункта 4 кодовые изменения запрещены.
+
 ## 1) Ключевое правило подтверждения пользователя
 Только по явному подтверждению пользователя в текущем диалоге разрешены:
 - `COMMIT_BY_NAME`;
@@ -70,6 +79,7 @@ result PASS
 - если задача не относится к текущей ветке, требуется: проверить dirty/ahead, согласовать действие с пользователем, перейти на `develop` (или `main` для hotfix), обновить и создать новую ветку;
 - перед `--apply` обязателен контекстный check: сравнить `AGENTS.md` (fallback: `agents.md`) текущей и базовой ветки, при diff запросить явное подтверждение пользователя;
 - сообщение коммита обязательно следует формату `#issue-number <summary>` (issue ref в начале).
+- если диалог ушёл за рамки текущей задачи, сначала предложить `CREATE_TASK` или завершить текущую задачу; кодирование до решения запрещено.
 
 Для GitHub трекера статус issue задаётся label-ом (одновременно только один статус из набора):
 - `TODO`
@@ -102,7 +112,7 @@ Name: Governance Watchdog Agent
 
 Governance Watchdog Agent: verify governance gate,
 task #12,
-checklist "PRD(Описание+Проверяемость), hard criteria, user confirmation policy",
+checklist "PRD(Описание+Проверяемость), architecture, verification matrix(unit/system/e2e_playwright/external_analysis), hard criteria, user confirmation policy, no-code-before-prd",
 result PASS
 ```
 
@@ -154,7 +164,7 @@ repo your-org/your-repo,
 short name "API редирект офферов",
 owner "Engineering Agent",
 description "Добавить API редиректа на офферы",
-verifiability "strict: schema+contracts; statistical: p95 latency < 200ms; human: reviewer approval required",
+verifiability "strict: schema+contracts; statistical: p95 latency < 200ms; human: reviewer approval required; architecture: contracts documented; tests_unit: required; tests_system: required; tests_e2e_playwright: required; external_analysis: required",
 sprint "SPRINT-3"
 ```
 
@@ -204,7 +214,7 @@ Governance Watchdog Agent: verify implementation gate,
 tracker __DEFAULT_TRACKER__,
 task #12,
 command "npm run meta:implementation-gate -- --task #12",
-required checks "issue_status_in_progress, prd_sections_complete, verifiability(strict/statistical/human), branch_alignment",
+required checks "issue_status_in_progress, prd_sections_complete, architecture_documented, verifiability(strict/statistical/human), tests_matrix(unit/system/e2e_playwright), external_analysis_defined, branch_alignment, no_code_before_pass",
 result PASS
 ```
 
@@ -427,6 +437,11 @@ reason "вошло в релиз v0.1.2"
 - strict:
 - statistical:
 - human:
+- architecture:
+- tests_unit:
+- tests_system:
+- tests_e2e_playwright:
+- external_analysis:
 - evidence:
 
 ### Что сделано
@@ -441,18 +456,19 @@ reason "вошло в релиз v0.1.2"
 3. `PREPARE_TASK_BRANCH`.
 4. `SET_STATUS -> IN_PROGRESS`.
 5. `VERIFY_IMPLEMENTATION_GATE`.
-6. Реализация + evidence.
-7. `SET_STATUS -> REVIEW`.
-8. `RUN_REVIEW_GATE` (получить report + `PASS_CANDIDATE`/`FAIL`).
-9. Пользователь подтверждает review (`Review Approved: yes`).
-10. `RUN_REVIEW_GATE` -> `PASS_CONFIRMED`.
-11. `COMMIT_BY_NAME` только после review PASS_CONFIRMED и отдельного подтверждения пользователя на коммит.
-12. Push + open PR в целевую ветку по Git Flow Lite.
-13. `RUN_MR_REVIEW_GATE` (получить report + `PASS_CANDIDATE`/`FAIL`).
-14. Пользователь подтверждает MR review (`MR Review Approved: yes`).
-15. `RUN_MR_REVIEW_GATE` -> `PASS_CONFIRMED`.
-16. Merge PR по Git Flow Lite.
-17. `SET_STATUS -> READY`.
-18. `SET_STATUS -> DONE` только после подтверждения пользователя.
-19. `PREPARE_RELEASE_NOTE` (какие задачи вошли в релиз).
-20. Для релизных задач после публикации: `MARK_TASKS_PUBLISH` (`SET_STATUS -> PUBLISH` для всех вошедших задач).
+6. Только после `VERIFY_IMPLEMENTATION_GATE: PASS` разрешена реализация.
+7. Реализация + evidence.
+8. `SET_STATUS -> REVIEW`.
+9. `RUN_REVIEW_GATE` (получить report + `PASS_CANDIDATE`/`FAIL`).
+10. Пользователь подтверждает review (`Review Approved: yes`).
+11. `RUN_REVIEW_GATE` -> `PASS_CONFIRMED`.
+12. `COMMIT_BY_NAME` только после review PASS_CONFIRMED и отдельного подтверждения пользователя на коммит.
+13. Push + open PR в целевую ветку по Git Flow Lite.
+14. `RUN_MR_REVIEW_GATE` (получить report + `PASS_CANDIDATE`/`FAIL`).
+15. Пользователь подтверждает MR review (`MR Review Approved: yes`).
+16. `RUN_MR_REVIEW_GATE` -> `PASS_CONFIRMED`.
+17. Merge PR по Git Flow Lite.
+18. `SET_STATUS -> READY`.
+19. `SET_STATUS -> DONE` только после подтверждения пользователя.
+20. `PREPARE_RELEASE_NOTE` (какие задачи вошли в релиз).
+21. Для релизных задач после публикации: `MARK_TASKS_PUBLISH` (`SET_STATUS -> PUBLISH` для всех вошедших задач).