claudeos-core 2.3.1 → 2.4.0

package/pass-prompts/templates/common/pass3-footer.md

@@ -259,14 +259,30 @@ Do NOT declare CLAUDE.md generation complete until count = 8 AND
 Section 8 contains exactly 2 `###` sub-sections.
 
 STEP 4b — Title determinism check. For each of the 8 `## N.` headings,
-confirm that the English canonical phrase is present as the primary
-heading text (a native-language translation may follow in parentheses).
-This rule is LANGUAGE-INVARIANT — applied regardless of `{OUTPUT_LANG}`:
-
-    ✅ `## 7. DO NOT Read`
-    ✅ `## 7. DO NOT Read (직접 읽지 말아야 할 파일)`
-    ❌ `## 7. 읽지 말 것 (Files Not to Be Read Directly)`
-       — English canonical must be PRIMARY, not parenthetical
+confirm that:
+  (a) the English canonical phrase is present as the primary heading text
+      (LANGUAGE-INVARIANT — applied regardless of `{OUTPUT_LANG}`), AND
+  (b) if `{OUTPUT_LANG}` != `en`, the canonical native-language gloss is
+      appended in parentheses (REQUIRED, not optional). If `{OUTPUT_LANG}`
+      == `en`, no gloss is emitted. The canonical gloss table lives in
+      `claude-md-scaffold.md` under "Section heading format".
+
+    en output:
+        ✅ `## 7. DO NOT Read`
+        ❌ `## 7. DO NOT Read (Files Not to Be Read Directly)`
+           — no gloss when OUTPUT_LANG == en
+
+    ko output:
+        ✅ `## 7. DO NOT Read (직접 읽지 말아야 할 파일)`
+        ❌ `## 7. DO NOT Read`
+           — gloss is required when OUTPUT_LANG != en
+        ❌ `## 7. 읽지 말 것 (Files Not to Be Read Directly)`
+           — English canonical must be PRIMARY, not parenthetical
+
+    ja output:
+        ✅ `## 7. DO NOT Read (直接読まないファイル)`
+        ❌ `## 7. DO NOT Read`
+           — gloss is required when OUTPUT_LANG != en
 
 Required canonical tokens by section number:
     §1 → "Role Definition"
@@ -300,71 +316,192 @@ write in rules, standard, or CLAUDE.md MUST be a literal, verbatim path
 from `pass2-merged.json` / `project-analysis.json` / `pass1-*.json`.
 Do not invent, augment, or "normalize" filenames.
 
-The single most common Pass 3 hallucination pattern is inferring a
-filename from its parent directory:
+**PRIMARY CHECK — pass3a-facts.md's Allowed Source Paths section**
+**(v2.3.x+ allowlist):**
+
+Before writing ANY `src/...`, `packages/...`, `apps/...`, or
+language-specific source path in a rule or standard file, you MUST
+verify the path appears VERBATIM in the `## Allowed Source Paths`
+section of `pass3a-facts.md`. If the section is in "full" mode (lists
+individual files), the exact filename must be present. If the section
+is in "rollup" mode (lists directories because the project exceeds the
+enumeration budget), at minimum the path's parent directory must match
+a listed directory entry — and for the specific filename you must
+cross-check `pass2-merged.json` before writing it.
+
+A path NOT in the allowlist is a fabrication. Do not write it under
+any circumstance. Not even when:
+- The framework's documentation shows that path as "canonical" — this
+  covers Next.js app-router provider files, Vite test-setup or mock
+  handler modules, Spring resource config files, Django settings
+  modules, and similar framework-canonical locations. These paths
+  may be canonical in framework docs yet absent from THIS project's
+  allowlist because the project chose a different layout; citing
+  the canonical form is still a fabrication. (Do NOT quote the
+  specific canonical paths here — describe the category abstractly
+  if you must warn about it.)
+- A similar path appears in the allowlist and you are tempted to
+  "extrapolate" a sibling — for example, if the allowlist has a
+  list-operation file under some API directory, do NOT cite a
+  hypothetical create-operation file in the same directory just
+  because it would be a natural sibling. Cite only what the
+  allowlist actually contains.
+- A TypeScript constant, Java annotation, or Python decorator name
+  suggests a filename (an ALL_CAPS constant naming a route path does
+  NOT mean a matching camelCase-basename .ts file exists; this was
+  the canonical v2.3.0 failure case and must remain a category
+  warning, not a filename warning).
+
+If the concept you want to describe has no corresponding file in the
+allowlist, either:
+  (a) describe the pattern abstractly ("a central router module"
+      rather than a fabricated concrete filename), OR
+  (b) omit the concrete citation entirely.
 
