azcodr 2.2.0 → 2.4.0

package/.agents/scripts/agent_guard.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+/**
+ * Cross-platform PreToolUse safety & architectural enforcement hook.
+ *
+ * Enforces:
+ *  1. Command safety (blocks destructive rm, force-push, drop db, etc.)
+ *  2. Refactor-Before-Add (blocks adding lines to files over line budget)
+ *  3. Test-First / RED-before-GREEN (when enabled)
+ */
+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));
+const guardModulePath = path.resolve(selfDir, '../../lib/agent-guard.js');
+
+async function getGuardModule() {
+  return import(pathToFileURL(guardModulePath).href);
+}
+
+async function readStdin(timeoutMs = 1500) {
+  if (process.stdin.isTTY) return '';
+  return new Promise((resolve) => {
+    let acc = '';
+    const timer = setTimeout(() => resolve(acc), timeoutMs);
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => { acc += chunk; });
+    process.stdin.on('end', () => {
+      clearTimeout(timer);
+      resolve(acc);
+    });
+    process.stdin.on('error', () => {
+      clearTimeout(timer);
+      resolve(acc);
+    });
+  });
+}
+
+async function main() {
+  const argvInput = process.argv.slice(2).join(' ').trim();
+  const stdinInput = (await readStdin()).trim();
+  const rawInput = argvInput || stdinInput;
+
+  if (!rawInput) {
+    process.exit(0);
+  }
+
+  const { inspectPreTool } = await getGuardModule();
+  const decision = inspectPreTool(rawInput, {
+    workspaceRoot: process.cwd()
+  });
+
+  if (!decision.allowed) {
+    console.error(`🚨 Architectural Guard: ${decision.reason}`);
+    process.exit(1);
+  }
+
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

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`), linter configurations, and boundary smoke test (`scripts/smoke_test.sh`).
+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`).
 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.
 

package/.github/workflows/ci.yml

@@ -54,6 +54,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
+
       - name: Run Syntax & Lint Checks
         run: npm run lint
 
@@ -84,6 +91,20 @@ jobs:
       - name: Verify Coverage Gates
         run: npm run test:coverage
 
+      - name: Verify Mutation Score Gate (100% Mutant Kill)
+        run: npm run test:mutation
+
+      - name: Verify Empirical Drift Benchmark
+        run: node benchmark/run-benchmark.js
+
+      - name: Upload Coverage Report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: coverage-report
+          path: coverage/
+          retention-days: 14
+
   shell-syntax:
     name: Shell Script Syntax (shipped hooks)
     runs-on: ubuntu-24.04

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/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

@@ -0,0 +1,85 @@
+# Contributing to azcodr
+
+Thank you for contributing to `azcodr`!
+
+This repository is governed by strict systemic atomicity, Clean Code fitness functions, and test-driven development.
+
+---
+
+## 🛠️ Development Setup
+
+### Prerequisites
+- Node.js `>=22.8.0` (required for native ESM VM modules)
+- npm `>=10.0.0`
+- Git
+
+### Installation
+Clone the repository and install exact-pinned development tooling:
+```bash
+git clone https://github.com/prosubodh/azcodr.git
+cd azcodr
+npm ci
+```
+
+---
+
+## 🧪 Verification & Quality Gates
+
+Before submitting any code changes, all 5 quality gates must pass with zero errors:
+
+1. **Type Checking:**
+   ```bash
+   npm run typecheck
+   ```
+2. **Production Build:**
+   ```bash
+   npm run build
+   ```
+3. **Clean Code Fitness Functions (ESLint):**
+   ```bash
+   npm run lint
+   ```
+   *Enforces:*
+   - Maximum 300 lines per file (including comments)
+   - Maximum 30 lines per function
+   - Cyclomatic complexity $\le 10$
+   - Maximum 3 parameters per function
+4. **Test Suite & Coverage Gate (Jest):**
+   ```bash
+   npm test
+   npm run test:coverage
+   ```
+   *Coverage gates enforced:*
+   - **100% lines coverage**
+   - **97% functions coverage**
+   - **98% branches coverage**
+5. **Agentic Architecture Validation:**
+   ```bash
+   npm run validate
+   ```
+   Validates root harness parity, progressive disclosure rules, skill formats, markdown links, and ADR ledger consistency.
+
+---
+
+## 🏛️ Architectural Invariants
+
+Every contribution must preserve these core invariants:
+- **Zero Runtime Dependencies:** `dependencies` in `package.json` must remain undefined. Runtime features rely strictly on Node.js standard builtins (`node:*`).
+- **Exact-Pinned DevDependencies:** Any tool in `devDependencies` must have an exact version (no `^`, `~`, or floating ranges) and committed `package-lock.json`.
+- **Refactor Before Adding:** When introducing changes, refactor structure first under existing green tests before adding new logic.
+- **Lightweight ADRs:** Significant architectural decisions or boundary changes must be recorded in `memory.md`.
+
+---
+
+## 🔄 Pull Request Guidelines
+
+1. Create a feature branch: `git checkout -b feat/your-feature-name`.
+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,6 +1,15 @@
 # azcodr: Enterprise Architecture & Agentic Engineering Starter Template
 
