azcodr 1.0.0 → 1.1.0

package/.agents/skills/agentic-architect/scripts/validate_agentic_configs.sh

@@ -45,21 +45,37 @@ if [[ -L "${CLAUDE_FILE}" ]]; then
   else
     log_fail "CLAUDE.md points to '${TARGET}' instead of 'AGENTS.md'."
   fi
+elif [[ -f "${CLAUDE_FILE}" ]] && [[ "$(< "${CLAUDE_FILE}")" == "AGENTS.md" ]]; then
+  log_pass "CLAUDE.md is a text pointer to AGENTS.md (symlink fallback)."
 else
   log_fail "CLAUDE.md is not a symbolic link."
 fi
 
-# Check agents.md symlink
+# Check agents.md symlink (case-insensitive filesystem aware)
 AGENTS_LOWER="${WORKSPACE_ROOT}/agents.md"
-if [[ -L "${AGENTS_LOWER}" ]]; then
-  TARGET=$(readlink "${AGENTS_LOWER}")
-  if [[ "${TARGET}" == "AGENTS.md" ]]; then
-    log_pass "agents.md is a valid symlink to AGENTS.md."
+IS_CASE_INSENSITIVE=false
+if [[ "$(uname -s)" == "Darwin" ]] || [[ "$(uname -s)" =~ (MINGW|MSYS|CYGWIN) ]]; then
+  IS_CASE_INSENSITIVE=true
+elif [[ -f "${AGENTS_FILE}" ]] && [[ -f "${AGENTS_LOWER}" ]] && [[ ! -L "${AGENTS_LOWER}" ]]; then
+  IS_CASE_INSENSITIVE=true
+fi
+
+if [[ "${IS_CASE_INSENSITIVE}" == "true" ]]; then
+  log_pass "agents.md is satisfied natively by AGENTS.md (case-insensitive filesystem)."
+else
+  if [[ ! -L "${AGENTS_LOWER}" ]] && [[ ! -e "${AGENTS_LOWER}" ]] && [[ -f "${AGENTS_FILE}" ]]; then
+    ln -sf "AGENTS.md" "${AGENTS_LOWER}"
+  fi
+  if [[ -L "${AGENTS_LOWER}" ]]; then
+    TARGET=$(readlink "${AGENTS_LOWER}")
+    if [[ "${TARGET}" == "AGENTS.md" ]]; then
+      log_pass "agents.md is a valid symlink to AGENTS.md."
+    else
+      log_fail "agents.md points to '${TARGET}' instead of 'AGENTS.md'."
+    fi
   else
-    log_fail "agents.md points to '${TARGET}' instead of 'AGENTS.md'."
+    log_fail "agents.md is not a symbolic link."
   fi
-else
-  log_fail "agents.md is not a symbolic link."
 fi
 
 # 2. Checking Progressive Disclosure Rules (docs/rules)

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

@@ -100,7 +100,7 @@ To prevent context bloat and keep prompt overhead minimal, detailed engineering
 | **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. |
-| **Upstream Sync** | [docs/rules/upstream_synchronization.md](./docs/rules/upstream_synchronization.md) | Syncing generic AI knowledge to upstream baselines; zero domain contamination. |
+| **Upstream Sync** | [docs/rules/upstream_synchronization.md](./docs/rules/upstream_synchronization.md) | Logging generic architecture improvements to changes.md; zero baseline pollution. |
 ---
 
 ## 4. Agent Configuration & Workspace Architecture
