@pukujan/create-modular-monolith 2.1.0 → 2.2.1

package/LICENSE

@@ -0,0 +1,50 @@
+# Pukujan Modular Monolith Platform License
+
+Copyright (c) 2026 Pukujan. All rights reserved.
+
+This repository and the `@pukujan/create-modular-monolith` npm package (including
+the `template/` directory) are proprietary. No rights are granted except as
+stated below.
+
+## Permitted use
+
+1. **Scaffold** — You may install and run `@pukujan/create-modular-monolith` to
+   generate a project for your own application development.
+
+2. **Your application code** — You retain ownership of code you write in a
+   scaffolded project. Platform files copied from the template remain subject
+   to this license for as long as you keep them in your repository.
+
+3. **Attribution (required)** — If your repository or product includes
+   substantial portions of this platform (for example: architecture contracts,
+   file-exchange layout, dev-log tooling, or scripts copied from the template),
+   you must include **visible attribution** in a prominent place (typically
+   README), such as:
+
+   > Built with the Pukujan Modular Monolith platform  
+   > https://github.com/Pukujan/create-modular-monolith
+
+   You must also retain copyright and license notices in `LICENSE` and `NOTICE`
+   files that you do not replace with your own.
+
+## Restrictions
+
+- Do not remove or obscure copyright or attribution notices from platform files
+  you retain.
+- Do not republish this package, its `template/`, or a substantially similar
+  scaffold under another name without written permission from the copyright holder.
+- Do not use the Pukujan name or branding to imply endorsement of your product.
+
+## No warranty
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING
+FROM USE OF THE SOFTWARE.
+
+## Licensing inquiries
+
+For permissions beyond this license (commercial redistribution of the scaffold,
+white-label templates, etc.), open an issue at  
+https://github.com/Pukujan/create-modular-monolith/issues

package/README.md

@@ -1,112 +1,197 @@
 # @pukujan/create-modular-monolith
 
-**npm create** scaffold for a modular monolith built for **human + agent** engineering at scale.
+**Scaffold a modular monolith built for human + Cursor agent engineering** — Express + React, versioned contracts, file-exchange handoffs, paired dev logs, and CI gates out of the box.
 
 ```bash
-npm create @pukujan/modular-monolith@2 my-platform
+npm create @pukujan/modular-monolith@2.2.1 my-platform
 cd my-platform
 npm install --prefix backend && npm install --prefix frontend
+npm run test:ci
 ```
 
