ai-execution-protocol 0.1.0 → 0.2.1

package/scripts/npm_install_protocol.js

@@ -10,6 +10,7 @@ const protocolFiles = [
   "README.yaml",
   "fast-path.yaml",
   "router.yaml",
+  "route-packs.yaml",
   "modes.yaml",
   "execution-rules.yaml",
   "risk-levels.yaml",
@@ -17,6 +18,7 @@ const protocolFiles = [
   "validation-checklist.yaml",
   "context-rules.yaml",
   "context-compiler.yaml",
+  "persistent-context.yaml",
   "formatting-rules.yaml",
   "prompt-economy.yaml",
   "spec-driven.yaml",
@@ -29,6 +31,50 @@ const aiignoreLines = [
   "scripts/__pycache__/",
   "*.pyc",
 ];
+const minimalCanonicalState = `id: canonical_state
+type: project_state
+version: 0.1
+purpose: small_current_truth_summary_for_ai_navigation
+status: bootstrap_template
+truth_order:
+  - current_user_request
+  - verified_current_files
+  - protocol_rules
+  - project_docs
+  - conversation_history
+notes:
+  - update_this_file_when_project_state_or_decisions_change
+  - do_not_treat_this_file_as_truth_without_current_file_verification
+`;
+const minimalContextMap = `id: project_context_map
+type: context_map
+version: 0.1
+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
+domains: {}
+retrieval_policy:
+  order:
+    - match_domain_by_alias
+    - read_domain_docs_only_when_needed
+    - search_candidate_files_or_symbols
+    - read_relevant_snippet_first
+    - read_full_file_when_snippet_is_not_enough
+`;
+const minimalDecisionsReadme = `# Decisions
+
+Use esta pasta para registrar decisoes estaveis que a IA deve considerar ao
+mapear contexto.
+
+Cada decisao deve indicar status, escopo, impacto e arquivo relacionado quando
+existir.
+`;
 const requiredText = {
   "AGENTS.md": [
     "AI_PROTOCOL_BEGIN",
@@ -38,7 +84,14 @@ const requiredText = {
     "Nenhum arquivo deve passar de 400 linhas.",
   ],
   ".aiignore": ["results/", "dist/", "*.pyc"],
+  "canonical-state.yaml": ["canonical_state", "truth_order"],
+  "context-map.yaml": ["project_context_map", "aliases_are_pointers_not_truth"],
   "protocol/router.yaml": ["feature_or_spec", "spec-driven.yaml", "prompt_improvement"],
+  "protocol/route-packs.yaml": [
+    "read_pack_first_expand_only_when_needed",
+    "simple_answer",
+    "context_optimization",
+  ],
   "protocol/spec-driven.yaml": ["protocol_is_base_spec_is_tool", "do_not_create_spec_for_low_value_tasks"],
 };
 
@@ -77,13 +130,15 @@ editar, classifique risco, escolha rota e valide a entrega.
 
 1. \`protocol/fast-path.yaml\`
 2. \`protocol/router.yaml\`
-3. Arquivo YAML especifico em \`protocol/\` conforme a rota.
+3. \`protocol/route-packs.yaml\` para ler o resumo compacto da rota.
+4. Arquivo YAML especifico em \`protocol/\` somente quando o pack nao bastar.
 
 ## Regras de execucao
 
 - Classifique o risco antes de agir.
 - Use o menor contexto suficiente.
 - Leia apenas os arquivos indicados por \`protocol/router.yaml\`.
+- Use \`protocol/route-packs.yaml\` antes de abrir todos os arquivos da rota.
 - 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
@@ -193,6 +248,17 @@ 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) {
+  writeIfMissing(path.join(targetRoot, "canonical-state.yaml"), minimalCanonicalState);
+  writeIfMissing(path.join(targetRoot, "context-map.yaml"), minimalContextMap);
+  writeIfMissing(path.join(targetRoot, "decisions", "README.md"), minimalDecisionsReadme);
+}
+
 function copyProtocol(target, force, backupRoot) {
   if (fs.existsSync(target) && !force) return;
   if (fs.existsSync(target)) {
@@ -218,6 +284,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);
@@ -226,7 +293,14 @@ 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 = [
+    "AGENTS.md",
+    ".aiignore",
+    "canonical-state.yaml",
+    "context-map.yaml",
+    "decisions/README.md",
+    ...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

@@ -10,9 +10,13 @@ from pathlib import Path
 REQUIRED_FILES = [
     "AGENTS.md",
     ".aiignore",
+    "canonical-state.yaml",
+    "context-map.yaml",
+    "decisions/README.md",
     "protocol/README.yaml",
     "protocol/fast-path.yaml",
     "protocol/router.yaml",
+    "protocol/route-packs.yaml",
     "protocol/modes.yaml",
     "protocol/execution-rules.yaml",
     "protocol/risk-levels.yaml",
@@ -20,6 +24,7 @@ REQUIRED_FILES = [
     "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",
@@ -41,11 +46,24 @@ REQUIRED_TEXT = {
         "dist/",
         "*.pyc",
     ],
+    "canonical-state.yaml": [
+        "canonical_state",
+        "truth_order",
+    ],
+    "context-map.yaml": [
+        "project_context_map",
+        "aliases_are_pointers_not_truth",
+    ],
     "protocol/router.yaml": [
         "feature_or_spec",
         "spec-driven.yaml",
         "prompt_improvement",
     ],
+    "protocol/route-packs.yaml": [
+        "read_pack_first_expand_only_when_needed",
+        "simple_answer",
+        "context_optimization",
+    ],
     "protocol/spec-driven.yaml": [
         "protocol_is_base_spec_is_tool",
         "do_not_create_spec_for_low_value_tasks",