@@ -113,7 +113,6 @@ To prevent context bloat and keep prompt overhead minimal, detailed engineering
   - [`clean-code-refactor`](.agents/skills/clean-code-refactor/SKILL.md): Refactoring code smells with Clean Code, SOLID, and design patterns.
   - [`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.
-  - [`merge-ai`](.agents/skills/merge-ai/SKILL.md): Auditing, filtering, and merging generic rules and skills to upstream baseline.
 - **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.
 - **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

@@ -31,7 +31,6 @@
 │       ├── clean-code-refactor/      # Refactoring code smells with GoF & Clean Code
 │       ├── compliance-audit/         # SOC 2, ISO 27001 & OWASP open-source audits
 │       ├── lets-build/               # Architecture interview & project bootstrapper
-│       ├── merge-ai/                 # Auditing & merging generic AI knowledge to upstream
 │       ├── product-analyst/          # INVEST user stories & Gherkin criteria
 │       └── relentless-questioner/    # Context-aware dynamic interrogation loop
 ├── docs/
@@ -45,6 +44,7 @@
 ├── AGENTS.md                         # Lean root agentic configuration (< 120 lines)
 ├── CLAUDE.md -> AGENTS.md            # Filesystem symlink for harness parity
 ├── agents.md -> AGENTS.md            # Filesystem symlink for harness parity
+├── changes.md                        # Upstream changes ledger
 ├── memory.md                         # Master memory hub & Lightweight ADR ledger
 └── README.md                         # Project documentation
 ```
@@ -103,7 +103,7 @@ The architecture enforces 47 atomic, single-responsibility domain rules. Read on
 | **Relentless Questioning** | [`relentless_questioning.md`](./docs/rules/relentless_questioning.md) | Dynamic context-aware interrogation loops, adaptive decision trees. |
 | **Workspace Isolation** | [`workspace_isolation.md`](./docs/rules/workspace_isolation.md) | Strict workspace sovereignty, zero global contamination, local ground truth. |
 | **Continuous Learning** | [`continuous_learning.md`](./docs/rules/continuous_learning.md) | Automated defect post-mortems, DO's/DONT's logging, dynamic rule updates. |
-| **Upstream Sync** | [`upstream_synchronization.md`](./docs/rules/upstream_synchronization.md) | Syncing generic AI knowledge to upstream baselines; zero domain contamination. |
+| **Upstream Sync** | [`upstream_synchronization.md`](./docs/rules/upstream_synchronization.md) | Logging generic architecture improvements to changes.md; zero baseline pollution. |
 
 ---
 
@@ -113,7 +113,6 @@ The architecture enforces 47 atomic, single-responsibility domain rules. Read on
 - [`clean-code-refactor`](.agents/skills/clean-code-refactor/SKILL.md): Refactoring code smells with Clean Code, SOLID, and modern design patterns.
 - [`compliance-audit`](.agents/skills/compliance-audit/SKILL.md): Conducting SOC 2, ISO 27001, and OWASP audits using open-source scanners.
 - [`lets-build`](.agents/skills/lets-build/SKILL.md): Conducting architecture interviews to finalize stack, frameworks, package managers, and bootstrapping projects.
-- [`merge-ai`](.agents/skills/merge-ai/SKILL.md): Auditing, filtering, and merging generic rules and skills to upstream baseline.
 - [`product-analyst`](.agents/skills/product-analyst/SKILL.md): Aligning OKRs, backlog ordering (Kano/MoSCoW/RICE), INVEST stories, and Gherkin criteria.
 - [`relentless-questioner`](.agents/skills/relentless-questioner/SKILL.md): Dynamic context-aware interrogation loops before planning and coding.
 
@@ -182,3 +181,4 @@ Once confirmed, the agent automatically executes:
 - 🐛 **[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.
+- 📝 **[Upstream Changes Ledger](./changes.md)**: Record candidate improvements and generic patterns for the upstream azcodr template.

package/bin/azcodr.js

@@ -3,149 +3,300 @@
 
 const path = require('node:path');
 const readline = require('node:readline');
-const { scaffold, getTemplateDir } = require('../lib/scaffold.js');
+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
 
 Usage:
   npx azcodr [directory] [options]
+  npx azcodr change <title> [options]
 
-Arguments:
-  directory       Target directory to scaffold (default: current directory)
+Commands:
+  [directory]     Scaffold azcodr template into directory (default: current directory)
+  change <title>  Log a generic architectural change to changes.md
 
-Options:
+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 (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 main() {
+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 < rawArgs.length; i++) {
+    const a = rawArgs[i];
+    if (a === '-c' || a === '--category') {
+      category = rawArgs[++i] || category;
+    } else if (a === '-f' || a === '--files') {
+      targetFiles = rawArgs[++i] || targetFiles;
+    } else if (a === '-r' || a === '--rationale') {
+      rationale = rawArgs[++i] || rationale;
+    } else if (a === '-d' || a === '--desc' || a === '--description') {
+      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 (stdin.isTTY) {
+      title = await askQuestion('? Change title: ', { input: stdin, output: stdout });
+    }
+  }
+
+  if (!title) {
+    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 = logChangeFn({
+      title,
+      category,
+      targetFiles,
+      rationale,
+      description,
+      targetDir: cwd
+    });
+    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 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 (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('  ✅ 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
+};

package/changes.md

@@ -0,0 +1,50 @@
+# Upstream Changes Ledger (`changes.md`)
+
+> **Core Purpose:** Record candidate improvements, generic architectural updates, defect post-mortems, and rule enhancements discovered in this workspace that should be incorporated into the upstream `azcodr` baseline template. No automated git merging or external repo mutation is performed.
+
+---
+
+## 1. Specification & Protocol
+
+When an AI agent or engineer discovers a generic architectural improvement, bug fix, or rule refinement during project development, append an entry below using this atomic format:
+
+```markdown
+### [YYYY-MM-DD] <Title of Change>
+- **Category:** Rule | Skill | Infrastructure | CLI | Knowledge Hub
+- **Target File(s):** `docs/rules/...`, `.agents/skills/...`, etc.
+- **Rationale:** Why this improvement is necessary or valuable across all enterprise projects.
+- **Description:** Concise summary of the mutation or invariant added.
+- **Domain Filter Verification:** Verified 100% generic; purged of all project-specific business entities and models.
+```
+
+---
+
+## 2. Upstream Changes Log
+
+### [2026-09-25] Initialized npx Scaffolder CLI and npm Package
+- **Category:** CLI & Infrastructure
+- **Target File(s):** `bin/azcodr.js`, `lib/scaffold.js`, `package.json`, `tests/`
+- **Rationale:** Eliminate manual `cp -r` copying; enable anyone to pull and scaffold the azcodr architecture template via `npx azcodr`.
+- **Description:** Implemented zero-dependency Node.js CLI executable with Outside-In TDD, harness parity symlink generation, script execution bit setting, and full test suite passing with 100% agentic config validation.
+- **Domain Filter Verification:** Verified 100% generic; no project-specific business models.
+
+### [2026-09-25] Streamlined Upstream Sync Protocol to changes.md Ledger
+- **Category:** Rule & Process
+- **Target File(s):** `docs/rules/upstream_synchronization.md`, `changes.md`, `AGENTS.md`
+- **Rationale:** Remove fragile git repo resolution and merge scripts; replace with atomic change logging in `changes.md`.
+- **Description:** Retired `merge-ai` skill and removed machine-specific hardcoded paths. All upstream improvements are now recorded atomically in `changes.md`.
+- **Domain Filter Verification:** Verified 100% generic.
+
+### [2026-09-25] Harden CLI, achieve 100% test coverage gates, add multi-OS CI workflow, and TypeScript declarations
+- **Category:** CLI
+- **Target File(s):** bin/azcodr.js, lib/scaffold.js, lib/index.d.ts, .github/workflows/ci.yml
+- **Rationale:** Fulfill 100.00% test coverage mandate, cross-platform CI matrix, and library type safety
+- **Description:** Remediate gap assessment findings: add --dry-run and --silent flags, enforce 100.00% line/branch/function coverage gates, add GitHub Actions CI matrix across Node 18/20/22/24 and Linux/macOS/Windows, add .editorconfig template item, and export ambient TypeScript typings.
+- **Domain Filter Verification:** Verified 100% generic; purged of all project-specific business entities and models.
+
+### [2026-09-25] Resolve macOS/Windows Git Case-Collision and Cross-Version CI Matrix Coverage
+- **Category:** Infrastructure & CI
+- **Target File(s):** .gitignore, lib/scaffold.js, scripts/test_coverage.js, validate_agentic_configs.sh
+- **Rationale:** Ensure flawless cross-platform and multi-version Node execution across macOS, Windows, and Linux on Node 18, 20, 22, 24.
+- **Description:** Untracked agents.md from Git to prevent cyclic symlink overwrite on case-insensitive filesystems; hardened ensureSymlink with isSameCaseInsensitiveFile check; added cross-version test coverage runner script; updated npm test runner to use native discovery.
+- **Domain Filter Verification:** Verified 100% generic; purged of all project-specific business entities and models.

package/docs/rules/upstream_synchronization.md

@@ -1,40 +1,37 @@
-# Upstream Baseline Synchronization & AI Knowledge Merging
+# Upstream Baseline Synchronization & changes.md Ledger
 
-> **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.
+> **Core Mandate:** Upstream template/baseline workspaces (`azcodr`) must remain strictly untouched during project development. When generic architectural improvements, rule refinements, or post-mortems are identified, record them solely into the `changes.md` ledger with zero automated repo merging or baseline contamination.
 
 ---
 
 ## 1. The Baseline-Project Decoupling Principle
 
-Workspaces operate under a strict unidirectional and on-demand bidirectional flow:
+Workspaces operate under a clean, decoupled flow:
 
 ```
 [Upstream Generic Baseline: azcodr]
                │
-               ▼  (One-time fork / clone at project inception)
+               ▼  (Scaffolded via npx azcodr)
 [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]
+               ▼  (Record reusable improvements)
+[Upstream Changes Ledger: changes.md]
 ```
 
-- **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.
+- **Pristine Upstream Mandate:** Never edit, commit, or attempt automated git merges to an upstream baseline repository during routine project development, feature implementation, or bug fixes.
+- **Ledger-Only Synchronization:** When generic architectural discoveries or defect post-mortems occur, document them cleanly in `changes.md` at the workspace root. No automated merge AI or remote repo synchronization is executed.
 
 ---
 
 ## 2. Zero-Contamination Invariant (Generic vs. Specific)
 
-When merging knowledge, rules, or skills back to the baseline, enforce strict domain filtering:
+When logging proposed changes into `changes.md`, enforce strict domain filtering:
 
-| Element Category | Keep in Specific Project Workspace | Allow in Generic Baseline (`azcodr`) |
+| Element Category | Keep in Specific Project Workspace | Allow in changes.md for Upstream (`azcodr`) |
 |---|---|---|
-| **Domain Entities** | Concrete business models (`Order`, `Customer`, `Invoice`, `Account`, etc.) | Abstract archetypes (`Entity`, `Aggregate`, `ValueObject`, `Resource`) |
+| **Domain Entities** | Concrete business models (`Order`, `Customer`, `Invoice`, 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`) |
@@ -42,25 +39,30 @@ When merging knowledge, rules, or skills back to the baseline, enforce strict do
 
 ---
 
-## 3. Direct Rule Colocation Protocol
+## 3. Atomic changes.md Entry Protocol
+
+Every upstream-bound proposal logged to `changes.md` must follow the standardized format:
 
-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.
+```markdown
+### [YYYY-MM-DD] <Title of Change>
+- **Category:** Rule | Skill | Infrastructure | CLI | Knowledge Hub
+- **Target File(s):** `docs/rules/...`, `.agents/skills/...`, etc.
+- **Rationale:** Why this improvement is necessary or valuable across all enterprise projects.
+- **Description:** Concise summary of the mutation or invariant added.
+- **Domain Filter Verification:** Verified 100% generic; purged of all project-specific business entities and models.
+```
 
 ---
 
 ## 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:** Record candidate generic architectural improvements in `changes.md`.
+- **DO:** Distill all lessons and post-mortems into generic, domain-agnostic language before logging.
 - **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.
+- **DO:** Verify that all entries in `changes.md` are 100% stack- and domain-agnostic.
 
 ### 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.
+- **DONT:** Never execute automated upstream git cloning or merge AI workflows during project work.
+- **DONT:** Never contaminate `changes.md` with project-specific business logic, schemas, or customer requirements.
+- **DONT:** Never leave machine-specific or absolute user paths in scripts or documentation.