@pukujan/create-modular-monolith 2.0.0 → 2.2.0

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

package/template/docs/architecture/PLATFORM_ARCHITECTURE.md

@@ -0,0 +1,221 @@
+# Platform architecture — built for agents and engineering at scale
+
+This starter is designed so **Cursor agents, CI, and humans** share the same map of the repository. Business features are added as modules; the **platform layer** stays stable.
+
+---
+
+## Design goals
+
+| Goal | Mechanism |
+|------|-----------|
+| **Agents know where files go** | `REPO_ARTIFACT_LAYOUT.md`, `file-exchange/`, contract manifest |
+| **Agents know what changed** | Pre-push dev log: Part I summary (mermaid, tables) + Part II detail + full tree |
+| **Agents know which APIs exist** | `docs/API.md` registry + `api-inventory` in every dev log |
+| **No silent drift** | `lint:contracts`, `lint:api-docs`, `lint:repo-artifacts` |
+| **Handoff without chaos** | Dated `file-exchange/imports/{stamp}/` — never process from `Downloads/` |
+| **Onboarding in one read** | `condense:all` → consolidated models, prompts, file tree in `exports/` |
+
+---
+
+## System map
+
+```mermaid
+flowchart TB
+  subgraph human [Human workflow]
+    import[npm run import:file-exchange]
+    code[Implement in modules]
+    devlog[npm run dev-log:pre-push]
+    push[git push]
+  end
+
+  subgraph artifacts [Canonical artifacts]
+    fx[file-exchange/]
+    wl[work-log/dev-logs/]
+    docs[docs/architecture/contracts/]
+    api[docs/API.md]
+  end
+
+  subgraph agent [Agent reads first]
+    agentJson[work-log/dev-logs/agent/*.json]
+    consolidated[file-exchange/exports/consolidated-*.json]
+  end
+
+  import --> fx
+  code --> api
+  devlog --> wl
+  devlog --> agentJson
+  condense[npm run condense:all] --> consolidated
+  agentJson --> code
+  consolidated --> code
+  push --> devlog
+```
+
+---
+
+## Modular monolith core
+
+```text
+backend/src/core/          module-loader → register(app)
+backend/src/modules/*      one feature = one folder
+frontend/src/core/         App shell + moduleRegistry
+frontend/src/modules/*     one route module per feature
+```
+
+**Rules** (enforced by `lint:boundaries`, `lint:layers`):
+
+- Modules import `shared/`, not other modules.
+- Backend: routes → services → repositories/domain.
+- Every new route appears in `docs/API.md`.
+
+Scaffold: `npm run new:module -- my-feature --label "My Feature"`
+
+---
+
+## Contract pipeline
+
+See [CONTRACTS_OVERVIEW.md](./CONTRACTS_OVERVIEW.md).
+
+1. **Register** in `contracts/manifest.json`
+2. **Document** in `contracts/*.contract.md`
+3. **Implement** in `*.contract.js` when code needs constants
+4. **Changelog** in `contracts/changelog.jsonl`
+5. **Lint** with `npm run lint:contracts`
+
+Contracts version independently (e.g. `fileExchange` v001, `prePushDevLog` v001).
+
+---
+
+## File exchange (agent inbox)
+
+```text
+file-exchange/imports/2026-05-23_15-59-43Z/    ← inbound only
+file-exchange/exports/2026-05-23_16-00-00Z/    ← session outputs
+file-exchange/exports/consolidated-*.json      ← repo snapshots
+```
+
+Stamp format: `YYYY-MM-DD_HH-MM-SSZ` via `formatExchangeTimestamp()`.
+
+**Cursor rule** (`.cursor/rules/file-exchange-inbox.mdc`, `alwaysApply: true`) makes import mandatory before processing user files.
+
+---
+
+## Pre-push dev log (audit trail)
+
+**Before every push:**
+
+```bash
+npm run dev-log:pre-push -- --slug <kebab-topic>
+```
+
+| File | Audience | Contents |
+|------|----------|----------|
+| `human/*_dev-log_*.md` | Humans | Part I: TOC, mermaid, API/version/test/git tables, condensed tree. Part II: decisions, iterations, full tree |
+| `agent/*_dev-log-agent_*.json` | Agents | Same facts in structured JSON — read this first when resuming |
+
+Tree capture ignores: `node_modules`, `.git`, `dist`, `build` (equivalent to `tree -I "node_modules|.git|dist|build"`).
+
+Works **without git** until `git init`; then git sections auto-fill.
+
+---
+
+## Consolidated exports (repository X-ray)
+
+```bash
+npm run condense:all
+```
+
+| Output | Purpose |
+|--------|---------|
+| `consolidated-models.json` | Schema inventory (model-condenser) |
+| `consolidated-prompts.json` | All prompt templates + manifests |
+| `consolidated-file-structure.json` | Full file tree + stats |
+
+Primary handoff path: `file-exchange/exports/`. Mirror: `models/` for API compatibility.
+
+---
+
+## Automation scripts reference
+
+### Governance (run in CI)
+
+| Command | Script |
+|---------|--------|
+| `npm run lint:contracts` | `scripts/lint-contracts.mjs` |
+| `npm run lint:repo-artifacts` | `scripts/lint-repo-artifacts.mjs` |
+| `npm run lint:api-docs` | `scripts/check-api-docs.mjs` |
+| `npm run lint:architecture` | boundaries + layers + api-docs |
+
+### Agent / session workflow
+
+| Command | Script |
+|---------|--------|
+| `npm run import:file-exchange` | `scripts/import-to-file-exchange.mjs` |
+| `npm run dev-log:pre-push` | `scripts/write-pre-push-dev-log.mjs` |
+| `npm run dev-log:verify` | `scripts/verify-dev-log.mjs` |
+| `npm run condense:all` | condense-prompts + file-structure + condense-models |
+
+### Scaffolding
+
+| Command | Script |
+|---------|--------|
+| `npm run new:module` | `scripts/new-module.mjs` |
+
+---
+
+## Scaling to many modules
+
+```mermaid
+flowchart LR
+  m1[module-a]
+  m2[module-b]
+  m3[module-n]
+  core[core + shared]
+  contracts[contracts/manifest]
+  m1 --> core
+  m2 --> core
+  m3 --> core
+  contracts --> m1
+  contracts --> m2
+  contracts --> m3
+```
+
+Adding a module does **not** change the platform contracts. You:
+
+1. Run `new:module`
+2. Add rows to `docs/API.md`
+3. Register prompts in `prompts/manifest.json`
+4. Run `dev-log:pre-push` before push
+
+The condenser and dev-log scripts scan the **whole repo** — new modules appear automatically in the next tree and API inventory.
+
+---
+
+## Cursor integration
+
+| File | Role |
+|------|------|
+| `AGENTS.md` | Mandatory workflows for agents |
+| `.cursor/commands/pre-push-dev-log.md` | How to fill dev logs |
+| `.cursor/commands/planning-study-log.md` | Planning-only study logs |
+| `.cursor/rules/file-exchange-inbox.mdc` | alwaysApply import discipline |
+| `.cursor/rules/api-documentation.mdc` | Keep API docs in sync |
+
+---
+
+## What to read first (agents)
+
+1. `work-log/dev-logs/agent/` — latest `*_dev-log-agent_*.json`
+2. `file-exchange/exports/consolidated-file-structure.json` — layout
+3. `docs/architecture/CONTRACTS_OVERVIEW.md` — contract index
+4. `docs/API.md` — HTTP surface
+5. `AGENTS.md` — required commands
+
+---
+
+## Related docs
+
+- [CONTRACTS_OVERVIEW.md](./CONTRACTS_OVERVIEW.md)
+- [REPO_ARTIFACT_LAYOUT.md](./REPO_ARTIFACT_LAYOUT.md)
+- [ARCHITECTURE_GUARDRAILS.md](./ARCHITECTURE_GUARDRAILS.md)
+- [MODULE_INTERNAL_CONTRACT.md](./MODULE_INTERNAL_CONTRACT.md)
+- [../STARTER_PACK.md](../STARTER_PACK.md)

