ai-execution-protocol 0.1.0

package/scripts/npm_install_protocol.js

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+const root = path.resolve(__dirname, "..");
+const markerStart = "<!-- AI_PROTOCOL_BEGIN -->";
+const markerEnd = "<!-- AI_PROTOCOL_END -->";
+const protocolFiles = [
+  "README.yaml",
+  "fast-path.yaml",
+  "router.yaml",
+  "modes.yaml",
+  "execution-rules.yaml",
+  "risk-levels.yaml",
+  "mapping-checklists.yaml",
+  "validation-checklist.yaml",
+  "context-rules.yaml",
+  "context-compiler.yaml",
+  "formatting-rules.yaml",
+  "prompt-economy.yaml",
+  "spec-driven.yaml",
+];
+const aiignoreLines = [
+  "results/",
+  "benchmarks/generated/",
+  "model-runs/generated/",
+  "dist/",
+  "scripts/__pycache__/",
+  "*.pyc",
+];
+const requiredText = {
+  "AGENTS.md": [
+    "AI_PROTOCOL_BEGIN",
+    "protocol/fast-path.yaml",
+    "protocol/router.yaml",
+    "Classifique o risco antes de agir",
+    "Nenhum arquivo deve passar de 400 linhas.",
+  ],
+  ".aiignore": ["results/", "dist/", "*.pyc"],
+  "protocol/router.yaml": ["feature_or_spec", "spec-driven.yaml", "prompt_improvement"],
+  "protocol/spec-driven.yaml": ["protocol_is_base_spec_is_tool", "do_not_create_spec_for_low_value_tasks"],
+};
+
+function readText(file) {
+  return fs.readFileSync(file, "utf8");
+}
+
+function writeText(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text, "utf8");
+}
+
+function sourceProtocolDir() {
+  const direct = path.join(root, "protocol");
+  if (fs.existsSync(path.join(direct, "fast-path.yaml"))) return direct;
+  return path.join(root, "dist", "minimal", "protocol");
+}
+
+function minimalAgents() {
+  const file = path.join(root, "dist", "minimal", "AGENTS.md");
+  if (fs.existsSync(file)) return readText(file);
+  return `# AGENTS.md
+
+## Regra principal
+
+${markerStart}
+
+Use \`protocol/fast-path.yaml\` como entrada operacional minima.
+
+Siga \`.aiignore\` antes de abrir relatorios gerados.
+
+Este protocolo e obrigatorio para tarefas tecnicas neste projeto. Antes de
+editar, classifique risco, escolha rota e valide a entrega.
+
+## Ordem de leitura
+
+1. \`protocol/fast-path.yaml\`
+2. \`protocol/router.yaml\`
+3. Arquivo YAML especifico em \`protocol/\` conforme a rota.
+
+## Regras de execucao
+
+- Classifique o risco antes de agir.
+- Use o menor contexto suficiente.
+- Leia apenas os arquivos indicados por \`protocol/router.yaml\`.
+- Quando houver contexto grande, historico longo ou risco de confusao, use
+  \`protocol/context-compiler.yaml\` antes de abrir muitos arquivos.
+- Use \`protocol/spec-driven.yaml\` para feature, refatoracao grande ou tarefa
+  critica, sem criar spec pesada para tarefa simples.
+- Sempre entregue \`Prompt original\` e \`Prompt melhorado da IA\`; em baixo risco,
+  prefira micro formato legivel com \`PO\`, \`PM\` e \`OK\`.
+- Nao edite arquivo que nao foi identificado como candidato.
+- Preserve documentos, regras de IDE e configuracoes de framework existentes,
+  salvo pedido explicito do usuario.
+- Se o risco subir, atualize a classificacao antes de continuar.
+- Para nivel critico, peca confirmacao antes de acao sensivel.
+- Quando houver risco de quebrar fluxo existente, entregue uma lista do que
+  testar.
+- Entregue com evidencia em poucas linhas: mudanca, validacao, limite e risco
+  residual.
+- Explique o resultado em linguagem clara para uma pessoa leiga entender.
+
+## Convivencia com arquivos existentes
+
+Quando houver conflito, siga esta prioridade:
+
+1. pedido atual do usuario;
+2. este bloco obrigatorio em \`AGENTS.md\`;
+3. regras especificas da IDE ou do projeto;
+4. docs e historico somente quando a rota pedir.
+
+Nao sobrescreva \`README.md\`, \`docs/\`, \`.cursorrules\`, \`CLAUDE.md\`,
+\`.github/copilot-instructions.md\` ou configs de framework sem pedido claro.
+
+## Regras de organizacao
+
+- Nenhum arquivo deve passar de 400 linhas.
+- Organize primeiro para legibilidade por IA.
+- Use YAML para regras operacionais.
+- Evite duplicar a mesma regra em muitos lugares.
+
+${markerEnd}
+`;
+}
+
+function protocolBlock() {
+  const text = minimalAgents();
+  const start = text.indexOf(markerStart);
+  const end = text.indexOf(markerEnd) + markerEnd.length;
+  return text.slice(start, end);
+}
+
+function copyRecursive(source, target) {
+  const stat = fs.statSync(source);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(target, { recursive: true });
+    for (const item of fs.readdirSync(source)) {
+      copyRecursive(path.join(source, item), path.join(target, item));
+    }
+    return;
+  }
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.copyFileSync(source, target);
+}
+
+function backup(existingPath, backupRoot) {
+  if (!fs.existsSync(existingPath)) return;
+  fs.mkdirSync(backupRoot, { recursive: true });
+  copyRecursive(existingPath, path.join(backupRoot, path.basename(existingPath)));
+}
+
+function timestamp() {
+  return new Date().toISOString().replace(/\D/g, "").slice(0, 14);
+}
+
+function printDryRun(targetRoot, force) {
+  console.log(`DRY-RUN target -> ${path.resolve(targetRoot)}`);
+  console.log(`${fs.existsSync(path.join(targetRoot, "AGENTS.md")) ? "update" : "create"}:AGENTS.md`);
+  console.log(`${fs.existsSync(path.join(targetRoot, ".aiignore")) ? "update" : "create"}:.aiignore`);
+  const protocolDir = path.join(targetRoot, "protocol");
+  if (fs.existsSync(protocolDir) && force) {
+    console.log("backup:protocol/");
+    console.log("replace:protocol/");
+  } else if (fs.existsSync(protocolDir)) {
+    console.log("keep:protocol/");
+  } else {
+    console.log("create:protocol/");
+  }
+}
+
+function installAgents(target) {
+  const block = protocolBlock();
+  if (!fs.existsSync(target)) {
+    writeText(target, minimalAgents());
+    return;
+  }
+  const text = readText(target);
+  if (text.includes(markerStart) && text.includes(markerEnd)) {
+    const before = text.slice(0, text.indexOf(markerStart)).trimEnd();
+    const after = text.slice(text.indexOf(markerEnd) + markerEnd.length);
+    writeText(target, `${before}\n\n${block}${after}`.trim() + "\n");
+    return;
+  }
+  writeText(target, `${block}\n\n## Instrucoes existentes do projeto\n\n${text}`.trim() + "\n");
+}
+
+function installAiignore(target) {
+  const existing = fs.existsSync(target) ? readText(target).split(/\r?\n/).filter(Boolean) : [];
+  for (const line of aiignoreLines) {
+    if (!existing.includes(line)) existing.push(line);
+  }
+  writeText(target, existing.join("\n").trim() + "\n");
+}
+
+function copyProtocol(target, force, backupRoot) {
+  if (fs.existsSync(target) && !force) return;
+  if (fs.existsSync(target)) {
+    backup(target, backupRoot);
+    fs.rmSync(target, { recursive: true, force: true });
+  }
+  fs.mkdirSync(target, { recursive: true });
+  const source = sourceProtocolDir();
+  for (const file of protocolFiles) {
+    fs.copyFileSync(path.join(source, file), path.join(target, file));
+  }
+}
+
+function install(target, force, dryRun) {
+  const targetRoot = path.resolve(target);
+  if (dryRun) {
+    printDryRun(targetRoot, force);
+    return 0;
+  }
+  fs.mkdirSync(targetRoot, { recursive: true });
+  const backupRoot = path.join(targetRoot, ".ai-protocol-backup", timestamp());
+  backup(path.join(targetRoot, "AGENTS.md"), backupRoot);
+  backup(path.join(targetRoot, ".aiignore"), backupRoot);
+  installAgents(path.join(targetRoot, "AGENTS.md"));
+  installAiignore(path.join(targetRoot, ".aiignore"));
+  copyProtocol(path.join(targetRoot, "protocol"), force, backupRoot);
+  console.log(`installed protocol -> ${targetRoot}`);
+  return verify(targetRoot);
+}
+
+function verify(target) {
+  const targetRoot = path.resolve(target);
+  const errors = [];
+  const requiredFiles = ["AGENTS.md", ".aiignore", ...protocolFiles.map((file) => `protocol/${file}`)];
+  for (const item of requiredFiles) {
+    const file = path.join(targetRoot, item);
+    if (!fs.existsSync(file)) {
+      errors.push(`missing:${item}`);
+      continue;
+    }
+    if (fs.statSync(file).isFile() && readText(file).split(/\r?\n/).length > 400) {
+      errors.push(`line_limit:${item}`);
+    }
+  }
+  for (const [item, snippets] of Object.entries(requiredText)) {
+    const file = path.join(targetRoot, item);
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) continue;
+    const text = readText(file);
+    for (const snippet of snippets) {
+      if (!text.includes(snippet)) errors.push(`missing_text:${item}:${snippet}`);
+    }
+  }
+  if (errors.length) {
+    console.log("FAIL");
+    for (const error of errors) console.log(error);
+    return 1;
+  }
+  console.log("PASS");
+  return 0;
+}
+
+function parseArgs(argv) {
+  const command = argv[0] || "install";
+  const flags = new Set(argv.filter((item) => item.startsWith("-")));
+  const target = argv.slice(1).find((item) => !item.startsWith("-")) || ".";
+  return {
+    command,
+    target,
+    force: !flags.has("--no-force"),
+    dryRun: flags.has("--dry-run"),
+  };
+}
+
+const parsed = parseArgs(process.argv.slice(2));
+if (parsed.command === "install" || parsed.command === "init") {
+  process.exit(install(parsed.target, parsed.force, parsed.dryRun));
+}
+if (parsed.command === "verify" || parsed.command === "--verify-only") {
+  process.exit(verify(parsed.target));
+}
+
+console.error("usage: ai-protocol install|init|verify [target] [--dry-run] [--no-force]");
+process.exit(1);

