azcodr 1.0.1 → 1.2.0

package/.agents/skills/lets-build/scripts/bootstrap_workspace.sh

@@ -1,52 +1,84 @@
 #!/usr/bin/env bash
 # ==============================================================================
 # bootstrap_workspace.sh
-# Deterministic Scaffolder for Hexagonal Multi-Tenant Workspaces
+# Topology-Aware Deterministic Scaffolder (Strict YAGNI, Zero Speculative Bloat)
 # ==============================================================================
 
 set -euo pipefail
 
 WORKSPACE_ROOT="${1:-$(pwd)}"
-LANGUAGE="${2:-generic}"
+TOPOLOGY="${2:-backend}"
+LANGUAGE="${3:-generic}"
 
-echo "🚀 Initializing Hexagonal Architecture Workspace in: ${WORKSPACE_ROOT}"
+echo "🚀 Initializing Topology-Aware Workspace in: ${WORKSPACE_ROOT}"
+echo "🏗️ Target Topology: ${TOPOLOGY}"
 echo "📦 Target Language Profile: ${LANGUAGE}"
 echo "--------------------------------------------------------------"
 
-# 1. Create Universal Specification Directories
-echo "1. Scaffolding Contract Specification Directories (specs/)..."
-mkdir -p "${WORKSPACE_ROOT}/specs/protobuf"
-mkdir -p "${WORKSPACE_ROOT}/specs/openapi"
-mkdir -p "${WORKSPACE_ROOT}/specs/schemas"
-mkdir -p "${WORKSPACE_ROOT}/specs/tokens"
+case "${TOPOLOGY}" in
+  extension)
+    echo "1. Scaffolding Browser Extension Source Tree (src/)..."
+    mkdir -p "${WORKSPACE_ROOT}/src/background"
+    mkdir -p "${WORKSPACE_ROOT}/src/content"
+    mkdir -p "${WORKSPACE_ROOT}/src/popup"
+    mkdir -p "${WORKSPACE_ROOT}/src/shared"
+    mkdir -p "${WORKSPACE_ROOT}/public"
+    
+    echo "2. Scaffolding Extension Test Suites (tests/)..."
+    mkdir -p "${WORKSPACE_ROOT}/tests/unit"
+    mkdir -p "${WORKSPACE_ROOT}/tests/e2e"
+    ;;
 
-# 2. Create Universal Hexagonal Source Directories
-echo "2. Scaffolding Hexagonal Source Tree (src/)..."
-mkdir -p "${WORKSPACE_ROOT}/src/domain/entities"
-mkdir -p "${WORKSPACE_ROOT}/src/domain/value_objects"
-mkdir -p "${WORKSPACE_ROOT}/src/domain/services"
-mkdir -p "${WORKSPACE_ROOT}/src/ports/primary"
-mkdir -p "${WORKSPACE_ROOT}/src/ports/secondary"
-mkdir -p "${WORKSPACE_ROOT}/src/adapters/primary"
-mkdir -p "${WORKSPACE_ROOT}/src/adapters/secondary"
+  game|engine)
+    echo "1. Scaffolding Game/Engine Source Tree (src/)..."
+    mkdir -p "${WORKSPACE_ROOT}/src/core"
+    mkdir -p "${WORKSPACE_ROOT}/src/ecs"
+    mkdir -p "${WORKSPACE_ROOT}/src/renderer"
+    mkdir -p "${WORKSPACE_ROOT}/src/assets"
+    
+    echo "2. Scaffolding Game/Engine Test Suites (tests/)..."
+    mkdir -p "${WORKSPACE_ROOT}/tests/unit"
+    mkdir -p "${WORKSPACE_ROOT}/tests/benchmarks"
+    ;;
 