-    Directory seen in facts:  src/feature/routers/
-    File seen in facts:       src/feature/routers/routePath.ts
-                              src/feature/routers/routeComponentMap.ts
+This rule is enforced post-generation by `content-validator [10/10]
+path-claim verification`. Fabricated paths will be flagged as
+`STALE_PATH` advisories. The allowlist exists so that those advisories
+become rare — not so they become suppressible.
 
-    ❌ WRONG: write `src/feature/routers/featureRoutePath.ts`
-                       (prepended "feature" because the dir is `feature/`)
-    ❌ WRONG: write `src/feature/routers/FEATURE_COMPONENT_MAP.ts`
-                       (uppercased to match the TS constant name)
-    ✅ RIGHT: write `src/feature/routers/routePath.ts`
+**Secondary: filename-from-parent-directory hallucination:**
 
-Mechanism of the error: the model sees a constant named
-`FEATURE_ROUTE_PATH` (a TypeScript identifier) and "renormalizes" the
-filename to match it. TypeScript identifiers and filenames are
-independent — do NOT let the constant's name drive the filename you
-write. The filename in `pass2-merged.json` is authoritative.
+The single most common Pass 3 hallucination pattern is inferring a
+filename from its parent directory. Consider a hypothetical project
+where pass3a-facts.md lists a directory `src/feature/Xxx/` containing
+files `Yyy.ts` and `Zzz.ts`:
+
+    Directory seen in facts:  src/feature/Xxx/
+    File seen in facts:       src/feature/Xxx/Yyy.ts
+                              src/feature/Xxx/Zzz.ts
+
+    ❌ WRONG: invent a new filename by prepending the parent directory
+             name (writing `src/feature/Xxx/featureYyy.ts` because the
+             parent dir is named `feature/`).
+    ❌ WRONG: uppercase the filename to match a TypeScript constant
+             name (writing `src/feature/Xxx/YYY_MAP.ts` because the
+             module exports a constant named `YYY_MAP`).
+    ✅ RIGHT: write the filename exactly as pass3a-facts.md lists it
+             (`src/feature/Xxx/Yyy.ts`).
+
+Mechanism of the error: the model sees an ALL_CAPS TypeScript
+constant name and "renormalizes" the filename to match it. TypeScript
+identifiers and filenames are independent — do NOT let the constant's
+name drive the filename you write. The filename in
+`pass2-merged.json` is authoritative.
 
 Same rule applies to domain prefixes in general:
-- `src/feature/X.ts` is the correct reference even when the file's
+- `src/feature/Xxx.ts` is the correct reference even when the file's
   exported symbols start with `Feature*` or `FEATURE_*`.
 - Do NOT prepend the parent directory name to the filename as a
   disambiguator. The directory path is already the scope.
 
 Library-convention hallucination class (equally important):
 