-Published package: `@pukujan/create-modular-monolith`  
-Product reference implementation: [litigation-prompt-engineering](https://github.com/Pukujan/litigation-prompt-engineering)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](package.json)
+[![License](https://img.shields.io/badge/License-Proprietary%20%2B%20attribution-lightgrey)](LICENSE)
+
+| | |
+|---|---|
+| **This package** | `npm create` boilerplate — architecture only (`_reference`, `model-condenser`) |
+| **Full product example** | [litigation-prompt-engineering](https://github.com/Pukujan/litigation-prompt-engineering) — domain modules, prompts, evals |
 
 ---
 
-## What you get
+## What this is
 
-This is **not** a minimal Express/React demo. It is an **architecture platform**:
+`@pukujan/create-modular-monolith` copies the `template/` folder into your chosen directory. You get a **platform**, not a hello-world demo:
 
-| Layer | Purpose |
-|-------|---------|
-| **Module contract** | Backend `register(app)` + frontend route modules — add features without rewriting core |
-| **Architecture contracts** | Versioned manifest (`docs/architecture/contracts/`) — paths, APIs, exports, dev logs |
-| **File exchange** | Dated `imports/` / `exports/` for human↔agent file handoff |
-| **Pre-push dev logs** | Paired **human markdown** (summary + detail, mermaid, TOC) + **agent JSON** audit |
-| **Consolidated snapshots** | `condense:all` → models, prompts, file tree in `file-exchange/exports/` |
-| **Lint automation** | Boundaries, layers, contracts, repo artifacts, API registry |
-| **Cursor-native** | `AGENTS.md`, `.cursor/rules`, `.cursor/commands` for repeatable agent workflows |
+- **Modular monolith** — feature modules with enforced boundaries and internal MVC layers
+- **Architecture contracts** — versioned manifest so paths and tooling stay in sync
+- **File exchange** — dated `imports/` / `exports/` for human↔agent file handoff
+- **Pre-push dev logs** — human markdown (summary + detail) + agent JSON audit before every push
+- **CI gates** — `npm run test:ci` matches GitHub Actions (lint, tests, module evals)
+- **Cursor-native** — `AGENTS.md`, `.cursor/rules`, `.cursor/commands`
 
-Domain business logic is **yours to add** via `npm run new:module`. The repo ships with `_reference` and `model-condenser` only.
+Domain logic is **yours**: `npm run new:module -- billing --label "Billing"`.
 
 ---
 
-## Why this architecture exists
+## Why use this
 
-Modern products are built as much by **agents** as by humans. This template encodes:
+| Problem | How the template helps |
+|---------|-------------------------|
+| Agents read random folders | Mandatory `file-exchange/imports/{stamp}/` + [AGENTS.md](template/AGENTS.md) |
+| Undocumented APIs | [docs/API.md](template/docs/API.md) registry + `lint:api-docs` |
+| Lost context between sessions | Paired dev logs under `work-log/dev-logs/` |
+| Repo layout drift | `lint:contracts` + [CONTRACTS_OVERVIEW](template/docs/architecture/CONTRACTS_OVERVIEW.md) |
+| No merge-quality bar | `.github/workflows/ci.yml` + `npm run test:ci` |
 
-1. **Discoverability** — Agents read JSON audits and contract manifests instead of guessing folder layout.
-2. **Repeatability** — Every push can produce the same artifact set (dev log pair, tree, API inventory, test results).
-3. **Scale** — New modules plug in under `backend/src/modules/` and `frontend/src/modules/` with enforced boundaries.
-4. **Governance** — `lint:contracts` fails CI if a contract path is missing; `lint:api-docs` keeps routes documented.
+---
 
-Read **`template/docs/architecture/PLATFORM_ARCHITECTURE.md`** (in this repo) for the full narrative. After scaffold, start at **`docs/architecture/CONTRACTS_OVERVIEW.md`** in your project.
+## How it works
+
+```mermaid
+flowchart LR
+  subgraph scaffold [npm create]
+    cli[index.js]
+    tpl[template/]
+    app[your-platform/]
+  end
+
+  subgraph platform [Platform layer]
+    fx[file-exchange/]
+    contracts[docs/architecture/contracts/]
+    devlog[work-log/dev-logs/]
+    ci[test:ci]
+  end
+
+  subgraph domain [You add]
+    mod[npm run new:module]
+    prompts[module prompts/]
+    evals[optional evals/golden/]
+  end
+
+  cli --> tpl --> app
+  app --> platform
+  app --> domain
+```
+
+After scaffold, read [template/docs/architecture/PLATFORM_ARCHITECTURE.md](template/docs/architecture/PLATFORM_ARCHITECTURE.md) and [template/docs/architecture/EVAL_AND_CI.md](template/docs/architecture/EVAL_AND_CI.md).
 
 ---
 
-## Repository layout (this GitHub repo)
+## Quick start (after scaffold)
 
-```text
-create-modular-monolith/
-  README.md              ← you are here (npm package docs)
-  package.json           ← @pukujan/create-modular-monolith
-  index.js               ← copies template/ into target directory
-  template/              ← full starter app (architecture only)
+```bash
+cd my-platform
+
+cp backend/.env.example backend/.env
+cp frontend/.env.example frontend/.env
+
+cd backend && npm run dev
+# new terminal:
+cd frontend && npm run dev
+```
+
+**Quality gate (run before push):**
+
+```bash
+npm run test:ci
+npm run dev-log:pre-push -- --slug initial-setup
 ```
 
 ---
 
-## Architecture scripts (in every scaffolded project)
+## What ships in `template/`
 
-These live under `template/scripts/` and are copied into new projects:
+| Area | Contents |
+|------|----------|
+| Backend | `backend/src/core/`, `modules/_reference`, `modules/model-condenser` |
+| Frontend | `frontend/src/core/`, `modules/_reference` |
+| Docs | `docs/architecture/` — guardrails, contracts, PLATFORM_ARCHITECTURE, EVAL_AND_CI |
+| Exchange | `file-exchange/imports/`, `file-exchange/exports/` |
+| Work log | `work-log/dev-logs/human/`, `agent/`, JSON schema |
+| CI | `.github/workflows/ci.yml` |
+| Scripts | `lint:contracts`, `condense:all`, `import:file-exchange`, `new:module`, … |
 
-| Script | npm command | Role |
-|--------|-------------|------|
-| `lint-contracts.mjs` | `npm run lint:contracts` | Verify `manifest.json` paths exist |
-| `lint-repo-artifacts.mjs` | `npm run lint:repo-artifacts` | Verify exchange, dev-log, contract docs |
-| `check-api-docs.mjs` | `npm run lint:api-docs` | Routes ⊆ `docs/API.md` registry |
-| `write-pre-push-dev-log.mjs` | `npm run dev-log:pre-push` | Human + agent pre-push audit pair |
-| `verify-dev-log.mjs` | `npm run dev-log:verify` | Validate latest dev-log structure |
-| `condense-file-structure.mjs` | `npm run condense-file-structure` | Repo tree → `exports/consolidated-file-structure.json` |
-| `condense-prompts.mjs` | `npm run condense-prompts` | All prompts → consolidated JSON |
-| `import-to-file-exchange.mjs` | `npm run import:file-exchange` | Inbound bundles → `imports/{stamp}/` |
-| `new-module.mjs` | `npm run new:module` | Scaffold backend + frontend module |
+**Not included:** domain batches, litigation prompts, or committed `evals/golden/` (add per project when you curate fixtures).
 
-Supporting libraries: `scripts/lib/repo-tree.mjs`, `api-inventory.mjs`, `dev-log-human-format.mjs`, `git-snapshot.mjs`, `run-tests.mjs`.
+---
+
+## Key commands (in every scaffolded app)
+
+| Command | Purpose |
+|---------|---------|
+| `npm run test:ci` | All CI gates locally |
+| `npm run new:module -- <name>` | Scaffold backend + frontend module |
+| `npm run import:file-exchange -- <path>` | Inbound files → `imports/{stamp}/` |
+| `npm run condense:all` | Snapshots → `file-exchange/exports/consolidated-*.json` |
+| `npm run dev-log:pre-push -- --slug <topic>` | Human + agent dev log pair |
+| `npm run lint:architecture` | Boundaries + layers + API docs |
 
 ---
 
-## Contract catalog (v001)
+## Contract catalog (platform v001)
 
 Registered in `template/docs/architecture/contracts/manifest.json`:
 
-- **fileExchange** — dated imports/exports, human-readable stamps
-- **consolidatedExports** — snapshot JSON in `file-exchange/exports/`
-- **prePushDevLog** — paired human MD + agent JSON before push
-- **apiDocumentationRegistry** — `docs/API.md` as HTTP source of truth
-- **repoArtifactLayout** — canonical data roots
+- **fileExchange** — dated imports/exports
+- **consolidatedExports** — `condense:all` output paths
+- **prePushDevLog** — paired human MD + agent JSON
+- **apiDocumentationRegistry** — `docs/API.md`
+- **repoArtifactLayout** — canonical roots
 
-Module-level contracts (storage layout, pipeline versions) are added when you build domain modules.
+Add domain contracts in your modules when you introduce pipelines or storage layouts.
 
 ---
 
-## Publishing this package
+## Golden evals (per project, not universal)
 
-```bash
-cd packages/create-modular-monolith   # or repo root if package.json is here
-npm version patch|minor|major
-npm publish --access public
+**Eval / regression** compares output to expected JSON for a **known fixture case** — not “truth for every future customer/case.”
+
+See [EVAL_AND_CI.md](template/docs/architecture/EVAL_AND_CI.md). Optional: create `evals/golden/{caseId}/` when you are ready to lock regression for one scenario.
+
+---
+
+## This repository layout
+
+```text
+create-modular-monolith/          ← npm package (this repo)
+├── README.md                     ← you are here
+├── package.json                  ← @pukujan/create-modular-monolith@2.2.1
+├── index.js                      ← copies template/ on npm create
+├── CHANGELOG.md
+└── template/                     ← full starter copied to user's folder
+    ├── README.md                   ← first doc in a new project
+    ├── AGENTS.md
+    ├── docs/architecture/
+    └── ...
 ```
 
-Users install with:
+---
+
+## Publishing
+
+Maintainers sync platform changes from product repos via `export:architecture-starter` (see [litigation-prompt-engineering](https://github.com/Pukujan/litigation-prompt-engineering)).
 
 ```bash
-npm create @pukujan/modular-monolith@2 <folder-name>
+npm version patch   # or minor / major
+npm publish --access public
 ```
 
+Requires npm auth (granular token with publish access).
+
+---
+
+## Related
+
+| Repo | Role |
+|------|------|
+| [create-modular-monolith](https://github.com/Pukujan/create-modular-monolith) | **This package** |
+| [litigation-prompt-engineering](https://github.com/Pukujan/litigation-prompt-engineering) | Reference product (domain + evals) |
+
 ---
 
-## Version
+## License
 
-Package version tracks **architecture platform** releases (contracts, agent tooling, template layout).  
-See `package.json` and git tags. Domain app code lives in separate product repos.
+**Proprietary — all rights reserved.** You may use the npm scaffold to build your
+own apps; **attribution is required** if you keep substantial platform files from
+the template. See [LICENSE](LICENSE) and [template/NOTICE](template/NOTICE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pukujan/create-modular-monolith",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Scaffold a modular monolith with architecture contracts, file-exchange, agent dev logs, and lint automation for Cursor-scale engineering.",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "index.js",
+    "LICENSE",
     "template"
   ],
   "keywords": [
@@ -21,7 +22,7 @@
     "create-app"
   ],
   "author": "Pukujan",
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Pukujan/create-modular-monolith.git"

package/template/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  quality-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: |
+            backend/package-lock.json
+            frontend/package-lock.json
+
+      - name: Install backend
+        run: npm ci
+        working-directory: backend
+
+      - name: Install frontend
+        run: npm ci
+        working-directory: frontend
+
+      - name: Lint contracts
+        run: npm run lint:contracts
+
+      - name: Lint repo artifacts
+        run: npm run lint:repo-artifacts
+
+      - name: Lint architecture
+        run: npm run lint:architecture
+
+      - name: Unit tests
+        run: npm test
+
+      - name: Module eval runners
+        run: npm run test:evals

package/template/LICENSE

@@ -0,0 +1,11 @@
+# Platform license (scaffolded from create-modular-monolith)
+
+Copyright (c) 2026 Pukujan. All rights reserved.
+
+This project includes platform files from @pukujan/create-modular-monolith.
+See NOTICE for attribution requirements and  
+https://github.com/Pukujan/create-modular-monolith/blob/main/LICENSE  
+for the full Pukujan Modular Monolith Platform License.
+
+Application code you add to this repository is yours. Platform files you retain
+remain subject to the license above until you replace them.

package/template/NOTICE

@@ -0,0 +1,13 @@
+Pukujan Modular Monolith Platform
+
+Copyright (c) 2026 Pukujan. All rights reserved.
+
+This project was scaffolded from @pukujan/create-modular-monolith
+(https://github.com/Pukujan/create-modular-monolith).
+
+Platform files (architecture contracts, file-exchange layout, dev-log tooling,
+and related scripts) remain subject to the Pukujan Modular Monolith Platform
+License. See LICENSE in the create-modular-monolith repository.
+
+Attribution: retain this NOTICE (or equivalent credit in README) if you keep
+substantial platform files from the template.

package/template/README.md

@@ -1,34 +1,114 @@
-# Modular monolith platform (scaffolded)
+# Modular Monolith Platform
 
-Architecture-first Express + React starter for products that scale with **human + agent** engineering.
+**Your scaffolded app** — Express + React modular monolith with architecture contracts, file-exchange, agent dev logs, and CI gates.
 
-**Read first:** [docs/architecture/PLATFORM_ARCHITECTURE.md](docs/architecture/PLATFORM_ARCHITECTURE.md)  
-**Contracts:** [docs/architecture/CONTRACTS_OVERVIEW.md](docs/architecture/CONTRACTS_OVERVIEW.md)  
-**Agents:** [AGENTS.md](AGENTS.md)
+| | |
+|---|---|
+| **Architecture** | This repo layout and contracts |
+| **npm package** | [@pukujan/create-modular-monolith](https://github.com/Pukujan/create-modular-monolith) |
+| **Example product** | [litigation-prompt-engineering](https://github.com/Pukujan/litigation-prompt-engineering) (domain-filled reference) |
+
+---
+
+## Start here
+
+| Doc | Purpose |
+|-----|---------|
+| [docs/architecture/PLATFORM_ARCHITECTURE.md](docs/architecture/PLATFORM_ARCHITECTURE.md) | How the platform works (agents + humans) |
+| [docs/architecture/CONTRACTS_OVERVIEW.md](docs/architecture/CONTRACTS_OVERVIEW.md) | Contract manifest and enforcement |
+| [docs/architecture/EVAL_AND_CI.md](docs/architecture/EVAL_AND_CI.md) | CI gates, evals, golden (per-case) |
+| [AGENTS.md](AGENTS.md) | **Required for Cursor / automation** |
+| [docs/README.md](docs/README.md) | Full documentation index |
+
+---
 
 ## Quick start
 
+**Requirements:** Node.js 20+
+
 ```bash
+cp backend/.env.example backend/.env
+cp frontend/.env.example frontend/.env
+
 cd backend && npm install && npm run dev
-# other terminal:
+# new terminal:
 cd frontend && npm install && npm run dev
 ```
 
-## Architecture commands
+- API: `http://localhost:3001` — [docs/API.md](docs/API.md)
+- UI: Vite dev server — see `frontend/package.json`
+
+---
+
+## Daily commands
+
+```bash
+# Before every git push
+npm run dev-log:pre-push -- --slug your-topic
+npm run test:ci
+
+# Inbound files for agents (never process from Downloads/ directly)
+npm run import:file-exchange -- "/path/to/bundle"
+
+# Refresh agent-readable snapshots
+npm run condense:all
+
+# New feature
+npm run new:module -- billing --label "Billing"
+```
+
+---
+
+## Repository map
+
+```text
+my-modular-monolith/
+├── backend/src/modules/       # add features here (_reference = layout example)
+├── frontend/src/modules/
+├── docs/architecture/         # contracts, guardrails
+├── file-exchange/             # imports/{stamp}/ exports/consolidated-*.json
+├── work-log/                  # handoffs + dev-logs (human + agent)
+├── scripts/                   # lint, condense, dev-log, new-module
+└── .github/workflows/ci.yml
+```
+
+Canonical paths: [docs/architecture/REPO_ARTIFACT_LAYOUT.md](docs/architecture/REPO_ARTIFACT_LAYOUT.md)
+
+---
+
+## What is included
+
+- **Modules:** `_reference` (example layout), `model-condenser` (schema inventory API)
+- **Platform contracts** v001 — file exchange, dev logs, consolidated exports, API registry
+- **Lint:** `lint:architecture`, `lint:contracts`, `lint:repo-artifacts`
+- **CI:** GitHub Actions runs the same checks as `npm run test:ci`
+- **Observability:** `backend/src/shared/utils/traceId.js` for correlating workflow steps
+
+---
+
+## What you add
+
+- Domain modules under `backend/src/modules/<name>/` and `frontend/src/modules/<name>/`
+- Prompts in each module’s `prompts/`
+- Optional `evals/golden/{caseId}/` when you have curated expected JSON for regression
+- Runtime data under `data/` (gitignored by default)
+
+---
+
+## Architecture checks
 
 ```bash
-npm run lint:contracts          # contract manifest paths
-npm run lint:architecture       # module boundaries + layers + API docs
-npm run import:file-exchange -- ./my-bundle
-npm run dev-log:pre-push -- --slug initial-setup
-npm run condense:all            # consolidated snapshots → file-exchange/exports/
-npm run new:module -- my-feature --label "My Feature"
+npm run test:ci              # recommended before push
+npm run lint:architecture
+npm run test:evals           # module example eval runners (offline)
 ```
 
-## What ships in this template
+---
+
+## License & attribution
 
-- `_reference` + `model-condenser` modules (no domain logic)
-- File exchange, work-log dev logs (human + agent), contract manifest v001
-- Lint and condense tooling for trees, prompts, and schemas
+This scaffold includes **platform files** licensed by Pukujan (see [LICENSE](LICENSE)
+and [NOTICE](NOTICE)). **Keep attribution** in README or NOTICE if you retain
+those files. Application code you write is yours.
 
-Built with [@pukujan/create-modular-monolith](https://github.com/Pukujan/create-modular-monolith).
+Full terms: [create-modular-monolith/LICENSE](https://github.com/Pukujan/create-modular-monolith/blob/main/LICENSE)