azcodr 1.0.0

package/docs/rules/upstream_synchronization.md

@@ -0,0 +1,66 @@
+# Upstream Baseline Synchronization & AI Knowledge Merging
+
+> **Core Mandate:** Upstream template/baseline workspaces (`azcodr`) must remain strictly untouched until the user explicitly requests merging. When merging via `/merge-ai`, strictly filter out all domain-specific entities, stacks, and models, keeping the baseline 100% generic.
+
+---
+
+## 1. The Baseline-Project Decoupling Principle
+
+Workspaces operate under a strict unidirectional and on-demand bidirectional flow:
+
+```
+[Upstream Generic Baseline: azcodr]
+               │
+               ▼  (One-time fork / clone at project inception)
+[Derived Project Workspace: my-app / others]
+               │
+               │  (Accumulates project code, specificities, and institutional lessons)
+               │
+               ▼  (ONLY when user explicitly triggers /merge-ai)
+[Distillation & Filter: Purge Domain Specificities, Colocate DOs/DONTs]
+               │
+               ▼
+[Clean Merge into Upstream Baseline: azcodr]
+```
+
+- **Pristine Upstream Mandate:** Never edit, commit, or push changes to an upstream baseline repository (`azcodr`) during routine project development, feature implementation, or bug fixes.
+- **Explicit Trigger Requirement:** Synchronization into the baseline template may occur **only and exclusively** when the user explicitly issues the `/merge-ai` slash command or direct merge directive.
+
+---
+
+## 2. Zero-Contamination Invariant (Generic vs. Specific)
+
+When merging knowledge, rules, or skills back to the baseline, enforce strict domain filtering:
+
+| Element Category | Keep in Specific Project Workspace | Allow in Generic Baseline (`azcodr`) |
+|---|---|---|
+| **Domain Entities** | Concrete business models (`Order`, `Customer`, `Invoice`, `Account`, etc.) | Abstract archetypes (`Entity`, `Aggregate`, `ValueObject`, `Resource`) |
+| **Tech Stack / Adapters** | Concrete choices (Prisma, SQLite dev, PostgreSQL prod, Vite React) | Hexagonal Ports, abstract repository contracts, polyglot adapter guidance |
+| **Architectural Rules** | Specific entity validation, specific route paths | Universal invariants (5-Phase Agile Lifecycle, SemVer trigger matrix, FK dropdowns) |
+| **ADRs** | Stack decisions (`ADR-006: Target Tech Stack for Project`) | Generic architecture patterns (`ADR-007` to `ADR-010`) |
+| **Test Suites** | Concrete domain tests (`order_domain.test.ts`, domain-specific suites) | Boundary smoke test pattern (`scripts/smoke_test.sh`), 100% coverage gate |
+
+---
+
+## 3. Direct Rule Colocation Protocol
+
+To prevent token bloat and documentation rot:
+1. **Never Duplicate in a Consolidated List:** Never dump merged rules into a monolithic `dos_and_donts.md`.
+2. **Colocate at Source:** Embed DO's and DONT's directly into the relevant atomic rule (`docs/rules/<domain>.md`) and skill (`.agents/skills/<skill>/SKILL.md`).
+3. **Index-Only Directory:** Maintain `docs/knowledge/dos_and_donts.md` strictly as a clean reference table pointing to atomic rules.
+
+---
+
+## 4. Invariants, DO's & DONT's
+
+### DO's:
+- **DO:** Leave the upstream baseline repository (`azcodr`) completely alone during regular development.
+- **DO:** Require an explicit `/merge-ai` command before proposing or executing any upstream synchronization.
+- **DO:** Distill all lessons and post-mortems into generic, domain-agnostic language before merging.
+- **DO:** Colocate DOs and DONTs directly inside the relevant atomic rules and skills.
+- **DO:** Run `validate_agentic_configs.sh` on the upstream baseline before and after any merge.
+
+### DONT's:
+- **DONT:** Never touch or edit the upstream baseline template automatically without explicit user command.
+- **DONT:** Never contaminate the baseline template with project-specific domain models, entity names, or framework setups.
+- **DONT:** Never overwrite upstream baseline files with raw project copies; merge generic concepts surgically.

package/docs/rules/workflow_state_machines.md

