ai-execution-protocol 0.2.0 → 0.3.0

package/scripts/build_dist.py

@@ -3,6 +3,7 @@
 
 from __future__ import annotations
 
+import json
 import shutil
 from pathlib import Path
 
@@ -10,88 +11,7 @@ from pathlib import Path
 ROOT = Path(__file__).resolve().parents[1]
 DIST = ROOT / "dist" / "minimal"
 PYTHON_PACKAGE_PROTOCOL = ROOT / "ai_execution_protocol" / "protocol"
-
-
-PROTOCOL_FILES = [
-    "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",
-    "persistent-context.yaml",
-    "formatting-rules.yaml",
-    "prompt-economy.yaml",
-    "spec-driven.yaml",
-]
-
-
-MINIMAL_AGENTS = """# AGENTS.md
-
-## Regra principal
-
-<!-- AI_PROTOCOL_BEGIN -->
-
-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.
-
-<!-- AI_PROTOCOL_END -->
-"""
+PYTHON_PACKAGE_TEMPLATES = ROOT / "ai_execution_protocol" / "templates" / "minimal"
 
 
 MINIMAL_README = """# Minimal AI Protocol
@@ -157,18 +77,15 @@ O `install.ps1` tambem roda a verificacao. O resultado esperado e `PASS`.
 """
 
 
-MINIMAL_AIIGNORE = """# Context files ignored by default for AI reading.
-
-results/
-benchmarks/generated/
-model-runs/generated/
-dist/
-scripts/__pycache__/
-*.pyc
-"""
+def copy_tree(source: Path, target: Path) -> None:
+    if target.exists():
+        shutil.rmtree(target)
+    shutil.copytree(source, target)
 
 
 def main() -> int:
+    manifest = json.loads((ROOT / "install-manifest.json").read_text(encoding="utf-8"))
+    protocol_files = manifest["protocol_files"]
     if DIST.exists():
         shutil.rmtree(DIST)
     (DIST / "protocol").mkdir(parents=True, exist_ok=True)
@@ -176,13 +93,14 @@ def main() -> int:
         shutil.rmtree(PYTHON_PACKAGE_PROTOCOL)
     PYTHON_PACKAGE_PROTOCOL.mkdir(parents=True, exist_ok=True)
 
-    (DIST / "AGENTS.md").write_text(MINIMAL_AGENTS, encoding="utf-8")
+    shutil.copytree(ROOT / "templates" / "minimal", DIST, dirs_exist_ok=True)
     (DIST / "README.md").write_text(MINIMAL_README, encoding="utf-8")
-    (DIST / ".aiignore").write_text(MINIMAL_AIIGNORE, encoding="utf-8")
-    for name in PROTOCOL_FILES:
+    for name in protocol_files:
         shutil.copy2(ROOT / "protocol" / name, DIST / "protocol" / name)
         shutil.copy2(ROOT / "protocol" / name, PYTHON_PACKAGE_PROTOCOL / name)
     (PYTHON_PACKAGE_PROTOCOL / "__init__.py").write_text("", encoding="utf-8")
+    shutil.copy2(ROOT / "install-manifest.json", ROOT / "ai_execution_protocol" / "install-manifest.json")
+    copy_tree(ROOT / "templates" / "minimal", PYTHON_PACKAGE_TEMPLATES)
 
     print(f"built {DIST}")
     return 0

package/scripts/npm_install_protocol.js

