@pukujan/create-modular-monolith 2.0.0 → 2.1.0

package/template/backend/src/modules/model-condenser/utils/index.js

@@ -0,0 +1 @@
+export {};

package/template/backend/src/shared/contracts/consolidatedExports.contract.js

@@ -0,0 +1,19 @@
+/** @readonly Consolidated repo snapshot exports contract. */
+
+export {
+  CONSOLIDATED_EXPORT_DIR,
+  CONSOLIDATED_FILENAMES,
+  writeConsolidatedExport
+} from "../utils/consolidatedExport.js";
+
+export const CONSOLIDATED_EXPORTS_VERSION = "v001";
+
+/** API / model-condenser mirror path. */
+export const CONSOLIDATED_MODELS_MIRROR_DIR = "models";
+
+export const CONSOLIDATED_NPM_SCRIPTS = {
+  models: "condense-models",
+  prompts: "condense-prompts",
+  fileStructure: "condense-file-structure",
+  all: "condense:all"
+};

package/template/backend/src/shared/contracts/prePushDevLog.contract.js

@@ -0,0 +1,28 @@
+/** @readonly Pre-push dev log contract (human MD + agent JSON). */
+
+export const PRE_PUSH_DEV_LOG_VERSION = "v001";
+export const DEV_LOG_AGENT_SCHEMA_VERSION = "1.0.0";
+
+export const DEV_LOG_HUMAN_DIR = "work-log/dev-logs/human";
+export const DEV_LOG_AGENT_DIR = "work-log/dev-logs/agent";
+export const DEV_LOG_AGENT_SCHEMA = "work-log/dev-logs/schemas/dev-log-agent.v1.schema.json";
+export const DEV_LOG_HUMAN_FORMAT = "scripts/lib/dev-log-human-format.mjs";
+
+export const DEV_LOG_GENERATOR_SCRIPT = "scripts/write-pre-push-dev-log.mjs";
+export const DEV_LOG_VERIFY_SCRIPT = "scripts/verify-dev-log.mjs";
+export const DEV_LOG_API_INVENTORY_SCRIPT = "scripts/lib/api-inventory.mjs";
+export const DEV_LOG_REPO_TREE_SCRIPT = "scripts/lib/repo-tree.mjs";
+
+/** Same as `tree -I "node_modules|.git|dist|build"`. */
+export const DEV_LOG_TREE_IGNORE_DIRS = ["node_modules", ".git", "dist", "build", ".DS_Store"];
+
+/** Filename patterns (paired by `{NNN}_{date}_{time}` prefix). */
+export const DEV_LOG_HUMAN_FILENAME_PATTERN =
+  "{NNN}_{YYYY-MM-DD}_{HH-MM}_dev-log_{slug}.md";
+export const DEV_LOG_AGENT_FILENAME_PATTERN =
+  "{NNN}_{YYYY-MM-DD}_{HH-MM}_dev-log-agent_{slug}.json";
+
+export const DEV_LOG_NPM_SCRIPTS = {
+  prePush: "dev-log:pre-push",
+  verify: "dev-log:verify"
+};

package/template/backend/src/shared/domain/case-filing/core-models.js