-# 3. Create Universal Test Directories
-echo "3. Scaffolding Test Suites (tests/)..."
-mkdir -p "${WORKSPACE_ROOT}/tests/unit"
-mkdir -p "${WORKSPACE_ROOT}/tests/integration"
-mkdir -p "${WORKSPACE_ROOT}/tests/contracts"
-mkdir -p "${WORKSPACE_ROOT}/tests/acceptance"
+  cli)
+    echo "1. Scaffolding CLI Source Tree (src/)..."
+    mkdir -p "${WORKSPACE_ROOT}/src/cmd"
+    mkdir -p "${WORKSPACE_ROOT}/src/core"
+    mkdir -p "${WORKSPACE_ROOT}/src/io"
+    
+    echo "2. Scaffolding CLI Test Suites (tests/)..."
+    mkdir -p "${WORKSPACE_ROOT}/tests/unit"
+    mkdir -p "${WORKSPACE_ROOT}/tests/integration"
+    ;;
 
-# 4. Create Deployment & Infrastructure Directories
-echo "4. Scaffolding Deployment Infrastructure (deploy/)..."
-mkdir -p "${WORKSPACE_ROOT}/deploy/docker"
-mkdir -p "${WORKSPACE_ROOT}/deploy/compose"
-mkdir -p "${WORKSPACE_ROOT}/deploy/k8s"
+  backend|web|saas)
+    echo "1. Scaffolding Backend / Enterprise Source Tree (src/)..."
+    mkdir -p "${WORKSPACE_ROOT}/src/domain/entities"
+    mkdir -p "${WORKSPACE_ROOT}/src/domain/value_objects"
+    mkdir -p "${WORKSPACE_ROOT}/src/domain/services"
+    mkdir -p "${WORKSPACE_ROOT}/src/ports/primary"
+    mkdir -p "${WORKSPACE_ROOT}/src/ports/secondary"
+    mkdir -p "${WORKSPACE_ROOT}/src/adapters/primary"
+    mkdir -p "${WORKSPACE_ROOT}/src/adapters/secondary"
+    
+    echo "2. Scaffolding Specifications (specs/)..."
+    mkdir -p "${WORKSPACE_ROOT}/specs/openapi"
+    mkdir -p "${WORKSPACE_ROOT}/specs/tokens"
+    
+    echo "3. Scaffolding Backend Test Suites (tests/)..."
+    mkdir -p "${WORKSPACE_ROOT}/tests/unit"
+    mkdir -p "${WORKSPACE_ROOT}/tests/integration"
+    mkdir -p "${WORKSPACE_ROOT}/tests/contracts"
+    mkdir -p "${WORKSPACE_ROOT}/tests/acceptance"
+    
+    echo "4. Scaffolding Deployment Infrastructure (deploy/)..."
+    mkdir -p "${WORKSPACE_ROOT}/deploy/docker"
+    mkdir -p "${WORKSPACE_ROOT}/deploy/compose"
 
-# 5. Create Default Design Tokens Spec
-TOKEN_SPEC="${WORKSPACE_ROOT}/specs/tokens/tokens.json"
-if [[ ! -f "${TOKEN_SPEC}" ]]; then
-  cat << 'EOF' > "${TOKEN_SPEC}"
+    TOKEN_SPEC="${WORKSPACE_ROOT}/specs/tokens/tokens.json"
+    if [[ ! -f "${TOKEN_SPEC}" ]]; then
+      cat << 'EOF' > "${TOKEN_SPEC}"
 {
   "color": {
     "brand": {
@@ -62,7 +94,15 @@ if [[ ! -f "${TOKEN_SPEC}" ]]; then
   }
 }
 EOF
-fi
+    fi
+    ;;
+
+  *)
+    echo "1. Scaffolding Generic / Library Source Tree (src/)..."
+    mkdir -p "${WORKSPACE_ROOT}/src"
+    mkdir -p "${WORKSPACE_ROOT}/tests/unit"
+    ;;
+esac
 
 echo "--------------------------------------------------------------"
-echo "✅ Hexagonal directory tree and contract specifications scaffolded successfully!"
+echo "✅ Topology '${TOPOLOGY}' scaffolded with strict YAGNI (0 speculative folders)!"