package/template/docs/architecture/REPO_ARTIFACT_LAYOUT.md

@@ -0,0 +1,33 @@
+# Repository artifact layout
+
+Canonical paths for platform artifacts and human↔agent exchange.
+
+## Roots
+
+| 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
+
+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).
+
+## Pre-push dev logs
+
+```text
+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
+```
+
+## Domain modules
+
+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/apiDocumentationRegistry.contract.md

@@ -0,0 +1,40 @@
+# Contract: API documentation registry
+
+**Version:** `v001`  
+**Registry:** [docs/API.md](../../API.md)  
+**Lint:** `npm run lint:api-docs` (`scripts/check-api-docs.mjs`)  
+**Dev-log inventory:** `scripts/lib/api-inventory.mjs`
+
+## Purpose
+
+Single **endpoint registry** for all mounted Express routes. Pre-push dev logs and agents read this for active / stub / deprecated HTTP surfaces.
+
+## Registry sections (docs/API.md)
+
+| Section | Use |
+|---------|-----|
+| **Endpoint registry** | Method, full path, module, description |
+| **Module index** | Active vs stub modules |
+
+## Route classification (dev-log / agents)
+
+| Class | Rule |
+|-------|------|
+| **active** | Documented route, not stub/deprecated in description |
+| **stub** | Description contains `stub` or `health only` |
+| **deprecated** | Description contains `deprecated` |
+
+Do not remove deprecated rows from the registry until the route is removed from code ([API_DOCUMENTATION_CONTRACT.md](../API_DOCUMENTATION_CONTRACT.md)).
+
+## Versioned surfaces (not HTTP)
+
+Captured in dev-log `apis.versioned` from:
+
+- `backend/src/modules/case-filing-ai/contracts/pipelineVersions.js`
+- `backend/src/modules/case-filing-ai/prompts/promptVersions.js`
+- `MASTER_PROMPT_VERSION` env (`v1` \| `compact` \| `v2` \| `v001`)
+
+## Related
+
+- [API_DOCUMENTATION_CONTRACT.md](../API_DOCUMENTATION_CONTRACT.md)
+- [prePushDevLog.contract.md](./prePushDevLog.contract.md)

