@pukujan/create-modular-monolith 2.1.0 → 2.2.1

package/template/backend/scripts/check-module-boundaries.mjs

@@ -22,6 +22,9 @@ for (const app of apps) {
     .map((d) => d.name);
 
   for (const moduleName of moduleNames) {
+    // model-condenser embeds repo path strings in schema inventory metadata only (no imports).
+    if (moduleName === "model-condenser") continue;
+
     const moduleRoot = join(modulesDir, moduleName);
     const files = walk(moduleRoot).filter((f) =>
       [".js", ".mjs", ".jsx"].some((ext) => f.endsWith(ext))

package/template/backend/src/modules/model-condenser/tests/unit/modelCondenser.service.test.js

@@ -18,8 +18,8 @@ test("condenseModels writes consolidated-models.json", async () => {
     });
 
     assert.equal(result.status, "condensed");
-    assert.ok(result.modelCount >= 16);
-    assert.ok(result.exampleInstanceCount >= 4);
+    assert.ok(result.modelCount >= 8);
+    assert.ok(result.exampleInstanceCount >= 2);
 
     const raw = await readFile(join(modelsDir, "consolidated-models.json"), "utf8");
     const parsed = JSON.parse(raw);

package/template/backend/src/shared/utils/traceId.js

@@ -0,0 +1,19 @@
+import { randomUUID } from "crypto";
+
+/**
+ * @param {string} [prefix]
+ * @returns {string}
+ */
+export function createTraceId(prefix = "trace") {
+  const short = randomUUID().replace(/-/g, "").slice(0, 12);
+  return `${prefix}_${short}`;
+}
+
+/**
+ * @param {string} batchTraceId
+ * @param {number} docIndex
+ * @returns {string}
+ */
+export function docTraceId(batchTraceId, docIndex) {
+  return `${batchTraceId}_doc${String(docIndex).padStart(3, "0")}`;
+}

package/template/docs/README.md

@@ -11,7 +11,9 @@ This folder describes the **modular monolith platform starter** and how **archit
 | [Starter pack](./STARTER_PACK.md) | What ships in the repo, how to run it, and how to add modules |
 | [Architecture guardrails](./architecture/ARCHITECTURE_GUARDRAILS.md) | Module contracts, boundaries, naming, and how enforcement works |
 | [Module internal contract](./architecture/MODULE_INTERNAL_CONTRACT.md) | MVC layers, prompts, evals, tests inside each feature module |
+| [Evals, regression, and CI gates](./architecture/EVAL_AND_CI.md) | `test:ci`, GitHub Actions, optional per-case golden |
+| [Evals, regression, and CI gates](./architecture/EVAL_AND_CI.md) | Golden evals, `test:evals`, GitHub Actions gates |
 | [Publishing the CLI](./PUBLISHING.md) | Release `@pukujan/create-modular-monolith` to npm |
 | [Case Filing AI starter](./case-filing-ai/README.md) | Domain blueprint, module split, pipeline, guardrails, and DB schema |
 
-Canonical repository: [https://github.com/Pukujan/litigation-workflow-application](https://github.com/Pukujan/litigation-workflow-application)
+Canonical repository: [https://github.com/Pukujan/litigation-prompt-engineering](https://github.com/Pukujan/litigation-prompt-engineering)

package/template/docs/architecture/CONTRACTS_OVERVIEW.md

@@ -158,6 +158,18 @@ HTTP entrypoint: `POST /api/case-filing-ai/process-batch` ([API.md](../API.md)).
 
 ---
 
+## Exporting architecture to the npm starter
+
+To refresh the **boilerplate CLI template** without domain modules:
+
+```bash
+npm run export:architecture-starter -- --to packages/create-modular-monolith/template
+```
+
+Output defaults to `export/architecture-starter/`. See `EXPORT_MANIFEST.json` and [PUBLISHING.md](../PUBLISHING.md).
+
+---
+
 ## Adding a new contract
 
 1. Add `docs/architecture/contracts/<name>.contract.md`

package/template/docs/architecture/EVAL_AND_CI.md

@@ -0,0 +1,79 @@
+# Evals, regression, and CI gates
+
+Plain-language guide for **domain-agnostic** projects scaffolded from this template.
+
+---
+
+## What is a “gate”?
+
+A **gate** is an automatic check that must pass before code is merged.
+
+| Gate | What it blocks |
+|------|----------------|
+| `npm run lint:contracts` | Broken contract paths in `manifest.json` |
+| `npm run lint:repo-artifacts` | Missing platform folders (file-exchange, dev-logs, …) |
+| `npm run lint:architecture` | Module boundary / layer / API doc violations |
+| `npm test` | Unit/integration failures |
+| `npm run test:evals` | Module `evals/runners/*.eval.mjs` failures |
+
+GitHub Actions runs these on push/PR (see `.github/workflows/ci.yml`). Locally: **`npm run test:ci`**.
+
+---
+
+## What is “eval / regression”?
+
+**Eval** = automated check that output meets expectations.
+
+**Regression** = re-run evals after a change to catch quality going **down**.
+
+### Golden data is per domain case — not universal
+
+Every product case is different (different users, documents, rules). You **do not** ship one golden dataset for all future cases.
+
+| Pattern | When to use |
+|---------|-------------|
+| **Module example evals** | Shipped in `_reference` — smoke tests, no API keys |
+| **Optional `evals/golden/{caseId}/`** | When **you** curate expected JSON for one fixed regression case |
+| **Live runs only** | New cases with no golden yet — process, review, optionally add golden later |
+
+Golden answers the question: *“On **this** known fixture, did we get worse than last time?”*  
+Not: *“We already know the truth for every new case.”*
+
+When you add a domain module (`npm run new:module`), add `evals/runners/` and optional `evals/golden/` for cases you control.
+
+---
+
+## Trace IDs (observability)
+
+Use `backend/src/shared/utils/traceId.js` in long-running workflows:
+
+```js
+import { createTraceId, docTraceId } from "../shared/utils/traceId.js";
+
+const batchTraceId = createTraceId("batch_my-job");
+const traceId = docTraceId(batchTraceId, 1);
+```
+
+Log both IDs in JSONL or structured logs so agents and humans can correlate steps. Plug the same IDs into Langfuse/OpenTelemetry later if needed.
+
+---
+
+## CI workflow
+
+`.github/workflows/ci.yml`:
+
+1. Install backend + frontend  
+2. `lint:contracts` · `lint:repo-artifacts` · `lint:architecture`  
+3. `npm test` · `npm run test:evals`
+
+---
+
+## Adding domain evals
+
+```bash
+npm run new:module -- billing --label "Billing"
+# Add backend/src/modules/billing/evals/runners/my-check.eval.mjs
+npm run test:evals -- billing
+```
+
+See [MODULE_INTERNAL_CONTRACT.md](./MODULE_INTERNAL_CONTRACT.md) for colocated `prompts/` and `evals/`.

package/template/docs/architecture/REPO_ARTIFACT_LAYOUT.md

@@ -1,40 +1,17 @@
 # Repository artifact layout
 
-Canonical paths for runtime data, golden fixtures, and human↔agent exchange.
+Canonical paths for platform artifacts and human↔agent exchange.
 
 ## Roots
 
-| Root | Env override | Writable at runtime |
-|------|----------------|---------------------|
-| `data/case-filing-ai/batches/` | `CASE_FILING_BATCH_DIR` | Yes (pipeline) |
-| `evals/golden/{caseId}/` | `GOLDEN_DATASET_DIR` | No (fixtures) |
-| `data/court-rules/fixtures/` | — | No |
-| `eval-bundles/` | `EVAL_BUNDLE_ROOT_DIR` | Yes (export API) |
-| `case-exports/` | `CASE_EXPORT_ROOT_DIR` | Yes (export API) |
-| `file-exchange/imports\|exports/` | — | Yes (human triage) |
-| `work-log/dev-logs/human\|agent/` | — | Yes (pre-push audit) |
-| `models/consolidated-*.json` | — | Yes (condenser mirror) |
-| `work-log/` | — | Yes (docs only) |
-
-## Batch folder (`batches/batch-NNN/`)
-
-```text
-uploads/
-parsed-documents/doc-NNN/    # v2+ parsed cache
-outputs/doc-NNN.json
-evals/doc_NNN.eval-report.json
-rule/
-case-snapshot.json
-processing-log.jsonl
-```
-
-## Golden (`evals/golden/case_001/`)
-
-```text
-case_001.golden-dataset.json
-doc_NNN.expected.json
-parsed/doc-NNN/              # optional parse golden (v2)
-```
+| Root | Writable at runtime | Purpose |
+|------|---------------------|---------|
+| `file-exchange/imports\|exports/` | Yes | Dated human↔agent handoff |
+| `work-log/dev-logs/human\|agent/` | Yes | Pre-push audit pairs |
+| `models/consolidated-*.json` | Yes | Mirror of `file-exchange/exports/consolidated-*.json` |
+| `work-log/handoffs/` | Yes | Session handoffs (markdown) |
+| `data/` | Yes | **Your** domain runtime data (gitignore by default) |
+| `evals/golden/{caseId}/` | Optional | Per-case regression fixtures when you add them |
 
 ## File exchange
 
@@ -42,7 +19,7 @@ Imports: `file-exchange/imports/{2026-05-23_15-59-43Z}/`
 Session exports: `file-exchange/exports/{stamp}/`  
 Consolidated snapshots: `file-exchange/exports/consolidated-*.json`
 
-See [file-exchange/README.md](../../file-exchange/README.md) and [contracts/fileExchange.contract.md](./contracts/fileExchange.contract.md).
+See [file-exchange/README.md](../../file-exchange/README.md).
 
 ## Pre-push dev logs
 
@@ -51,26 +28,6 @@ work-log/dev-logs/human/{NNN}_{date}_{time}_dev-log_{slug}.md
 work-log/dev-logs/agent/{NNN}_{date}_{time}_dev-log-agent_{slug}.json
 ```
 
-`npm run dev-log:pre-push` — see [contracts/prePushDevLog.contract.md](./contracts/prePushDevLog.contract.md).
-
-## Consolidated exports
-
-`npm run condense:all` → [contracts/consolidatedExports.contract.md](./contracts/consolidatedExports.contract.md).
-
-## Contracts
-
-**Overview (start here):** [CONTRACTS_OVERVIEW.md](./CONTRACTS_OVERVIEW.md)  
-Manifest: [contracts/manifest.json](./contracts/manifest.json) · Changelog: [contracts/changelog.jsonl](./contracts/changelog.jsonl)
-
-| Contract | Doc |
-|----------|-----|
-| File exchange | [fileExchange.contract.md](./contracts/fileExchange.contract.md) |
-| Consolidated exports | [consolidatedExports.contract.md](./contracts/consolidatedExports.contract.md) |
-| Pre-push dev log | [prePushDevLog.contract.md](./contracts/prePushDevLog.contract.md) |
-| API registry | [apiDocumentationRegistry.contract.md](./contracts/apiDocumentationRegistry.contract.md) |
-| Case filing storage | `backend/src/modules/case-filing-ai/contracts/storageLayout.contract.js` |
-| Parsed artifacts | `parsedDocumentArtifacts.contract.js` |
-| Pipeline versions | `pipelineVersions.js` |
-| Rule authority | `court-rules/contracts/ruleAuthority.contract.js` |
+## Domain modules
 
-Human storage doc: [docs/case-filing-ai/STORAGE.md](../case-filing-ai/STORAGE.md)
+When you add features with `npm run new:module`, colocate runtime data under `data/<module>/` and optional `evals/golden/` per [EVAL_AND_CI.md](./EVAL_AND_CI.md).

package/template/docs/architecture/contracts/manifest.json

@@ -35,22 +35,5 @@
     "registry": "docs/API.md",
     "lintScript": "scripts/check-api-docs.mjs",
     "architectureDoc": "docs/architecture/API_DOCUMENTATION_CONTRACT.md"
-  },
-  "caseFilingStorageLayout": {
-    "version": "v001",
-    "file": "backend/src/modules/case-filing-ai/contracts/storageLayout.contract.js"
-  },
-  "parsedDocumentArtifacts": {
-    "version": "v001",
-    "file": "backend/src/modules/case-filing-ai/contracts/parsedDocumentArtifacts.contract.js"
-  },
-  "pipelineVersions": {
-    "version": "v001",
-    "file": "backend/src/modules/case-filing-ai/contracts/pipelineVersions.js",
-    "promptVersions": "backend/src/modules/case-filing-ai/prompts/promptVersions.js"
-  },
-  "ruleAuthority": {
-    "version": "v001",
-    "file": "backend/src/modules/court-rules/contracts/ruleAuthority.contract.js"
   }
 }

package/template/file-exchange/README.md

@@ -32,7 +32,7 @@ npm run condense:all
 ## Workflow
 
 1. Triage loose files into `imports/{stamp}/` (`npm run import:file-exchange -- <path>`).
-2. Process via case-filing APIs using files **under that stamp** only.
+2. Process via your domain module APIs using files **under that stamp** only.
 3. Copy batch bundles / reports to `exports/{stamp}/` when done.
 4. Refresh consolidated snapshots: `npm run condense:all`.