@@ -0,0 +1,117 @@
+/** @typedef {"unreviewed" | "partially_reviewed" | "reviewed" | "rejected"} ReviewStatus */
+
+/** @typedef {"ai_extracted_unreviewed" | "source_supported_auto_saved" | "conditional" | "needs_ocr_review" | "corrected_later" | "superseded" | "human_verified"} WorkflowStatus */
+
+/**
+ * @typedef {Object} CaseModel
+ * @property {string} caseId
+ * @property {string | null} county
+ * @property {string | null} court
+ * @property {string | null} indexNumber
+ * @property {string | null} caseName
+ * @property {string | null} caseType
+ * @property {string | null} judgeName
+ * @property {string | null} partName
+ * @property {string | null} currentPhase
+ * @property {string | null} currentMiniPhase
+ * @property {"high" | "medium" | "low"} confidence
+ */
+
+/**
+ * @typedef {Object} DocumentModel
+ * @property {string} documentId
+ * @property {string} caseId
+ * @property {number | null} nyscefDocNo
+ * @property {string | null} title
+ * @property {string | null} documentType
+ * @property {string | null} filedDateTime
+ * @property {string | null} filedBy
+ * @property {string} sourceFileName
+ * @property {number | null} pageCount
+ * @property {string} extractionStatus
+ * @property {ReviewStatus} textReviewStatus
+ */
+
+/**
+ * @typedef {Object} DocumentTextVersionModel
+ * @property {string} id
+ * @property {string} caseId
+ * @property {string} documentId
+ * @property {"embedded_text" | "ocr_text" | "ai_parsed_text" | "human_reviewed_text"} versionType
+ * @property {string} [textContent]
+ * @property {unknown} [structuredJson]
+ * @property {"pdf_text" | "ocr" | "llm" | "human_review"} extractionMethod
+ * @property {ReviewStatus} reviewStatus
+ * @property {"system" | "ai" | "human"} createdBy
+ * @property {string} createdAt
+ */
+
+/**
+ * @typedef {Object} RuleSourceProvenance
+ * @property {string} [sourceAuthority] cplr | uniform | county | judge | part | case_order | later_case_order
+ * @property {string} [sourceName]
+ * @property {number | null} [sourceDocNo]
+ * @property {string} [ruleSourceApplied]
+ * @property {number} [authorityRank]
+ * @property {unknown} [supersedes]
+ * @property {string} [sourceText]
+ * @property {number} [sourcePage]
+ */
+
+/**
+ * @typedef {Object} TaskModel
+ * @property {string} taskId
+ * @property {string} caseId
+ * @property {string} [documentId]
+ * @property {string} taskDescription
+ * @property {string} taskType
+ * @property {string | null} responsibleParty
+ * @property {string | null} dueDate
+ * @property {"fixed" | "calculated" | "no_fixed_due_date" | "needs_review"} dueDateStatus
+ * @property {WorkflowStatus} status
+ * @property {number} [sourcePage]
+ * @property {"high" | "medium" | "low"} confidence
+ * @property {string} [docketingNote]
+ * @property {string} [sourceAuthority]
+ * @property {string} [sourceName]
+ * @property {number | null} [sourceDocNo]
+ * @property {string} [ruleSourceApplied]
+ * @property {number} [authorityRank]
+ * @property {unknown} [supersedes]
+ * @property {string} [sourceText]
+ */
+
+/**
+ * @typedef {Object} HumanReviewItemModel
+ * @property {string} itemId
+ * @property {string} caseId
+ * @property {string} documentId
+ * @property {number} pageNumber
+ * @property {string} location
+ * @property {string} issue
+ * @property {string} reason
+ * @property {string} suggestedAction
+ * @property {string} [cropFilePath]
+ * @property {boolean} blocking
+ * @property {"pending" | "reviewed" | "resolved"} status
+ */
+
+/**
+ * @typedef {Object} CaseStateSnapshotModel
+ * @property {string} snapshotId
+ * @property {string} caseId
+ * @property {number | null} afterDocNo
+ * @property {string | null} currentPhase
+ * @property {string | null} currentMiniPhase
+ * @property {unknown[]} confirmedFacts
+ * @property {unknown[]} carriedForwardContext
+ * @property {TaskModel[]} openTasks
+ * @property {TaskModel[]} completedTasks
+ * @property {TaskModel[]} conditionalTasks
+ * @property {HumanReviewItemModel[]} unresolvedHumanReviewItems
+ * @property {unknown[]} conflicts
+ * @property {string[]} auditNotes
+ * @property {string} createdAt
+ */
+
+export {};

package/template/backend/src/shared/http/errors.js