package/template/docs/architecture/contracts/changelog.jsonl

@@ -0,0 +1,12 @@
+{"time":"2026-05-23T15:45:00Z","contract":"repoArtifactLayout","from":null,"to":"v001","reason":"Initial REPO_ARTIFACT_LAYOUT and file-exchange","author":"agent"}
+{"time":"2026-05-23T15:45:00Z","contract":"fileExchange","from":null,"to":"v001","reason":"file-exchange/ imports and exports dated folders","author":"agent"}
+{"time":"2026-05-23T15:46:00Z","contract":"caseFilingStorageLayout","from":null,"to":"v001","reason":"storageLayout.contract.js and storagePaths.js","author":"agent"}
+{"time":"2026-05-23T15:46:00Z","contract":"parsedDocumentArtifacts","from":null,"to":"v001","reason":"parsed-documents artifact names and audit events","author":"agent"}
+{"time":"2026-05-23T17:00:00Z","contract":"pipelineVersions","from":"case_001-v0-wiped","to":"case_001-v1-parsed-synthetic","reason":"Ingested synthetic golden parsed baseline (14 docs)","author":"agent"}
+{"time":"2026-05-23T17:00:00Z","contract":"ruleAuthority","from":null,"to":"v001","reason":"Court rules services and authority rank enum","author":"agent"}
+{"time":"2026-05-23T18:00:00Z","contract":"pipelineVersions","from":"case_001-v1-parsed-synthetic","to":"case_001-v2-full-expected","reason":"Ingested full doc/snapshot golden from bundle ground_truth.json","author":"agent"}
+{"time":"2026-05-23T19:00:00Z","contract":"fileExchange","from":"v001","to":"v001","reason":"AGENTS.md + alwaysApply file-exchange-inbox rule; import:file-exchange script","author":"agent"}
+{"time":"2026-05-23T20:00:00Z","contract":"consolidatedExports","from":null,"to":"v001","reason":"file-exchange/exports consolidated-*.json + models/ mirror; condense:all","author":"agent"}
+{"time":"2026-05-23T20:00:00Z","contract":"prePushDevLog","from":null,"to":"v001","reason":"Paired human MD + agent JSON pre-push logs; API/tree/test audits","author":"agent"}
+{"time":"2026-05-23T20:00:00Z","contract":"apiDocumentationRegistry","from":null,"to":"v001","reason":"docs/API.md registry contract for dev-log api inventory","author":"agent"}
+{"time":"2026-05-23T20:01:00Z","contract":"fileExchange","from":"v001","to":"v001","reason":"Human-readable stamps; consolidated exports at exports root; contract doc","author":"agent"}