package/.editorconfig

@@ -0,0 +1,19 @@
+# http://editorconfig.org
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab
+
+[*.go]
+indent_style = tab

package/.gitignore

@@ -18,3 +18,6 @@ Thumbs.db
 .env
 .env.local
 .env.*.local
+
+# Case-insensitive filesystem parity (agents.md is generated/symlinked on Linux, native on macOS/Windows)
+agents.md

package/AGENTS.md

@@ -4,7 +4,7 @@
 > **Rule Zero:** Assume nothing. Every action must be grounded in verified evidence from this workspace or direct instructions from the user.  
 > **Open-Source Mandate:** Always utilize 100% open-source tools, frameworks, libraries, and packages across all architectural domains.  
 > **Atomicity Mandate:** All rules, skills, code units, migrations, and transactions must be strictly atomic (indivisible, self-contained, and composable with full ACID safety).  
-> **Agnostic Mandate:** Decouple domain core from transient technologies, languages, and stacks (Hexagonal Ports & Adapters; zero language bias).
+> **Architecture Mandate:** Architecture emerges strictly from problem constraints and execution targets (Problem-First; zero tool/platform bias). Match architectural style to problem topology (Hexagonal for enterprise backends, Platform Scripting for extensions, Data-Oriented Design for game engines, Command Pipeline for CLIs, Game Loop for canvas games). Never force premature abstractions or universal templates.
 
 ---
 
@@ -14,10 +14,12 @@
 2. **Ground Truth Only:** A statement is only true if proven by a workspace file, verified command output, or direct user instruction.
 3. **Unknown Until Verified:** If something is not explicitly written in the workspace or stated by the user, treat it as unknown.
 4. **Strict Open Standards:** Standardize on open-source solutions and open specs (Semgrep, Trivy, Gitleaks, OpenTelemetry, OPA, OCI, Wasm, CloudEvents).
-5. **Universal Agnosticism:** Core business rules are technology-, language-, and stack-agnostic; runtimes connect via swappable adapters with zero language bias.
-6. **Systemic Atomicity:** Every skill, rule, database transaction, and refactoring step must be atomic (Single Responsibility, zero side-effects, full rollback).
-7. **Workspace Sovereignty:** Total containment within the local workspace root (`./`). Zero interference from global configs, tools, or sibling projects.
-8. **Continuous Learning:** Log all defects, DO's/DONT's, and lessons into `docs/knowledge/` and `memory.md`, dynamically updating atomic rules.
+5. **Problem-First & Topology Alignment:** Problem domain and operational constraints (latency budget, GC tolerance, memory, execution environment) strictly dictate the architectural style and toolchain. Never select tools before defining the problem space.
+6. **Evolutionary Architecture & Refactor-Before-Add:** As complexity grows, code must graduate across explicit architectural tipping points. Refactor structure first under existing green tests before implementing new features. Never append code into rotting files.
+7. **True Incremental TDD & Nano-Cycles:** Never dump test suites in batches ("Test-First Waterfall"). Follow Uncle Bob's Three Laws: write one micro-assertion at a time, verify RED failure output, write minimal code to turn GREEN, and refactor under green.
+8. **Systemic Atomicity:** Every skill, rule, database transaction, and refactoring step must be atomic (Single Responsibility, zero side-effects, full rollback).
+9. **Workspace Sovereignty:** Total containment within the local workspace root (`./`). Zero interference from global configs, tools, or sibling projects.
+10. **Continuous Learning:** Ingest all verified defects, lessons, and architectural invariants directly into domain rules and `memory.md`.
 
 ### The 5 Core Branch Questions
 Before acting on any decision branch, answer:
@@ -40,10 +42,10 @@ Before acting on any decision branch, answer:
 
 Progress all tasks systematically through the unified **Agent Cognitive & Agile Domain Lifecycle**, seamlessly interlocking the 5 agent operational disciplines with the 5-phase domain engineering pipeline:
 ```
-1. DISCOVER / REQUIREMENTS   ──► Read-only inspection; INVEST user stories & executable Gherkin scenarios.
-2. INTERROGATE / DOMAIN     ──► Relentless questioning; Ubiquitous Language & domain invariants.
+1. DISCOVER / REQUIREMENTS   ──► Read-only inspection; Problem Space & operational constraints; INVEST stories & Gherkin.
+2. INTERROGATE / DOMAIN     ──► Relentless questioning; Ubiquitous Language, Aggregate invariants & state machines.
 3. PLAN / OUTER TDD         ──► Minimal blast radius; failing Outer Acceptance Test (UI/API RED).
-4. EXECUTE / INNER TDD      ──► Surgical edits; Inner TDD collaborator discovery (RED-GREEN-REFACTOR).
+4. EXECUTE / INNER TDD      ──► Incremental nano-cycles (Uncle Bob's 3 Laws: 1 micro-assertion RED ➔ MINIMAL pass GREEN ➔ REFACTOR).
 5. VERIFY / DoD & PROOF     ──► Outer test turns GREEN; boundary smoke tests & 100.00% test coverage.
 ```
 ---
@@ -99,7 +101,7 @@ To prevent context bloat and keep prompt overhead minimal, detailed engineering
 | **Domain Modeling** | [docs/rules/domain_expertise.md](./docs/rules/domain_expertise.md) | Business capabilities, Aggregate Root invariants, Ubiquitous Language. |
 | **Relentless Questioning** | [docs/rules/relentless_questioning.md](./docs/rules/relentless_questioning.md) | Dynamic context-aware interrogation loops, adaptive decision trees. |
 | **Workspace Isolation** | [docs/rules/workspace_isolation.md](./docs/rules/workspace_isolation.md) | Strict workspace sovereignty, zero global contamination, local ground truth. |
-| **Continuous Learning** | [docs/rules/continuous_learning.md](./docs/rules/continuous_learning.md) | Automated defect post-mortems, DO's/DONT's logging, dynamic rule updates. |
+| **Continuous Learning** | [docs/rules/continuous_learning.md](./docs/rules/continuous_learning.md) | Direct rule ingestion, root-cause analysis, dynamic invariant updates. |
 | **Upstream Sync** | [docs/rules/upstream_synchronization.md](./docs/rules/upstream_synchronization.md) | Logging generic architecture improvements to changes.md; zero baseline pollution. |
 ---
 
@@ -114,5 +116,5 @@ To prevent context bloat and keep prompt overhead minimal, detailed engineering
   - [`lets-build`](.agents/skills/lets-build/SKILL.md): Conducting architecture interviews to finalize stack, frameworks, package managers, and bootstrapping projects.
   - [`relentless-questioner`](.agents/skills/relentless-questioner/SKILL.md): Dynamic context-aware interrogation loops before planning and coding.
 - **Relentless Skill Architecture Inquiry:** Never author or update skills on assumptions. Interrogate all 7 inquiry branches (placement, trigger intent, domain truth, gotchas/anti-patterns, determinism, progressive bloat, verification loop) defined in [docs/rules/agentic_configuration.md](./docs/rules/agentic_configuration.md) before writing `SKILL.md`.
-- **Workspace Memory & Knowledge Hub:** Consult [`memory.md`](./memory.md) for ADRs, and [`docs/knowledge/`](./docs/knowledge/knowledge_graph.md) for system topologies, issue logs, and DO's/DONT's.
+- **Workspace Memory & Knowledge Hub:** Consult [`memory.md`](./memory.md) for ADRs, and [`docs/knowledge/`](./docs/knowledge/knowledge_graph.md) for system topologies and domain glossaries.
 - **Harness Parity & Symlinks:** `AGENTS.md`, `CLAUDE.md`, and `agents.md` must remain identical via filesystem symbolic links to eliminate configuration divergence across different agent harnesses.

package/README.md