@@ -1,3 +1,11 @@
+export class AppError extends Error {
+  constructor(message, status = 500) {
+    super(message);
+    this.name = "AppError";
+    this.status = status;
+  }
+}
+
 export function errorHandler(error, _req, res, _next) {
   const status = Number.isInteger(error?.status) ? error.status : 500;
   const message = error?.message || "Internal Server Error";

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

@@ -0,0 +1,30 @@
+import { mkdir, writeFile } from "fs/promises";
+import { join } from "path";
+
+/** Consolidated deliverables live directly under file-exchange/exports/. */
+export const CONSOLIDATED_EXPORT_DIR = "file-exchange/exports";
+
+export const CONSOLIDATED_FILENAMES = {
+  models: "consolidated-models.json",
+  prompts: "consolidated-prompts.json",
+  fileStructure: "consolidated-file-structure.json"
+};
+
+/**
+ * Write a consolidated JSON artifact to file-exchange/exports/.
+ * @param {string} repoRoot
+ * @param {string} filename
+ * @param {string} jsonText
+ * @returns {Promise<string>} absolute path written
+ */
+export async function writeConsolidatedExport(repoRoot, filename, jsonText) {
+  const dest = join(repoRoot, CONSOLIDATED_EXPORT_DIR, filename);
+  await mkdir(join(repoRoot, CONSOLIDATED_EXPORT_DIR), { recursive: true });
+  await writeFile(dest, jsonText, "utf8");
+  return dest;
+}
+
+/** @deprecated use writeConsolidatedExport */
+export async function mirrorConsolidatedExport(repoRoot, filename, jsonText) {
+  return writeConsolidatedExport(repoRoot, filename, jsonText);
+}

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

@@ -0,0 +1,47 @@
+/**
+ * UTC folder stamp for file-exchange imports/exports.
+ * Human-readable and lexicographically sortable.
+ * @param {Date} [date]
+ * @returns {string} e.g. 2026-05-23_15-59-43Z
+ */
+export function formatExchangeTimestamp(date = new Date()) {
+  const d = date instanceof Date ? date : new Date(date);
+  const iso = d.toISOString();
+  const [datePart, rest] = iso.split("T");
+  const hh = rest.slice(0, 2);
+  const mm = rest.slice(3, 5);
+  const ss = rest.slice(6, 8);
+  return `${datePart}_${hh}-${mm}-${ss}Z`;
+}
+
+/**
+ * Convert legacy compact stamps (20260523T154523Z) to human-readable form.
+ * @param {string} stamp
+ * @returns {string}
+ */
+export function normalizeExchangeStamp(stamp) {
+  const s = String(stamp || "").trim();
+  const legacy = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/;
+  const m = s.match(legacy);
+  if (m) {
+    return `${m[1]}-${m[2]}-${m[3]}_${m[4]}-${m[5]}-${m[6]}Z`;
+  }
+  return s;
+}
+
+/**
+ * Human-readable stamp for work-log filenames (date + time).
+ * @param {Date} [date]
+ * @returns {{ date: string, time: string, folder: string }}
+ */
+export function formatWorkLogTimestamp(date = new Date()) {
+  const d = date instanceof Date ? date : new Date(date);
+  const iso = d.toISOString();
+  const [datePart, timePart] = iso.slice(0, 16).split("T");
+  const time = timePart.replace(":", "-");
+  return {
+    date: datePart,
+    time,
+    folder: formatExchangeTimestamp(d)
+  };
+}

package/template/backend/src/shared/utils/formatExchangeTimestamp.test.js

@@ -0,0 +1,30 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  formatExchangeTimestamp,
+  formatWorkLogTimestamp,
+  normalizeExchangeStamp
+} from "./formatExchangeTimestamp.js";
+
+test("formatExchangeTimestamp", () => {
+  const stamp = formatExchangeTimestamp(new Date("2026-05-23T15:45:23.767Z"));
+  assert.equal(stamp, "2026-05-23_15-45-23Z");
+});
+
+test("normalizeExchangeStamp converts legacy compact stamps", () => {
+  assert.equal(
+    normalizeExchangeStamp("20260523T154523Z"),
+    "2026-05-23_15-45-23Z"
+  );
+  assert.equal(
+    normalizeExchangeStamp("2026-05-23_15-45-23Z"),
+    "2026-05-23_15-45-23Z"
+  );
+});
+
+test("formatWorkLogTimestamp", () => {
+  const t = formatWorkLogTimestamp(new Date("2026-05-23T15:45:23.767Z"));
+  assert.equal(t.date, "2026-05-23");
+  assert.equal(t.time, "15-45");
+  assert.equal(t.folder, "2026-05-23_15-45-23Z");
+});

