create-genia-os 2.4.0 → 3.0.0

package/template/.aiox-core/development/templates/ptc-entity-validation.md

@@ -0,0 +1,113 @@
+# PTC Template: Entity Validation Batch
+
+---
+execution_mode: programmatic
+ptc_type: bash-batch  # Fallback — true PTC not available in Claude Code CLI (ADR-7)
+adr_reference: ADR-3 (PTC native ONLY — no MCP tools in batch blocks)
+story: TOK-3
+---
+
+## Purpose
+
+Batch-scan all entities in entity-registry.yaml against their validation rules.
+N entities x M checks consolidated into a single Bash block with one summary output.
+
+**Token savings:** ~20-30% vs individual Grep/Read calls per entity.
+
+## Restriction (ADR-3)
+
+**ONLY native/CLI tools allowed inside this batch block.**
+MCP tools are EXCLUDED. Uses: Bash, grep (via bash), file reads (via bash).
+
+## Template
+
+```bash
+#!/bin/bash
+# PTC-ENTITY-VALIDATION: Batch entity registry scan
+# Usage: Execute as single Bash tool call. Only the final summary enters context.
+
+REGISTRY=".aiox-core/data/entity-registry.yaml"
+TOOL_REGISTRY=".aiox-core/data/tool-registry.yaml"
+
+PASS=0
+FAIL=0
+WARN=0
+RESULTS=""
+
+# --- Check 1: Registry file exists ---
+if [ ! -f "$REGISTRY" ]; then
+  echo "FATAL: entity-registry.yaml not found at $REGISTRY"
+  exit 1
+fi
+
+# --- Check 2: Required fields present in each entity ---
+required_fields=("name" "type" "layer" "description")
+for field in "${required_fields[@]}"; do
+  count=$(grep -c "  $field:" "$REGISTRY" 2>/dev/null || echo "0")
+  if [ "$count" -gt 0 ]; then
+    RESULTS+="FIELD '$field': found $count occurrences — PASS\n"
+    ((PASS++))
+  else
+    RESULTS+="FIELD '$field': NOT FOUND — FAIL\n"
+    ((FAIL++))
+  fi
+done
+
+# --- Check 3: No duplicate entity names ---
+duplicates=$(grep "^  [a-zA-Z]" "$REGISTRY" | sort | uniq -d)
+if [ -z "$duplicates" ]; then
+  RESULTS+="DUPLICATES: none — PASS\n"
+  ((PASS++))
+else
+  RESULTS+="DUPLICATES: found\n$duplicates\n— FAIL\n"
+  ((FAIL++))
+fi
+
+# --- Check 4: Tool registry consistency ---
+if [ -f "$TOOL_REGISTRY" ]; then
+  tool_count=$(grep -c "tier:" "$TOOL_REGISTRY" 2>/dev/null || echo "0")
+  RESULTS+="TOOL-REGISTRY: $tool_count tools found — PASS\n"
+  ((PASS++))
+else
+  RESULTS+="TOOL-REGISTRY: file missing — WARN\n"
+  ((WARN++))
+fi
+
+# --- Check 5: Layer annotations valid (L1-L4) ---
+invalid_layers=$(grep "layer:" "$REGISTRY" | grep -v "L[1-4]" | head -5)
+if [ -z "$invalid_layers" ]; then
+  RESULTS+="LAYERS: all valid (L1-L4) — PASS\n"
+  ((PASS++))
+else
+  RESULTS+="LAYERS: invalid entries found\n$invalid_layers\n— FAIL\n"
+  ((FAIL++))
+fi
+
+# --- Summary ---
+echo "=== ENTITY VALIDATION SUMMARY ==="
+echo "Passed: $PASS | Failed: $FAIL | Warnings: $WARN"
+echo ""
+echo -e "$RESULTS"
+
+if [ $FAIL -gt 0 ]; then
+  echo "VERDICT: FAIL"
+  exit 1
+else
+  echo "VERDICT: PASS"
+  exit 0
+fi
+```
+
+## Token Comparison
+
+| Approach | Tool Calls | Context Entries | Estimated Tokens |
+|----------|-----------|-----------------|-----------------|
+| Direct (N checks) | 5-10 | 5-10 (each result) | ~5,000-10,000 |
+| Batch (1 call) | 1 | 1 (summary only) | ~2,000-3,000 |
+| **Reduction** | -80% calls | -80% entries | **~20-40%** |
+
+## Notes
+
+- Extensible: add more checks by appending to the script
+- Each check reports PASS/FAIL/WARN independently
+- Only summary enters context — intermediate grep/read results stay in shell