@@ -34,11 +34,8 @@
 │       ├── product-analyst/          # INVEST user stories & Gherkin criteria
 │       └── relentless-questioner/    # Context-aware dynamic interrogation loop
 ├── docs/
-│   ├── knowledge/                    # Institutional knowledge & token economy
-│   │   ├── dos_and_donts.md          # Consolidated DO's and DONT's directory
-│   │   ├── issue_log.md              # Defect post-mortems & preventing rules
+│   ├── knowledge/                    # Institutional knowledge & domain contracts
 │   │   ├── knowledge_graph.md        # Visual topologies & fast-lookup matrices
-│   │   ├── lessons_learned.md        # Strategic architectural takeaways
 │   │   └── ubiquitous_language.md    # Living Ubiquitous Language glossary template
 │   └── rules/                        # 47 atomic single-responsibility domain rules
 ├── AGENTS.md                         # Lean root agentic configuration (< 120 lines)
@@ -177,8 +174,6 @@ Once confirmed, the agent automatically executes:
 ## 🏛️ Workspace Memory & Knowledge Hub
 
 - 🗺️ **[System Knowledge Graph](./docs/knowledge/knowledge_graph.md)**: Visual subsystem topologies and entity-relationship models.
-- 📋 **[Consolidated DO's & DONT's](./docs/knowledge/dos_and_donts.md)**: High-impact engineering invariants and anti-patterns to avoid.
-- 🐛 **[Coding Issue Log](./docs/knowledge/issue_log.md)**: Defect post-mortems and preventative rules.
-- 💡 **[Institutional Lessons Learned](./docs/knowledge/lessons_learned.md)**: Strategic engineering insights.
-- 📜 **[Lightweight ADR Ledger](./memory.md)**: Formal Architectural Decision Records.
+- 📖 **[Living Ubiquitous Language Glossary](./docs/knowledge/ubiquitous_language.md)**: Authoritative domain vocabulary contract.
+- 📜 **[Lightweight ADR Ledger](./memory.md)**: Formal Architectural Decision Records and governing rules.
 - 📝 **[Upstream Changes Ledger](./changes.md)**: Record candidate improvements and generic patterns for the upstream azcodr template.

package/bin/azcodr.js

@@ -3,13 +3,12 @@
 
 const path = require('node:path');
 const readline = require('node:readline');
+const fs = require('node:fs');
 const { scaffold, logChange, getTemplateDir } = require('../lib/scaffold.js');
 const pkg = require('../package.json');
 