package/template/docs/API.md

@@ -0,0 +1,42 @@
+# Backend HTTP API reference
+
+Base URL (local dev): `http://localhost:3001`
+
+Global health:
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/health` | Server up |
+
+---
+
+## Endpoint registry
+
+Maintained manually when routes change. Enforced by `npm run lint:api-docs`. See [API documentation contract](./architecture/API_DOCUMENTATION_CONTRACT.md).
+
+| Method | Path | Module | Description |
+|--------|------|--------|-------------|
+| GET | `/api/_reference/health` | Reference | Example module health |
+| GET | `/api/model-condenser/health` | Model condenser | Module health |
+| POST | `/api/model-condenser/condense` | Model condenser | Regenerate consolidated-models.json |
+| GET | `/api/model-condenser/consolidated` | Model condenser | Read consolidated schema inventory |
+
+_Add rows here when you scaffold new modules with `npm run new:module`._
+
+---
+
+## Module index
+
+| Module | Base path | API doc | Status |
+|--------|-----------|---------|--------|
+| Reference | `/api/_reference` | [_reference stub] | Example layout |
+| Model condenser | `/api/model-condenser` | [model-condenser/API.md](./model-condenser/API.md) | Active — schema inventory export |
+
+---
+
+## Conventions
+
+- **JSON** unless noted (multipart for file uploads).
+- **Errors**: `{ "error": "message" }` with 4xx/5xx status.
+- Route definitions: `backend/src/modules/{module}/routes/`.
+- **New routes:** update `docs/{module}/API.md` and this registry.

package/template/docs/PUBLISHING.md

@@ -15,9 +15,21 @@ npm create @pukujan/modular-monolith@2 my-platform
 
 On branch **`v2`**:
 
+**Architecture-only** (no domain modules — recommended for boilerplate updates):
+
+```bash
+npm run export:architecture-starter -- --to packages/create-modular-monolith/template
+```
+
+**Full repo copy** (legacy — includes all modules):
+
 ```bash
 npm run sync:cli-template