package/template/docs/architecture/contracts/consolidatedExports.contract.md

@@ -0,0 +1,58 @@
+# Contract: consolidated exports
+
+**Version:** `v001`  
+**Code:** `backend/src/shared/contracts/consolidatedExports.contract.js`
+
+## Purpose
+
+Regenerable **repo snapshots** for human handoff and agent onboarding — not runtime filing data.
+
+## Primary paths (handoff)
+
+```text
+file-exchange/exports/
+  consolidated-models.json
+  consolidated-prompts.json
+  consolidated-file-structure.json
+```
+
+## Mirror paths (API / git)
+
+```text
+models/
+  consolidated-models.json      ← model-condenser API writes here first
+  consolidated-prompts.json
+  consolidated-file-structure.json
+```
+
+Every condense run writes **both** export and mirror.
+
+## Commands
+
+```bash
+npm run condense:all
+npm run condense-prompts
+npm run condense-file-structure
+npm --prefix backend run condense-models   # or POST /api/model-condenser/condense
+```
+
+## Contents
+
+| File | Source |
+|------|--------|
+| `consolidated-models.json` | Model condenser — schema inventory |
+| `consolidated-prompts.json` | All `.prompt.md` / `.prompt.js` + manifests |
+| `consolidated-file-structure.json` | Full file tree (tree ignore rules) |
+
+## File tree ignore (consolidated-file-structure)
+
+Same as pre-push dev log: `node_modules`, `.git`, `dist`, `build`.
+
+## Deprecated
+
+- `scripts/export-consolidated-models.mjs` → use `npm run condense-models` or `POST /api/model-condenser/condense`
+
+## Related
+
+- [file-exchange/README.md](../../../file-exchange/README.md)
+- [docs/model-condenser/API.md](../../model-condenser/API.md)

package/template/docs/architecture/contracts/fileExchange.contract.md