package/template/.aiox-core/development/templates/ptc-qa-gate.md

@@ -0,0 +1,100 @@
+# PTC Template: QA Gate Batch
+
+---
+execution_mode: programmatic
+ptc_type: bash-batch  # Fallback — true PTC not available in Claude Code CLI (ADR-7)
+adr_reference: ADR-3 (PTC native ONLY — no MCP tools in batch blocks)
+story: TOK-3
+---
+
+## Purpose
+
+Consolidate QA Gate checks (lint, typecheck, test) into a single Bash block.
+Intermediate results stay in shell variables — only the final summary enters context.
+
+**Token savings:** ~20% vs 3 separate tool calls (conservative estimate).
+True PTC (API-level) would yield ~37% but is not available in Claude Code CLI.
+
+## Restriction (ADR-3)
+
+**ONLY native/CLI tools allowed inside this batch block.**
+MCP tools (EXA, Playwright, Apify, Context7, Nogic, Code-Graph) are EXCLUDED.
+
+Eligible tools: Bash, Read, Write, Edit, Grep, Glob (all `ptc_eligible: true` in tool-registry.yaml).
+
+## Template
+
+```bash
+#!/bin/bash
+# PTC-QA-GATE: Batch quality checks — single Bash block, one summary output
+# Usage: Execute as single Bash tool call. Only the final echo enters context.
+
+set -o pipefail
+
+PASS=0
+FAIL=0
+RESULTS=""
+
+# --- Check 1: Lint ---
+lint_output=$(npm run lint 2>&1)
+lint_exit=$?
+if [ $lint_exit -eq 0 ]; then
+  RESULTS+="LINT: PASS\n"
+  ((PASS++))
+else
+  RESULTS+="LINT: FAIL\n${lint_output}\n"
+  ((FAIL++))
+fi
+
+# --- Check 2: TypeCheck ---
+typecheck_output=$(npm run typecheck 2>&1)
+typecheck_exit=$?
+if [ $typecheck_exit -eq 0 ]; then
+  RESULTS+="TYPECHECK: PASS\n"
+  ((PASS++))
+else
+  RESULTS+="TYPECHECK: FAIL\n${typecheck_output}\n"
+  ((FAIL++))
+fi
+
+# --- Check 3: Tests ---
+test_output=$(npm test 2>&1)
+test_exit=$?
+if [ $test_exit -eq 0 ]; then
+  RESULTS+="TESTS: PASS\n"
+  ((PASS++))
+else
+  RESULTS+="TESTS: FAIL\n${test_output}\n"
+  ((FAIL++))
+fi
+
+# --- Summary (only this enters context) ---
+echo "=== QA GATE SUMMARY ==="
+echo "Passed: $PASS / $((PASS + FAIL))"
+echo "Failed: $FAIL"
+echo ""
+echo -e "$RESULTS"
+
+if [ $FAIL -gt 0 ]; then
+  echo "VERDICT: FAIL"
+  exit 1
+else
+  echo "VERDICT: PASS"
+  exit 0
+fi
+```
+
+## Token Comparison
+
+| Approach | Tool Calls | Context Entries | Estimated Tokens |
+|----------|-----------|-----------------|-----------------|
+| Direct (3 calls) | 3 | 3 (each result) | ~3,000-9,000 |
+| Batch (1 call) | 1 | 1 (summary only) | ~1,500-3,000 |
+| **Reduction** | -67% calls | -67% entries | **~20-50%** |
+
+## Notes
+
+- If any check fails, the full output for that check is included in summary
+- Passing checks show only "PASS" (minimal context)
+- Exit code 1 = at least one check failed
+- This template can be extended with additional checks (build, coverage, etc.)

