azcodr 2.4.0 → 2.6.0

package/.agents/scripts/boundary_guard.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+/**
+ * Cross-platform architectural boundary & cycle guard.
+ *
+ * Ships inside scaffolded projects so structural drift (circular imports and
+ * Clean/Hexagonal layer breaches) is machine-checked with zero third-party
+ * dependencies. The engine is vendored under `.agents/lib/` and byte-locked to
+ * `lib/boundaries.js`; this wrapper only resolves it and reports the verdict.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const selfDir = path.dirname(fileURLToPath(import.meta.url));
+
+// Resolution order (first existing file wins):
+//   1. AZCODR_BOUNDARY_ENGINE override (tests, embedders).
+//   2. ../lib/boundaries.js — vendored engine inside `.agents/`
+//      (present in scaffolded projects; `.agents` is copied recursively).
+//   3. ../../lib/boundaries.js — azcodr repo dev layout (fallback only).
+const engineCandidates = [
+  process.env.AZCODR_BOUNDARY_ENGINE,
+  path.resolve(selfDir, '../lib/boundaries.js'),
+  path.resolve(selfDir, '../../lib/boundaries.js')
+].filter(Boolean);
+
+async function getEngine() {
+  const tried = [];
+  for (const candidate of engineCandidates) {
+    if (!fs.existsSync(candidate)) {
+      tried.push(candidate);
+      continue;
+    }
+    try {
+      return await import(pathToFileURL(candidate).href);
+    } catch (err) {
+      tried.push(`${candidate} (unreadable: ${err.message})`);
+    }
+  }
+  // Fail CLOSED: a guard with no engine is a broken install, never a silent pass.
+  console.error(
+    '🚨 Boundary Guard misconfigured: engine module not found, refusing to fail open. Tried:\n' +
+    tried.map((t) => `  - ${t}`).join('\n')
+  );
+  process.exit(2);
+}
+
+function resolveTarget(positional) {
+  const explicit = positional[0];
+  if (explicit) return path.resolve(explicit);
+  const srcDir = path.resolve(process.cwd(), 'src');
+  return fs.existsSync(srcDir) ? srcDir : process.cwd();
+}
+
+function rel(p) {
+  return path.relative(process.cwd(), p) || '.';
+}
+
+function printReport(report) {
+  console.log('🔍 Inspecting Architectural Boundaries in: ' + rel(report.targetDir));
+  console.log('--------------------------------------------------------------');
+  if (report.ok) {
+    console.log(`✅ No cycles or boundary violations across ${report.moduleCount} module(s).`);
+    return;
+  }
+  for (const cycle of report.cycles) {
+    console.error('   - Circular Dependency: ' + cycle.map(rel).join(' -> '));
+  }
+  for (const v of report.violations) {
+    console.error(`   - Layer Boundary Breach: ${rel(v.file)} imports ${rel(v.importedFile)} (${v.fromLayer} -> ${v.toLayer})`);
+  }
+}
+
+function emit(report, silent) {
+  if (!silent) printReport(report);
+}
+
+async function main() {
+  const args = process.argv.slice(2).filter((a) => a !== '--silent');
+  const silent = process.argv.includes('--silent');
+  const { inspectBoundaries } = await getEngine();
+  const target = resolveTarget(args);
+  const report = inspectBoundaries(target);
+  emit({ ...report, targetDir: target }, silent);
+  process.exit(report.ok ? 0 : 1);
+}
+
+main().catch((err) => {
+  console.error(`🚨 Boundary Guard crashed: ${err?.message || err}`);
+  process.exit(2);
+});

package/.agents/skills/clean-code-refactor/SKILL.md

@@ -51,6 +51,7 @@ Target concrete flaws:
 ### Step 5: Verify Continuous Green State
 - Run tests after every single atomic change. Use the workspace's own command — do not assume one exists. Verify with the package manifest first (`node -p "JSON.stringify(require('./package.json').scripts)"`); for this template that is `npm test`, with `npm run test:coverage` for the coverage gate.
 - Ensure coverage remains at **100.00%**.
+- Verify architectural boundaries: Run `npx azcodr boundaries` to guarantee the refactoring introduced 0 circular dependencies and 0 layer boundary breaches.
 
 ---
 

package/.agents/skills/lets-build/SKILL.md

@@ -100,7 +100,7 @@ Upon user confirmation:
    - *Extension:* `manifest.json`, `src/background/index.ts`, `src/content/index.ts`, `src/popup/index.html`.
    - *Game / Engine:* `src/core/`, `src/ecs/`, asset manifest, frame loop entrypoint.
    - *CLI:* `src/cmd/`, `src/core/`, CLI entrypoint with exit code handling.
-3. Generate build manifests (`Cargo.toml`, `package.json`, `go.mod`, `pyproject.toml`), deterministic linter configurations strictly enforcing the [Polyglot Fitness Function Standards](../../../docs/rules/clean_code.md#polyglot-fitness-function-standards), and boundary smoke test (`scripts/smoke_test.sh`).
+3. Generate build manifests (`Cargo.toml`, `package.json`, `go.mod`, `pyproject.toml`) for the recorded language, install the pinned linter from the emitted gate configuration (`eslint.config.js`, `ruff.toml`, `clippy.toml`, `.golangci.yml`, `checkstyle.xml`, `.editorconfig` CA block, `.clang-tidy` — written deterministically by `bootstrap_workspace.sh`, never invented). Node profiles arrive with `package.json` lint already rewired to `eslint .`; other profiles need the lint entry wired by hand. Prove the gate in Phase 5, and keep the boundary smoke test (`scripts/smoke_test.sh`).
 4. **Replace Starter README with Project-Specific README**:
    Generate a clean, project-specific `README.md` using [references/project_readme_template.md](./references/project_readme_template.md), completely replacing meta-template content with the project's actual name, mission, stack highlights, quickstart commands, and directory tree.
 
@@ -114,6 +114,7 @@ Upon user confirmation:
 2. Execute toolchain dependency checks, build commands, and health/smoke tests:
    - Compile code and verify zero compiler or lint errors.
    - Verify boundary verification smoke test (`scripts/smoke_test.sh`).
+   - **Prove enforcement is live:** enable the shipped hooks in `.agents/hooks.json` (`safety-guard`, `architectural-guard`), then deliberately attempt a blocked action (e.g. append lines to a file already over budget, or a denied command) and confirm the hook rejects it before re-disabling nothing — hooks stay enabled. A guard that has never blocked anything is a rumor, not a control.
 3. **Mandatory Handover to Domain Analysis (STOP & PIVOT):**
    - **`lets-build` IS NOW COMPLETE.** Do NOT proceed to write domain business entities, repositories, or application features.
    - Present the bootstrapped technical skeleton to the user.
@@ -160,7 +161,7 @@ Upon user confirmation:
 
 ## 4. Quality & Verification
 - **Testing Strategy:** Outside-In TDD with Nano-Cycles (Uncle Bob's 3 Laws)
-- **Code Health Gates:** 100.00% test coverage gate, zero lint errors
+- **Code Health Gates:** 100% coverage on all metrics + mutation kill gate on guards, zero lint errors
 - **DevSecOps:** <Semgrep / Trivy / Gitleaks / None>
 ```
 

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

@@ -324,6 +324,165 @@ EOF
     ;;
 esac
 
+# ------------------------------------------------------------------------------
+# DETERMINISTIC TOOLCHAIN FILES. Directories alone enforce nothing: until this
+# section existed, every language produced zero gate configurations and the
+# starter `lint` script was an echo placeholder, so all enforcement was
+# agent-authored. Each profile below emits its pinned gate configuration with
+# values mirroring docs/rules/clean_code.md (300/30/10/3); the agent installs
+# the named tool and proves the gate in Phase 5. Files are created only when
+# absent, so re-runs never clobber agent-authored configs. Build manifests
+# (Cargo.toml, go.mod, csproj, ...) stay with the agent: they carry project
+# naming and version decisions no script may invent.
+# ------------------------------------------------------------------------------
+write_unless_exists() {
+  local target="$1"
+  if [[ -f "${target}" ]]; then
+    echo "   keeping existing ${target}"
+    return
+  fi
+  mkdir -p "$(dirname "${target}")"
+  cat > "${target}"
+}
+
+append_unless_present() {
+  local target="$1"
+  local marker="$2"
+  if [[ -f "${target}" ]] && grep -qF "${marker}" "${target}"; then
+    echo "   keeping existing ${target} gates"
+    return
+  fi
+  cat >> "${target}"
+}
+
+echo "6. Emitting deterministic toolchain configs for '${LANGUAGE}'..."
+case "${LANGUAGE}" in
+  typescript|javascript|deno|bun)
+    write_unless_exists "${WORKSPACE_ROOT}/eslint.config.js" << 'EOF'
+// Deterministic fitness functions (azcodr clean_code.md section 5).
+// Install the pinned tool, then prove the gate: npm run lint
+export default [
+  {
+    files: ['src/**/*.{js,ts}', 'tests/**/*.{js,ts}'],
+    rules: {
+      'max-lines': ['error', 300],
+      'max-lines-per-function': ['error', 30],
+      complexity: ['error', 10],
+      'max-params': ['error', 3]
+    }
+  }
+];
+EOF
+    ;;
+  python)
+    write_unless_exists "${WORKSPACE_ROOT}/ruff.toml" << 'EOF'
+# Deterministic fitness functions (azcodr clean_code.md section 5).
+# Install the pinned tool, then prove the gate: ruff check .
+[lint]
+select = ["E", "F", "C901", "PLR0912", "PLR0913", "PLR0915"]
+[lint.mccabe]
+max-complexity = 10
+[lint.pylint]
+max-args = 3
+max-statements = 30
+# NOTE: ruff has no file-length rule; the 300-line file cap is enforced by
+# the project's lint entry (see lets-build Phase 5 proof).
+EOF
+    ;;
+  rust)
+    write_unless_exists "${WORKSPACE_ROOT}/clippy.toml" << 'EOF'
+# Deterministic fitness functions (azcodr clean_code.md section 5).
+# Enforce with: cargo clippy -- -D clippy::too_many_lines -D clippy::cognitive_complexity -D clippy::too_many_arguments
+too-many-lines-threshold = 30
+cognitive-complexity-threshold = 10
+too-many-arguments-threshold = 3
+# NOTE: clippy has no file-length lint; the 300-line file cap is enforced by
+# the project's lint entry (see lets-build Phase 5 proof).
+EOF
+    ;;
+  go)
+    write_unless_exists "${WORKSPACE_ROOT}/.golangci.yml" << 'EOF'
+# Deterministic fitness functions (azcodr clean_code.md section 5).
+# Install the pinned tool, then prove the gate: golangci-lint run ./...
+linters:
+  enable: [funlen, gocyclo]
+linters-settings:
+  funlen:
+    lines: 30
+    statements: 25
+  gocyclo:
+    min-complexity: 10
+# NOTE: no golangci-native file-length check; the 300-line file cap is
+# enforced by the project's lint entry (see lets-build Phase 5 proof).
+EOF
+    ;;
+  java)
+    write_unless_exists "${WORKSPACE_ROOT}/checkstyle.xml" << 'EOF'
+<?xml version="1.0"?>
+<!-- Deterministic fitness functions (azcodr clean_code.md section 5). -->
+<!DOCTYPE module PUBLIC "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN" "https://checkstyle.org/dtds/configuration_1_3.dtd">
+<module name="Checker">
+  <module name="FileLength">
+    <property name="max" value="300"/>
+  </module>
+  <module name="TreeWalker">
+    <module name="MethodLength">
+      <property name="max" value="30"/>
+    </module>
+    <module name="CyclomaticComplexity">
+      <property name="max" value="10"/>
+    </module>
+    <module name="ParameterNumber">
+      <property name="max" value="3"/>
+    </module>
+  </module>
+</module>
+EOF
+    ;;
+  csharp)
+    append_unless_present "${WORKSPACE_ROOT}/.editorconfig" "azcodr fitness functions" << 'EOF'
+
+# --- azcodr fitness functions (CA gates; exact numbers in lint entry) ---
+[*.cs]
+dotnet_diagnostic.CA1501.severity = error
+dotnet_diagnostic.CA1502.severity = error
+EOF
+    ;;
+  cpp|c)
+    write_unless_exists "${WORKSPACE_ROOT}/.clang-tidy" << 'EOF'
+# Deterministic fitness functions (azcodr clean_code.md section 5).
+Checks: 'readability-function-size,readability-function-cognitive-complexity'
+CheckOptions:
+  - { key: readability-function-size.LineThreshold, value: 30 }
+  - { key: readability-function-size.ParameterThreshold, value: 3 }
+  - { key: readability-function-cognitive-complexity.Threshold, value: 10 }
+# NOTE: clang-tidy has no file-length check; the 300-line file cap is
+# enforced by the project's lint entry (see lets-build Phase 5 proof).
+EOF
+    ;;
+  generic)
+    echo "   language undecided: no toolchain configs emitted (re-run with a language profile)"
+    ;;
+esac
+
+# For Node profiles the starter package.json ships a lint placeholder that
+# always succeeds. Point it at the emitted config so `npm run lint` fails
+# until the pinned eslint is installed (fail-closed) instead of echoing.
+# Only the placeholder is ever replaced; agent-wired entries are sacred.
+case "${LANGUAGE}" in
+  typescript|javascript|deno|bun)
+    STARTER_PKG="${WORKSPACE_ROOT}/package.json"
+    if [[ -f "${STARTER_PKG}" ]] && grep -q 'No linter configured yet' "${STARTER_PKG}"; then
+      if command -v node >/dev/null 2>&1; then
+        node -e 'const fs=require("fs");const p=process.argv[1];const j=JSON.parse(fs.readFileSync(p,"utf8"));j.scripts=j.scripts||{};j.scripts.lint="eslint .";fs.writeFileSync(p,JSON.stringify(j,null,2)+"\n");' "${STARTER_PKG}"
+        echo "   wired package.json lint -> eslint ."
+      else
+        echo "   node not found: leaving starter lint placeholder (agent wires it in Phase 4)"
+      fi
+    fi
+    ;;
+esac
+
 # ------------------------------------------------------------------------------
 # memory.md is an APPEND-ONLY LEDGER. It is never rewritten automatically.
 #