-When generating a standard file about testing, mocking, styling,
-state management, or similar library-centric topics, do NOT reach
-for "the canonical file location" from the library's own docs. There
-is no canonical location — every project chooses its own.
-
-    ❌ WRONG: writing `testing-strategy.md` and referencing
-       `src/__mocks__/handlers.ts`, `src/test/setup.ts`,
-       `src/setupTests.ts`, or `src/test-utils.tsx` because MSW,
-       Vitest, or Jest docs show these paths.
-    ❌ WRONG: writing `styling-patterns.md` and referencing a
-       `src/styles/globals.css` or `src/theme.ts` because the
-       framework's quick-start uses them.
-
-    ✅ RIGHT: if pass3a-facts.md lists no test setup file (e.g.,
-       the project has 0% coverage with vitest installed but
-       no tests), write the testing guidance in abstract terms
-       ("a shared setup module in a test directory of your
-       choice") without naming a specific path.
-    ✅ RIGHT: for any library-centric standard, if the specific
-       file is not in pass3a-facts.md, describe the pattern
-       by role (what the file does) rather than by name (what
-       it is called).
-
-Critical triggers for this class:
-- `testing-strategy.md` / `testing-patterns.md` — almost always
-  tries to name a mock handler file or test setup file.
-- `styling-patterns.md` — almost always tries to name a global
-  stylesheet or theme file.
-- `state-management.md` — almost always tries to name a store
-  bootstrap file (Redux, Zustand, etc.) even when the project
-  uses only React Context.
+When discussing testing, mocking, styling, state management, environment
+configuration, or similar library-centric topics in ANY generated file
+(standard, rule, skill, guide — not just files named for the topic), do
+NOT reach for "the canonical file location" from the library's own docs.
+There is no canonical location — every project chooses its own.
+
+**Scope note (v2.3.2+):** this constraint applies to EVERY file being
+generated, not only to files whose names match the topic. A rule file
+called `52.ai-work-rules.md` discussing test-running protocol can still
+trip this trap; an infra file `01.environment-config.md` discussing env
+typing can still trip it. The trigger is **the topic being described**,
+not the filename of the document describing it.
+
+Guidance (by topic):
+
+- **Testing / mocking.** If pass3a-facts.md lists no test setup file
+  (e.g., the project has 0% coverage with vitest installed but no
+  tests), write the testing guidance in abstract terms ("a shared setup
+  module in a test directory of your choice") without citing a
+  framework-canonical path.
+- **Environment typing.** If no `.d.ts` file appears in the allowlist,
+  describe the `ImportMetaEnv` interface inline ("augment `ImportMetaEnv`
+  in a type-declaration file of your project's choosing") without
+  naming a specific filename.
+- **Styling / theming / state management.** If the specific file is
+  not in pass3a-facts.md, describe the pattern by role (what the file
+  does) rather than by name (what it is called).
+
+**Important — how to write examples in rules (v2.3.2+):** rule files
+(especially `52.ai-work-rules.md` and similar "meta" rules) sometimes
+need to illustrate bad path habits as educational examples. When they
+do, write the illustrative paths as **abstract placeholders** so the
+validator recognizes them as teaching examples, not as concrete path
+claims:
+
+- Use generic directory references with a glob or ellipsis:
+  `src/test/…`, `src/types/*.d.ts`, `src/*/mocks/…`
+- Use the `{placeholder}` form the validator already skips:
+  `src/{feature}/api/{Entity}.ts`, `src/hooks/use{Domain}.ts`
+- Use the prose form: "a mock handler file under a `__mocks__/`
+  directory of your choice" rather than a concrete filename.
+
+Do NOT cite a specific literal path (e.g., naming an exact file and
+extension that happens to be the library's canonical location) in an
+educational example. Literal paths are interpreted as real claims by
+`content-validator [10/10]` regardless of surrounding prose. If the
+example you want to give MUST be literal, add it to pass3a-facts.md
+first (i.e., only literal paths that actually exist in the project).
+
+**Hypothetical / future-tense framing is NOT a loophole (v2.3.2+):**
+wrapping a framework-canonical path in conditional or future-tense
+language (`if we adopted X`, `were this feature introduced, it would
+live at …`, `for a future Y`, `when Z is added later`, etc., in ANY
+output language) does NOT make the literal path safe. The validator
+is content-blind and will flag
+``if middleware is added later, place it at `src/middleware.ts` `` as
+a `STALE_PATH` advisory because `src/middleware.ts` does not exist on
+disk. This is the Next.js / Vite / Spring blind spot: the LLM, when
+discussing future extensions, reaches for the framework's canonical
+path as the "natural" location and writes it verbatim.
+
+The correct hypothetical form describes the ROLE or DIRECTORY without
+committing to a filename:
+
+- ❌ WRONG: "If middleware is added, place it at `src/middleware.ts`."
+- ❌ WRONG: "For a health endpoint in the future,
+  `src/app/api/health/route.ts`."
+- ✅ RIGHT: "If middleware is added later, place it at the path
+  Next.js's routing convention expects for the version in use
+  (describe the role; do not cite a literal filename)."
+- ✅ RIGHT: "A future health endpoint belongs under the project's
+  API route directory structure (see Next.js documentation for the
+  routing convention — do not assume a specific filename until the
+  file exists)."
+- ✅ RIGHT: "If an env-typing file is introduced, augment
+  `ImportMetaEnv` in a type-declaration file placed under the
+  project's chosen convention."
+
+In every case, if you cannot name the role + directory without
+committing to a specific `src/...` path that does NOT appear in
+pass3a-facts.md, OMIT the example entirely. An omitted example is
+better than a fabricated path that downstream readers may treat as
+authoritative. This rule applies regardless of the output language:
+translated conditional phrases (Korean, Japanese, Chinese, etc.) do
+not change the validator's literal-path detection — use a placeholder
+form or omit.
+
+Critical triggers for this class (the **topic**, not the filename):
+- Testing / mocking / test-runner protocol — almost always tempts a mock
+  handler file or test setup file, even in AI-work or onboarding rules.
+- Environment configuration / env typing — almost always tempts a
+  `.d.ts` file for `ImportMetaEnv` augmentation.
+- Styling / theming — almost always tempts a global stylesheet or
+  theme file.
+- State management — almost always tempts a store bootstrap file
+  (Redux, Zustand, etc.) even when the project uses only React Context.
 
 The rule in all cases: if pass3a-facts.md has the concrete path,
 use it verbatim; if not, describe the role without naming a file.
 
 This rule is enforced post-generation by `content-validator [10/10]
 path-claim verification`. Fabricated paths will be flagged as
-`STALE_PATH` errors with the path quoted back, forcing re-generation.
+`STALE_PATH` advisories with the path quoted back; the allowlist and
+this explicit denylist exist so that those advisories become rare —
+not so they become suppressible.
 
 CRITICAL — MANIFEST ↔ CLAUDE.md §6 Skills consistency:
 
@@ -398,5 +535,109 @@ level (the scaffold's PROJECT_CONTEXT mentions architecture style),
 but it does NOT enumerate rules. Section 6 "Standard / Rules / Skills
 Reference" provides a REFERENCE INDEX (what exists), not rule content.
 
+CRITICAL — Standard files MUST include both ✅ and ❌ examples:
+Every file under `claudeos-core/standard/**/*.md` (except pure index/overview
+files like `00.core/01.project-overview.md`) MUST contain BOTH:
+  - At least one ✅ Correct example (a fenced code block showing the right way)
+  - At least one ❌ Incorrect example (a fenced code block showing the wrong way)
+
+Skipping the ❌ block is a common Pass 3b LLM failure mode that produces
+`[NO_BAD_EXAMPLE]` advisories from `content-validator`. Even if you can only
+think of a minimal contrastive ❌ (a one-line wrong call, a missing
+annotation, a typo'd config key), include it. The contrast is what gives
+the standard its didactic value — a file with only ✅ examples reads as
+"this is one way to do it", whereas ✅+❌ reads as "this is the way; here is
+the failure mode".
+
+Self-check before finalizing each standard file:
+  - Does this file have at least one ```...``` block marked ✅?
+  - Does this file have at least one ```...``` block marked ❌?
+  If either is missing, add it before moving on.
+
+CRITICAL — Per-domain folder convention (`70.domains/{type}/`, plural):
+
+When generating per-domain files (any output that's specific to one
+project domain — e.g. `payment.md`, `order.md`, `member.md`), use the
+canonical `70.domains/` folder (PLURAL, collection-style) and ALWAYS
+include a `{type}/` sub-folder (`backend/` or `frontend/`) regardless
+of single-stack or multi-stack project. Uniform-convention rationale
+in the next paragraph.
+
+  - Per-domain standard:
+    `claudeos-core/standard/70.domains/{type}/{domain}.md`
+    where `{type}` is `backend` or `frontend`
+  - Per-domain rule:
+    `.claude/rules/70.domains/{type}/{domain}-rules.md`
+    (via staging-override path
+    `claudeos-core/generated/.staged-rules/70.domains/{type}/{domain}-rules.md`,
+    each rule file MUST have a `paths:` frontmatter glob scoping to that
+    domain's source directories)
+
+**Why ALWAYS the `{type}/` sub-folder, even for single-stack projects?**
+A single-stack project pays a 1-folder depth cost
+(`70.domains/backend/order.md` instead of `70.domains/order.md`). In
+exchange:
+
+  1. **Zero migration when the other stack is added.** A backend-only
+     project that later adds a Next.js frontend does NOT need to move
+     existing files to `backend/` — they're already there.
+  2. **No LLM probabilistic drift.** Pass 3 LLM never has to decide
+     "is this single-stack or multi?" — the pattern is always the
+     same.
+  3. **One pattern for validators.** `content-validator` and
+     `claude-md-validator` recognize a single layout instead of
+     branching.
+  4. **Future-proof for new stack types** (mobile, cli, agent, ...).
+
+The Pass 3 orchestrator (`bin/commands/init.js`) classifies each
+domain via `project-analysis.json` and emits per-domain target paths
+explicitly in the batch scope note. **Follow the explicit
+per-domain target paths shown in the scope note** rather than infer
+from the domain name. If the scope note shows
+`order → claudeos-core/standard/70.domains/backend/order.md`, that's
+the path to use — the type sub-folder is already classified for you.
+
+  - Per-domain skill notes:
+    `claudeos-core/skills/{category}/domains/{domain}.md`
+    (sub-folder under skill category — `skills/` is a separate namespace
+    from standard/rules, so no number prefix here. The `{category}`
+    folder name already encodes stack: `10.backend-crud/`,
+    `20.frontend-page/`. So skills don't need the additional `{type}/`
+    sub-folder that standard/rules use.)
+  - Per-domain skill ORCHESTRATOR (sibling to the `domains/` sub-folder):
+    `claudeos-core/skills/{category}/02.domains.md`
+    The orchestrator is REQUIRED when the `domains/` sub-folder is
+    populated. It mirrors the canonical pattern already used for
+    `01.scaffold-crud-feature.md` ↔ `scaffold-crud-feature/` (orchestrator
+    file at category root + sub-folder of the same stem). The basename
+    stem (`domains`) MUST match the sub-folder name so
+    `content-validator`'s standard orchestrator-stem matching covers
+    the sub-skills directly — without depending on the
+    global-MANIFEST coverage fallback. The orchestrator content lists
+    every per-domain note file in the `domains/` sub-folder, links to
+    `00.shared/MANIFEST.md`, and describes the per-domain anti-pattern
+    catalog if applicable. Numbered `02.` because `01.scaffold-*-feature.md`
+    already occupies the `01.` slot at the category root.
+
+Why `70.` and not `60.`: `60.memory/*` is the canonical L4 memory rules
+folder (regression-guarded since v2.0.0; cannot move to 70). Putting
+domains at `60.domains/` causes a `60.` prefix collision with
+`60.memory/` that makes directory listings ambiguous. `70.domains/` sits
+after memory and before `90.optional/`, giving per-domain content its
+own clean slot.
+
+Why PLURAL `domains/`: the folder holds N files, one per project domain
+— `payment.md`, `order.md`, etc. This matches the standard filesystem
+convention for collections (`users/user.md`, `posts/post.md`). The other
+numbered category folders (`00.core/`, `10.backend/`, etc.) are singular
+because each represents ONE topic, not a collection of items.
+
+DO NOT use:
+  - `60.domains/` (collides with `60.memory/`)
+  - `70.domain/` (singular is wrong for a collection folder)
+  - Inlining per-domain content into `00.core/*` or topical files
+    (per-domain content is DOMAIN-scoped, topical files are TOPIC-scoped
+    — `paths` glob scoping breaks if they share files)
+
 After completion, run the following commands in order:
 1. npx claudeos-core health

package/pass-prompts/templates/common/pass3a-facts.md

@@ -124,6 +124,42 @@ IMPORT, not redefine.
 
 - ...
 - ...
+
+## Allowed Source Paths (v2.3.x+ — MANDATORY)
+
+Copy the **entire** `allowedSourcePaths` section from `pass3-context.json`
+verbatim into this pass3a-facts.md. Do NOT summarize it, do NOT truncate
+it, do NOT reword it. The shape to copy:
+
+- Header: whether the list is in `full` mode (individual file paths) or
+  `rollup` mode (parent directories, used when the project exceeds the
+  enumeration budget).
+- Body: the exact list of paths (or directories in rollup mode), each
+  wrapped in backticks as a markdown bullet.
+
+This section is the authoritative allowlist that Pass 3b/3c/3d consult
+when deciding whether a `src/...`, `packages/...`, `apps/...`, or
+language-specific source path may appear in a generated rule or standard
+file. A path not appearing in this allowlist MUST NOT be written by
+later passes — no exceptions, not even for paths that are "obvious" from
+framework convention.
+
+Rendering spec:
+
+```markdown
+## Allowed Source Paths
+
+Source files on disk (total: <N>). [full-mode description paragraph from
+pass3-context.json's allowedSourcePaths.paths field, copied verbatim.]
+
+- `path/to/file1.ts`
+- `path/to/file2.ts`
+- ... (every entry from pass3-context.json)
+```
+
+If `pass3-context.json`'s `allowedSourcePaths.paths` array is empty
+(collection failed), emit a single line `(allowlist unavailable —
+fall back to pass2-merged.json verification per file)` instead.
 ```
 
 ## Rules for Pass 3a
@@ -131,13 +167,22 @@ IMPORT, not redefine.
 1. **Read each input file AT MOST ONCE.** After reading, all fact extraction
    must be from your in-context memory of the file.
 2. **Be terse.** This document will be loaded into every subsequent Pass 3
-   step's context. Keep it under 10 KB. Use bullet lists, not prose.
+   step's context. Keep the non-allowlist portions under 10 KB. The
+   `## Allowed Source Paths` section is exempt from the 10 KB budget
+   because it is the authoritative path reference that prevents Pass 3
+   hallucination — its size is bounded by the MAX_PATHS (500) / MAX_DIRS
+   (300) caps in plan-installer/source-paths.js.
 3. **Exact values only.** Every class name, method name, package path, and
    file path must be verbatim from the analysis data. If a value is not
    captured in the analysis, write `(not in analysis)` — do NOT guess.
-4. **Do NOT write any other files.** CLAUDE.md, standard/, rules/, etc.
+4. **Allowed Source Paths section is COPIED, not extracted.** Do not apply
+   judgment, ranking, or "relevance filtering" to the allowlist. The
+   whole point is that Pass 3b/3c/3d get the complete enumeration; any
+   path you drop here becomes a path they can fabricate later without
+   the downstream validator catching it until after Pass 3 completes.
+5. **Do NOT write any other files.** CLAUDE.md, standard/, rules/, etc.
    come in later Pass 3 steps. Writing them here is a bug.
-5. **Do NOT read source code.** All information comes from the three JSON
+6. **Do NOT read source code.** All information comes from the three JSON
    inputs. The source has already been analyzed in Pass 1 and Pass 2.
 
 Once `pass3a-facts.md` is written, Pass 3a is complete.

package/pass-prompts/templates/common/pass4.md

@@ -29,48 +29,86 @@ MUST appear verbatim in `pass3a-facts.md` or `pass2-merged.json`. If a
 concrete path is not in those analysis artifacts, OMIT it — do NOT write it.
 
 Do NOT invent paths based on framework convention, prior training knowledge,
-or extrapolation from symbol names. The most common v2.3.0 dogfood failures
-observed were all in this class:
-
-❌ `src/feature/main.tsx`
-  — invented based on Vite's stock convention. This project may use a
-    different entry (e.g. `index.html` referencing a non-`main.tsx` file),
-    or may be a multi-entry project where no single `main.tsx` exists.
-    Check pass3a-facts.md; if no such path is listed, do not write it.
-
-❌ `src/feature/routers/featureRoutePath.ts`
-  — invented by prepending the parent directory name ("feature") to the
-    filename, or by converting a TypeScript constant name
-    (`FEATURE_ROUTE_PATH`) into a filename. TypeScript identifiers and
-    filenames are independent. The authoritative filename is in
-    pass3a-facts.md under the "Routing" or "Shared imports" section.
-    If pass3a-facts.md says `routePath.ts`, write `routePath.ts`, not
-    `featureRoutePath.ts`.
-
-❌ `src/components/utils/classNameMaker.ts`
-  — plausibly-named utility, but unverified. "Plausible" is not a
-    sufficient ground for a concrete path claim. If you want to reference
-    a utility layer in a rule file, reference the directory
-    (`src/components/utils/`) rather than inventing a filename.
-
-❌ `src/__mocks__/handlers.ts`, `src/test/setup.ts`, `src/test-utils.tsx`,
-   `src/setupTests.ts`
-  — invented based on testing-library conventions (MSW, Vitest, Jest,
-    React Testing Library). If the project has no tests (0% coverage in
-    pass3a-facts.md) or uses a different layout, these paths do not
-    exist. Anti-pattern triggers: writing a `testing-strategy.md` or
-    similar standard file and reaching for "the canonical test-setup
-    location" from the library's docs. There is no canonical location —
-    every project chooses its own, and only pass3a-facts.md knows which.
-    If pass3a-facts.md lists no test files, write the testing guidance
-    in general terms ("a shared setup module under a test directory of
-    your choice") rather than naming a specific path.
-
-✅ If pass3a-facts.md shows `ApiClient` (`src/admin/api/apiClient.ts`) as
-   the response wrapper, write `src/admin/api/apiClient.ts` verbatim.
+or extrapolation from symbol names. The three most common hallucination
+failures are described below by MECHANISM (not by literal example path,
+because literal examples in educational prose have historically leaked
+into generated outputs as real claims):
+
+❌ **Framework-convention entry-point invention.**
+  Citing a framework's stock entry-point file (Vite's main module, Next.js
+  app-router files, Spring's default resource config, etc.) because the
+  framework docs show that as the canonical location. This project may use
+  a different entry, a renamed entry, or a multi-entry layout where no
+  single canonical file exists. Check pass3a-facts.md; if no such path is
+  listed, do NOT write it.
+
+❌ **Parent-directory or constant-name renormalization of a filename.**
+  Inventing a filename by prepending the parent directory's name to it
+  (the <dirname><actual-basename>.ts anti-pattern), or by converting a
+  TypeScript constant / Java annotation / Python decorator name into
+  a filename (an ALL_CAPS_CONSTANT becoming a camelCase or PascalCase
+  filename). Identifiers and filenames are independent. The
+  authoritative filename is whatever pass3a-facts.md lists under the
+  relevant section — use that verbatim, do not "normalize" it.
+
+❌ **Plausibly-named utility invention.**
+  Writing a concrete filename for a utility that "would naturally" exist
+  under a seen directory (a class-name-builder helper under a `utils/`
+  directory, a string-formatter under a `helpers/` directory). "Plausible"
+  is not a sufficient ground for a concrete path claim. If you want to
+  reference a utility layer in a rule file, reference the directory
+  itself rather than inventing a filename.
+
+❌ Library-convention canonical paths (testing / env typing / styling /
+   state management / routing conventions) — invented based on framework
+   or library documentation.
+  — Testing frameworks (MSW, Vitest, Jest, RTL) show canonical mock /
+    setup / test-utility locations in their docs; TypeScript + Vite /
+    CRA show a canonical `ImportMetaEnv` augmentation location; CSS-in-JS
+    and state-management libraries show canonical store / theme
+    locations. These are PROJECT-CHOICE files — every project picks its
+    own structure, and the library's canonical path may not exist here.
+    **Scope note (v2.3.2+):** this trap fires whenever the topic of a
+    generated file touches these areas (testing, env typing, styling,
+    state management), not only when the file is named after the topic.
+    It fires in `ai-work-rules.md`, onboarding guides, infra rules,
+    CRUD skills — anywhere the topic appears. If pass3a-facts.md lacks
+    the concrete file, describe the pattern by role ("a shared setup
+    module under a test directory of your choice", "augment
+    `ImportMetaEnv` in a type-declaration file of your choosing"), not
+    by filename. When illustrating bad path habits as an educational
+    example in a rule, use abstract placeholders (`{placeholder}`,
+    `src/*/dir/…`) rather than literal paths — literal example paths
+    are interpreted as real claims by `content-validator [10/10]`
+    regardless of surrounding prose.
+
+❌ **Hypothetical / future-tense framing is NOT a loophole (v2.3.2+).**
+  Wrapping a framework-canonical path in conditional or future-tense
+  language (`if we adopted X`, `were this feature introduced, it
+  would live at …`, `for a future Y`, `when Z is added later`, etc.,
+  in ANY output language — translated conditional phrases do not
+  change the validator's literal-path detection) does NOT make the
+  literal path safe. The validator is content-blind and will flag
+  ``if middleware is added later, place it at `src/middleware.ts` ``
+  as a `STALE_PATH` advisory because the file does not exist on disk.
+  This is the Next.js / Vite / Spring blind spot: the LLM, when
+  discussing future extensions, reaches for the framework's canonical
+  path as the "natural" location and writes it verbatim. The correct
+  hypothetical form describes the ROLE or DIRECTORY without
+  committing to a filename (e.g., "If middleware is added, place it
+  at the path the routing convention expects — do not cite a
+  specific filename until the file actually exists"). When in doubt,
+  OMIT the hypothetical example entirely; an omitted example is
+  better than a fabricated path readers may treat as authoritative.
+
+✅ If pass3a-facts.md shows a specific filename and path for a role
+   (e.g., a response-wrapper module at a specific location under the
+   api directory), write that exact path verbatim — do not re-describe
+   it, do not abbreviate it, do not rename it.
 
 ✅ When in doubt, write the rule in terms of the pattern (e.g., "handwritten
-   API modules under `src/admin/api/`") rather than a specific file name.
+   API modules under the api directory listed in pass3a-facts.md") rather
+   than a specific file name invented on the spot.
    A directory-scoped rule is correct; an invented file path is a bug.
 
 ✅ For testing-strategy documents specifically: if the project has zero