@@ -6,42 +6,10 @@ 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",
-  "persistent-context.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"],
-};
+const manifest = JSON.parse(fs.readFileSync(path.join(root, "install-manifest.json"), "utf8"));
+const protocolFiles = manifest.protocol_files;
+const aiignoreLines = manifest.aiignore_lines;
+const requiredText = manifest.required_text;
 
 function readText(file) {
   return fs.readFileSync(file, "utf8");
@@ -60,69 +28,7 @@ function sourceProtocolDir() {
 
 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}
-`;
+  return readText(file);
 }
 
 function protocolBlock() {
@@ -194,6 +100,18 @@ function installAiignore(target) {
   writeText(target, existing.join("\n").trim() + "\n");
 }
 
+function writeIfMissing(file, text) {
+  if (fs.existsSync(file)) return;
+  writeText(file, text);
+}
+
+function installContextTemplates(targetRoot) {
+  for (const item of manifest.required_files) {
+    if (item === "AGENTS.md" || item === ".aiignore") continue;
+    writeIfMissing(path.join(targetRoot, item), readText(path.join(root, "dist", "minimal", item)));
+  }
+}
+
 function copyProtocol(target, force, backupRoot) {
   if (fs.existsSync(target) && !force) return;
   if (fs.existsSync(target)) {
@@ -219,6 +137,7 @@ function install(target, force, dryRun) {
   backup(path.join(targetRoot, ".aiignore"), backupRoot);
   installAgents(path.join(targetRoot, "AGENTS.md"));
   installAiignore(path.join(targetRoot, ".aiignore"));
+  installContextTemplates(targetRoot);
   copyProtocol(path.join(targetRoot, "protocol"), force, backupRoot);
   console.log(`installed protocol -> ${targetRoot}`);
   return verify(targetRoot);
@@ -227,7 +146,10 @@ function install(target, force, dryRun) {
 function verify(target) {
   const targetRoot = path.resolve(target);
   const errors = [];
-  const requiredFiles = ["AGENTS.md", ".aiignore", ...protocolFiles.map((file) => `protocol/${file}`)];
+  const requiredFiles = [
+    ...manifest.required_files,
+    ...protocolFiles.map((file) => `protocol/${file}`),
+  ];
   for (const item of requiredFiles) {
     const file = path.join(targetRoot, item);
     if (!fs.existsSync(file)) {

package/scripts/verify_install.py

@@ -1,76 +1,34 @@
 #!/usr/bin/env python3
-"""Verify that a target project has the mandatory AI protocol installed."""
+"""Verify an installed protocol using the shared install manifest."""
 
 from __future__ import annotations
 
 import argparse
+import json
 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/persistent-context.yaml",
-    "protocol/formatting-rules.yaml",
-    "protocol/prompt-economy.yaml",
-    "protocol/spec-driven.yaml",
-]
+ROOT = Path(__file__).resolve().parents[1]
 
-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 load_manifest() -> dict:
+    return json.loads((ROOT / "install-manifest.json").read_text(encoding="utf-8"))
 
-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:
+def verify(root: Path) -> list[str]:
+    manifest = load_manifest()
+    required = manifest["required_files"] + [
+        f"protocol/{name}" for name in manifest["protocol_files"]
+    ]
+    errors = []
+    for item in required:
         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():
+    for item, snippets in manifest["required_text"].items():
         path = root / item
         if not path.exists() or not path.is_file():
             continue
@@ -78,15 +36,18 @@ def main() -> int:
         for snippet in snippets:
             if snippet not in text:
                 errors.append(f"missing_text:{item}:{snippet}")
+    return errors
 
-    if errors:
-        print("FAIL")
-        for error in errors:
-            print(error)
-        return 1
 
-    print("PASS")
-    return 0
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--target", required=True, help="Project root to verify")
+    args = parser.parse_args()
+    errors = verify(Path(args.target).resolve())
+    print("PASS" if not errors else "FAIL")
+    for error in errors:
+        print(error)
+    return 1 if errors else 0
 
 
 if __name__ == "__main__":

package/templates/minimal/.aiignore

@@ -0,0 +1,8 @@
+results/
+benchmarks/generated/
+model-runs/generated/
+dist/
+memory/archive/
+candidate-memory/
+scripts/__pycache__/
+*.pyc

package/templates/minimal/AGENTS.md

@@ -0,0 +1,41 @@
+# AGENTS.md
+
+## Regra principal
+
+<!-- AI_PROTOCOL_BEGIN -->
+
+Use `protocol/fast-path.yaml` como entrada operacional minima.
+
+Este protocolo e obrigatorio para tarefas tecnicas. Classifique risco, escolha
+rota, consulte o pack compacto, carregue somente memoria relevante e valide a
+entrega.
+
+## Ordem de leitura
+
+1. `protocol/fast-path.yaml`
+2. `protocol/router.yaml`
+3. `protocol/route-packs.yaml`
+4. `memory/INDEX.yaml` somente quando memoria puder ajudar
+5. YAML completo da rota somente quando o pack nao bastar
+
+## Regras de execucao
+
+- Classifique o risco antes de agir.
+- Use o menor contexto suficiente e respeite `protocol/context-budget.yaml`.
+- Memoria orienta; pedido atual autoriza; codigo verificado define realidade.
+- Nunca amplie escopo com base em previsao ou preferencia antiga.
+- Use `protocol/selective-validation.yaml` para escolher a menor prova suficiente.
+- Ao terminar, verifique memoria: updated, unchanged, candidate, replaced ou
+  blocked_sensitive.
+- Nao persista segredo, token, dado de cliente ou informacao pessoal desnecessaria.
+- Para nivel critico, peca confirmacao antes de acao sensivel.
+- Entregue mudanca, validacao, limite e risco residual em poucas linhas.
+
+## Regras de organizacao
+
+- Nenhum arquivo fonte deve passar de 400 linhas.
+- Organize por assunto rastreavel.
+- Use YAML para operacao e Markdown para explicacao.
+- Evite duplicar regras e memoria.
+
+<!-- AI_PROTOCOL_END -->

package/templates/minimal/candidate-memory/README.md

@@ -0,0 +1,4 @@
+# Candidate Memory
+
+Store inferred, non-sensitive memory candidates here until evidence or user
+confirmation is enough for promotion.

package/templates/minimal/canonical-state.yaml

@@ -0,0 +1,16 @@
+id: canonical_state
+type: project_state
+version: 0.3
+purpose: small_current_truth_summary_for_ai_navigation
+status: bootstrap_template
+truth_order:
+  - current_user_request
+  - verified_current_files
+  - active_project_decisions
+  - explicit_user_preferences
+  - inferred_patterns_with_evidence
+  - project_docs
+  - conversation_history
+notes:
+  - memory_guides_current_request_authorizes
+  - update_when_verified_project_state_changes

package/templates/minimal/context-map.yaml

@@ -0,0 +1,22 @@
+id: project_context_map
+type: context_map
+version: 0.3
+purpose: small_index_for_progressive_context_retrieval
+maintenance:
+  current_mode: manual_bootstrap
+  rule: aliases_are_pointers_not_truth
+read_first:
+  - canonical-state.yaml
+  - protocol/fast-path.yaml
+  - protocol/router.yaml
+  - protocol/route-packs.yaml
+  - memory/INDEX.yaml
+domains: {}
+retrieval_policy:
+  order:
+    - match_domain_by_alias
+    - read_matching_memory_subjects
+    - read_domain_docs_only_when_needed
+    - search_candidate_files_or_symbols
+    - read_relevant_snippet_first
+    - read_full_file_when_snippet_is_not_enough

package/templates/minimal/decisions/README.md

@@ -0,0 +1,4 @@
+# Decisions
+
+Record confirmed project decisions with status, scope, evidence and replacement
+history.

package/templates/minimal/memory/INDEX.yaml

@@ -0,0 +1,20 @@
+id: memory_index
+type: memory_index
+version: 0.3
+purpose: route_to_minimum_relevant_persistent_memory
+policy:
+  - read_only_matching_subjects
+  - do_not_load_archive_by_default
+  - current_request_overrides_memory
+  - verified_files_override_stale_memory
+entries: []
+areas:
+  user:
+    path: memory/user/
+  projects:
+    path: memory/projects/
+  patterns:
+    path: memory/patterns/
+  archive:
+    path: memory/archive/
+    read_by_default: false