package/scripts/verify_install.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""Verify that a target project has the mandatory AI protocol installed."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+
+REQUIRED_FILES = [
+    "AGENTS.md",
+    ".aiignore",
+    "protocol/README.yaml",
+    "protocol/fast-path.yaml",
+    "protocol/router.yaml",
+    "protocol/modes.yaml",
+    "protocol/execution-rules.yaml",
+    "protocol/risk-levels.yaml",
+    "protocol/mapping-checklists.yaml",
+    "protocol/validation-checklist.yaml",
+    "protocol/context-rules.yaml",
+    "protocol/context-compiler.yaml",
+    "protocol/formatting-rules.yaml",
+    "protocol/prompt-economy.yaml",
+    "protocol/spec-driven.yaml",
+]
+
+REQUIRED_TEXT = {
+    "AGENTS.md": [
+        "AI_PROTOCOL_BEGIN",
+        "protocol/fast-path.yaml",
+        "protocol/router.yaml",
+        "Classifique o risco antes de agir",
+        "Prompt original",
+        "Prompt melhorado da IA",
+        "lista do que",
+        "Nenhum arquivo deve passar de 400 linhas.",
+    ],
+    ".aiignore": [
+        "results/",
+        "dist/",
+        "*.pyc",
+    ],
+    "protocol/router.yaml": [
+        "feature_or_spec",
+        "spec-driven.yaml",
+        "prompt_improvement",
+    ],
+    "protocol/spec-driven.yaml": [
+        "protocol_is_base_spec_is_tool",
+        "do_not_create_spec_for_low_value_tasks",
+    ],
+}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--target", required=True, help="Project root to verify")
+    args = parser.parse_args()
+
+    root = Path(args.target).resolve()
+    errors: list[str] = []
+
+    for item in REQUIRED_FILES:
+        path = root / item
+        if not path.exists():
+            errors.append(f"missing:{item}")
+            continue
+        if path.is_file() and len(path.read_text(encoding="utf-8").splitlines()) > 400:
+            errors.append(f"line_limit:{item}")
+
+    for item, snippets in REQUIRED_TEXT.items():
+        path = root / item
+        if not path.exists() or not path.is_file():
+            continue
+        text = path.read_text(encoding="utf-8")
+        for snippet in snippets:
+            if snippet not in text:
+                errors.append(f"missing_text:{item}:{snippet}")
+
+    if errors:
+        print("FAIL")
+        for error in errors:
+            print(error)
+        return 1
+
+    print("PASS")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())