@@ -0,0 +1,118 @@
+# Workflow Engines, State Machines & State Configurability
+
+> **Core Mandate:** Separate non-negotiable core domain invariants (Aggregate Root FSM) from tenant-configurable operational workflows (Metadata-Driven State Machines / Orchestration Engines).
+
+---
+
+## 1. The Fallacy of Universal Configurability
+
+A common architectural anti-pattern is the **"Universal Workflow Fallacy"** (a variant of the *Inner Platform Effect*), which presumes that *every* status and state transition in a system should be dynamically configurable by end-users or tenants.
+
+### The Architectural Invariant
+1. **Core Invariant States (Hard FSM / In-Aggregate)**:
+   - Fundamental lifecycle states governed by business integrity, accounting invariants, or legal rules.
+   - Enforced **strictly within the Aggregate Root** in compiled code.
+   - Cannot be bypassed or arbitrarily restructured by tenant configuration.
+   - *Examples*:
+     - A `Payment` or `Transaction` with status `SETTLED` cannot transition back to `PENDING` without a compensating `REFUND` or reversal ledger entry.
+     - An `Order` cannot become `FULFILLED` without valid payment authorization and inventory deduction.
+2. **Operational / Business Process Stages (Soft FSM / Configurable Orchestration)**:
+   - Tenant-specific pipeline stages, review checklists, approval tiers, and sub-statuses.
+   - Managed via **Declarative State Transition Matrices**, **Workflow Engines** (Temporal / Camunda BPMN), or **CEL (Common Expression Language)** transition guards.
+   - *Examples*:
+     - An application/lead review pipeline: Tenant A uses `[NEW -> REVIEW -> ACCEPTED]`; Tenant B uses `[NEW -> VETTING -> INTERVIEW -> APPROVAL -> ACCEPTED]`.
+     - A support/ticket resolution lifecycle.
+
+---
+
+## 2. State Machine Architectural Patterns
+
+### Pattern A: In-Aggregate State Machine (Hard Invariants)
+Model states as **Discriminated Unions** or the GoF **State Pattern** encapsulated inside the domain entity. Public mutations must be explicit domain actions:
+
+```typescript
+// Correct: Explicit domain command asserting state invariant
+export class OrderAggregate {
+  private constructor(private state: OrderState) {}
+
+  fulfill(actorId: string): Result<void, DomainError> {
+    if (this.state.status !== 'PAID') {
+      return err(new DomainError(`Cannot fulfill order in status: ${this.state.status}`));
+    }
+    this.state.status = 'FULFILLED';
+    this.state.updatedAt = new Date();
+    this.state.updatedBy = actorId;
+    return ok(undefined);
+  }
+}
+```
+
+### Pattern B: Declarative State Transition Matrix (Configurable FSM)
+For tenant-configurable operational stages, store transitions as declarative metadata:
+
+```json
+{
+  "workflow": "resource_review_pipeline",
+  "tenantId": "org_123",
+  "initialState": "SUBMITTED",
+  "transitions": [
+    {
+      "from": "SUBMITTED",
+      "to": "UNDER_REVIEW",
+      "event": "START_REVIEW",
+      "allowedRoles": ["MANAGER", "REVIEWER"],
+      "guard": "resource.score >= 60"
+    },
+    {
+      "from": "UNDER_REVIEW",
+      "to": "APPROVED",
+      "event": "APPROVE",
+      "allowedRoles": ["ADMIN"],
+      "guard": "resource.verified == true"
+    }
+  ]
+}
+```
+
+### Pattern C: Durable Distributed Orchestration (Temporal / BPMN)
+When a state transition requires coordination across multiple aggregates or asynchronous third parties (e.g. external payment gateway, background verification API, webhook delivery):
+- Use a **Durable Workflow Engine** (Temporal or Camunda BPMN 2.0).
+- The workflow coordinates activities by sending commands to Aggregate Roots and awaiting Domain Events.
+- **Invariant**: The workflow engine never mutates aggregate state directly; it issues domain commands.
+
+---
+
+## 3. Mandatory State Transition Audit Trail
+
+Every state change across any entity or workflow MUST be immutably recorded in a transition log:
+
+| Field | Type | Description |
+|---|---|---|
+| `transitionId` | String (UUIDv7) | Unique identifier of the transition record. |
+| `entityType` | String | Name of the entity (`Order`, `Application`, `Invoice`). |
+| `entityId` | String | Target entity identifier. |
+| `fromState` | String | Pre-transition state value. |
+| `toState` | String | Post-transition state value. |
+| `event` | String | Domain event or action triggering transition. |
+| `actorId` | String | User ID or `SYSTEM` triggering the change. |
+| `reason` | String? | Optional justification or audit comment. |
+| `metadata` | JSON? | Snapshot of transition context or rule evaluation. |
+| `createdAt` | DateTime | Immutable timestamp of transition. |
+
+---
+
+## 4. Invariants (DO's & DONT's)
+
+### DO
+- **DO** enforce core business invariants inside Aggregate Roots using strongly-typed state transitions.
+- **DO** decouple core domain state from operational display stages or tenant-specific sub-statuses.
+- **DO** use non-Turing complete expression languages (CEL) to evaluate dynamic transition guards.
+- **DO** maintain an immutable transition history table for all status alterations.
+- **DO** validate state transition graphs at creation time to prevent dead-end or unreachable states.
+
+### DONT
+- **DONT** make financial or legal integrity states (e.g., `SETTLED`, `CANCELLED`, `REFUNDED`) freely rewritable by tenant configuration.
+- **DONT** expose generic status setters (`entity.setStatus(newStatus)`) on domain models.
+- **DONT** execute untrusted scripts or dynamic strings in the host runtime for workflow evaluations.
+- **DONT** allow a workflow orchestrator to bypass aggregate invariants by directly updating database columns.
+- **DONT** delete historical state transitions; status audit logs must be append-only.