-const args = process.argv.slice(2);
-
-function printHelp() {
-  console.log(`
+function printHelp(out = console.log) {
+  out(`
 azcodr v${pkg.version}
 Enterprise Multi-Tenant Architecture & Agentic Engineering Starter Template
 
@@ -22,208 +21,282 @@ Commands:
   change <title>  Log a generic architectural change to changes.md
 
 Scaffold Options:
+  -d, --dry-run   Simulate scaffolding without modifying filesystem
+  -s, --silent    Suppress console output messages
   -f, --force     Overwrite existing files in target directory without confirmation
   --no-git        Do not initialize a git repository
   -v, --version   Display version number
   -h, --help      Display this help message
 
 Change Options:
-  -c, --category  Category (Rule | Skill | Infrastructure | CLI | Knowledge Hub)
+  -c, --category  Category (Architecture | Rule | Skill | Infrastructure | CLI | Knowledge Hub)
   -f, --files     Target file(s) affected (e.g. "docs/rules/caching.md")
   -r, --rationale Rationale for upstream template incorporation
   -d, --desc      Detailed description of the change
 
 Examples:
   npx azcodr my-project
+  npx azcodr . --dry-run
   npx azcodr . --force
   npx azcodr change "Add Wasm plugin interface" -c Architecture
 `);
 }
 
-function printVersion() {
-  console.log(pkg.version);
+function printVersion(out = console.log) {
+  out(pkg.version);
 }
 
-function askQuestion(query) {
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout
-  });
+function askQuestion(query, { input = process.stdin, output = process.stdout } = {}) {
+  const rl = readline.createInterface({ input, output });
 
   return new Promise((resolve) => {
+    let resolved = false;
     rl.question(query, (answer) => {
-      rl.close();
-      resolve(answer.trim());
+      if (!resolved) {
+        resolved = true;
+        rl.close();
+        resolve(answer.trim());
+      }
+    });
+    rl.on('close', () => {
+      if (!resolved) {
+        resolved = true;
+        resolve('');
+      }
     });
   });
 }
 
-async function handleLogChange() {
+async function handleLogChange(rawArgs = process.argv.slice(2), io = {}) {
+  const {
+    out = console.log,
+    err = console.error,
+    exit = process.exit,
+    stdin = process.stdin,
+    stdout = process.stdout,
+    cwd = process.cwd(),
+    logChange: logChangeFn = logChange
+  } = io;
+
   let title = null;
   let category = 'Architecture';
   let targetFiles = 'docs/rules/';
   let rationale = 'Generic architectural enhancement';
   let description = '';
 
-  for (let i = 1; i < args.length; i++) {
-    const a = args[i];
+  for (let i = 1; i < rawArgs.length; i++) {
+    const a = rawArgs[i];
     if (a === '-c' || a === '--category') {
-      category = args[++i] || category;
+      category = rawArgs[++i] || category;
     } else if (a === '-f' || a === '--files') {
-      targetFiles = args[++i] || targetFiles;
+      targetFiles = rawArgs[++i] || targetFiles;
     } else if (a === '-r' || a === '--rationale') {
-      rationale = args[++i] || rationale;
+      rationale = rawArgs[++i] || rationale;
     } else if (a === '-d' || a === '--desc' || a === '--description') {
-      description = args[++i] || description;
-    } else if (!a.startsWith('-')) {
-      if (!title) {
-        title = a;
-      }
+      description = rawArgs[++i] || description;
+    } else if (a.startsWith('-')) {
+      err(`❌ Error: Unknown argument '${a}'. Run 'npx azcodr --help' for available options.`);
+      return exit(1);
+    } else if (!title) {
+      title = a;
     }
   }
 
   if (!title) {
-    if (process.stdin.isTTY) {
-      title = await askQuestion('? Change title: ');
+    if (stdin.isTTY) {
+      title = await askQuestion('? Change title: ', { input: stdin, output: stdout });
     }
   }
 
   if (!title) {
-    console.error('❌ Error: A title is required to log an upstream change.');
-    console.error('Usage: npx azcodr change "<title>" [-c Category] [-f Files] [-r Rationale] [-d Description]');
-    process.exit(1);
+    err('❌ Error: A title is required to log an upstream change.');
+    err('Usage: npx azcodr change "<title>" [-c Category] [-f Files] [-r Rationale] [-d Description]');
+    return exit(1);
   }
 
   try {
-    const res = logChange({
+    const res = logChangeFn({
       title,
       category,
       targetFiles,
       rationale,
       description,
-      targetDir: process.cwd()
+      targetDir: cwd
     });
-    console.log(`\n✅ Upstream change logged to ${res.filePath}\n`);
-    process.exit(0);
-  } catch (err) {
-    console.error(`\n❌ Failed to log change: ${err.message}\n`);
-    process.exit(1);
+    out(`\n✅ Upstream change logged to ${res.filePath}\n`);
+    return exit(0);
+  } catch (error) {
+    err(`\n❌ Failed to log change: ${error.message}\n`);
+    return exit(1);
   }
 }
 
-async function main() {
-  if (args.length > 0 && (args[0] === '-h' || args[0] === '--help')) {
-    printHelp();
-    process.exit(0);
-  }
-
-  if (args.length > 0 && (args[0] === '-v' || args[0] === '--version')) {
-    printVersion();
-    process.exit(0);
-  }
+async function runCli(rawArgs = process.argv.slice(2), io = {}) {
+  const {
+    out = console.log,
+    err = console.error,
+    exit = process.exit,
+    stdin = process.stdin,
+    stdout = process.stdout,
+    cwd = process.cwd(),
+    templateDir = getTemplateDir(),
+    scaffold: scaffoldFn = scaffold
+  } = io;
 
-  if (args.length > 0 && (args[0] === 'change' || args[0] === 'log-change')) {
-    await handleLogChange();
-    return;
+  if (rawArgs[0] === 'change' || rawArgs[0] === 'log-change') {
+    return handleLogChange(rawArgs, io);
   }
 
   let targetDir = null;
   let force = false;
   let noGit = false;
+  let dryRun = false;
+  let silent = false;
 
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
+  for (let i = 0; i < rawArgs.length; i++) {
+    const arg = rawArgs[i];
     if (arg === '-h' || arg === '--help') {
-      printHelp();
-      process.exit(0);
+      printHelp(out);
+      return exit(0);
     } else if (arg === '-v' || arg === '--version') {
-      printVersion();
-      process.exit(0);
+      printVersion(out);
+      return exit(0);
     } else if (arg === '-f' || arg === '--force') {
       force = true;
     } else if (arg === '--no-git') {
       noGit = true;
-    } else if (!arg.startsWith('-')) {
-      if (!targetDir) {
-        targetDir = arg;
-      }
+    } else if (arg === '-d' || arg === '--dry-run') {
+      dryRun = true;
+    } else if (arg === '-s' || arg === '--silent') {
+      silent = true;
+    } else if (arg.startsWith('-')) {
+      err(`❌ Error: Unknown argument '${arg}'. Run 'npx azcodr --help' for available options.`);
+      return exit(1);
+    } else if (!targetDir) {
+      targetDir = arg;
     }
   }
 
-  console.log('\n🚀 azcodr - Enterprise Multi-Tenant Architecture & Agentic Engineering\n');
+  if (!silent) {
+    out('\n🚀 azcodr - Enterprise Multi-Tenant Architecture & Agentic Engineering\n');
+  }
 
   if (!targetDir) {
-    if (process.stdin.isTTY) {
-      const answer = await askQuestion('? Where would you like to initialize your project? (./) ');
+    if (stdin.isTTY) {
+      const answer = await askQuestion('? Where would you like to initialize your project? (./) ', {
+        input: stdin,
+        output: stdout
+      });
       targetDir = answer || '.';
     } else {
       targetDir = '.';
     }
   }
 
-  const resolvedTarget = path.resolve(process.cwd(), targetDir);
-  const templateDir = getTemplateDir();
+  const resolvedTarget = path.resolve(cwd, targetDir);
 
   if (resolvedTarget === templateDir) {
-    console.error(`❌ Error: Cannot scaffold into the template directory itself: ${resolvedTarget}`);
-    process.exit(1);
+    err(`❌ Error: Cannot scaffold into the template directory itself: ${resolvedTarget}`);
+    return exit(1);
   }
 
-  const fs = require('node:fs');
   if (fs.existsSync(resolvedTarget)) {
+    const stat = fs.statSync(resolvedTarget);
+    if (!stat.isDirectory()) {
+      err(`❌ Error: Target '${resolvedTarget}' already exists and is not a directory.`);
+      return exit(1);
+    }
     const entries = fs.readdirSync(resolvedTarget);
     if (entries.length > 0 && !force) {
-      if (process.stdin.isTTY) {
+      if (stdin.isTTY) {
         const confirm = await askQuestion(
-          `⚠️  Target directory '${targetDir}' is not empty (${entries.length} items). Continue? (y/N) `
+          `⚠️  Target directory '${targetDir}' is not empty (${entries.length} items). Continue? (y/N) `,
+          { input: stdin, output: stdout }
         );
         if (confirm.toLowerCase() !== 'y' && confirm.toLowerCase() !== 'yes') {
-          console.log('Scaffolding aborted.');
-          process.exit(0);
+          out('Scaffolding aborted.');
+          return exit(0);
         }
         force = true;
       } else {
-        console.error(
-          `❌ Error: Target directory '${resolvedTarget}' is not empty. Use --force to proceed.`
-        );
-        process.exit(1);
+        err(`❌ Error: Target directory '${resolvedTarget}' is not empty. Use --force to proceed.`);
+        return exit(1);
       }
     }
   }
 
-  console.log(`📦 Scaffolding azcodr into: ${resolvedTarget}`);
+  if (dryRun) {
+    if (!silent) {
+      out(`🔍 DRY RUN: Simulating azcodr scaffolding into: ${resolvedTarget}\n`);
+    }
+  } else if (!silent) {
+    out(`📦 Scaffolding azcodr into: ${resolvedTarget}`);
+  }
 
   try {
-    const result = scaffold({
+    const result = scaffoldFn({
       targetDir: resolvedTarget,
       force,
       noGit,
-      templateDir
+      templateDir,
+      dryRun,
+      silent
     });
 
-    console.log('  ✅ Progressive disclosure rules copied (docs/rules/)');
-    console.log('  ✅ Workspace knowledge hub and ADR ledger copied (docs/knowledge/, memory.md)');
-    console.log('  ✅ Specialized agentic skills copied (.agents/skills/)');
-    console.log('  ✅ Upstream changes ledger initialized (changes.md)');
-    console.log('  ✅ Agent directives and harness symlinks established (AGENTS.md, CLAUDE.md, agents.md)');
-    if (result.gitInitialized) {
-      console.log('  ✅ Git repository initialized');
+    if (dryRun) {
+      if (!silent) {
+        for (const action of result.actions) {
+          out(`  [preview] ${action}`);
+        }
+        out('\n🎉 Dry run completed. 0 files modified on disk.\n');
+      }
+      return exit(0);
     }
 
-    console.log('\n🎉 azcodr initialized successfully!\n');
-    console.log('Next steps:');
-    if (targetDir !== '.' && targetDir !== './') {
-      console.log(`  1. cd ${targetDir}`);
+    if (!silent) {
+      out('  ✅ Progressive disclosure rules copied (docs/rules/)');
+      out('  ✅ Workspace knowledge hub and ADR ledger copied (docs/knowledge/, memory.md)');
+      out('  ✅ Specialized agentic skills copied (.agents/skills/)');
+      out('  ✅ Upstream changes ledger initialized (changes.md)');
+      out('  ✅ Editor formatting standards initialized (.editorconfig)');
+      out('  ✅ Agent directives and harness symlinks established (AGENTS.md, CLAUDE.md, agents.md)');
+      if (result.gitInitialized) {
+        out('  ✅ Git repository initialized');
+      }
+
+      out('\n🎉 azcodr initialized successfully!\n');
+      out('Next steps:');
+      if (targetDir !== '.' && targetDir !== './') {
+        out(`  1. cd ${targetDir}`);
+      }
+      out('  2. Open the project in your AI coding assistant (Antigravity, Claude Code, Cursor, OpenHands)');
+      out('  3. Run /lets-build to start the architectural interview and scaffold your application stack!\n');
     }
-    console.log('  2. Open the project in your AI coding assistant (Antigravity, Claude Code, Cursor, OpenHands)');
-    console.log('  3. Run /lets-build to start the architectural interview and scaffold your application stack!\n');
+    return exit(0);
+  } catch (error) {
+    err(`\n❌ Scaffolding failed: ${error.message}\n`);
+    return exit(1);
+  }
+}
+
+async function main() {
+  try {
+    await runCli(process.argv.slice(2));
   } catch (err) {
-    console.error(`\n❌ Scaffolding failed: ${err.message}\n`);
+    console.error('Unexpected error:', err);
     process.exit(1);
   }
 }
 
-main().catch((err) => {
-  console.error('Unexpected error:', err);
-  process.exit(1);
-});
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  runCli,
+  handleLogChange,
+  askQuestion,
+  printHelp,
+  printVersion,
+  main
+};