@pukujan/create-modular-monolith 2.2.0 → 2.2.3

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,114 +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.2.0 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
+
+| 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` |
 
-Modern products are built as much by **agents** as by humans. This template encodes:
+---
 
-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.
+## 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
+```
 
-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.
+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/`
+
+| 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`, … |
 
-These live under `template/scripts/` and are copied into new projects:
+**Not included:** domain batches, litigation prompts, or committed `evals/golden/` (add per project when you curate fixtures).
 
-| 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 |
+---
 
-Scaffolded projects also ship **`npm run test:ci`**, **`.github/workflows/ci.yml`**, **`traceId.js`**, and **[EVAL_AND_CI.md](template/docs/architecture/EVAL_AND_CI.md)** (gates + per-case golden guidance).
+## Key commands (in every scaffolded app)
 
-Supporting libraries: `scripts/lib/repo-tree.mjs`, `api-inventory.mjs`, `dev-log-human-format.mjs`, `git-snapshot.mjs`, `run-tests.mjs`.
+| 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.2.0",
+  "version": "2.2.3",
   "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/.cursor/rules/file-exchange-inbox.mdc

@@ -18,7 +18,7 @@ alwaysApply: true
 - Ingest golden from that stamp: `npm run ingest:golden-parsed`, `npm run ingest:golden-expected`.
 - Point `process-batch` / `curl` uploads at PDFs **inside** `file-exchange/imports/{stamp}/`, not `Downloads/` or repo root.
 - Copy deliverables to `file-exchange/exports/{stamp}/` when done.
-- Consolidated repo snapshots: `file-exchange/exports/consolidated-*.json` (`npm run condense:all`).
+- Consolidated repo snapshots: `file-exchange/exports/{stamp}_consolidated/` (`npm run condense:all`); latest copies at `exports/consolidated-*.json`.
 
 ## Do not
 

package/template/ARCHITECTURE_EXPORT_README.md

@@ -0,0 +1,30 @@
+# Architecture starter export
+
+Generated by `npm run export:architecture-starter`.
+
+## What this is
+
+A **clean modular-monolith boilerplate**: contracts, file-exchange, dev-logs, model-condenser, `_reference` module, lint scripts — **without** litigation/case-filing domain modules or runtime data.
+
+## What was excluded
+
+- Domain backend/frontend modules (case-filing-ai, court-rules, …)
+- `node_modules`, `dist`, `build`
+- `data/`, `evals/golden`, batch PDFs, import bundles
+- Legal-specific ingest/eval scripts
+
+See `EXPORT_MANIFEST.json` for the full list.
+
+## Update npm CLI template
+
+```bash
+npm run export:architecture-starter -- --to ../create-modular-monolith/packages/template
+# or from this repo:
+npm run export:architecture-starter -- --to packages/create-modular-monolith/template
+cd packages/create-modular-monolith && npm publish --access public
+```
+
+## Docs
+
+Start at [docs/architecture/CONTRACTS_OVERVIEW.md](docs/architecture/CONTRACTS_OVERVIEW.md).
+

package/template/EXPORT_MANIFEST.json

