@genvidtech/c3-domain-manager 0.0.1 → 0.6.1

package/docs/decisions/0002-configurable-locations-adapters-seam.md

@@ -0,0 +1,72 @@
+# ADR 0002: Configurable config/extracted locations via a `src/adapters` resolution seam
+
+**Status:** Accepted
+**Date:** 2026-06-03
+**Issue:** #7 — make the domain-config path and extracted-output dir overridable
+
+> Recovered retroactively (2026-06-30) from commit `64554bd`.
+
+---
+
+## Context
+
+The tool originally hardcoded its paths: `domain-config.json` and `extracted/`
+were always resolved as `path.join(PROJECT_ROOT, …)`. The MCP server recomputed
+`path.join(PROJECT_ROOT, "domain-config.json")` inline in five places. This
+blocked legitimate uses — a config file living outside the project root, a
+custom output directory, or a no-side-effect validation pass that writes nothing
+into the project tree.
+
+Both the CLI and the MCP server need the same resolution logic, so the question
+was not only *what* to make configurable but *where* the resolution should live
+so the two adapters share one implementation without leaking it onto the public
+library API.
+
+## Decision
+
+**Introduce a pure `src/adapters/locations.ts` seam — `resolveLocations(opts,
+projectRoot)` returning a `ResolvedLocations`** — that resolves the
+domain-config path, the extracted-output directory, and the ephemeral-temp
+behaviour from CLI flags / `startServer` options. Add two global CLI flags
+(`--config`, `--extracted`) and thread the server through a single
+`CONFIG_PATH`/`CONFIG_WATCH_KEY` set once at `startServer` time.
+
+Resolution rules:
+
+- **Absolute operator paths pass through; relative paths rebase to the project
+  root.** Operator-supplied paths are trusted — paths outside the project root
+  are intentionally allowed.
+- **`--extracted none`** routes generation into an ephemeral `os.tmpdir()`
+  directory, removed in a `finally` (CLI) or the shutdown handler (server).
+- `configWatchKey` is the forward-slash-normalized absolute config path, used by
+  the server's `ExpectedChanges` self-write suppression on both add and consume,
+  so it stays correct for a custom config name/location.
+
+The `src/adapters/` layer holds code shared *between* the CLI and MCP adapters
+and is **deliberately not re-exported** from the public library API
+(`src/index.ts`).
+
+## Alternatives Considered
+
+**Put the resolution helpers in `src/domain/` (the pure core).** Rejected:
+location resolution is adapter concern (CLI flags / server options), not domain
+analysis. Placing it in the core would either pollute the public API surface or
+force the pure functions to know about CLI/server option shapes.
+
+**Duplicate the resolution in each adapter.** Rejected: the watch-key
+normalization and the ephemeral-temp lifecycle are subtle enough that two copies
+would drift. A single tested seam (16 unit tests, including a real
+`ExpectedChanges` add/consume round-trip) is the safer factoring.
+
+## Consequences
+
+- A new architectural layer, `src/adapters/`, is established for
+  CLI↔server-shared code that should not be public. Later decisions extend it —
+  see [[0003-adopt-loadprojectconfig-schema-first]] (the `configDir`/
+  `configFileName` split lives here) and
+  [[0007-project-dir-resolverootfolder]] (`resolveProjectRoot` joins it).
+- The server's five inline `path.join` recomputations collapse to one
+  module-level `CONFIG_PATH`; ephemeral extracted dirs are cleaned up on
+  shutdown.
+- The explicit `.version(PKG_VERSION)` yargs wiring (the issue #3 guard) is left
+  untouched by this change.

package/docs/decisions/0003-adopt-loadprojectconfig-schema-first.md

@@ -0,0 +1,73 @@
+# ADR 0003: Adopt `@genvid/mcp-utils` 0.3.0 `loadProjectConfig`; make `DomainConfig` schema-first
+
+**Status:** Accepted
+**Date:** 2026-06-03
+**Issue:** #9 — adopt the mcp-utils 0.3.0 configuration API
+
+> Recovered retroactively (2026-06-30) from commit `99f01f2`.
+
+---
+
+## Context
+
+Config loading was three unguarded `JSON.parse(...) as DomainConfig` casts — one
+each in the pure core, the CLI, and the MCP server. A missing file, malformed
+JSON, a schema violation, or a path escape produced an opaque parse throw, and
+the `as DomainConfig` cast asserted a shape the loader never actually checked.
+The `DomainConfig` family was also a set of hand-written TypeScript interfaces
+kept in sync with the runtime expectations by hand.
+
+`@genvid/mcp-utils` 0.3.0 shipped `loadProjectConfig(projectRoot, fileName,
+schema)` — an async, never-throwing read+merge+zod-validate that returns either
+the typed config or a structured `CallToolResult` error — plus its `isMcpError`
+guard. This builds directly on the resolution seam from
+[[0002-configurable-locations-adapters-seam]].
+
+## Decision
+
+**Adopt `loadProjectConfig` everywhere config is read, and make `DomainConfig`
+schema-first.**
+
+1. **Schema-first types.** Replace the `DomainConfig` / `DomainDefinition` /
+   `SharedSubdomainDefinition` / `Relationship` interfaces with lenient zod
+   schemas; export `DomainConfigSchema` as the single source of truth and derive
+   the types via `z.infer`. Schemas use `.passthrough()` so unknown keys survive
+   the MCP server's load→mutate→write round-trip; non-essential fields are
+   optional; `description` stays required. The derived types are structurally
+   identical to the old interfaces, so all consumers compile unchanged.
+
+2. **Keep MCP types out of the pure core.** The core's `loadConfig(configDir,
+   configFileName)` becomes an **async throwing wrapper** around
+   `loadProjectConfig` that throws on `isMcpError` (prefixed
+   `loadProjectConfig(…)`), so the pure core never surfaces `CallToolResult`.
+   `generateDomainIndex` becomes async.
+
+3. **Server calls `loadProjectConfig` directly** so its tool handlers can return
+   the structured `CallToolResult` error verbatim; its caches store only on
+   success. `configDir`/`configFileName` (added to `ResolvedLocations`) thread
+   the resolved location through — `path.join(configDir, configFileName)` always
+   equals the absolute `configPath`, preserving the outside-root `--config` case.
+
+## Alternatives Considered
+
+**Have the pure core return `CallToolResult` too.** Rejected: it would leak the
+MCP error type into the public library API and into the CLI, which has no use for
+a `CallToolResult`. The throwing wrapper keeps the core MCP-agnostic while the
+server still gets the structured error by calling `loadProjectConfig` directly.
+
+**Keep hand-written interfaces, validate separately.** Rejected: two sources of
+truth (the interface and a parallel validator) inevitably drift. Deriving the
+types from the schema makes the validator authoritative for free.
+
+## Consequences
+
+- Config errors (missing file, bad JSON, schema violation, path escape) now
+  produce a clear, structured `loadProjectConfig(domain-config.json): …` error
+  instead of an opaque parse throw — aborting the CLI command or returning a
+  structured MCP tool error.
+- The lenient `.passthrough()` schema is what makes the MCP mutate tools safe:
+  extra config keys survive a `set-overrides`/`remove-overrides` round-trip.
+- `generateDomainIndex` and the affected CLI handlers become async.
+- This is the first mcp-utils helper adoption; the pattern of "verify the packed
+  `.d.ts`, not the release notes" continues in
+  [[0004-adopt-mcp-utils-0.4.0-helpers]].

package/docs/decisions/0004-adopt-mcp-utils-0.4.0-helpers.md

@@ -0,0 +1,74 @@
+# ADR 0004: Adopt `@genvid/mcp-utils` 0.4.0 server helpers; harden mutate writes
+
+**Status:** Accepted
+**Date:** 2026-06-09
+**Issue:** #10 / #11 — upgrade mcp-utils to 0.4.0 and adopt its helpers
+
+> Recovered retroactively (2026-06-30) from commit `66debb4`.
+
+---
+
+## Context
+
+`src/mcp/server.ts` had grown hand-rolled equivalents of plumbing that
+`@genvid/mcp-utils` already exported (some since 0.3.0, adopted only now): local
+`READ_ONLY`/`REGENERATE`/`MUTATE` annotation objects, a local
+`paginatedResponse` helper, and ad-hoc result+footer string assembly. More
+seriously, the `set-overrides` and `remove-overrides` handlers had **no
+try/catch around their write path**: a failed `fs.writeFileSync` propagated
+uncaught out of the tool callback instead of returning a `CallToolResult` error,
+and a partial write left `txId` un-bumped while the on-disk file had changed —
+and the watcher swallows its own event via `expectedChanges` — so the client
+would never learn to reconcile.
+
+mcp-utils 0.4.0 is additive/drop-in and provides `mcpContent` (single-block
+result+footer), `withMcpErrors` (wraps an async handler so thrown errors become
+`CallToolResult` errors, with an `onError` hook), and surfaces the annotation
+constants and `paginatedContent` already present since 0.3.0.
+
+## Decision
+
+**Bump to `^0.4.0` and adopt the library helpers, replacing the hand-rolled
+equivalents; wrap the mutate handlers in `withMcpErrors` with an `onError` txId
+bump.**
+
+- Drop the local annotation objects → import `READ_ONLY`/`REGENERATE`/`MUTATE`.
+- `set-overrides`/`remove-overrides` build responses with `mcpContent(body,
+  \`txId: ${txId}\`)`.
+- `read-domain-index` uses `paginatedContent`; the stale-index warning rides as
+  its trailing footer.
+- Wrap both mutate handlers in `withMcpErrors` with an `onWriteError` hook that
+  **bumps `txId` and logs** on write failure, so a failed write (a) returns a
+  proper error result and (b) forces the client to re-read. The early-return
+  validation paths (txId mismatch, override validation, empty input) return
+  `isError` without throwing, so they correctly bypass `onError`. `regenerate`
+  keeps its existing try/catch and is left unwrapped.
+
+The issue's proposed `{prefix}` adoption was **dropped**: verification showed
+`loadConfig` unwraps rather than produces errors, so it has no valid target.
+
+## Alternatives Considered
+
+**Keep the hand-rolled helpers.** Rejected: they had silently sat as duplicates
+of the library's exports, and the dedup removes a maintenance burden. The
+annotation constants in particular must match the library's shapes exactly.
+
+**Add a bespoke try/catch to each mutate handler instead of `withMcpErrors`.**
+Rejected: `withMcpErrors` standardizes the thrown-error → `CallToolResult`
+conversion and gives the `onError` side-effect hook for free; bespoke try/catch
+would re-implement it inconsistently across the two handlers.
+
+## Consequences
+
+- Observable response-shape deltas (no server test harness guards these):
+  `read-domain-index` collapses from two content blocks to one; the stale-index
+  warning moves into the paginated footer; the mutate `txId:` line now hugs the
+  body with a single newline instead of a blank line. All intentional.
+- A failed mutate write now returns an error result **and** bumps `txId` so the
+  client reconciles. Known residual gap: the in-memory config is mutated before
+  the write, so on failure the cache can still diverge from disk — out of scope;
+  the txId bump at least signals reconciliation.
+- Reinforces the standing rule (recorded in CLAUDE.md from this issue's retro):
+  when bumping mcp-utils, audit the server for hand-rolled equivalents and verify
+  the API against the packed types, not the release notes — the same discipline
+  applied in [[0003-adopt-loadprojectconfig-schema-first]].

package/docs/decisions/0005-validateforeditor-read-side-diagnostic.md

@@ -0,0 +1,65 @@
+# ADR 0005: Adopt `validateForEditor` as a read-side editor-strictness diagnostic
+
+**Status:** Accepted
+**Date:** 2026-06-11
+**Issue:** #13 (reframing #12) — adopt c3source 1.4.0 `validateForEditor`
+
+> Recovered retroactively (2026-06-30) from commit `bc76696`,
+> CLAUDE.md, and `docs/domain-architecture.md`.
+
+---
+
+## Context
+
+`@genvidtech/c3source` 1.4.0 shipped `validateForEditor(sheet)` /
+`EditorValidationIssue`, which checks a parsed event sheet against the structural
+rules the C3 editor enforces on import (e.g. a `variable` event missing its
+`comment` field, or a `group` event missing its `description`).
+
+The originating issue (#12) framed this as a guard to run **"before write-out"** —
+the implicit assumption being that `c3-domain-manager` writes or modifies C3
+event sheets and should validate them before doing so. It does not.
+`c3-domain-manager` only ever *reads* event sheets to analyze them; the only files
+it writes are its own `extracted/` markdown index and (via MCP mutate tools) the
+`domain-config.json`. There is no C3-sheet write site for a "before write-out"
+guard to attach to. (This "verify the integration site the issue assumes actually
+exists" lesson is now recorded in CLAUDE.md.)
+
+## Decision
+
+**Adopt `validateForEditor`, but as a read-side diagnostic — not a write
+guard.** Add `validateEditorStrictness` / `formatEditorStrictnessReport`
+(`src/domain/editorValidation.ts`) and expose them as the `validate-editor` CLI
+subcommand and the MCP `READ_ONLY` "Validate Editor Strictness" tool.
+
+The diagnostic re-walks `eventSheets/` fresh from disk (it does **not** consume
+the cached `DomainData[]`), attributes each sheet to a domain via `classifyFile`,
+runs `validateForEditor` per sheet, and returns issues grouped by sheet. Sheets
+matching no domain are still validated and reported under `"(unclassified)"`. The
+report surfaces sheets the C3 editor would refuse to import, so the user can fix
+them in the editor.
+
+## Alternatives Considered
+
+**Implement the issue as written — a pre-write guard.** Rejected because the
+premise is false: there is no C3-sheet write path in this tool. Forcing a guard
+in would have meant inventing a write site that does not exist.
+
+**Skip adoption entirely** (no write site ⇒ no use). Rejected: the validation
+has clear standalone value as a read-side health check, independent of any write.
+Reframing it as a diagnostic preserves the value without the bogus premise.
+
+## Consequences
+
+- `validate-editor` is the first read-side capability that intentionally does
+  **not** read the cached domain index — it re-walks sheets from disk, so the MCP
+  tool deliberately omits the stale-index warning that other read tools append
+  (index freshness is irrelevant to its output).
+- `editorValidation.ts` is independent of the `DomainData[]` pipeline that every
+  other downstream module consumes; it shares only `classifyFile`.
+- Continues the c3source-supersedes-local-logic pattern of
+  [[0001-adopt-c3source-extractors]]; the file-discovery half of this walk is
+  later migrated to the project handle in [[0008-adopt-openproject-option-a]]
+  (via `hasEventSheets()` / `findAllEventSheets()`).
+- Establishes the durable lesson — verify the integration site an issue assumes
+  actually exists before building to its premise.

package/docs/decisions/0006-event-variable-reference-coupling.md

@@ -0,0 +1,77 @@
+# ADR 0006: Add event-variable references as a second cross-domain coupling source
+
+**Status:** Accepted
+**Date:** 2026-06-11
+**Issue:** #14 — enrich the cross-domain dependency graph
+
+> Recovered retroactively (2026-06-30) from commit `cc8b5fd`,
+> CLAUDE.md, and `docs/domain-architecture.md`.
+
+---
+
+## Context
+
+Cross-domain coupling was derived from a single source: `include` events. When a
+sheet in domain A includes a sheet in domain B, that is an include edge A → B
+(the `includesFrom` / `includedBy` graphs). But C3 event sheets couple in a
+second way the include graph misses entirely: a sheet can **reference an event
+variable declared in another sheet** via System ACEs. Two domains can be coupled
+through shared global variables without any include relationship between them.
+
+c3source 1.4.0 also shipped the primitives needed to detect this:
+`getEventVarReferenceName` / `EVENTVAR_REFERENCE_ACES`, plus the
+`visitEvents` / `hasConditions` / `hasActions` tree-visitors.
+
+## Decision
+
+**Derive a second, sibling coupling source — event-variable references — and
+aggregate it with include coupling under union semantics.**
+
+- `extractEventVarDecls` indexes top-level (`variable`) declarations per domain;
+  `extractEventVarRefs` collects System-ACE references via
+  `getEventVarReferenceName` + the visitors. `computeDomainData` resolves each
+  reference to its declaring domain(s) and builds `referencesFrom` /
+  `referencedBy`, sibling to the include maps.
+
+**Resolution policy:**
+
+- **Global-scope approximation** — only top-level (sheet-root) `variable` events
+  are indexed as declarations (C3 cross-sheet references require globals).
+  Variables inside groups/functions are deliberately excluded.
+- **Attribute-to-all on collision** — a name declared at the top level of
+  multiple domains creates an edge to every declaring domain.
+- **Unresolved references produce no edge** — a referenced name with no indexed
+  declaration anywhere is silently ignored (no diagnostics bucket).
+- **Same-domain references produce no edge** — consistent with include coupling.
+
+No `domain-config.json` schema change is required — reference coupling is derived
+entirely from sheet content.
+
+## Alternatives Considered
+
+**Fold references into the existing include edges.** Rejected: the two coupling
+kinds have different meanings and different fixes, so they are kept distinct. The
+context map renders references as a separate `observed-ref` edge kind
+(`[observed-ref]` in text, `-.->|var|` in Mermaid), with precedence declared >
+observed (include) > observed-ref.
+
+**Track unresolved references in a diagnostics bucket.** Rejected as scope creep
+for this issue — the "unresolved → no edge" path is simple and correct for the
+coupling question; a diagnostics surface can come later if warranted.
+
+**Index variables declared inside groups/functions too.** Rejected: those are
+not visible across sheets in C3, so a cross-sheet reference to one is genuinely
+unresolvable — excluding them is the correct behaviour, not a limitation to fix.
+
+## Consequences
+
+- Both coupling sources are aggregated with **union semantics** across every
+  downstream consumer: health (Ca/Ce count the deduped union),
+  `validateBoundaries` (a reference to an undeclared domain is an `undeclared`
+  violation just like an include), the context map (the `observed-ref` edge
+  kind), and domain pages (two new reference subsections).
+- Reuses the c3source 1.4.0 primitives adopted alongside
+  [[0005-validateforeditor-read-side-diagnostic]] — the same release supplied
+  both the validator and these reference helpers.
+- Full policy and aggregation are documented in `docs/domain-architecture.md`
+  ("Cross-domain coupling sources").

package/docs/decisions/0007-project-dir-resolverootfolder.md

@@ -0,0 +1,72 @@
+# ADR 0007: Add `--project-dir` via `@genvid/mcp-utils` 0.5.0 `resolveRootFolder`
+
+**Status:** Accepted
+**Date:** 2026-06-17
+**Issue:** #16 — set the C3 project source root explicitly
+
+> Recovered retroactively (2026-06-30) from commit `a2130aa`,
+> CLAUDE.md, and `docs/domain-architecture.md`.
+
+---
+
+## Context
+
+The C3 project source root — the directory whose `eventSheets/`, `layouts/`, and
+`scripts/` are scanned — was effectively `process.cwd()`. There was no way to
+point the tool at a sibling directory, and no way to disambiguate a repository
+that hosts more than one C3 project. The issue asked to add a `--project-dir`
+flag and, implicitly, to hand-roll the root-discovery logic (explicit path → env
+var → marker-file search → cwd fallback).
+
+While scoping it, `@genvid/mcp-utils` 0.5.0 turned out to ship exactly that
+resolver: `resolveRootFolder` resolves a project root from an explicit path, an
+env var, or `project.c3proj` marker discovery, returning `ResolvedRoot |
+CallToolResult` and never throwing. This is the inverse of the usual lesson — the
+issue said "hand-roll Y," but a dependency bump already provided Y. (`project.c3proj`
+itself comes from `@genvidtech/c3source`'s `PROJECT_MANIFEST_FILE`, exported since
+1.5.0.)
+
+## Decision
+
+**Add `--project-dir` (and `C3_PROJECT_DIR`), implemented as `resolveProjectRoot`
+in `src/adapters/locations.ts` — a thin wrapper over mcp-utils'
+`resolveRootFolder`** passing `PROJECT_MANIFEST_FILE` as the discovery marker
+rather than hand-rolling the resolution.
+
+Resolution precedence (highest to lowest):
+
+1. `--project-dir <path>` — relative resolves against the **current working
+   directory**, absolute used as-is, no containment restriction (`../sibling` is
+   valid).
+2. `C3_PROJECT_DIR` env var — same rules.
+3. Discovery — the current dir and its immediate children (depth 1) are searched
+   for a `project.c3proj` marker. Exactly one match becomes the root; two or more
+   matches print an ambiguity error and exit non-zero (the intended behaviour for
+   a repo hosting multiple C3 projects).
+4. Fallback — the current working directory (preserves prior behaviour).
+
+The MCP server does **not** re-run discovery; the root is fixed at `startServer`
+time. Note `--project-dir` resolves relative to **cwd**, whereas `--config`/
+`--extracted` resolve relative to the project root (per
+[[0002-configurable-locations-adapters-seam]]).
+
+## Alternatives Considered
+
+**Hand-roll the resolution as the issue framed it.** Rejected once
+`resolveRootFolder` was found: it provides the same precedence chain, the
+never-throw `ResolvedRoot | CallToolResult` contract, and the marker search —
+adopting it avoids duplicating root-discovery logic that mcp-utils now owns. This
+is the standing "verify whether a dep bump already ships the primitive" discipline
+applied in reverse.
+
+**Silently pick the first match on ambiguity.** Rejected: a repo with multiple
+C3 projects is a real configuration the tool should not guess at — erroring and
+requiring an explicit `--project-dir` is safer than analyzing the wrong project.
+
+## Consequences
+
+- `resolveProjectRoot` joins `resolveLocations` in the `src/adapters/` shared
+  layer; the new root feeds the existing location resolution unchanged.
+- Adopting `resolveRootFolder` is what raised the mcp-utils floor to `^0.5.0`.
+- Full precedence table and the cwd-vs-project-root resolution distinction are
+  documented in `docs/domain-architecture.md` ("Paths and locations").

package/docs/decisions/0008-adopt-openproject-option-a.md

@@ -0,0 +1,74 @@
+# ADR 0008: Adopt `C3Project`/`openProject` for C3 file discovery (Option A)
+
+**Status:** Accepted
+**Date:** 2026-06-29
+**Issue:** #19 — migrate `@genvid/c3source` → `@genvidtech/c3source` 1.7.0
+
+---
+
+## Context
+
+`c3-domain-manager` discovers C3 source files by hardcoding section-folder joins
+(`path.join(rootDir, "eventSheets")`, `path.join(rootDir, "layouts")`,
+`path.join(rootDir, "scripts")`) in `src/domain/domainGenerator.ts`
+(`computeDomainData`, `findScriptEntries`), `src/domain/editorValidation.ts`,
+and `src/domain/domainAnalysis.ts` (`listUncategorized`), then — for the
+discovery path — calling the free functions `find_all_eventsheets_path` /
+`find_all_layouts_path`.
+
+The `@genvidtech/c3source` 1.7.0 bump completes the `C3Project` handle's section
+coverage. `openProject(root): C3Project` exposes canonical section dirs
+(`eventSheetsDir`, `layoutsDir`, `scriptsDir`, …) and
+`findAllEventSheets()` / `findAllLayouts()` / `findAllScripts()` walkers,
+centralizing the C3-folder facts that were previously hand-rolled here.
+Per the standing guidance in `CLAUDE.md` ("when bumping c3source, check whether
+new exports supersede local C3-parsing logic"), this bump triggered a formal
+evaluation of three adoption options.
+
+## Decision
+
+**Option A — call `openProject(rootDir)` locally at the top of each pure
+function** (`computeDomainData`, `validateEditorStrictness`, and
+`listUncategorized`) and use `project.findAllEventSheets()` /
+`project.findAllLayouts()` / `project.scriptsDir` (the discovery path), or the
+`project.eventSheetsDir` / `layoutsDir` / `scriptsDir` directory fields where a
+function does its own walk (`listUncategorized`'s `collectFiles`). The pure
+functions keep their existing `rootDir`-first signatures and their position on
+the `src/index.ts` public surface is unchanged.
+
+## Alternatives Considered
+
+**Option B — thread a `C3Project` handle through the public API.**
+Change `computeDomainData` / `validateEditorStrictness` to accept a `C3Project`
+instead of `rootDir`. Rejected: exposes a dependency type on the pure-core public
+surface (`src/index.ts` re-exports these) and ripples into `generateDomainIndex`,
+`cli.ts`, `server.ts`, and every test — large blast radius for thin gain.
+
+**Option C — adopt only the dir-path constants, keep free `find_all_*` functions.**
+Use `project.eventSheetsDir` etc. as inputs but keep the existing free-function
+walkers. Rejected: keeps two import styles, forgoes the missing-dir robustness of
+the handle's walkers, and offers almost no improvement over the status quo.
+
+## Consequences
+
+- Removes all hardcoded C3 section-folder name literals from this repo; the folder
+  facts now live in `c3source`. (`listUncategorized`'s swap is purely cosmetic —
+  its `collectFiles`/`collectRootTsFiles` walkers already return `[]` on a missing
+  dir, so only the discovery path in `computeDomainData` gains the behavioural fix
+  below.)
+- **Behavioral improvement (deliberate):** a project missing `eventSheets/` or
+  `layouts/` previously caused `computeDomainData` to throw `ENOENT`;
+  `findAllEventSheets()` / `findAllLayouts()` return `[]` instead, so analysis
+  continues gracefully. Pinned by new tests. `editorValidation` preserves its
+  existing skip-log via `project.hasEventSheets()`.
+- **Scope limit — `findScriptEntries` is not replaced:** `project.findAllScripts()`
+  returns a flat list of `.ts` paths without the `{relativePath, isDirectory}`
+  directory entries and `LAYER_DIRS` recursion that classification depends on.
+  Only its input narrows to `project.scriptsDir`; it still throws on a missing
+  `scripts/` dir (unchanged).
+- `findScriptEntries`'s narrowed signature (`rootDir` → `scriptsDir`) is a
+  public-API change with no known external consumers; noted for release notes.
+- **Deferred — `comparisonSymbol`/`COMPARISON_OPERATORS` (also new in 1.7.0):**
+  no integration site exists today (this repo renders no condition/comparison
+  params), so adoption is deferred to a future measurement spike if a real
+  diagnostic warrants it.