-# bump version in packages/create-modular-monolith/package.json if needed
+```
+
+Then bump version and publish:
+
+```bash
 cd packages/create-modular-monolith
 npm publish --access public
 ```

package/template/docs/README.md

@@ -4,10 +4,14 @@ This folder describes the **modular monolith platform starter** and how **archit
 
 | Document | Purpose |
 | --- | --- |
+| [**HTTP API reference**](./API.md) | All backend module endpoints (master index + endpoint registry) |
+| [API documentation contract](./architecture/API_DOCUMENTATION_CONTRACT.md) | Required when adding routes (`npm run lint:api-docs`) |
 | [Dev log: v2](./DEVLOG_V2.md) | Changes from `main`, contract rationale, benefits/cons, challenges, growth path |
+| [Work log / dev-logs](../work-log/dev-logs/) | Per-session **shipped work** — `{NNN}_{date}_{time}_dev-log_{slug}.md`; see [work-log/](../work-log/) |
 | [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 |
 | [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)

package/template/docs/STARTER_PACK.md

@@ -30,6 +30,10 @@ git clone https://github.com/Pukujan/litigation-workflow-application.git
 | `backend/scripts/check-module-layers.mjs` | Intra-module layer import rules (backend) |
 | `docs/architecture/ARCHITECTURE_GUARDRAILS.md` | Inter-module contract |
 | `docs/architecture/MODULE_INTERNAL_CONTRACT.md` | Intra-module MVC, prompts, evals, tests |
+| `docs/architecture/REPO_ARTIFACT_LAYOUT.md` | Data roots, file-exchange, golden paths |
+| `file-exchange/` | Dated imports/exports for human↔agent handoff |
+| `AGENTS.md` | **Mandatory** agent workflow (import stamp before `process-batch`) |
+| `work-log/` | Handoffs, study-docs, dev-logs |
 | `backend/src/modules/_reference/` | Example layout (skipped by loaders) |
 
 Guardrails are **documented** and **automated** where practical. See [Architecture guardrails](./architecture/ARCHITECTURE_GUARDRAILS.md) and [Module internal contract](./architecture/MODULE_INTERNAL_CONTRACT.md).

package/template/docs/architecture/API_DOCUMENTATION_CONTRACT.md

@@ -0,0 +1,112 @@
+# API documentation contract
+
+Every **new or changed** HTTP route in `backend/src/modules/*/routes/` must be reflected in markdown **before** the work is considered done (same PR / same change set).
+
+This is enforced by `npm run lint:api-docs` (also part of `npm run lint:architecture`).
+
+---
+
+## Two places to update
+
+| # | File | What to add |
+|---|------|-------------|
+| 1 | `docs/<module-name>/API.md` | Per-module reference: method, path, description, request/response notes |
+| 2 | `docs/API.md` → **Endpoint registry** | One row per route: full path + short description |
+
+Module folder name = docs folder name (e.g. `case-filing-ai` → `docs/case-filing-ai/API.md`).
+
+Base path comes from `app.use("/api/...", router)` in the module’s `index.js`.
+
+---
+
+## 1. Module API (`docs/<module>/API.md`)
+
+### Required for every route
+
+1. **Endpoint quick reference** table (top of file, after the header block):
+
+```markdown
+## Endpoint quick reference
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Module health and config summary |
+| POST | `/process-batch` | Upload filings and run the master prompt pipeline |
+```
+
+2. **Detailed section** (recommended): `### \`METHOD /path\`` with body fields, response shape, examples.
+
+### Rules
+
+- **Path** column uses the route path **relative to the module base** (starts with `/`), matching Express exactly (including `:param` segments).
+- **Description** is one short sentence: what it does, not how it is implemented.
+- **Method** is uppercase (`GET`, `POST`, …).
+- Do **not** remove old rows when deprecating — mark deprecated routes in the description until removed from code.
+
+### New module
+
+`npm run new:module <name>` scaffolds `docs/<name>/API.md` with a health row. Append rows when you add routes.
+
+---
+
+## 2. Consolidated registry (`docs/API.md`)
+
+Under `## Endpoint registry`, append one row per route:
+
+```markdown
+| POST | `/api/case-filing-ai/process-batch` | Case Filing AI | Upload filings and run master prompt |
+```
+
+| Column | Content |
+|--------|---------|
+| Method | HTTP verb |
+| Path | Full path including `/api/<module-id>` |
+| Module | Human label (match module index table) |
+| Description | Same intent as module doc (can be slightly shorter) |
+
+Keep rows **sorted by module**, then method, then path.
+
+The **Module index** table (above the registry) must list every loaded module; stub modules stay “Health only” until domain routes ship.
+
+---
+
+## 3. Optional but encouraged
+
+| Artifact | When |
+|----------|------|
+| `frontend/src/modules/<module>/api/*.js` | Wrapper for UI callers |
+| Integration test under `tests/integration/` | Exercises the route |
+| `backend/.env.example` | New env vars |
+
+---
+
+## 4. Checklist (copy when adding a route)
+
+```text
+[ ] Route in backend/src/modules/<module>/routes/
+[ ] Row in docs/<module>/API.md (quick reference + detail section)
+[ ] Row in docs/API.md → Endpoint registry
+[ ] npm run lint:api-docs passes
+```
+
+---
+
+## 5. Enforcement
+
+```bash
+npm run lint:api-docs          # repo root or backend/
+npm run lint:architecture      # includes api-docs
+```
+
+The linter compares Express `router.get/post/...` registrations to:
+
+- Path (+ method) in `docs/<module>/API.md`
+- Full path (+ method) in `docs/API.md` endpoint registry
+
+---
+
+## Related
+
+- [Master API index](../API.md)
+- [Module internal contract](./MODULE_INTERNAL_CONTRACT.md)
+- [Architecture guardrails](./ARCHITECTURE_GUARDRAILS.md)

package/template/docs/architecture/CONTRACTS_OVERVIEW.md

@@ -0,0 +1,168 @@
+# Architecture contracts — how it works
+
+**One-page map** of repo contracts: what they are, how they connect, and how they are enforced.
+
+| Quick links | |
+|-------------|---|
+| **Index (machine)** | [contracts/manifest.json](./contracts/manifest.json) |
+| **History** | [contracts/changelog.jsonl](./contracts/changelog.jsonl) |
+| **Paths on disk** | [REPO_ARTIFACT_LAYOUT.md](./REPO_ARTIFACT_LAYOUT.md) |
+| **Lint** | `npm run lint:contracts` · `npm run lint:repo-artifacts` |
+
+---
+
+## What “contract” means here
+
+A **contract** is a versioned agreement about paths, filenames, API shapes, or pipeline metadata. It can be:
+
+| Form | Example |
+|------|---------|
+| **Markdown spec** | `docs/architecture/contracts/prePushDevLog.contract.md` |
+| **JS constants** | `backend/src/modules/case-filing-ai/contracts/pipelineVersions.js` |
+| **Registry doc** | `docs/API.md` endpoint table |
+
+Contracts are **not** runtime filing data. They tell humans and agents where artifacts live and which versions are current.
+
+---
+
+## The contract pipeline (repo level)
+
+```mermaid
+flowchart TB
+  subgraph define [Define]
+    manifest[manifest.json]
+    md[contracts/*.contract.md]
+    js[*.contract.js in backend]
+  end
+
+  subgraph use [Use at runtime / workflow]
+    batch[Batch pipeline writes pipelineVersions]
+    exchange[file-exchange imports/exports]
+    devlog[pre-push dev logs]
+    condense[condense:all snapshots]
+  end
+
+  subgraph enforce [Enforce]
+    lintC[lint:contracts]
+    lintR[lint:repo-artifacts]
+    lintApi[lint:api-docs]
+  end
+
+  manifest --> md
+  manifest --> js
+  md --> exchange
+  md --> devlog
+  md --> condense
+  js --> batch
+  manifest --> lintC
+  manifest --> lintR
+  md --> lintApi
+```
+
+### 1. Register — `manifest.json`
+
+Every contract has an entry with:
+
+- `version` (e.g. `v001`)
+- `doc` — human-readable spec (required for new contracts)
+- `file` / `utility` / `schema` / scripts — paths lint must verify exist
+
+**Source of truth for “what contracts exist”:** [contracts/manifest.json](./contracts/manifest.json)
+
+### 2. Document — `contracts/*.contract.md`
+
+Each entry’s `doc` explains purpose, paths, commands, and related contracts.
+
+### 3. Implement — `*.contract.js` (where needed)
+
+Code exports version strings and path constants so services and scripts share one definition:
+
+| File | Exports |
+|------|---------|
+| `pipelineVersions.js` | `buildPipelineVersions()` on batch outputs |
+| `storageLayout.contract.js` | `BATCH_LAYOUT_VERSION`, folder names |
+| `parsedDocumentArtifacts.contract.js` | Parsed cache filenames |
+| `prePushDevLog.contract.js` | Dev-log paths, tree ignores, npm scripts |
+| `consolidatedExports.contract.js` | `file-exchange/exports/consolidated-*.json` |
+
+### 4. Record changes — `changelog.jsonl`
+
+One JSON line per bump: `contract`, `from`, `to`, `reason`, `time`.
+
+### 5. Enforce — npm lint scripts
+
+| Command | Checks |
+|---------|--------|
+| `npm run lint:contracts` | Every path listed in `manifest.json` exists |
+| `npm run lint:repo-artifacts` | Key folders + contract docs + golden stub paths |
+| `npm run lint:api-docs` | Routes in code ⊆ `docs/API.md` registry |
+
+---
+
+## Contract catalog (current)
+
+| ID | Version | What it governs |
+|----|---------|-----------------|
+| **repoArtifactLayout** | v001 | All canonical roots (`data/`, `evals/`, `file-exchange/`, `work-log/`) |
+| **fileExchange** | v001 | `imports/{stamp}/`, `exports/{stamp}/`, human-readable UTC stamps |
+| **consolidatedExports** | v001 | `exports/consolidated-*.json` + `models/` mirror, `condense:all` |
+| **prePushDevLog** | v001 | Paired `human/*.md` + `agent/*.json`, tree/API/test audits |
+| **apiDocumentationRegistry** | v001 | `docs/API.md`, active/stub/deprecated routes |
+| **caseFilingStorageLayout** | v001 | `batches/batch-NNN/` folder layout |
+| **parsedDocumentArtifacts** | v001 | `parsed-documents/doc-NNN/` file names |
+| **pipelineVersions** | v001 | Version blob on batch outputs (prompt, parser, golden, …) |
+| **ruleAuthority** | v001 | Court rule authority ranks |
+
+Per-contract detail: follow the `doc` link in [manifest.json](./contracts/manifest.json).
+
+---
+
+## Case-filing **processing** pipeline (runtime)
+
+This is separate from the **contract** pipeline above but uses contract versions:
+
+```mermaid
+flowchart LR
+  import[file-exchange import] --> upload[POST process-batch]
+  upload --> parse[Parsed doc cache v001]
+  parse --> llm[Master prompt v1 / v001]
+  llm --> out[outputs + case-snapshot]
+  out --> eval[Golden evals]
+  eval --> export[exports/ or eval-bundles]
+```
+
+Version defaults come from `pipelineVersions.js` + env `MASTER_PROMPT_VERSION`.  
+Batch folders follow `storageLayout.contract.js`.  
+HTTP entrypoint: `POST /api/case-filing-ai/process-batch` ([API.md](../API.md)).
+
+---
+
+## Human ↔ agent workflows (contract-driven)
+
+| When | Command | Contract |
+|------|---------|----------|
+| Inbound files | `npm run import:file-exchange` | fileExchange |
+| Before push | `npm run dev-log:pre-push` | prePushDevLog |
+| Snapshot handoff | `npm run condense:all` | consolidatedExports |
+| Golden refresh | `npm run ingest:golden-*` | fileExchange + pipelineVersions |
+
+---
+
+## Related architecture docs (not in manifest)
+
+| Doc | Scope |
+|-----|--------|
+| [ARCHITECTURE_GUARDRAILS.md](./ARCHITECTURE_GUARDRAILS.md) | Module boundaries, loader, lint:boundaries |
+| [MODULE_INTERNAL_CONTRACT.md](./MODULE_INTERNAL_CONTRACT.md) | Inside one module (routes, services, prompts) |
+| [API_DOCUMENTATION_CONTRACT.md](./API_DOCUMENTATION_CONTRACT.md) | How to maintain `docs/API.md` |
+
+---
+
+## Adding a new contract
+
+1. Add `docs/architecture/contracts/<name>.contract.md`
+2. Add JS constants under `backend/.../contracts/` if code needs them
+3. Add entry to [manifest.json](./contracts/manifest.json) with all paths
+4. Append line to [changelog.jsonl](./contracts/changelog.jsonl)
+5. Update [REPO_ARTIFACT_LAYOUT.md](./REPO_ARTIFACT_LAYOUT.md) if new roots
+6. Run `npm run lint:contracts` and `npm run lint:repo-artifacts`

package/template/docs/architecture/MODULE_INTERNAL_CONTRACT.md

@@ -44,6 +44,8 @@ Every feature module lives at `backend/src/modules/<module-name>/` and **must**
 | --- | --- | --- |
 | **index** | `register(app, context)` — mount routes, register listeners | Any layer in **this** module, `src/shared/*`, npm |
 | **routes** | HTTP mapping, status codes, call services | `services`, `schemas`, `shared`, npm |
+
+**HTTP API docs:** Every route must be listed in `docs/<module-name>/API.md` and `docs/API.md` (endpoint registry). See [API documentation contract](./API_DOCUMENTATION_CONTRACT.md). Enforced via `npm run lint:api-docs`.
 | **services** | Business logic, transactions, AI orchestration | `domain`, `repositories`, `adapters`, `prompts`, `schemas`, `events`, `utils`, `config`, `shared`, npm |
 | **repositories** | DB/files/API persistence | `domain`, `adapters`, `schemas`, `utils`, `shared`, npm |
 | **adapters** | Third-party APIs, SDK wrappers | `domain`, `schemas`, `utils`, `shared`, npm |