@@ -0,0 +1,74 @@
+{
+  "exportedAt": "2026-05-23T17:53:29.141Z",
+  "sourceRepo": "legal-prmpt-eng",
+  "description": "Architecture-only starter — no domain modules, no build artifacts",
+  "included": {
+    "backendModules": [
+      "_reference",
+      "model-condenser"
+    ],
+    "frontendModules": [
+      "_reference"
+    ],
+    "docs": [
+      "docs/architecture/**",
+      "docs/API.md (starter)",
+      "docs/model-condenser/API.md"
+    ],
+    "scripts": [
+      "new-module.mjs",
+      "sync-cli-template.mjs",
+      "export-architecture-starter.mjs",
+      "check-api-docs.mjs",
+      "lint-contracts.mjs",
+      "lint-repo-artifacts.mjs",
+      "condense-models.mjs",
+      "condense-prompts.mjs",
+      "condense-file-structure.mjs",
+      "condense-all.mjs",
+      "consolidated-output.mjs",
+      "write-pre-push-dev-log.mjs",
+      "verify-dev-log.mjs",
+      "import-to-file-exchange.mjs",
+      "resolve-import-stamp.mjs",
+      "export-consolidated-models.mjs",
+      "run-module-evals.mjs",
+      "scripts/lib/**",
+      "scripts/git-hooks/**"
+    ],
+    "other": [
+      "file-exchange/",
+      "work-log/ (structure)",
+      ".cursor/",
+      "backend/src/core",
+      "backend/src/shared",
+      "frontend/src/core",
+      "frontend/src/shared"
+    ]
+  },
+  "excluded": {
+    "dirs": [
+      "node_modules",
+      ".git",
+      "dist",
+      "build",
+      "coverage",
+      "packages",
+      "export",
+      "data",
+      "eval-bundles",
+      "case-exports",
+      "evals"
+    ],
+    "backendModules": "case-filing-ai, court-rules, case-workflow, filing-*, human-review, task-docketing",
+    "data": "runtime batches, golden fixtures, PDFs",
+    "scripts": "ingest-golden-*, rerun-batch-evals, run-module-evals"
+  },
+  "nextSteps": [
+    "Review export/ARCHITECTURE_EXPORT_README.md",
+    "npm install in backend/ and frontend/",
+    "npm run lint:contracts && npm run lint:architecture",
+    "node scripts/new-module.mjs my-feature --label \"My Feature\"",
+    "Copy into packages/create-modular-monolith/template or publish CLI"
+  ]
+}

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,12 @@
+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 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,43 +1,54 @@
-# 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)  
-**Evals & CI gates:** [docs/architecture/EVAL_AND_CI.md](docs/architecture/EVAL_AND_CI.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
 ```
 
-## Quality gates
-
-```bash
-npm run test:ci             # lint + unit tests + module evals (same as GitHub Actions)
-npm run lint:contracts
-npm run lint:architecture
-npm run test:evals
-```
+---
 
-## Architecture commands
+## Daily commands
 
 ```bash
-npm run import:file-exchange -- ./my-bundle
-npm run dev-log:pre-push -- --slug initial-setup
+npm run dev-log:pre-push -- --slug your-topic
+npm run test:ci
+npm run import:file-exchange -- "/path/to/bundle"
 npm run condense:all
-npm run new:module -- my-feature --label "My Feature"
+npm run new:module -- billing --label "Billing"
 ```
 
-## What ships in this template
+---
 
-- `_reference` + `model-condenser` modules (no domain logic)
-- File exchange, work-log dev logs (human + agent), contract manifest v001
-- CI workflow (`.github/workflows/ci.yml`), trace ID helper
-- Lint and condense tooling for trees, prompts, and schemas
+## License & attribution
 
-Built with [@pukujan/create-modular-monolith](https://github.com/Pukujan/create-modular-monolith).
+Platform files from [@pukujan/create-modular-monolith](https://github.com/Pukujan/create-modular-monolith). See [LICENSE](LICENSE) and [NOTICE](NOTICE).

package/template/backend/package.json

@@ -10,7 +10,7 @@
     "lint:layers": "node scripts/check-module-layers.mjs",
     "lint:api-docs": "node ../scripts/check-api-docs.mjs",
     "lint:architecture": "npm run lint:boundaries && npm run lint:layers && npm run lint:api-docs",
-    "test": "node --test 'src/modules/**/tests/**/*.test.js'",
+    "test": "node --test",
     "condense-models": "node ../scripts/condense-models.mjs",
     "condense-prompts": "node ../scripts/condense-prompts.mjs",
     "condense-file-structure": "node ../scripts/condense-file-structure.mjs",