universal-agent-memory 1.0.15 → 1.0.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-agent-memory",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "description": "Universal AI agent memory system - CLAUDE.md templates, memory, worktrees for Claude Code, Factory.AI, VSCode, OpenCode",
   "type": "module",
   "main": "dist/index.js",

package/templates/CLAUDE.template.md

@@ -1,7 +1,20 @@
 <!--
-  CLAUDE.md Universal Template - v10.10
+  CLAUDE.md Universal Template - v10.12
   
   CHANGES IN THIS VERSION:
+  - SECRETS CLARIFICATION: All secrets in GitHub, secret-dependent ops MUST use pipelines
+  - Ephemeral pipelines for one-time secret operations (self-destruct after run)
+  - Local testing limited to non-secret operations (read-only kubectl, cloud console)
+  - Clear pipeline routing table for secret-dependent operations
+  
+  PREVIOUS (v10.11):
+  - INFRASTRUCTURE POLICY UPDATE: Local testing now ALLOWED for proving solutions
+  - IaC parity MANDATORY before completion (test locally, then codify in IaC)
+  - Two-phase workflow: Phase 1 (local proof) → Phase 2 (IaC parity verification)
+  - Parity verification checklist with state diff confirmation
+  - Updated completion checklist for infrastructure tasks
+  
+  PREVIOUS (v10.10):
   - PROJECT.md SEPARATION: Project-specific content can now be in .factory/PROJECT.md
   - Seamless template upgrades without merge conflicts
   - Generator auto-detects PROJECT.md and imports as Handlebars partial