package/template/.aiox-core/development/templates/ptc-research-aggregation.md

@@ -0,0 +1,94 @@
+# PTC Template: Research Aggregation Batch
+
+---
+execution_mode: programmatic
+ptc_type: bash-batch  # Fallback — true PTC not available in Claude Code CLI (ADR-7)
+adr_reference: ADR-3 (PTC native ONLY — no MCP tools in batch blocks)
+story: TOK-3
+---
+
+## Purpose
+
+Consolidate multi-file research aggregation (scan docs, extract findings, merge)
+into a single Bash block. Intermediate grep/read results stay in shell variables.
+
+**Token savings:** ~20% vs multiple Read + Grep tool calls.
+
+**Note:** This template uses native CLI tools only. For web-based research
+(WebSearch, EXA), those tool calls must remain separate — they are NOT
+ptc_eligible (MCP tools excluded per ADR-3). This template covers the
+**aggregation** phase (local file scanning), not the **search** phase.
+
+## Restriction (ADR-3)
+
+**ONLY native/CLI tools allowed inside this batch block.**
+MCP tools (EXA, Context7, Apify) are EXCLUDED from batch blocks.
+WebSearch/WebFetch are native Tier 1 but operate as API calls — they can be
+included in batch if executed via shell scripting patterns.
+
+## Template
+
+```bash
+#!/bin/bash
+# PTC-RESEARCH-AGGREGATION: Batch scan research docs and aggregate findings
+# Usage: Execute as single Bash tool call. Only the final summary enters context.
+
+RESEARCH_DIR="docs/research"
+OUTPUT=""
+TOPICS_FOUND=0
+FILES_SCANNED=0
+
+# --- Scan all research directories ---
+for dir in "$RESEARCH_DIR"/*/; do
+  if [ -d "$dir" ]; then
+    readme="$dir/README.md"
+    if [ -f "$readme" ]; then
+      ((FILES_SCANNED++))
+
+      # Extract title (first H1)
+      title=$(grep -m1 "^# " "$readme" | sed 's/^# //')
+
+      # Extract key findings (lines with "finding" or "conclusion" or "result")
+      findings=$(grep -i -c "finding\|conclusion\|result\|recommendation" "$readme" 2>/dev/null || echo "0")
+
+      # Extract token/performance metrics if present
+      metrics=$(grep -i "token\|reduction\|saving\|performance\|latency" "$readme" | head -3)
+
+      OUTPUT+="## $title\n"
+      OUTPUT+="- Source: $readme\n"
+      OUTPUT+="- Key findings count: $findings\n"
+      if [ -n "$metrics" ]; then
+        OUTPUT+="- Metrics:\n"
+        while IFS= read -r line; do
+          OUTPUT+="  - $line\n"
+        done <<< "$metrics"
+      fi
+      OUTPUT+="\n"
+      ((TOPICS_FOUND++))
+    fi
+  fi
+done
+
+# --- Summary ---
+echo "=== RESEARCH AGGREGATION SUMMARY ==="
+echo "Directories scanned: $FILES_SCANNED"
+echo "Topics with findings: $TOPICS_FOUND"
+echo ""
+echo -e "$OUTPUT"
+```
+
+## Token Comparison
+
+| Approach | Tool Calls | Context Entries | Estimated Tokens |
+|----------|-----------|-----------------|-----------------|
+| Direct (N reads + N greps) | 10-20 | 10-20 results | ~8,000-15,000 |
+| Batch (1 call) | 1 | 1 (summary only) | ~3,000-5,000 |
+| **Reduction** | -90% calls | -90% entries | **~30-50%** |
+
+## Notes
+
+- Scans `docs/research/*/README.md` by default — adjust path as needed
+- Extracts title, findings count, and performance metrics per research doc
+- Only the aggregated summary enters context
+- For web research (EXA, WebSearch), run those as separate tool calls first,
+  then use this template to aggregate the saved results