-> **Production-ready, battle-tested software architecture governed by problem-first topology alignment, strict systemic atomicity, evolutionary architecture tipping points, 100% open-source standards, true incremental TDD nano-cycles, and zero speculative bloat.**
+[![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)
+[![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.*
 
 ---
 
@@ -8,7 +17,7 @@
 
 1. **Problem-First & Topology Alignment**: Architecture emerges strictly from problem constraints and execution targets (Problem-First; zero preemptive tool bias). Architectural styles match the problem topology: Hexagonal for enterprise backends, Platform Scripting for extensions, Data-Oriented Design for game engines, Command Pipeline for CLIs, and Game Loop for canvas games.
 2. **Systemic Atomicity**: Every rule, skill, database transaction, and code unit adheres to the Single Responsibility Principle (SRP)—indivisible, self-contained, orthogonal, and composable with zero conjunction naming.
-3. **Evolutionary Architecture & Refactor-Before-Add**: To eliminate AI-accelerated architectural drift, code graduates across 5 deterministic tipping points. Refactor structure first under existing green tests before implementing new features. Never append code into rotting files.
+3. **Evolutionary Architecture & Refactor-Before-Add**: To catch AI-accelerated architectural drift, code graduates across [5 deterministic tipping points](./docs/tipping-points.md). Refactor structure first under existing green tests before implementing new features. Never append code into rotting files.
 4. **True Incremental TDD & Nano-Cycles**: Prohibit batch-test dumps ("Test-First Waterfall"). Follow Uncle Bob's Three Laws: write one micro-assertion at a time, verify RED failure output, write minimal code to turn GREEN, and refactor under green with Ping-Pong pair programming.
 5. **100% Open-Source & Open Standards**: Standardized exclusively on open-source solutions and vendor-neutral specifications (OpenTelemetry, OPA, OpenFGA, Protocol Buffers, OpenAPI 3.1, JSON Schema Draft 2020-12, CloudEvents, Semgrep, Trivy, Gitleaks, Cosign).
 6. **Zero-Assumption Framework**: Ground truth is established solely through workspace configurations, code evidence, or direct user confirmation.
@@ -23,6 +32,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
 
 ```
@@ -165,4 +235,4 @@ The scaffolder declares two expected capabilities:
 
 Failures carry stable machine-readable codes (`E_TARGET_NOT_EMPTY`, `E_GIT_BLOCKED`, `E_PATH_ESCAPE`, ...). Branch on `err.code`, never on message text — see the exported `ERROR_CODES` map and `ScaffoldError` type.
 
-Initial-commit fallback identity is `Subodh Khanal <prosubodh@gmail.com>` via `GIT_AUTHOR_*` / `GIT_COMMITTER_*` env (no `git -c` shell flags).
+Initial-commit fallback identity is `azcodr[bot] <bot@azcodr.internal>` via `GIT_AUTHOR_*` / `GIT_COMMITTER_*` env (no `git -c` shell flags).

package/SECURITY.md

@@ -0,0 +1,32 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 2.x     | :white_check_mark: |
+| 1.x     | :x:                |
+
+## Reporting a Vulnerability
+
+We take the security of `azcodr` and the architectures scaffolded with it seriously. If you discover a security vulnerability, please report it responsibly:
+
+1. **GitHub Private Vulnerability Reporting (Preferred):**  
+   Submit a private advisory directly through [GitHub Security Advisories](https://github.com/prosubodh/azcodr/security/advisories/new).
+2. **Email Disclosure:**  
+   Email `prosubodh+security@gmail.com` with:
+   - Detailed description of the vulnerability and potential impact.
+   - Minimal, reproducible steps or proof-of-concept payload.
+   - Affected subsystem (`src/guards.ts`, `src/scaffold.ts`, `.agents/scripts/`, etc.).
+
+### Response Commitments
+- **Initial Acknowledgment:** Within 48 hours.
+- **Triage & Reproduction:** Within 5 business days.
+- **Coordinated Disclosure:** Security patch release with accompanying advisory disclosure once remediated.
+
+### Scope & Hardening Invariants
+The core supply-chain invariants defended by `azcodr` include:
+- **Zero Runtime Dependencies:** Supply chain attack surface bounded to standard library Node.js builtins.
+- **Strict Process Isolation:** No shell-string execution (`execSync`/`exec` forbidden; `execFileSync` requires `shell: false`).
+- **Filesystem Containment:** Path boundary enforcement (`assertInside`) preventing directory traversal or escape.
+- **Target Protection:** Refusal to write into system root, user home directory, or ancestors (`isProtectedTarget`), even with `--force`.

package/data/memory.template

@@ -0,0 +1,36 @@
+# Workspace Memory, Architecture Decisions & Knowledge Hub
+
+> **Core Purpose:** Authoritative persistent memory ledger for the workspace repository (`./`), maintaining Lightweight Architectural Decision Records (ADRs), system topologies, and living domain contracts.
+
+---
+
+## 1. Quick Navigation & Knowledge Repositories
+
+- 📖 **[Living Ubiquitous Language Glossary](./docs/knowledge/ubiquitous_language.md)**: Authoritative, single-name domain vocabulary contract.
+- 📜 **[Lightweight ADR Master Index](#adr-master-index)**: Summary of all architectural decisions and direct links to governing rules.
+
+---
+
+## 2. Consolidated Architectural Decision Records (ADRs)
+
+### ADR Master Index
+
+| ID | Title | Date | Status | Governing Rule / Skill |
+|---|---|---|---|---|
+| *(No decisions recorded yet)* | *Record initial architecture decisions during Phase 3 of /lets-build.* | *YYYY-MM-DD* | *ACCEPTED* | *e.g. [`clean_code.md`](./docs/rules/clean_code.md)* |
+
+---
+
+### Lightweight Decision Summaries
+
+<!--
+Record project Architectural Decision Records (ADRs) below as decisions are finalized.
+Format:
+
+#### ADR-001: [Imperative Title]
+- **Date:** YYYY-MM-DD | **Status:** ACCEPTED
+- **Context:** Problem space, constraints, and operational context requiring a decision.
+- **Decision:** Chosen architecture, invariants, and implementation patterns.
+- **Consequences:** Positive benefits and deliberate trade-offs accepted.
+- **Enforced In:** Relevant rule files in docs/rules/ or code paths.
+-->

package/docs/rules/clean_code.md

@@ -60,3 +60,16 @@ Prevent AI-generated code rot using automated fitness functions integrated into
 - **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.
 - **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:
+
+| Language | Linter / Static Tool | Max File Lines (300) | Max Function Lines (30) | Max Complexity (10) | Max Arguments (3) |
+|---|---|---|---|---|---|
+| **TypeScript / Node** | `eslint` | `max-lines: [error, 300]` | `max-lines-per-function: [error, 30]` | `complexity: [error, 10]` | `max-params: [error, 3]` |
+| **Python** | `ruff` + `flake8` | `flake8-lines: max-line-count = 300` | `flake8-functions: max-function-length = 30` | `mccabe: max-complexity = 10` | `flake8-functions: max-parameters = 3` |
+| **Rust** | `cargo clippy` | `#![deny(clippy::too_many_lines)]` | `clippy::too_many_lines = 30` | `clippy::cognitive_complexity = 10` | `clippy::too_many_arguments = 3` |
+| **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` |

package/docs/tipping-points.md

@@ -0,0 +1,37 @@
+# Deterministic Architectural Tipping Points
+
+> **Core Mandate:** Architecture evolves incrementally as complexity grows. AI coding agents naturally take the path of least resistance (local token minimization), repeatedly appending code to simple files until they rot into a Big Ball of Mud. Whenever code crosses one of the 5 Deterministic Tipping Points, the agent must pause and execute an architectural refactor under green tests before adding new features.
+
+---
+
+## The 5 Deterministic Tipping Points
+
+| # | Simple Baseline (Day 1) | Tipping Point / Mutation Trigger | Required Architectural Upgrade |
+|---|---|---|---|
+| **1** | **Flat Script / Single File** | File exceeds **250 lines**, coordinates **>2 distinct I/O resources**, or is imported by **>3 distinct callers**. | **Extract Modular Subsystems:** Decouple domain logic from platform I/O; split into dedicated, cohesive submodules. |
+| **2** | **Inline Branching (`if/else` / `switch`)** | **Rule of Three:** The 3rd branching variant, payment provider, or protocol format is introduced. | **Strategy Pattern / Registry:** Replace conditional cascades with a polymorphic Strategy interface or handler registry; update `memory.md`. |
+| **3** | **In-Memory Store / Global State** | State requires **concurrent mutations**, **persistence across restarts**, or **transactional rollback**. | **Repository Pattern & Persistence Port:** Introduce an explicit storage port contract; swap in-memory mock for a persistent database adapter. |
+| **4** | **Direct Platform / Third-Party SDK Calls** | External SDK or platform API is called from **>2 places**, or throws untyped exceptions across boundaries. | **Adapter Pattern (Anti-Corruption Layer):** Wrap external SDK inside an application-owned port interface; mock only the owned interface in tests. |
+| **5** | **Monolithic Domain Model** | The same business noun represents divergent lifecycles or definitions across workflows (e.g. `User` in Auth vs `User` in Billing). | **Bounded Context Split:** Separate into isolated domain contexts with explicit DTO / Anti-Corruption translation between them. |
+
+---
+
+## Refactor-Before-Add Protocol (Kent Beck's Rule)
+
+> *"Make the change easy (warning: this may be hard), then make the easy change."* — Kent Beck
+
+Before writing production code for any new feature or user story:
+
+1. **Assess Tipping Points**: Will adding this requirement cause any module, function, or data structure to cross an architectural tipping point?
+2. **Phase A — Structural Refactoring (Under Green)**: If yes, refactor the existing architecture *first* while existing test suites remain 100% green. Zero behavioral changes; purely structural evolution.
+3. **Phase B — ADR Mutation**: When an architectural tipping point is crossed, log a Lightweight Architectural Decision Record in `memory.md` summarizing the new structural boundary and trade-off.
+4. **Phase C — Feature Implementation (Inner TDD)**: Only once the architecture cleanly accommodates the new capability, write the failing micro-test and implement the feature.
+
+---
+
+## References
+
+- [Clean Code & Pragmatic Directives](./rules/clean_code.md)
+- [Design Patterns & Result Types](./rules/design_patterns.md)
+- [Domain-Driven Design](./rules/domain_driven_design.md)
+- [Test-Driven Development](./rules/test_driven_development.md)

package/lib/agent-guard-command.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Command safety guard inspecting shell commands against a destructive denylist.
+ */
+export interface CommandViolation {
+    blocked: boolean;
+    reason?: string;
+    command?: string;
+}
+export interface DenylistRule {
+    pattern: RegExp;
+    reason: string;
+}
+export declare const DESTRUCTIVE_RULES: readonly DenylistRule[];
+export declare function normalizeCommand(raw: string): string;
+/**
+ * Checks a command string against the safety denylist.
+ *
+ * @param command - Raw shell command string.
+ * @returns Violation details if blocked, or clean outcome.
+ */
+export declare function inspectCommand(command: string): CommandViolation;
+declare const _default: {
+    DESTRUCTIVE_RULES: readonly DenylistRule[];
+    normalizeCommand: typeof normalizeCommand;
+    inspectCommand: typeof inspectCommand;
+};
+export default _default;
+//# sourceMappingURL=agent-guard-command.d.ts.map

package/lib/agent-guard-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-guard-command.d.ts","sourceRoot":"","sources":["../src/agent-guard-command.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,iBAAiB,EAAE,SAAS,YAAY,EAyEpD,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAehE;;;;;;AAED,wBAAuE"}