package/docs/rules/workspace_isolation.md

@@ -0,0 +1,25 @@
+# Workspace Isolation & Zero Global Context Interference
+
+> **Core Mandate:** Enforce strict workspace containment within the workspace root (`./`), strictly prohibiting any leakage, interference, or unverified assumptions from global configurations, external directories, or sibling projects.
+
+---
+
+## 1. Principle of Workspace Sovereignty
+
+- **Ground Truth Boundary**: Only files, dependencies, configuration files (`package.json`, `tsconfig.json`, `docker-compose.yml`), and verified command executions within the local workspace (`./`) constitute project truth.
+- **Zero Global Contamination**: Never import, execute, or assume tools, environment variables, or conventions from global system directories (e.g. `~/.config`, `/tmp`, `~/.gemini/antigravity-cli`, or parent directories) unless explicitly defined within local workspace configuration.
+- **Sibling Project Isolation**: Strictly ignore all external or legacy projects. Do not read from or write to directories outside the local repository (`./`).
+
+---
+
+## 2. Dependency & Tooling Isolation
+
+- **Local Package Manager**: Standardize strictly on local workspace dependencies managed via `npm` within this workspace. Never rely on global npm packages (`npm install -g`).
+- **Container Network Containment**: All Docker containers and bridge networks must be named and scoped specifically to this project (e.g. `azcodr_network`, `azcodr_postgres`) to prevent port collisions or cross-project data leakage.
+
+---
+
+## 3. Subagent & Execution Context Sandboxing
+
+- When spawning subagents or executing commands, ensure the working directory (`Cwd`) is anchored strictly to the workspace root (`./`).
+- Subagents must never carry over assumptions from other workspaces or global memory pools.

package/lib/index.js

@@ -0,0 +1,5 @@
+'use strict';
+
+const scaffold = require('./scaffold.js');
+
+module.exports = scaffold;

package/lib/scaffold.js