@@ -408,7 +567,14 @@ if [[ ! -f "${SMOKE_TEST}" ]]; then
 # ==============================================================================
 set -euo pipefail
 
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
 echo "Running boundary smoke verification..."
+if [[ -f "${ROOT}/.agents/scripts/boundary_guard.js" ]] && command -v node >/dev/null 2>&1; then
+  node "${ROOT}/.agents/scripts/boundary_guard.js" "${ROOT}/src"
+else
+  echo "⚠️  Boundary guard skipped (node or guard script unavailable)."
+fi
 # Extend with project-specific runtime health checks (e.g. ping health endpoint, CLI --help)
 echo "✅ Boundary smoke verification passed!"
 EOF

package/.agents/skills/relentless-questioner/SKILL.md

@@ -119,7 +119,7 @@ Synthesize the answers into an unambiguous **Feature Alignment Specification (FA
     When [Action]
     Then [Observable Outcome]
   ```
-- **Test Strategy:** [Contract / Integration / Unit tests required for 100% coverage]
+- **Test Strategy:** [Contract / Integration / Unit tests required; 100% on all metrics, assertion-free tests rejected]
 ```
 
 ---

package/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-> **azcodr: Enterprise Architecture & Agentic Engineering Starter Template**  
+> **azcodr: Architecture governance toolkit, with an optional starter**  
 > **Workspace Mission:** Problem-first, topology-aligned production architectures governed by strict systemic atomicity, 100% open-source standards, true incremental TDD nano-cycles, and zero speculative bloat.  
 > **Runtime & Tools:** Node.js (`>=22.8.0`), npm (`>=10.0.0`) | `npm test` (test runner), `npm run test:coverage` (coverage gate), `npm run lint`, `npm run validate`.
 > **Node floor rationale:** `>=22.8.0` satisfies Jest native ESM requirements (`--experimental-vm-modules`) and modern LTS security baselines. Node 18 (EOL 2025-04-30) and 20 (EOL 2026-04-30) no longer receive security patches.  
@@ -48,7 +48,7 @@ Progress all tasks systematically through the unified **Agent Cognitive & Agile
 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      ──► 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.
+5. VERIFY / DoD & PROOF     ──► Outer test turns GREEN; boundary smoke tests & 100% coverage on all metrics + mutation gate.
 ```
 ---
 
@@ -58,7 +58,7 @@ To prevent context bloat and keep prompt overhead minimal, detailed engineering
 
 | Domain | Rule Reference File | When to Consult |
 |---|---|---|
-| **TDD & Isolation** | [docs/rules/test_driven_development.md](./docs/rules/test_driven_development.md) | Outside-In TDD, Uncle Bob's 3 Laws, 100% coverage, test isolation & DB rollback. |
+| **TDD & Isolation** | [docs/rules/test_driven_development.md](./docs/rules/test_driven_development.md) | Outside-In TDD, Uncle Bob's 3 Laws, 100% coverage on all metrics + mutation gate, test isolation & DB rollback. |
 | **Clean Code** | [docs/rules/clean_code.md](./docs/rules/clean_code.md) | Naming, small functions, CQS, SLAP, DRY, DbC, zero side-effects. |
 | **Design Patterns** | [docs/rules/design_patterns.md](./docs/rules/design_patterns.md) | Adapter, Factory, Strategy, Result `<T, E>`, and GoF pattern catalog. |
 | **Type Safety** | [docs/rules/type_safety.md](./docs/rules/type_safety.md) | Compiler strictness, branded nominal types, type discriminators across polyglot languages. |

package/CONTRIBUTING.md

@@ -49,15 +49,21 @@ Before submitting any code changes, all 5 quality gates must pass with zero erro
    npm test
    npm run test:coverage
    ```
-   *Coverage gates enforced:*
+   *Coverage gates enforced (CI fails below 100% on any metric):*
    - **100% lines coverage**
-   - **97% functions coverage**
-   - **98% branches coverage**
+   - **100% functions coverage**
+   - **100% branches coverage**
+   - **100% statements coverage**
+   - Plus **100% mutant-kill on guards** (`npm run test:mutation`) and rejection of assertion-free tests.
 5. **Agentic Architecture Validation:**
    ```bash
    npm run validate
    ```
-   Validates root harness parity, progressive disclosure rules, skill formats, markdown links, and ADR ledger consistency.
+   Validates root harness parity, progressive disclosure rules, skill formats, markdown links, ADR ledger consistency, and toolchain gate presence.
+6. **Vendored Engine Sync:** after any change under `src/agent-guard*.ts` or `src/boundaries.ts` and `npm run build`, re-copy the compiled engine files into `.agents/lib/` (byte-equality is enforced by `tests/agent-guard.test.ts` and `tests/boundary-guard.test.ts`):
+   ```bash
+   node -e "const fs=require('fs');for(const f of['agent-guard.js','agent-guard-command.js','agent-guard-file.js','agent-guard-tdd.js','boundaries.js'])fs.copyFileSync('lib/'+f,'.agents/lib/'+f)"
+   ```
 
 ---
 

package/README.md

@@ -1,13 +1,15 @@
-# azcodr: Enterprise Architecture & Agentic Engineering Starter Template
+# azcodr: Architecture governance toolkit, with an optional starter
 
 [![npm version](https://img.shields.io/npm/v/azcodr.svg?color=cb3837)](https://www.npmjs.com/package/azcodr)
 [![JSR Package](https://jsr.io/badges/@azcodr/azcodr)](https://jsr.io/@azcodr/azcodr)
 [![CI Status](https://github.com/prosubodh/azcodr/actions/workflows/ci.yml/badge.svg)](https://github.com/prosubodh/azcodr/actions/workflows/ci.yml)
-[![Coverage](https://img.shields.io/badge/coverage-100.00%25-brightgreen.svg)](https://github.com/prosubodh/azcodr)
-[![Mutation Score](https://img.shields.io/badge/mutants%20killed-100%25-brightgreen.svg)](https://github.com/prosubodh/azcodr)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/prosubodh/azcodr/actions/workflows/ci.yml)
+[![Mutation Score](https://img.shields.io/badge/mutants%20killed-100%25-brightgreen.svg)](https://github.com/prosubodh/azcodr/blob/main/benchmark/RESULTS.md)
 [![Dependencies](https://img.shields.io/badge/dependencies-0-success.svg)](https://www.npmjs.com/package/azcodr)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
+> CI-enforced 100% gate (lines / branches / functions / statements) + 100% mutant kill on guards; the public report is the `coverage-report` artifact on every CI run.
+
 > **Production-oriented architecture governance and topology-scoped scaffolding for AI-assisted development (early release).**  
 > *AI agents move fast. Architecture drifts. Azcodr turns architectural intent into executable constraints your agent cannot skip.*
 
@@ -34,7 +36,7 @@
 
 ## ⚡ 60-Second Demo: See Drift Prevention in Action
 
-Azcodr turns architectural philosophy into machine-checked constraints your agent cannot skip.
+Azcodr turns architectural philosophy into machine-checked constraints. In a fresh scaffold the runtime hooks ship **enabled by default**, and the boundary engine runs in CI, so drift is caught both while the agent edits and after it commits.
 
 ### 1. Standalone Architectural Check
 Run the validator on any repository without scaffolding:
@@ -63,7 +65,7 @@ When an AI coding agent attempts to dump new logic into a file already exceeding
 ```
 
 ### 3. Zero-Dependency Boundary & Cycle Enforcement
-Inspect dependency cycles and layer boundaries on demand without third-party linters:
+Inspect dependency cycles and layer boundaries on demand without third-party linters. The same engine is vendored into every scaffolded project (`.agents/scripts/boundary_guard.js`) and runs in the generated CI:
 ```bash
 npx azcodr boundaries [directory]
 ```
@@ -76,17 +78,17 @@ npx azcodr boundaries [directory]
    Action Required: Invert dependencies via Ports or extract shared modules.
 ```
 
-### 4. Empirical Benchmark Proof (3 Arms, 10 Sequential Tickets)
-In an automated empirical trial across 10 sequential tickets with 3 architectural traps ([`benchmark/RESULTS.md`](https://github.com/prosubodh/azcodr/blob/main/benchmark/RESULTS.md)):
+### 4. Detector Validation on Synthetic Fixtures (Not a Live-Agent Trial)
+The evaluator's ability to detect the 3 trap classes is exercised against **hand-written fixtures**, not live agent output ([`benchmark/RESULTS.md`](https://github.com/prosubodh/azcodr/blob/main/benchmark/RESULTS.md)):
 
 | Metric | Arm A (Control) | Arm B (Hooks Only) | Arm C (Full Azcodr) |
 |---|:---:|:---:|:---:|
 | **Files >300 Lines** | 1 (365 lines in `auth.ts`) | **0** (Modularized) | **0** (Modularized) |
 | **Circular Dependency Cycles** | 1 (`billing <-> tenant`) | 1 (`billing <-> tenant`) | **0** (Decoupled Port) |
 | **Layer Boundary Breaches** | 1 (`domain -> infra`) | 1 (`domain -> infra`) | **0** (Hexagonal Port) |
-| **Overall Drift Reduction** | ❌ FAILED | ❌ FAILED | ✅ **100% DRIFT-FREE** |
+| **Detected drift-free** | ❌ FAILED | ❌ FAILED | ✅ **0 detector violations** |
 
-Run the empirical benchmark yourself:
+These fixtures are committed by hand to prove the detector fires; they are **not evidence** that an AI agent drifts. Real-agent results (tokens, completion, review minutes) are planned and not yet measured. Run the detector yourself:
 ```bash
 node benchmark/run-benchmark.js
 ```
@@ -127,7 +129,7 @@ The architecture enforces 28 cohesive, single-responsibility domain rules. Read
 
 | Domain | Rule Reference File | Key Focus & Invariants |
 |---|---|---|
-| **TDD & Isolation** | [`test_driven_development.md`](./docs/rules/test_driven_development.md) | Outside-In TDD, Uncle Bob's 3 Laws, 100% coverage, test isolation & DB rollback. |
+| **TDD & Isolation** | [`test_driven_development.md`](./docs/rules/test_driven_development.md) | Outside-In TDD, Uncle Bob's 3 Laws, 100% coverage on all metrics + mutation gate, test isolation & DB rollback. |
 | **Clean Code** | [`clean_code.md`](./docs/rules/clean_code.md) | Naming, small functions, CQS, SLAP, DRY, DbC, zero side-effects. |
 | **Design Patterns** | [`design_patterns.md`](./docs/rules/design_patterns.md) | Adapter, Factory, Strategy, Result `<T, E>`, and GoF pattern catalog. |
 | **Type Safety** | [`type_safety.md`](./docs/rules/type_safety.md) | Compiler strictness, branded nominal types, type discriminators across polyglot languages. |
@@ -171,10 +173,10 @@ The architecture enforces 28 cohesive, single-responsibility domain rules. Read
 
 ## 🚀 Starting a New Project with `/lets-build`
 
-This repository serves as an **enterprise architectural starter template**. When beginning a new software project:
+This repository serves as an **architecture governance toolkit, with an optional starter**. When beginning a new software project:
 
 ### Step 1: Initialize Workspace with npx
-Pull and scaffold the complete enterprise architectural template into your project directory using `npx`:
+Pull and scaffold the complete architecture governance toolkit into your project directory using `npx`:
 ```bash
 npx azcodr my-new-project
 cd my-new-project

package/docs/generated-enforcement-analysis.md

@@ -0,0 +1,162 @@
+# Generated-Project Enforcement Analysis: What a Scaffolded Project Actually Gets
+
+> **Status:** evidence, not prose. Every claim below was produced by running the
+> scaffolder on 2026-10-08, not by reading the skills docs.
+> **Answers the plan's open question:** which linters does a non-TypeScript
+> project actually get — and whether the "executable architecture" promise holds
+> outside azcodr's own repo.
+
+---
+
+## Method
+
+1. Ran `scaffold({ force: true, noGit: true })` from compiled `lib/` into a clean
+   temp dir; inventoried every emitted file.
+2. Ran `bootstrap_workspace.sh . <topology> <language>` under Git Bash for
+   `backend+typescript`, `backend+python`, `cli+go`, `extension+typescript`,
+   `systems-library+c`; diffed the file lists.
+3. Executed the scaffolded project's `.agents/scripts/agent_guard.js` with a
+   must-block payload (`rm -rf /`), with the azcodr repo itself as control.
+
+## Finding 1: No deterministic linter in any generated project
+
+The scaffolded project contains exactly one toolchain-adjacent file:
+`.editorconfig`. Its `package.json` lint script is:
+
+```json
+"lint": "echo \"No linter configured yet. Run /lets-build to configure toolchain.\""
+```
+
+The polyglot fitness-function table (`docs/rules/clean_code.md`, § Polyglot
+Fitness Function Standards: ESLint / ruff / clippy / golangci-lint /
+Checkstyle / Roslyn) ships as **documentation only**. Phase 4 step 3 of
+`lets-build/SKILL.md` instructs the *agent* to "generate … deterministic
+linter configurations" — i.e. enforcement in a user's project is agent-authored
+and non-deterministic, exactly the gap the plan flagged. **A non-TypeScript
+project gets no linter at all unless the agent writes one.**
+
+## Finding 2: LANGUAGE does not change generated output
+
+`backend+typescript` and `backend+python` produce byte-identical file lists
+(18 files each: `.gitkeep` dirs, `tokens.json`, `smoke_test.sh`,
+`workspace-profile.env`). `LANGUAGE` is validated and recorded but never
+branches generation. Topology *does* scope directories (7–18 files by
+topology). So: topology-scoping is deterministic; language support is a
+recorded intention, not a generated artifact.
+
+## Finding 3: The shipped runtime guard is inert in generated projects (fail-open)
+
+`TEMPLATE_ITEMS` (`src/scaffold.ts`) ships `docs`, `.agents`, `scripts`,
+`.github` — but **not** `src/`, `lib/`, or `bin/`. Consequences, all verified:
+
+| Check | azcodr repo (control) | Scaffolded project |
+|---|---|---|
+| `.agents/scripts/agent_guard.js` vs `rm -rf /` payload | **BLOCKED** (exit 1) | **ALLOWED** (exit 0) |
+| `lib/agent-guard.js` present | yes | **missing** — the guard's dynamic import rejects, and `main().catch(() => process.exit(0))` fails open |
+| `.agents/hooks.json` references `agent_guard.js` | no | no |
+| All hook blocks in `hooks.json` | `enabled: false` | `enabled: false` (shipped copy) |
+
+The flagship "agent cannot skip" control therefore degrades, in a generated
+project, to: an unwired hook script, with its engine missing, configured off,
+that permits on error. The `boundaries` engine (`npx azcodr boundaries`)
+likewise does not ship — only `scripts/validate-cli.js` (config/ledger/link
+checks) is present.
+
+## What *does* transfer deterministically
+
+- 28 rule docs, 6 skills, `AGENTS.md` parity pointers, empty ADR ledger
+  (`data/memory.template`), `safety_guard.sh` + `verify_completion.sh` (present
+  but disabled in `hooks.json`), `smoke_test.sh` placeholder, topology-scoped
+  directories, `tokens.json` (backend/web only), `.azcodr/workspace-profile.env`.
+
+## Recommendations (product decisions, not taken here)
+
+1. **Either ship the engine or stop implying it ships.** Options: (a) add a
+   dependency on the published `azcodr` package + `lib/`- backed guard entry in
+   the starter `package.json`; (b) vendor a self-contained guard bundle into
+   `.agents/scripts/` with no `../../lib` import; (c) reword SKILL.md Phase 4
+   step 3 from "generate deterministic linter configurations" to an explicit
+   agent-authored checklist with verification (`npm run lint` must fail before
+   configs land, not echo).
+2. **Fail closed, and wire the hook.** `agent_guard.js`'s catch-all `exit(0)`
+   is the wrong default for a security boundary; and `hooks.json` should ship
+   with at least the safety guard enabled plus a setup step that proves the
+   harness honors it (harnesses ignore unknown/unenabled hooks silently).
+3. **Make LANGUAGE generative or say it isn't.** Either branch
+   `bootstrap_workspace.sh` per language (build manifests + pinned linter
+   configs per `clean_code.md` table) or change the skill wording to record the
+   language decision for the agent to implement in Phase 4.
+4. **Close the benchmark gap this reveals.** `benchmark/RESULTS.md` Arm B/C
+   assume working hooks + boundary engine; in a real scaffolded project neither
+   is present. A fourth arm — *raw scaffolded project, no agent-authored
+   additions* — would measure the actual out-of-box enforcement: expect 0/3
+   traps caught.
+
+---
+
+## Addendum (2026-10-08): findings fixed — verify, don't trust
+
+The three findings above are closed by the enforcement change set; each fix
+names the test that locks it:
+
+1. **No deterministic linter → per-language gate configs emitted.**
+   `bootstrap_workspace.sh` now writes the pinned config for the recorded
+   language (`eslint.config.js`, `ruff.toml`, `clippy.toml`, `.golangci.yml`,
+   `checkstyle.xml`, `.editorconfig` CA block, `.clang-tidy`; `generic` emits
+   none). Locked by `tests/bootstrap-toolchain.test.ts` (9 tests); presence is
+   re-checked on every `validate` run by the new phase 7
+   (`scripts/validate/toolchain.js`, 100% covered).
+2. **LANGUAGE decorative → generative for toolchain.**
+   `backend+typescript` and `backend+python` still share directory trees
+   (topology-scoping, by design) but now differ in emitted gate configs; the
+   profile feed (`readProfileLanguage`) drives the validator. The agent still
+   owns build manifests (naming decisions) plus tool install and the Phase 5
+   live-block proof (`lets-build/SKILL.md`).
+3. **Fail-open guard → vendored engine + fail-closed install.**
+   The guard engine ships inside `.agents/` (`.agents/lib/`, byte-locked to
+   `lib/` output by test), `agent_guard.js` resolves vendored-first, and a
+   missing engine exits 2 naming every path tried. Unparseable *payloads*
+   still fail open inside `inspectPreTool` per ADR-005 (ambiguous input, not a
+   broken install). `hooks.json` (+`.example`) wires an `architectural-guard`
+   PreToolUse entry. Locked by the three new `tests/agent-guard.test.ts` cases.
+4. **Benchmark assumes working hooks → Arm D measures the scaffold.**
+   `runArmD()` + `auditScaffoldEnforcement()` score a real scaffold before and
+   after bootstrap; `benchmark/RESULTS.md` §5 carries the scorecard.
+5. **Echo lint placeholder → rewired for Node profiles.** `bootstrap` points
+   the starter `lint` script at the emitted `eslint.config.js` (placeholder
+   only, never agent-wired entries; skipped when node is unavailable), so
+   `npm run lint` fails until the pinned tool lands instead of echoing
+   success.
+
+## Addendum (2026-10-09): boundaries shipped, starter CI generated, hooks on
+
+6. **Boundary engine now ships in the scaffold.** `lib/boundaries.js` is
+   vendored into `.agents/lib/boundaries.js` (byte-locked by
+   `tests/boundary-guard.test.ts`, re-copied after every build per
+   `CONTRIBUTING.md`) and a vendored-first runner `.agents/scripts/boundary_guard.js`
+   exits 0/1 on a repo's cycle & layer verdict (exit 2 on a missing engine).
+   The starter `package.json` gains a `boundaries` script pointing at it.
+7. **Generated CI is now green out of the box.** azcodr's own dev workflows
+   (`ci.yml`, `publish.yml`) call scripts a fresh project does not have, so
+   shipping them verbatim made a scaffolded repo's CI fail on every push. The
+   scaffolder now replaces them with a starter `.github/workflows/ci.yml` that
+   only needs Node, the vendored boundary guard, and `scripts/validate-cli.js`.
+   Locked by `tests/scaffold-ci.test.ts`.
+8. **Hooks ship enabled.** `.agents/hooks.json` (+`.example`) now ships all four
+   hooks `enabled: true` (safety, architectural, post-tool-lint, stop-verifier),
+   amending ADR-020 which deliberately shipped them disabled. The trade-off is
+   recorded in the 2026-10-09 ADR: default-on means a harness that loads the
+   file blocks immediately, at the cost that lint/stop hooks can interrupt
+   worthless-but-harmless sessions in a bare scaffold.
+
+## Reproduce
+
+```bash
+# 1. Scaffold inventory
+node -e "const {scaffold}=require('./lib/scaffold.js'); scaffold({targetDir:'<tmp>',force:true,noGit:true})"
+# 2. Topology x language matrix (Git Bash)
+bash .agents/skills/lets-build/scripts/bootstrap_workspace.sh <tmp> backend python
+# 3. Guard fail-open proof
+echo '{"tool_name":"run_command","tool_input":{"command":"rm -rf /"}}' \
+  | node <scaffold>/.agents/scripts/agent_guard.js; echo "exit=$?"
+```

package/docs/rules/clean_code.md

@@ -57,13 +57,13 @@ Before writing production code for any new feature or user story, the agent must
 Prevent AI-generated code rot using automated fitness functions integrated into linting and continuous verification:
 - **File Length Gates**: Maximum 250–300 lines per file (ESLint `max-lines`).
 - **Function Length Gates**: Maximum 20–30 lines per function (ESLint `max-lines-per-function`).
-- **Dependency Direction Gates**: Enforce unidirectional import rules (e.g. `import/no-restricted-paths`, `dependency-cruiser`, `ArchUnit`) ensuring domain core never imports infrastructure or transport adapters.
+- **Dependency Direction & Boundary Gates**: Enforce unidirectional import rules and cycle prevention natively with Azcodr's zero-dependency boundary linter (`npx azcodr boundaries [dir]`) or polyglot equivalents (ArchUnit, dependency-cruiser) ensuring domain core never imports infrastructure or transport adapters, and circular dependencies are forbidden.
 - **Complexity Budgets**: Enforce cyclomatic complexity limits (maximum 10 per function).
 If an AI attempt to add code violates any fitness function, the build fails immediately, blocking completion until the architecture is refactored.
 
 ### Polyglot Fitness Function Standards
 
-When bootstrapping non-TypeScript projects via `/lets-build`, the agent must instantiate deterministic, automated fitness function gates matching these exact rules:
+When bootstrapping projects via `/lets-build`, `bootstrap_workspace.sh` emits the pinned gate configuration for the recorded language (never invented, never absent); the agent then installs the named tool, wires the project's lint entry to it, and proves the gate in Phase 5. Gates must match these exact rules:
 
 | Language | Linter / Static Tool | Max File Lines (300) | Max Function Lines (30) | Max Complexity (10) | Max Arguments (3) |
 |---|---|---|---|---|---|
@@ -73,3 +73,4 @@ When bootstrapping non-TypeScript projects via `/lets-build`, the agent must ins
 | **Go** | `golangci-lint` | `maintidx: 300` | `funlen: lines = 30` | `gocyclo: min-complexity = 10` | `funlen: statements = 25` |
 | **Java** | `Checkstyle` + `ArchUnit` | `FileLength: max 300` | `MethodLength: max 30` | `CyclomaticComplexity: max 10` | `ParameterNumber: max 3` |
 | **C# / .NET** | `.editorconfig` + Roslyn | `file_length = 300:error` | `method_length = 30:error` | `CA1502: Avoid excessive complexity <= 10` | `CA1501: max 3 params` |
+| **C / C++** | `clang-tidy` | project lint entry (no native check) | `readability-function-size LineThreshold = 30` | `readability-function-cognitive-complexity Threshold = 10` | `readability-function-size ParameterThreshold = 3` |