azcodr 2.3.0 → 2.5.1

package/.github/workflows/publish.yml

@@ -43,6 +43,13 @@ jobs:
           node --version
           npm --version
 
+      - name: Verify TypeScript Compilation & lib/ Parity
+        shell: bash
+        run: |
+          npm run build
+          git diff --exit-code lib/
+          npm run typecheck
+
       # Re-run the full gate on the exact release tag. prepublishOnly also runs
       # on `npm publish`, but failing fast here avoids building a tarball at all.
       - name: Run Syntax & Lint Checks

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/CODE_OF_CONDUCT.md

@@ -0,0 +1,122 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[prosubodh+conduct@gmail.com](mailto:prosubodh+conduct@gmail.com).
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).

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 Guard Sync:** after any change under `src/agent-guard*.ts` and `npm run build`, re-copy the four compiled engine files into `.agents/lib/` (byte-equality is enforced by `tests/agent-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'])fs.copyFileSync('lib/'+f,'.agents/lib/'+f)"
+   ```
 
 ---
 
@@ -77,3 +83,9 @@ Every contribution must preserve these core invariants:
 2. Follow Conventional Commits: `feat(...)`, `fix(...)`, `docs(...)`, `test(...)`.
 3. Ensure all tests and validation pass locally (`npm run prepublishOnly`).
 4. Submit your pull request with a concise summary and verification evidence.
+
+---
+
+## 📜 Code of Conduct
+
+All contributors and maintainers are expected to abide by our [Code of Conduct](./CODE_OF_CONDUCT.md). Please report any violations to `prosubodh+conduct@gmail.com`.

package/README.md

@@ -1,4 +1,16 @@
-# 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%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.
+[![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)
 
 > **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.*
@@ -24,6 +36,67 @@
 
 ---
 
+## ⚡ 60-Second Demo: See Drift Prevention in Action
+
+Azcodr turns architectural philosophy into machine-checked constraints your agent cannot skip.
+
+### 1. Standalone Architectural Check
+Run the validator on any repository without scaffolding:
+```bash
+npx azcodr check
+```
+```text
+🔍 Validating Architecture & Agent Invariants in: ./
+--------------------------------------------------------------
+1. Root Config & Symlinks        -> PASS
+2. Progressive Disclosure Rules  -> PASS (28 rules verified)
+3. Specialized Skills (.agents)  -> PASS (6 skills active)
+4. Markdown Cross-References    -> PASS (0 broken links)
+5. Memory & ADR Ledger           -> PASS (16 ADRs verified)
+6. ADR Index Consistency         -> PASS
+🎉 SUCCESS: All architectural invariants are healthy! (0 warnings)
+```
+
+### 2. Real-Time PreToolUse Guard: Refactor-Before-Add
+When an AI coding agent attempts to dump new logic into a file already exceeding 300 lines, Azcodr's agent hook intercepts the tool call at runtime before it touches the disk:
+```text
+🚨 TOOL USE BLOCKED: Refactor-Before-Add Violation
+   File 'src/auth.ts' has 315 lines (limit: 300).
+   Mutations that add code are blocked.
+   Extract strategy classes or helper modules to reduce file size before adding new features.
+```
+
+### 3. Zero-Dependency Boundary & Cycle Enforcement
+Inspect dependency cycles and layer boundaries on demand without third-party linters:
+```bash
+npx azcodr boundaries [directory]
+```
+```text
+🔍 Inspecting Architectural Boundaries in: ./src
+--------------------------------------------------------------
+🚨 ARCHITECTURAL VIOLATIONS DETECTED (2):
+   - Circular Dependency: src/billing.ts -> src/tenant.ts -> src/billing.ts
+   - Layer Boundary Breach: src/domain/payment.ts illegally imports src/infrastructure/db.ts (domain -> infrastructure)
+   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)):
+
+| 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** |
+
+Run the empirical benchmark yourself:
+```bash
+node benchmark/run-benchmark.js
+```
+
+---
+
 ## 🗂️ Workspace Architecture
 
 ```
@@ -58,7 +131,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. |
@@ -102,10 +175,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,141 @@
+# 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.
+
+## 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` |

package/docs/rules/test_driven_development.md

@@ -1,6 +1,6 @@
 # Test-Driven Development (London School TDD) & Test Isolation Standards
 
-> **Core Mandate:** Drive all features through the non-negotiable 5-Phase Agile Domain Lifecycle (Outside-In Double-Loop TDD, Uncle Bob's 3 Laws), enforcing transactional database rollback per test, zero-sleep determinism, and non-negotiable 100.00% statement, branch, and function coverage gates.
+> **Core Mandate:** Drive all features through the non-negotiable 5-Phase Agile Domain Lifecycle (Outside-In Double-Loop TDD, Uncle Bob's 3 Laws), enforcing transactional database rollback per test, zero-sleep determinism, and CI-enforced 100% coverage on all metrics plus mutation floor (assertion-free tests rejected).
 
 ---
 
@@ -14,7 +14,7 @@ flowchart TD
     P2["Phase 2: Tactical Domain Analysis<br/>• Ubiquitous Language & Bounded Contexts<br/>• Aggregate Roots & Business Invariants"]
     P3["Phase 3: Outer Acceptance Test (RED)<br/>• Failing UI component or API route test<br/>• Verifies failure for expected reason"]
     P4["Phase 4: Inner TDD & Collaborator Discovery (RED-GREEN-REFACTOR)<br/>• Discovers Use Cases & Ports<br/>• Nano-cycles with Uncle Bob's 3 Laws"]
-    P5["Phase 5: Outer Verification & Proof (GREEN)<br/>• Outer test passes with zero regressions<br/>• 100.00% coverage & boundary smoke verification"]
+    P5["Phase 5: Outer Verification & Proof (GREEN)<br/>• Outer test passes with zero regressions<br/>• 100% coverage on all metrics + mutation gate & boundary smoke verification"]
 
     P1 --> P2 --> P3 --> P4 --> P5
 ```
@@ -125,10 +125,13 @@ sequenceDiagram
 
 ---
 
-## 7. Mandatory 100.00% Test Coverage Thresholds
+## 7. Mandatory 100% Coverage on All Metrics + Mutation Floor (No Assertion-Free Tests)
 
-- **Strict Coverage Thresholds**: Maintain line, function, branch, and statement test coverage at **100.00%** across all backend domain logic, adapters, contracts, and frontend suites. Strictly enforce 100% threshold failure gates in CI pipelines (`scripts/test_coverage.js`).
-- **Exhaustive Status Codes & Error Branches**: Explicitly test all HTTP/gRPC response codes:
+- **Strict 100% thresholds:** CI fails unless line, function, branch, AND statement coverage are all 100% (`jest.config.js`: lines 100 / functions 100 / branches 100 / statements 100). Generated projects must hold the same 100% bar in their own stack via the per-language gates in `docs/rules/clean_code.md`. Lowering any metric requires an ADR.
+- **Mutation floor on guards:** line coverage alone proves little. Behavioral guards (`agent-guard-*`, `boundaries.ts`, protected-target checks) must hold a 100% mutant-kill gate (`npm run test:mutation`, `benchmark/mutation-test.js`). A green suite that lets a `blocked: true → false` or `return cycles → return []` mutant survive is a failure, even at 100% lines.
+- **Assertion-density check:** agents asked to hit a line number write assertion-free tests to cover lines. Reject that explicitly: every new behavioral test must contain at least one behavior-asserting expectation (no `expect(true).toBe(true)`, no tests without assertions). Prefer `benchmark/evaluate.js --strict-tests` style checks (assertions per test ≥ 1, critical paths ≥ 2) over raising the line percentage.
+- **What this repo enforces vs what users get:** this repo's exact thresholds live in `jest.config.js` (100% lines, branches, functions, statements) and are locked by `tests/coverage-config.test.ts`. Generated polyglot projects get the equivalent per-language fitness gates in `docs/rules/clean_code.md` (ESLint / ruff / clippy / golangci-lint / Checkstyle / Roslyn) at the same 100% bar — the tooling differs by stack, the bar must not.
+- **Exhaustive status codes & error branches:** explicitly test all HTTP/gRPC response codes:
   - Success: `200 OK`, `201 Created`, `204 No Content`
   - Client Errors: `400 Bad Request`, `401 Unauthorized`, `403 Forbidden`, `404 Not Found`, `409 Conflict`, `422 Unprocessable Entity`, `429 Too Many Requests`
   - Server Failures: `500 Internal Server Error`, `503 Service Unavailable`

package/lib/cli-boundaries.d.ts

@@ -0,0 +1,18 @@
+import type { BoundaryReport } from './boundaries.js';
+import type { CliParsedOptions } from './cli-parse.js';
+export interface BoundaryIo {
+    out: (msg: string) => void;
+    err: (msg: string) => void;
+    exit: (code: number) => void | number;
+    cwd: string;
+}
+export declare function resolveBoundaryTarget(targetDir: string | null, cwd: string): string;
+export declare function formatBoundaryReport(targetDir: string, report: BoundaryReport, out: (msg: string) => void): void;
+export declare function handleBoundariesCommand(parsed: CliParsedOptions, io: BoundaryIo): Promise<void | number>;
+declare const _default: {
+    resolveBoundaryTarget: typeof resolveBoundaryTarget;
+    formatBoundaryReport: typeof formatBoundaryReport;
+    handleBoundariesCommand: typeof handleBoundariesCommand;
+};
+export default _default;
+//# sourceMappingURL=cli-boundaries.d.ts.map

package/lib/cli-boundaries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-boundaries.d.ts","sourceRoot":"","sources":["../src/cli-boundaries.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3B,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,CAAC;IACtC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAMnF;AAcD,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GACzB,IAAI,CASN;AAED,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,gBAAgB,EACxB,EAAE,EAAE,UAAU,GACb,OAAO,CAAC,IAAI,GAAG,MAAM,CAAC,CASxB;;;;;;AAED,wBAIE"}

package/lib/cli-boundaries.js

@@ -0,0 +1,46 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { inspectBoundaries } from './boundaries.js';
+export function resolveBoundaryTarget(targetDir, cwd) {
+    if (targetDir) {
+        return path.resolve(cwd, targetDir);
+    }
+    const defaultSrc = path.join(cwd, 'src');
+    return fs.existsSync(defaultSrc) ? defaultSrc : cwd;
+}
+function printViolations(report, out) {
+    const total = report.cycles.length + report.violations.length;
+    out(`🚨 ARCHITECTURAL VIOLATIONS DETECTED (${total}):`);
+    for (const cycle of report.cycles) {
+        out(`   - Circular Dependency: ${cycle.join(' -> ')}`);
+    }
+    for (const v of report.violations) {
+        out(`   - Layer Boundary Breach: ${v.file} illegally imports ${v.importedFile} (${v.fromLayer} -> ${v.toLayer})`);
+    }
+    out('   Action Required: Invert dependencies via Ports or extract shared modules.\n');
+}
+export function formatBoundaryReport(targetDir, report, out) {
+    out(`\n🔍 Inspecting Architectural Boundaries in: ${targetDir}`);
+    out('--------------------------------------------------------------');
+    if (report.ok) {
+        out(`✅ Analyzed ${report.moduleCount} modules: 0 circular cycles, 0 boundary violations.`);
+        out('🎉 SUCCESS: Architecture is clean and drift-free! (0 violations)\n');
+    }
+    else {
+        printViolations(report, out);
+    }
+}
+export async function handleBoundariesCommand(parsed, io) {
+    const targetDir = resolveBoundaryTarget(parsed.targetDir, io.cwd);
+    const report = inspectBoundaries(targetDir);
+    if (!parsed.silent) {
+        formatBoundaryReport(targetDir, report, io.out);
+    }
+    return io.exit(report.ok ? 0 : 1);
+}
+export default {
+    resolveBoundaryTarget,
+    formatBoundaryReport,
+    handleBoundariesCommand
+};
+//# sourceMappingURL=cli-boundaries.js.map

package/lib/cli-boundaries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-boundaries.js","sourceRoot":"","sources":["../src/cli-boundaries.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAWpD,MAAM,UAAU,qBAAqB,CAAC,SAAwB,EAAE,GAAW;IACzE,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IACtC,CAAC;IACD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACzC,OAAO,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC;AACtD,CAAC;AAED,SAAS,eAAe,CAAC,MAAsB,EAAE,GAA0B;IACzE,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC;IAC9D,GAAG,CAAC,yCAAyC,KAAK,IAAI,CAAC,CAAC;IACxD,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClC,GAAG,CAAC,6BAA6B,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACzD,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QAClC,GAAG,CAAC,+BAA+B,CAAC,CAAC,IAAI,sBAAsB,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,SAAS,OAAO,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC;IACpH,CAAC;IACD,GAAG,CAAC,gFAAgF,CAAC,CAAC;AACxF,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,SAAiB,EACjB,MAAsB,EACtB,GAA0B;IAE1B,GAAG,CAAC,gDAAgD,SAAS,EAAE,CAAC,CAAC;IACjE,GAAG,CAAC,gEAAgE,CAAC,CAAC;IACtE,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;QACd,GAAG,CAAC,cAAc,MAAM,CAAC,WAAW,qDAAqD,CAAC,CAAC;QAC3F,GAAG,CAAC,oEAAoE,CAAC,CAAC;IAC5E,CAAC;SAAM,CAAC;QACN,eAAe,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC/B,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,MAAwB,EACxB,EAAc;IAEd,MAAM,SAAS,GAAG,qBAAqB,CAAC,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;IAClE,MAAM,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAE5C,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QACnB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;IAClD,CAAC;IAED,OAAO,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC;AAED,eAAe;IACb,qBAAqB;IACrB,oBAAoB;IACpB,uBAAuB;CACxB,CAAC"}

package/lib/cli-parse.d.ts

@@ -4,7 +4,7 @@
  * Table-driven: every boolean flag is one Map entry, so adding a flag cannot
  * raise the complexity of the parser itself.
  */
-export type CliCommand = 'scaffold' | 'check';
+export type CliCommand = 'scaffold' | 'check' | 'boundaries';
 export interface CliParsedOptions {
     command: CliCommand;
     targetDir: string | null;
@@ -18,6 +18,7 @@ export interface CliParsedOptions {
 export type BooleanFlagKey = 'force' | 'noGit' | 'dryRun' | 'silent';
 export declare function emptyOptions(): Omit<CliParsedOptions, 'terminal' | 'message'>;
 export declare const CHECK_COMMANDS: Set<string>;
+export declare const BOUNDARY_COMMANDS: Set<string>;
 export declare const BOOLEAN_FLAGS: Map<string, BooleanFlagKey>;
 export interface ArgOutcome {
     terminal: 'help' | 'version' | 'unknown-flag' | 'extra-arg' | null;

package/lib/cli-parse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-parse.d.ts","sourceRoot":"","sources":["../src/cli-parse.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,OAAO,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,UAAU,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,GAAG,WAAW,GAAG,IAAI,CAAC;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAErE,wBAAgB,YAAY,IAAI,IAAI,CAAC,gBAAgB,EAAE,UAAU,GAAG,SAAS,CAAC,CAS7E;AAED,eAAO,MAAM,cAAc,aAA0C,CAAC;AAEtE,eAAO,MAAM,aAAa,6BAQxB,CAAC;AAEH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,GAAG,WAAW,GAAG,IAAI,CAAC;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAQD,wBAAgB,QAAQ,CACtB,KAAK,EAAE,IAAI,CAAC,gBAAgB,EAAE,UAAU,GAAG,SAAS,CAAC,EACrD,GAAG,EAAE,MAAM,GACV,UAAU,CA0BZ;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,gBAAgB,CAStE;;;;;;;;AAED,wBAAoF"}
+{"version":3,"file":"cli-parse.d.ts","sourceRoot":"","sources":["../src/cli-parse.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,OAAO,GAAG,YAAY,CAAC;AAE7D,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,UAAU,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,GAAG,WAAW,GAAG,IAAI,CAAC;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAErE,wBAAgB,YAAY,IAAI,IAAI,CAAC,gBAAgB,EAAE,UAAU,GAAG,SAAS,CAAC,CAS7E;AAED,eAAO,MAAM,cAAc,aAA0C,CAAC;AACtE,eAAO,MAAM,iBAAiB,aAAgD,CAAC;AAE/E,eAAO,MAAM,aAAa,6BAQxB,CAAC;AAEH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,GAAG,WAAW,GAAG,IAAI,CAAC;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAwBD,wBAAgB,QAAQ,CACtB,KAAK,EAAE,IAAI,CAAC,gBAAgB,EAAE,UAAU,GAAG,SAAS,CAAC,EACrD,GAAG,EAAE,MAAM,GACV,UAAU,CAuBZ;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,gBAAgB,CAStE;;;;;;;;AAED,wBAAoF"}