@@ -0,0 +1,177 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execSync } = require('node:child_process');
+
+const TEMPLATE_ITEMS = [
+  'AGENTS.md',
+  'memory.md',
+  'README.md',
+  'docs',
+  '.agents',
+  '.gitignore'
+];
+
+/**
+ * Returns the root path to the azcodr template files.
+ */
+function getTemplateDir() {
+  return path.resolve(__dirname, '..');
+}
+
+/**
+ * Validates the target directory to ensure it is suitable for scaffolding.
+ */
+function validateTarget(targetDir, options = {}) {
+  const { templateDir = getTemplateDir(), force = false } = options;
+  const resolvedTarget = path.resolve(targetDir);
+  const resolvedTemplate = path.resolve(templateDir);
+
+  if (resolvedTarget === resolvedTemplate) {
+    throw new Error(`Cannot scaffold into the azcodr template directory itself: ${resolvedTarget}`);
+  }
+
+  if (!fs.existsSync(resolvedTarget)) {
+    fs.mkdirSync(resolvedTarget, { recursive: true });
+    return;
+  }
+
+  const entries = fs.readdirSync(resolvedTarget);
+  if (entries.length > 0 && !force) {
+    throw new Error(
+      `Target directory is not empty (${entries.length} items found: ${resolvedTarget}). ` +
+      `Use --force to overwrite existing files.`
+    );
+  }
+}
+
+/**
+ * Safely creates or updates a symbolic link, falling back to a file copy if symlinks are unsupported.
+ */
+function ensureSymlink(targetDir, linkName, targetFileName) {
+  const linkPath = path.join(targetDir, linkName);
+  try {
+    const stat = fs.lstatSync(linkPath);
+    if (stat) {
+      fs.rmSync(linkPath, { force: true });
+    }
+  } catch {
+    // Path does not exist, proceed
+  }
+
+  try {
+    fs.symlinkSync(targetFileName, linkPath);
+  } catch {
+    // Fallback if environment (e.g., certain Windows configs) prevents symlink creation
+    const sourceFile = path.join(targetDir, targetFileName);
+    if (fs.existsSync(sourceFile)) {
+      fs.copyFileSync(sourceFile, linkPath);
+    }
+  }
+}
+
+/**
+ * Ensures all bash scripts in skill directories have executable permissions (0o755).
+ */
+function makeScriptsExecutable(targetDir) {
+  const skillsDir = path.join(targetDir, '.agents', 'skills');
+  if (!fs.existsSync(skillsDir)) return;
+
+  const skills = fs.readdirSync(skillsDir);
+  for (const skill of skills) {
+    const scriptsDir = path.join(skillsDir, skill, 'scripts');
+    if (fs.existsSync(scriptsDir) && fs.statSync(scriptsDir).isDirectory()) {
+      const files = fs.readdirSync(scriptsDir);
+      for (const file of files) {
+        if (file.endsWith('.sh')) {
+          const filePath = path.join(scriptsDir, file);
+          try {
+            fs.chmodSync(filePath, 0o755);
+          } catch {
+            // Non-critical if filesystem does not support POSIX permissions
+          }
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Recursively copies template files into the target directory and sets up symlinks and permissions.
+ */
+function copyTemplate(targetDir, templateDir = getTemplateDir()) {
+  const resolvedTarget = path.resolve(targetDir);
+  const resolvedTemplate = path.resolve(templateDir);
+
+  if (!fs.existsSync(resolvedTarget)) {
+    fs.mkdirSync(resolvedTarget, { recursive: true });
+  }
+
+  for (const item of TEMPLATE_ITEMS) {
+    const srcPath = path.join(resolvedTemplate, item);
+    if (!fs.existsSync(srcPath)) continue;
+
+    const destPath = path.join(resolvedTarget, item);
+    fs.cpSync(srcPath, destPath, { recursive: true, force: true, dereference: false });
+  }
+
+  // Ensure harness parity symlinks per AGENTS.md mandate
+  ensureSymlink(resolvedTarget, 'CLAUDE.md', 'AGENTS.md');
+  ensureSymlink(resolvedTarget, 'agents.md', 'AGENTS.md');
+
+  // Ensure scripts are executable
+  makeScriptsExecutable(resolvedTarget);
+}
+
+/**
+ * Initializes a git repository in the target directory if not already inside one.
+ */
+function initGit(targetDir, options = {}) {
+  const { noGit = false } = options;
+  if (noGit) return false;
+
+  const gitDir = path.join(targetDir, '.git');
+  if (fs.existsSync(gitDir)) return false;
+
+  try {
+    execSync('git init -q', { cwd: targetDir, stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * High-level orchestration function to scaffold the azcodr workspace into targetDir.
+ */
+function scaffold(options = {}) {
+  const {
+    targetDir = process.cwd(),
+    force = false,
+    noGit = false,
+    templateDir = getTemplateDir()
+  } = options;
+
+  const resolvedTarget = path.resolve(targetDir);
+  validateTarget(resolvedTarget, { templateDir, force });
+  copyTemplate(resolvedTarget, templateDir);
+  const gitInitialized = initGit(resolvedTarget, { noGit });
+
+  return {
+    success: true,
+    targetDir: resolvedTarget,
+    gitInitialized
+  };
+}
+
+module.exports = {
+  scaffold,
+  validateTarget,
+  copyTemplate,
+  ensureSymlink,
+  makeScriptsExecutable,
+  initGit,
+  getTemplateDir,
+  TEMPLATE_ITEMS
+};