@@ -0,0 +1,47 @@
+# Contract: file exchange
+
+**Version:** `v001`  
+**Timestamp helper:** `backend/src/shared/utils/formatExchangeTimestamp.js`  
+**User doc:** [file-exchange/README.md](../../../file-exchange/README.md)
+
+## Layout
+
+```text
+file-exchange/
+  imports/{stamp}/     ← inbound bundles (mandatory before processing)
+  exports/{stamp}/     ← session deliverables (batch runs, curl logs)
+  exports/consolidated-*.json   ← see consolidatedExports contract
+```
+
+## Stamp format (human-readable UTC)
+
+```text
+YYYY-MM-DD_HH-MM-SSZ
+```
+
+Example: `2026-05-23_15-59-43Z`
+
+Legacy compact stamps (`20260523T155943Z`) are normalized by `normalizeExchangeStamp()` in the timestamp helper.
+
+## Mandatory workflow (agents)
+
+1. `npm run import:file-exchange -- "<path>"`
+2. Process only from `imports/{stamp}/`
+3. Copy deliverables to `exports/{stamp}/`
+4. `npm run condense:all` when refreshing consolidated snapshots
+
+Enforced by `AGENTS.md` and `.cursor/rules/file-exchange-inbox.mdc` (`alwaysApply: true`).
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/import-to-file-exchange.mjs` | Copy bundle → `imports/{stamp}/` |
+| `scripts/resolve-import-stamp.mjs` | Resolve human or legacy stamp folder |
+| `scripts/ingest-golden-parsed.mjs` | Parsed cache → `evals/golden/` |
+| `scripts/ingest-golden-expected.mjs` | Ground truth → `doc_NNN.expected.json` |
+
+## Related contracts
+
+- [consolidatedExports.contract.md](./consolidatedExports.contract.md)
+- [prePushDevLog.contract.md](./prePushDevLog.contract.md)

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

@@ -0,0 +1,39 @@
+{
+  "repoArtifactLayout": {
+    "version": "v001",
+    "doc": "docs/architecture/REPO_ARTIFACT_LAYOUT.md",
+    "overview": "docs/architecture/CONTRACTS_OVERVIEW.md"
+  },
+  "fileExchange": {
+    "version": "v001",
+    "doc": "docs/architecture/contracts/fileExchange.contract.md",
+    "userDoc": "file-exchange/README.md",
+    "timestampHelper": "backend/src/shared/utils/formatExchangeTimestamp.js",
+    "importScript": "scripts/import-to-file-exchange.mjs"
+  },
+  "consolidatedExports": {
+    "version": "v001",
+    "doc": "docs/architecture/contracts/consolidatedExports.contract.md",
+    "file": "backend/src/shared/contracts/consolidatedExports.contract.js",
+    "utility": "backend/src/shared/utils/consolidatedExport.js"
+  },
+  "prePushDevLog": {
+    "version": "v001",
+    "doc": "docs/architecture/contracts/prePushDevLog.contract.md",
+    "file": "backend/src/shared/contracts/prePushDevLog.contract.js",
+    "schema": "work-log/dev-logs/schemas/dev-log-agent.v1.schema.json",
+    "generator": "scripts/write-pre-push-dev-log.mjs",
+    "humanFormat": "scripts/lib/dev-log-human-format.mjs",
+    "verify": "scripts/verify-dev-log.mjs",
+    "apiInventory": "scripts/lib/api-inventory.mjs",
+    "repoTree": "scripts/lib/repo-tree.mjs",
+    "workLogReadme": "work-log/dev-logs/README.md"
+  },
+  "apiDocumentationRegistry": {
+    "version": "v001",
+    "doc": "docs/architecture/contracts/apiDocumentationRegistry.contract.md",
+    "registry": "docs/API.md",
+    "lintScript": "scripts/check-api-docs.mjs",
+    "architectureDoc": "docs/architecture/API_DOCUMENTATION_CONTRACT.md"
+  }
+}

package/template/docs/architecture/contracts/prePushDevLog.contract.md

@@ -0,0 +1,69 @@
+# Contract: pre-push dev log
+
+**Version:** `v001`  
+**Code:** `backend/src/shared/contracts/prePushDevLog.contract.js`  
+**Agent schema:** `work-log/dev-logs/schemas/dev-log-agent.v1.schema.json` (`1.0.0`)
+
+## Purpose
+
+Before each git push, produce a **paired audit**:
+
+| Audience | Path | Format |
+|----------|------|--------|
+| Human | `work-log/dev-logs/human/` | Markdown — Part I summary + Part II detail |
+| Agent | `work-log/dev-logs/agent/` | JSON — machine-readable audit |
+
+## Commands
+
+```bash
+npm run dev-log:pre-push -- --slug <kebab-topic> [--program 005] [--no-tests]
+npm run dev-log:verify
+npm run dev-log:pre-push -- --check   # requires git + agent log for HEAD
+```
+
+## Human log structure (Part I + Part II)
+
+**Part I — Summary** (auto-filled):
+
+- Table of contents with anchor links
+- Mermaid: HTTP modules, pipeline versions, pre-push flow
+- Audit tables: API surface, version/prompt contracts, tests, git, repo shape
+- Condensed repository tree (link to full tree in Part II)
+
+**Part II — Detailed** (fill):
+
+- Goals, decisions, changes, iterations, outcomes, follow-ups
+- Full HTTP registry from `docs/API.md`
+- Full git porcelain + diff stat
+- Full repository tree
+
+Generator: `scripts/lib/dev-log-human-format.mjs`
+
+## Agent log (required fields)
+
+- `meta`, `summary`, `apis`, `git`, `tests`, `repositoryTree`
+- `changes`, `decisions[]`, `iterations[]`
+- `tradeoffs`, `improvements`, `regressions`, `risks`, `followUps`
+
+`apis` is built by `scripts/lib/api-inventory.mjs` from `docs/API.md` + `pipelineVersions.js` + `promptVersions.js`.
+
+## Repository tree rules
+
+Equivalent to:
+
+```bash
+tree -I "node_modules|.git|dist|build"
+```
+
+Implemented in `scripts/lib/repo-tree.mjs`. `.DS_Store` files also excluded.
+
+## Git
+
+- Works **without** git (fields show `unknown` until `git init`)
+- After git init: branch, SHA, porcelain, diff stat populate automatically
+
+## Related
+
+- [work-log/dev-logs/README.md](../../../work-log/dev-logs/README.md)
+- [AGENTS.md](../../../AGENTS.md) — pre-push section
+- `.cursor/commands/pre-push-dev-log.md`