@@ -181,10 +194,10 @@ Under what conditions does this work?
 - Solve problems you weren't asked to solve
 - Produce code you wouldn't want to debug at 3am
 {{#if HAS_PIPELINE_POLICY}}
-- Run kubectl commands directly (use `ops-approved-operations.yml`)
-- Run terraform locally (use `iac-terraform-cicd.yml`)
-- Document manual infrastructure commands (link to pipelines instead)
-- Create secrets outside of Sealed Secrets or pipelines
+- Leave manual infrastructure changes without IaC parity
+- Skip pipeline deployment after local testing
+- Create production secrets via kubectl (use Sealed Secrets)
+- Mark infrastructure work complete without verifying IaC matches live state
 {{/if}}
 
 ### Expected Output Format
@@ -198,45 +211,121 @@ Under what conditions does this work?
 ---
 
 {{#if HAS_INFRA}}
-## 🚫 PIPELINE-ONLY POLICY - ABSOLUTE RULE
+## 🚫 INFRASTRUCTURE AS CODE POLICY - IaC PARITY REQUIRED
 
-**ALL infrastructure changes MUST go through CI/CD pipelines. NO EXCEPTIONS.**
+**Local testing is ALLOWED for proving solutions. IaC parity is MANDATORY before completion.**
 
-### Core Inhibitions
+### Critical: Secrets Are in GitHub
+
+**ALL secrets are stored in GitHub Actions secrets.** Operations requiring secrets MUST use pipelines:
+
+| If operation needs... | Use this pipeline |
+|-----------------------|-------------------|
+| Terraform with secrets | `iac-terraform-cicd.yml` or `ops-ephemeral-terraform.yml` |
+| kubectl with secrets | `ops-approved-operations.yml` |
+| One-time secret operation | `ops-create-ephemeral.yml` (self-destructs after run) |
+
+**Local commands without secrets** (read-only, public resources) are allowed for testing.
+
+### Two-Phase Infrastructure Workflow
 
 ```
-Do not run kubectl commands directly against clusters.
-Do not run terraform apply from local machines.
-Do not make changes via cloud console that should be in IaC.
-Do not document manual commands in runbooks - link to pipelines instead.
+┌─────────────────────────────────────────────────────────────────┐
+│  PHASE 1: LOCAL PROOF (ALLOWED - NO SECRETS)                    │
+│  ─────────────────────────────────────────────────────────────  │
+│  ✓ kubectl get/describe/logs (read-only operations)             │
+│  ✓ terraform plan (uses GitHub pipeline for secrets)            │
+│  ✓ Direct cloud console changes for rapid prototyping           │
+│  ✓ Manual commands to verify behavior (public resources)        │
+│                                                                  │
+│  ⚠️  SECRETS REQUIRED? → Use pipeline, not local commands       │
+│                                                                  │
+│  PURPOSE: Prove the solution works before codifying             │
+├─────────────────────────────────────────────────────────────────┤
+│  PHASE 2: IaC PARITY (MANDATORY - VIA PIPELINE)                 │
+│  ─────────────────────────────────────────────────────────────  │
+│  ☐ Translate ALL manual changes to Terraform/Kubernetes YAML    │
+│  ☐ Commit IaC changes to feature branch                         │
+│  ☐ Run `terraform plan` via pipeline (has secrets)              │
+│  ☐ Deploy via pipeline to confirm 100% match                    │
+│  ☐ Delete any manual/ephemeral resources                        │
+│                                                                  │
+│  RULE: Work is NOT complete until IaC matches live state        │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Core Principle
+
+```
+Local testing proves the solution. IaC ensures reproducibility.
+Manual changes are TEMPORARY. IaC changes are PERMANENT.
+If it's not in IaC, it doesn't exist (will be destroyed/lost).
+Secrets live in GitHub - use pipelines for secret-dependent operations.
 ```
 
 ### Approved Pipelines
 
-| Task | Pipeline | Trigger |
-|------|----------|---------|
-| Kubernetes operations | `ops-approved-operations.yml` | Manual dispatch |
-| Ephemeral environments | `ops-create-ephemeral.yml` | Manual dispatch |
-| Terraform changes | `iac-terraform-cicd.yml` | PR to main |
-| Ephemeral Terraform | `ops-ephemeral-terraform.yml` | Manual dispatch |
+| Task | Pipeline | Trigger | Notes |
+|------|----------|---------|-------|
+| Kubernetes operations | `ops-approved-operations.yml` | Manual dispatch | Has cluster secrets |
+| Ephemeral environments | `ops-create-ephemeral.yml` | Manual dispatch | Self-destructs after run |
+| Terraform changes | `iac-terraform-cicd.yml` | PR to main | Has TF secrets |
+| Ephemeral Terraform | `ops-ephemeral-terraform.yml` | Manual dispatch | One-time TF operations |
 
-### One-Time Operations
+### Using Ephemeral Pipelines for One-Time Operations
+
+For operations that need secrets but are one-time (migrations, testing, data fixes):
+
+```bash
+# Create ephemeral pipeline that self-destructs after completion
+gh workflow run ops-create-ephemeral.yml \
+  -f operation_name="test-new-config" \
+  -f commands="terraform apply -target=module.new_feature"
+  
+# Pipeline runs with secrets, then self-removes
+```
 
-For operations that need to run once (migrations, data fixes, cleanups):
+### Parity Verification Checklist
 
-1. Use `ops-create-ephemeral.yml` to create a pipeline
-2. Define the operation in the pipeline configuration
-3. Run via GitHub Actions workflow dispatch
-4. Pipeline self-destructs after completion
+Before marking infrastructure work complete:
+
+```bash
+# 1. Capture current state (after testing via pipeline)
+kubectl get all -n <namespace> -o yaml > /tmp/current-state.yaml
+
+# 2. Destroy test resources (via pipeline if secrets needed)
+gh workflow run ops-approved-operations.yml \
+  -f operation="delete" \
+  -f target="test-resources"
+
+# 3. Apply ONLY from IaC (via pipeline - has secrets)
+# Push IaC changes → PR → iac-terraform-cicd.yml runs automatically
+
+# 4. Verify parity - must produce IDENTICAL state
+kubectl get all -n <namespace> -o yaml > /tmp/iac-state.yaml
+diff /tmp/current-state.yaml /tmp/iac-state.yaml  # Should be empty
+```
 
 ### What This Means for Agents
 
-- **NEVER**: Run `kubectl apply`, `kubectl delete`, `kubectl patch` directly
-- **NEVER**: Run `terraform apply`, `terraform destroy` locally
-- **NEVER**: Create Kubernetes secrets via `kubectl create secret`
-- **ALWAYS**: Make infrastructure changes via PR → pipeline
-- **ALWAYS**: Use `ops-approved-operations.yml` for operational tasks
-- **ALWAYS**: Reference pipeline workflows instead of manual commands
+**PHASE 1 - Local Testing (ALLOWED for non-secret operations):**
+- ✓ Run read-only commands: `kubectl get`, `kubectl describe`, `kubectl logs`
+- ✓ Run `terraform plan` via pipeline (needs secrets)
+- ✓ Make cloud console changes to prototype
+- ✓ Use ephemeral pipelines for secret-dependent testing
+
+**PHASE 2 - IaC Parity (MANDATORY - always via pipeline):**
+- ☐ ALL manual changes MUST be translated to IaC (Terraform/K8s YAML)
+- ☐ IaC MUST be committed to version control
+- ☐ Deployment MUST go through CI/CD pipeline (has secrets)
+- ☐ Final state MUST match IaC exactly (verify with diff)
+- ☐ Manual/ephemeral resources MUST be cleaned up
+
+**NEVER:**
+- Run `terraform apply` locally (no secrets available)
+- Run `kubectl apply` with secret-dependent resources locally
+- Create secrets via `kubectl create secret` (use Sealed Secrets)
+- Hardcode or expose secrets in code/logs
 
 📖 See: `docs/adr/ADR-0006-pipeline-only-infrastructure-changes.md`
 
@@ -1367,9 +1456,10 @@ kubectl create secret ...
 ☐ Terraform plan verified
 {{/if}}
 {{#if HAS_PIPELINE_POLICY}}
-☐ No manual kubectl commands (use pipelines)
-☐ No local terraform apply (use pipelines)
-☐ Infrastructure changes via iac-terraform-cicd.yml
+☐ IaC parity verified (manual changes translated to Terraform/K8s YAML)
+☐ Final deployment via pipeline (iac-terraform-cicd.yml)
+☐ State diff confirmed empty (IaC matches live)
+☐ Manual/ephemeral resources cleaned up
 {{/if}}
 ☐ No secrets in code
 ```