From 37fa107d92a6db9db39ceda07f62931226a35961 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 25 Jun 2026 05:45:40 +0000
Subject: [PATCH 1/6] Use Qwen3-Coder-30B-A3B-Instruct-UD-Q4_K_XL for both AI
 summary phases

Add a single aiDefinition (key Qwen3-Coder-30B-A3B-Instruct-UD-Q4_K_XL-C64k)
pointing at the locally-present 17.7 GB UD-Q4_K_XL GGUF, and reference it from
both the ai-generate (file-body) and ai-aggregate-packages (package-body)
executions.

- contextSize 65536: generous but CPU-feasible (native 262144; 256k prefill
  is unusable on CPU).
- maxOutputTokens 1536: short dense bullet summaries, not long code gen.
- Official Qwen3-Coder sampling: temp 0.7 / top_p 0.8 / top_k 20 / repeat 1.05.
- Non-thinking model: no enable_thinking flag set.
- Remove the two stale Qwen3-Coder Q4_K_M entries (C32k/C256k) that pointed at
  a file not present locally; update the model-selection legend accordingly.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017i6A5bMhgCSbiKibQhxwuz
---
 pom.xml | 69 +++++++++++++++++++++++----------------------------------
 1 file changed, 28 insertions(+), 41 deletions(-)

diff --git a/pom.xml b/pom.xml
index 8894b19..8b061cd 100644
--- a/pom.xml
+++ b/pom.xml
@@ -840,18 +840,14 @@ SPDX-License-Identifier: Apache-2.0
                                       Gemma 4 entries; only pick Q6_K_P if Q4_K_M quality is visibly short.
                                     Use when: a light model keeps refusing, or you need the lightest Gemma 4.
 
-                                  Qwen3-Coder-30B-A3B-Instruct-Q4_K_M-C32k   (RECOMMENDED default for code)
-                                    + MoE 30B total / ~3B active: code-specialized AND fast on CPU; fewer
-                                      active params than Gemma-4-26B-A4B; Apache-2.0.
-                                    - 18.6 GB download; needs Qwen sampling (temp 0.7 / top_p 0.8 / top_k 20).
+                                  Qwen3-Coder-30B-A3B-Instruct-UD-Q4_K_XL-C64k   (RECOMMENDED default for code; ACTIVE for both phases)
+                                    + MoE 30B total / ~3.3B active: code-specialized AND fast on CPU; fewer
+                                      active params than Gemma-4-26B-A4B; non-thinking; Apache-2.0.
+                                    + Locally present (X:/Modelle/Qwen3-Coder-30B-A3B-Instruct-UD-Q4_K_XL.gguf,
+                                      17.7 GB); 64K context — generous but CPU-feasible (256K prefill is unusable on CPU).
+                                    - Needs Qwen sampling (temp 0.7 / top_p 0.8 / top_k 20 / repeat 1.05).
                                     Use when: this is the go-to for most code summarization on CPU.
 
-                                  Qwen3-Coder-30B-A3B-Instruct-Q4_K_M-C256k   (same file, huge window)
-                                    + Native 256K context; MoE + GQA keep the KV cache small (~+4.8 GB vs 32K).
-                                    - CPU PREFILL of a near-full window can take minutes; only worth it for
-                                      very large package roll-ups (Phase 2) or huge files.
-                                    Use when: a single input genuinely exceeds the 32K entries.
-
                                   Qwen2.5-Coder-14B-Instruct-Q4_K_M-C32k
                                     + The cited top LOCAL dense code model at the 16 GB tier; big step up
                                       from the 7B entry.
@@ -1110,36 +1106,27 @@ SPDX-License-Identifier: Apache-2.0
                                         <stopString>&lt;end_of_turn&gt;</stopString>
                                     </stopStrings>
                                 </aiDefinition>
-                                <!-- Qwen3-Coder-30B-A3B-Instruct-Q4_K_M (32 K context)
-                                     MoE 30B total / ~3B active, Apache-2.0. Code-specialized; fewer active
-                                     params than Gemma-4-26B-A4B, so a strong CPU pick. Qwen sampling:
-                                     temp 0.7, top_p 0.8, top_k 20, repeat_penalty 1.05.
-                                     Single-file GGUF (18.6 GB). Download:
-                                     https://huggingface.co/unsloth/Qwen3-Coder-30B-A3B-Instruct-GGUF/resolve/main/Qwen3-Coder-30B-A3B-Instruct-Q4_K_M.gguf -->
+                                <!-- Qwen3-Coder-30B-A3B-Instruct-UD-Q4_K_XL (64 K context) — the
+                                     locally-present file and the active model for BOTH AI phases
+                                     (file-body + package-body). MoE 30B total / ~3.3B active,
+                                     non-thinking (emits no <think> blocks, so no enable_thinking flag
+                                     is needed or set), Apache-2.0. Unsloth Dynamic UD-Q4_K_XL quant,
+                                     single-file GGUF (17.7 GB) at
+                                     X:/Modelle/Qwen3-Coder-30B-A3B-Instruct-UD-Q4_K_XL.gguf.
+                                     Official Qwen3-Coder sampling (model card): temperature 0.7,
+                                     top_p 0.8, top_k 20, repetition_penalty 1.05.
+                                     Context: native window is 262144; 64 K is a deliberate, generous
+                                     yet CPU-feasible cap — 256 K prefill is unusable on CPU.
+                                     maxOutputTokens is deliberately 1536 (NOT the model card's generic
+                                     65536): the purpose here is short, dense bullet-point summaries,
+                                     not long code generations, so a tight output cap keeps each
+                                     generation fast and on-topic.
+                                     https://huggingface.co/unsloth/Qwen3-Coder-30B-A3B-Instruct-GGUF -->
                                 <aiDefinition>
-                                    <key>Qwen3-Coder-30B-A3B-Instruct-Q4_K_M-C32k</key>
-                                    <modelPath>X:/Modelle/Qwen3-Coder-30B-A3B-Instruct-Q4_K_M.gguf</modelPath>
-                                    <contextSize>32768</contextSize>
-                                    <maxOutputTokens>2048</maxOutputTokens>
-                                    <temperature>0.7</temperature>
-                                    <threads>8</threads>
-                                    <charsPerToken>4</charsPerToken>
-                                    <warnOnTrim>true</warnOnTrim>
-                                    <retryTemperatureIncrement>0.0</retryTemperatureIncrement>
-                                    <topP>0.8</topP>
-                                    <topK>20</topK>
-                                    <repeatPenalty>1.05</repeatPenalty>
-                                </aiDefinition>
-                                <!-- Qwen3-Coder-30B-A3B-Instruct-Q4_K_M (256 K context)
-                                     Same single-file GGUF as above, opened to its native 256 K window.
-                                     MoE (~3B active) + GQA keeps the KV cache small (~+4.8 GB for 256 K vs 32 K),
-                                     so this stays the most practical LARGE-context CPU code option.
-                                     https://huggingface.co/unsloth/Qwen3-Coder-30B-A3B-Instruct-GGUF/resolve/main/Qwen3-Coder-30B-A3B-Instruct-Q4_K_M.gguf -->
-                                <aiDefinition>
-                                    <key>Qwen3-Coder-30B-A3B-Instruct-Q4_K_M-C256k</key>
-                                    <modelPath>X:/Modelle/Qwen3-Coder-30B-A3B-Instruct-Q4_K_M.gguf</modelPath>
-                                    <contextSize>262144</contextSize>
-                                    <maxOutputTokens>2048</maxOutputTokens>
+                                    <key>Qwen3-Coder-30B-A3B-Instruct-UD-Q4_K_XL-C64k</key>
+                                    <modelPath>X:/Modelle/Qwen3-Coder-30B-A3B-Instruct-UD-Q4_K_XL.gguf</modelPath>
+                                    <contextSize>65536</contextSize>
+                                    <maxOutputTokens>1536</maxOutputTokens>
                                     <temperature>0.7</temperature>
                                     <threads>8</threads>
                                     <charsPerToken>4</charsPerToken>
@@ -1313,7 +1300,7 @@ Source:
                                     <fieldGenerations>
                                         <fieldGeneration>
                                             <promptKey>file-body</promptKey>
-                                            <aiDefinitionKey>Gemma-4-26B-A4B-it-UD-Q4_K_M-C32k</aiDefinitionKey>
+                                            <aiDefinitionKey>Qwen3-Coder-30B-A3B-Instruct-UD-Q4_K_XL-C64k</aiDefinitionKey>
                                         </fieldGeneration>
                                     </fieldGenerations>
                                 </configuration>
@@ -1329,7 +1316,7 @@ Source:
                                     <fieldGenerations>
                                         <fieldGeneration>
                                             <promptKey>package-body</promptKey>
-                                            <aiDefinitionKey>Gemma-4-26B-A4B-it-UD-Q4_K_M-C32k</aiDefinitionKey>
+                                            <aiDefinitionKey>Qwen3-Coder-30B-A3B-Instruct-UD-Q4_K_XL-C64k</aiDefinitionKey>
                                         </fieldGeneration>
                                     </fieldGenerations>
                                 </configuration>

From 98dc92988c41b80db933bf2ee983450edfac1eb5 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 25 Jun 2026 05:46:55 +0000
Subject: [PATCH 2/6] Replace file-body prompt with structured multi-language
 code indexer

Swap the Java-centric prose file-summary prompt for a dense, section-based
multi-language indexer prompt (Java/C/C++/OpenCL/SQL) that emits a blockquote
lead plus fixed '####' sections (Purpose, Type, Input, Output, Core logic,
Public API, Dependencies, Exceptions/Errors). The File/Source %s placeholders
are unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017i6A5bMhgCSbiKibQhxwuz
---
 pom.xml | 63 +++++++++++++++++++++++++++++++++++----------------------
 1 file changed, 39 insertions(+), 24 deletions(-)

diff --git a/pom.xml b/pom.xml
index 8b061cd..61c60b4 100644
--- a/pom.xml
+++ b/pom.xml
@@ -1219,31 +1219,46 @@ SPDX-License-Identifier: Apache-2.0
                                 <promptDefinition>
                                     <key>file-body</key>
                                     <template><![CDATA[
-You generate a detailed markdown body section for a Java source file. Output the description directly as markdown prose. Do not wrap the output in XML tags, code fences, or any other delimiters.
+You are a multi-language code indexer. Produce a dense, structured markdown summary of ONE source file (Java, C/C++, OpenCL, SQL, or similar) for a searchable code index. Prioritize core logic and data flow. Avoid filler words. Write in English.
 
-Rules for the entire output:
-- Output markdown only.
-- Do not output explanations outside the body content.
-- Never return an empty response.
-- Start immediately with prose (no leading whitespace or empty lines).
-- The summary is already rendered inside a '###' heading (the filename). Do NOT start the summary with another heading. Use '####' or deeper headings only for subsections within the summary when the content is long enough to warrant internal structure.
-- The summary may be multiple lines.
-- The length should adapt to the file size and complexity.
-- Small files -> short summary.
-- Large or complex files -> longer, more detailed summary is allowed.
-- Do not use '###' or higher-level headings anywhere in the summary.
-- Do not wrap the summary in code fences.
-- Do not output ```markdown, ```java, or ```.
-- Do not output formatter comments like // @formatter:on or // @formatter:off.
-- For each public or protected method, include a brief one-line description of its purpose.
-- Integrate all relevant class names, interface names, annotation names, and domain-specific terms naturally into the prose — do NOT list them separately.
-- Focus the summary on purpose, behavior, important abstractions, and search-relevant terms woven into sentences.
-- Mention every directly extended class.
-- Mention every directly implemented interface.
-- Mention generic declarations and important generic types when present.
-- Do not mention standard Java methods unless they are meaningfully overridden or central to the class behavior.
-- Summarize recurring exception behavior across methods when relevant.
-- **IMPORTANT: If the source contains "[EOF - source was truncated]", the file is incomplete. Do NOT guess, invent, or hallucinate any methods, classes, fields, or code that is not explicitly present in the provided source. Only summarize what is actually shown.**
+## Output: start with the lead, then the sections below.
+Begin with a single blockquote line — one sentence capturing what this file does:
+> <one-sentence essence>
+
+Then output these sections as markdown. Omit any section that does not apply. Use '####' for section labels. Never use '###' or higher.
+
+#### Purpose
+One or two bullets: what the file/unit is for.
+
+#### Type
+Kind (class / interface / enum / record / header / kernel / SQL object) and language. For OO code: extends X; implements Y; key generics. For C: header vs implementation, exported vs static. For SQL: table / view / procedure / function / trigger.
+
+#### Input
+What comes in: key parameters, consumed fields, read resources (files, buffers, streams, kernels, tables/columns, env/config).
+
+#### Output
+What comes out: return types, produced state, written resources/tables, side effects.
+
+#### Core logic
+The essential steps / algorithm / responsibility as bullets. This is the most important section.
+
+#### Public API
+Each public/exported unit as `name(params) -> returnType` + a clause (max 6 words) on its purpose. For SQL: procedures/functions with params and result.
+
+#### Dependencies
+Imports / includes / referenced modules or tables, as searchable names.
+
+#### Exceptions / Errors
+Notable thrown/handled exceptions or error conditions.
+
+## Rules
+- Markdown bullets and short clauses, not prose paragraphs. Sentences allowed only where a bullet would lose meaning.
+- Weave class / type / table / domain names into the bullets so they are searchable.
+- No code fences, no ```markdown / ```java / ```sql, no XML tags, no formatter comments.
+- The filename heading is already rendered above your output. Start immediately with the blockquote lead. Never produce empty output.
+
+## Critical
+If the source contains "[EOF - source was truncated]", index ONLY what is literally present. Never infer, guess, or invent any unit, field, table, or behavior beyond the shown source.
 
 File: %s
 

From fa77da90ee921f99d7f6999f8f3bb7c260524051 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 25 Jun 2026 05:47:52 +0000
Subject: [PATCH 3/6] Replace package-body prompt with structured
 multi-language indexer

Swap the Java-centric prose package-summary prompt for a dense, section-based
multi-language indexer prompt that synthesizes the per-file summaries into a
blockquote lead plus fixed '####' sections (Purpose, Responsibilities, Key
units, Data flow, Dependencies, Cross-cutting). Both %s placeholders are
preserved (now labeled Package / File summaries).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017i6A5bMhgCSbiKibQhxwuz
---
 pom.xml | 63 +++++++++++++++++++++++++++++++++------------------------
 1 file changed, 37 insertions(+), 26 deletions(-)

diff --git a/pom.xml b/pom.xml
index 61c60b4..e8010d9 100644
--- a/pom.xml
+++ b/pom.xml
@@ -1269,34 +1269,45 @@ Source:
                                 <promptDefinition>
                                     <key>package-body</key>
                                     <template><![CDATA[
-You generate a detailed markdown body section for a Java package or package-like index. Output the description directly as markdown prose. Do not wrap the output in XML tags, code fences, or any other delimiters.
-
-Rules for the entire output:
-- Output markdown only.
-- Do not output explanations outside the body content.
-- Never return an empty response.
-- Start immediately with prose (no leading whitespace or empty lines).
-- The summary is already rendered inside a '###' heading (the package name). Do NOT start the summary with another heading. Use '####' or deeper headings only for subsections within the summary when the content is long enough to warrant internal structure.
-- The summary may be multiple lines.
-- The length should adapt to the size and complexity of the package.
-- Small packages -> short summary.
-- Large packages -> more detailed summary is allowed.
-- Do not use '###' or higher-level headings anywhere in the summary.
-- Do not wrap the summary in code fences.
-- Do not output ```markdown, ```java, or ```.
-- Do not output formatter comments like // @formatter:on or // @formatter:off.
-- For each contained file, include a brief one-line description of its purpose.
-- Integrate all relevant class names, interface names, annotation names, and domain-specific terms naturally into the prose — do NOT list them separately.
-- Focus the summary on the overall purpose, structure, responsibilities, and collaboration of the contained files.
-- Mention important directly extended classes and directly implemented interfaces if they are central and repeatedly represented in the package content.
-- Mention important generic declarations or important generic type patterns if they are central to the package design.
-- Summarize recurring exception behavior across the package when relevant.
-- For larger packages, group contained files by responsibility instead of listing every file.
-- **IMPORTANT: If the source contains "[EOF - source was truncated]", the index is incomplete. Do NOT guess, invent, or hallucinate any files, classes, or content that is not explicitly present in the provided source. Only summarize what is actually shown.**
+You are a multi-language code indexer. You receive the already-generated per-file summaries of all files in ONE package or directory (NOT raw source code). Produce one dense, structured markdown summary of the whole package for a searchable code index. Synthesize and group — do not just concatenate the file summaries. Avoid filler. Write in English.
 
-File: %s
+## Output: start with the lead, then the sections below.
+Begin with a single blockquote line — one sentence capturing what this package does as a whole:
+> <one-sentence essence>
 
-Source:
+Then output these sections as markdown. Omit any that do not apply. Use '####' for labels. Never '###' or higher.
+
+#### Purpose
+One or two bullets: the package's overall responsibility.
+
+#### Responsibilities
+The main functional groups inside the package, as bullets. Group files by role; do not list every file separately for large packages.
+
+#### Key units
+The central classes / interfaces / modules / SQL objects and their job, one clause each, with their searchable names.
+
+#### Data flow
+How inputs move through the package to outputs, if a clear pipeline or collaboration exists across the files.
+
+#### Dependencies
+Notable internal collaborations and external modules/packages/tables the package depends on.
+
+#### Cross-cutting
+Recurring patterns across files: shared base types/interfaces, common exception/error handling, threading/concurrency notes, configuration.
+
+## Rules
+- Markdown bullets and short clauses, not prose paragraphs.
+- Weave type / module / table / domain names in as searchable terms.
+- Base every statement only on the provided file summaries. Do NOT invent units, methods, tables, or behavior not present in them.
+- No code fences, no ```markdown, no XML tags, no formatter comments.
+- The package-name heading is already rendered above your output. Start immediately with the blockquote lead. Never empty.
+
+## Critical
+If the input contains "[EOF - source was truncated]", summarize ONLY what is present. Never infer or invent files or content beyond the provided summaries.
+
+Package: %s
+
+File summaries:
 %s
                                     ]]></template>
                                 </promptDefinition>

From c1f86061a966e7df5d1e9f25a4c5d184994495d7 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 25 Jun 2026 06:13:32 +0000
Subject: [PATCH 4/6] PackageIndexer: feed real child AI bodies into the
 package prompt source
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The package-body prompt expects the already-generated per-file summaries, but
buildPackageSourceText only emitted the package header plus a '#### Contents'
list of child file *names*. The model therefore had nothing to synthesise.

Embed each child .ai.md's actual AI body (per-file and sub-package summaries)
into the %s package source, each under a '### <name>' heading so the model can
attribute which summary belongs to which file. Only the child body is inlined;
the single-letter child header metadata is deliberately omitted to save context.

- Sub-package children reuse their aggregated package.ai.md body, labelled with
  a trailing '/'.
- Children with a blank/unreadable body get a '(no summary available)' note
  instead of a fabricated summary.
- When no child yields a usable body, fall back to the existing '#### Contents'
  name listing so the source is never empty.
- No bespoke truncation: the combined source flows through the existing
  AiPromptPreparationSupport.preparePrompt trim/warnOnTrim budget logic.
- The deterministic '#### Contents' fallback for the written package body is
  unchanged; package checksums (child name|c|d|x) are unaffected, so this does
  not trigger spurious regeneration.

The package-body prompt text is unchanged — the code now matches the prompt.

Add two PackageIndexerTest cases proving the %s source contains the real child
bodies (per-file and bubbled-up sub-package), via a capturing provider.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017i6A5bMhgCSbiKibQhxwuz
---
 .../aiindex/indexer/PackageIndexer.java       | 176 +++++++++++++++++-
 .../aiindex/indexer/PackageIndexerTest.java   | 119 ++++++++++++
 2 files changed, 290 insertions(+), 5 deletions(-)

diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/indexer/PackageIndexer.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/indexer/PackageIndexer.java
index 6a5551e..a86beda 100644
--- a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/indexer/PackageIndexer.java
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/indexer/PackageIndexer.java
@@ -49,6 +49,28 @@ public class PackageIndexer {
      */
     private static final String CONTENTS_HEADING = "#### Contents";
 
+    /**
+     * Markdown heading prefix used to label each child summary embedded in the package
+     * source text fed to the AI model, e.g. {@code "### Foo.java"}. Identifies which
+     * per-file (or sub-package) summary follows so the model can attribute it correctly.
+     * Independent from {@link AiMdHeaderCodec#HEADER_TITLE_PREFIX} despite the same literal:
+     * this one structures the AI <em>input</em>, not a persisted {@code .ai.md} header.
+     */
+    private static final String CHILD_SUMMARY_HEADING_PREFIX = "### ";
+
+    /**
+     * Suffix appended to a sub-package entry name so it is visually distinguishable from a
+     * regular file entry in content listings and child-summary labels (e.g. {@code "sub/"}).
+     */
+    private static final String CHILD_DIRECTORY_SUFFIX = "/";
+
+    /**
+     * Placeholder note emitted under a child-summary heading when the corresponding
+     * {@code .ai.md} body is blank or could not be read, so the model still learns the
+     * child exists without being given a fabricated summary.
+     */
+    private static final String CHILD_SUMMARY_MISSING_NOTE = "(no summary available)";
+
     /**
      * Earliest possible date value used as the starting point when scanning child nodes
      * to find the latest index creation date.
@@ -254,7 +276,7 @@ private void writePackageFile(final Path directory) throws IOException {
             return;
         }
 
-        final String sourceText = buildPackageSourceText(baseHeader, contents);
+        final String sourceText = buildPackageSourceText(baseHeader, directory, contents);
 
         final AiGenerationResult result = fieldGenerationSupport.processFieldGenerations(
                 fieldGenerations, packageFile, CONTEXT_TYPE_PACKAGE, sourceText, baseHeader);
@@ -283,7 +305,7 @@ private List<String> collectContents(final Path directory) throws IOException {
 
                 if (Files.isDirectory(path)) {
                     if (hasPackageAiMdFile(path)) {
-                        entries.add(name + "/");
+                        entries.add(name + CHILD_DIRECTORY_SUFFIX);
                     }
                     continue;
                 }
@@ -297,8 +319,59 @@ private List<String> collectContents(final Path directory) throws IOException {
         return entries;
     }
 
-    private String buildPackageSourceText(final AiMdHeader header, final Collection<String> contents) {
+    /**
+     * Builds the source text passed to the AI model for a package summary.
+     *
+     * <p>The text starts with the package's own deterministic header block, then embeds the
+     * <em>already-generated</em> AI body of every child {@code .ai.md} (per-file summaries and
+     * sub-package summaries), each under a {@link #CHILD_SUMMARY_HEADING_PREFIX} heading that
+     * names the child. This is what the {@code package-body} prompt expects: it synthesises a
+     * package summary from the child summaries, not from a bare name listing. Only the child
+     * bodies are inlined; the single-letter child headers (metadata) are deliberately omitted
+     * to save context and avoid distracting the model.</p>
+     *
+     * <p>When no child contributes a usable body (all blank or unreadable), the method falls
+     * back to the plain {@link #CONTENTS_HEADING} name listing so the model still receives the
+     * package contents.</p>
+     *
+     * <p>No explicit length cap is applied here: the combined text is subject to the existing
+     * trim logic in {@link net.ladenthin.maven.llamacpp.aiindex.prompt.AiPromptPreparationSupport#preparePrompt}, which truncates at a line
+     * boundary to the computed {@code maxInputChars} budget and triggers the {@code warnOnTrim}
+     * warning — so large packages degrade gracefully without a bespoke truncation scheme.</p>
+     *
+     * @param header    the package's own header (its title and metadata)
+     * @param directory the package directory whose child {@code .ai.md} bodies are embedded
+     * @param contents  pre-collected child entry names, used only for the no-body fallback
+     * @return the rendered source text for the AI prompt
+     * @throws IOException if a child {@code .ai.md} file cannot be read
+     */
+    private String buildPackageSourceText(
+            final AiMdHeader header, final Path directory, final Collection<String> contents) throws IOException {
         final StringBuilder builder = new StringBuilder();
+        appendPackageHeaderLines(builder, header);
+
+        final StringBuilder summaries = new StringBuilder();
+        final int bodyCount = appendChildSummaries(summaries, directory);
+
+        if (bodyCount > 0) {
+            builder.append(summaries);
+        } else {
+            // No child bodies were available — fall back to the plain name listing so the
+            // model still receives the package contents rather than an empty source.
+            appendContentsSection(builder, contents, true);
+        }
+
+        return builder.toString();
+    }
+
+    /**
+     * Appends the package's own deterministic header block (title plus single-letter fields)
+     * to {@code builder}, mirroring the on-disk {@code .ai.md} header layout.
+     *
+     * @param builder target string builder
+     * @param header  the package header to render
+     */
+    private void appendPackageHeaderLines(final StringBuilder builder, final AiMdHeader header) {
         builder.append(AiMdHeaderCodec.HEADER_TITLE_PREFIX)
                 .append(header.title())
                 .append('\n');
@@ -330,8 +403,101 @@ private String buildPackageSourceText(final AiMdHeader header, final Collection<
                 .append("X: ")
                 .append(header.x())
                 .append('\n');
-        appendContentsSection(builder, contents, true);
-        return builder.toString();
+    }
+
+    /**
+     * Appends one labelled child-summary block per child {@code .ai.md} under {@code directory}
+     * to {@code builder}, in deterministic ascending name order. Each block is a
+     * {@link #CHILD_SUMMARY_HEADING_PREFIX} heading naming the child followed by that child's
+     * already-generated AI body (or {@link #CHILD_SUMMARY_MISSING_NOTE} when the body is blank).
+     * Sub-package children reuse their aggregated {@code package.ai.md} body; the trailing
+     * {@link #CHILD_DIRECTORY_SUFFIX} marks them as directories.
+     *
+     * @param builder   target string builder
+     * @param directory the package directory whose children are scanned
+     * @return the number of children that contributed a non-blank body
+     * @throws IOException if a child {@code .ai.md} file cannot be read
+     */
+    private int appendChildSummaries(final StringBuilder builder, final Path directory) throws IOException {
+        int bodyCount = 0;
+
+        try (Stream<Path> stream = Files.list(directory)) {
+            for (Path path : compatibilityHelper.toList(stream.sorted(BY_FILE_NAME))) {
+                final Path fileNamePath = path.getFileName();
+                if (fileNamePath == null) {
+                    continue;
+                }
+                final String name = fileNamePath.toString();
+
+                if (Files.isDirectory(path)) {
+                    if (hasPackageAiMdFile(path)) {
+                        final String body = readChildBody(path.resolve(AiMdHeaderCodec.PACKAGE_AI_MD_FILENAME));
+                        if (appendChildSummary(builder, name + CHILD_DIRECTORY_SUFFIX, body)) {
+                            bodyCount++;
+                        }
+                    }
+                    continue;
+                }
+
+                if (isAiMdContentFile(name)) {
+                    final String body = readChildBody(path);
+                    if (appendChildSummary(builder, toChildDisplayName(name), body)) {
+                        bodyCount++;
+                    }
+                }
+            }
+        }
+
+        return bodyCount;
+    }
+
+    /**
+     * Appends a single child-summary block (heading plus body or missing-note) to {@code builder}.
+     *
+     * @param builder target string builder
+     * @param label   child display label (file or sub-package name)
+     * @param body    the child's AI body; may be blank
+     * @return {@code true} if a non-blank body was appended, {@code false} for the missing-note case
+     */
+    private boolean appendChildSummary(final StringBuilder builder, final String label, final String body) {
+        builder.append('\n').append(CHILD_SUMMARY_HEADING_PREFIX).append(label).append('\n');
+
+        if (compatibilityHelper.isBlank(body)) {
+            builder.append(CHILD_SUMMARY_MISSING_NOTE).append('\n');
+            return false;
+        }
+
+        builder.append(body);
+        if (!body.endsWith("\n")) {
+            builder.append('\n');
+        }
+        return true;
+    }
+
+    /**
+     * Reads and returns the AI body of a child {@code .ai.md} file, discarding its header.
+     *
+     * @param aiMdFile path to the child {@code .ai.md} file
+     * @return the document body (possibly blank); never {@code null}
+     * @throws IOException if the file cannot be read
+     */
+    private String readChildBody(final Path aiMdFile) throws IOException {
+        return documentCodec.read(aiMdFile).body();
+    }
+
+    /**
+     * Strips the {@link AiMdHeaderCodec#AI_MD_EXTENSION} suffix from a child file name so the
+     * embedded heading reads as the original source name (e.g. {@code "Foo.java.ai.md"} →
+     * {@code "Foo.java"}). Names without the extension are returned unchanged.
+     *
+     * @param fileName the child {@code .ai.md} file name
+     * @return the display name with the {@code .ai.md} extension removed
+     */
+    private String toChildDisplayName(final String fileName) {
+        if (fileName.endsWith(AiMdHeaderCodec.AI_MD_EXTENSION)) {
+            return fileName.substring(0, fileName.length() - AiMdHeaderCodec.AI_MD_EXTENSION.length());
+        }
+        return fileName;
     }
 
     private String buildDefaultPackageBody(final Collection<String> contents) {
diff --git a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/indexer/PackageIndexerTest.java b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/indexer/PackageIndexerTest.java
index 22b3300..ff8ff98 100644
--- a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/indexer/PackageIndexerTest.java
+++ b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/indexer/PackageIndexerTest.java
@@ -8,15 +8,20 @@
 import static org.hamcrest.CoreMatchers.notNullValue;
 import static org.hamcrest.MatcherAssert.assertThat;
 
+import java.io.IOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
 import net.ladenthin.maven.llamacpp.aiindex.CommonTestFixtures;
+import net.ladenthin.maven.llamacpp.aiindex.document.AiGenerationRequest;
 import net.ladenthin.maven.llamacpp.aiindex.document.AiMdDocument;
 import net.ladenthin.maven.llamacpp.aiindex.document.AiMdDocumentCodec;
 import net.ladenthin.maven.llamacpp.aiindex.document.AiMdHeader;
 import net.ladenthin.maven.llamacpp.aiindex.document.AiMdHeaderCodec;
 import net.ladenthin.maven.llamacpp.aiindex.prompt.AiPromptSupport;
+import net.ladenthin.maven.llamacpp.aiindex.provider.AiGenerationProvider;
 import net.ladenthin.maven.llamacpp.aiindex.provider.MockAiGenerationProvider;
 import org.apache.maven.plugin.logging.SystemStreamLog;
 import org.junit.jupiter.api.Test;
@@ -89,4 +94,118 @@ public void aggregate_singleChildFile_createsPackageAiMdFile() throws Exception
         assertThat(document.body().trim().isEmpty(), is(false));
     }
     // </editor-fold>
+
+    // <editor-fold defaultstate="collapsed" desc="child summaries in package source">
+    @Test
+    public void aggregate_childFileBodies_areEmbeddedInPackageSourceText() throws Exception {
+        // arrange
+        final Path temp = Files.createTempDirectory("ai-index-test");
+        final Path outputRoot = temp.resolve("ai");
+        final Path packageDirectory = outputRoot.resolve("main/java/com/example");
+        Files.createDirectories(packageDirectory);
+
+        writeChildFile(packageDirectory.resolve("Foo.java.ai.md"), "Foo.java", "FOO_BODY_MARKER summary of Foo.");
+        writeChildFile(packageDirectory.resolve("Bar.java.ai.md"), "Bar.java", "BAR_BODY_MARKER summary of Bar.");
+
+        final CapturingProvider provider = new CapturingProvider();
+        final AiPromptSupport promptSupport = new AiPromptSupport(CommonTestFixtures.createPackagePromptDefinitions());
+        final PackageIndexer indexer = new PackageIndexer(
+                new SystemStreamLog(),
+                temp,
+                outputRoot,
+                "1.0.0",
+                "0.0.0",
+                Collections.<Path>emptyList(),
+                false,
+                provider,
+                CommonTestFixtures.createPackageFieldGenerations(),
+                promptSupport,
+                CommonTestFixtures.createDefaultAiModelDefinitionSupport());
+
+        // act
+        indexer.aggregate(outputRoot);
+
+        // assert: the example package's AI source text contains both child bodies, each under a
+        // per-file heading — not merely the file names.
+        final String exampleSource = provider.sourceTextFor(packageDirectory.resolve("package.ai.md"));
+        assertThat(exampleSource, is(notNullValue()));
+        assertThat(exampleSource.contains("### Foo.java"), is(true));
+        assertThat(exampleSource.contains("FOO_BODY_MARKER summary of Foo."), is(true));
+        assertThat(exampleSource.contains("### Bar.java"), is(true));
+        assertThat(exampleSource.contains("BAR_BODY_MARKER summary of Bar."), is(true));
+        // the raw .ai.md file-name form must NOT leak into the labelled headings
+        assertThat(exampleSource.contains("### Foo.java.ai.md"), is(false));
+    }
+
+    @Test
+    public void aggregate_subPackageBody_isEmbeddedInParentSourceText() throws Exception {
+        // arrange: a child file in the leaf package, whose generated body bubbles up into the parent.
+        final Path temp = Files.createTempDirectory("ai-index-test");
+        final Path outputRoot = temp.resolve("ai");
+        final Path leafDirectory = outputRoot.resolve("main/java/com/example");
+        Files.createDirectories(leafDirectory);
+
+        writeChildFile(leafDirectory.resolve("Foo.java.ai.md"), "Foo.java", "FOO_BODY_MARKER summary of Foo.");
+
+        final CapturingProvider provider = new CapturingProvider();
+        final AiPromptSupport promptSupport = new AiPromptSupport(CommonTestFixtures.createPackagePromptDefinitions());
+        final PackageIndexer indexer = new PackageIndexer(
+                new SystemStreamLog(),
+                temp,
+                outputRoot,
+                "1.0.0",
+                "0.0.0",
+                Collections.<Path>emptyList(),
+                false,
+                provider,
+                CommonTestFixtures.createPackageFieldGenerations(),
+                promptSupport,
+                CommonTestFixtures.createDefaultAiModelDefinitionSupport());
+
+        // act
+        indexer.aggregate(outputRoot);
+
+        // assert: the parent ("com") package source embeds the leaf sub-package's generated body
+        // under a directory-suffixed heading.
+        final Path comPackageFile = outputRoot.resolve("main/java/com").resolve("package.ai.md");
+        final String comSource = provider.sourceTextFor(comPackageFile);
+        assertThat(comSource, is(notNullValue()));
+        assertThat(comSource.contains("### example/"), is(true));
+        assertThat(comSource.contains(CapturingProvider.GENERATED_BODY), is(true));
+    }
+    // </editor-fold>
+
+    private void writeChildFile(final Path file, final String title, final String body) throws IOException {
+        final AiMdHeader header = new AiMdHeader(
+                title,
+                AiMdHeaderCodec.HEADER_VERSION_1_0,
+                "AAAAAAAA",
+                "2026-03-16T00:00:00Z",
+                "2026-03-16T00:00:10Z",
+                "1.0.0",
+                "0.0.0",
+                AiMdHeaderCodec.NODE_TYPE_FILE);
+        documentCodec.write(file, new AiMdDocument(header, body));
+    }
+
+    /**
+     * Test {@link AiGenerationProvider} that records the source text passed for each context file
+     * and returns a fixed non-blank body, so a generated {@code package.ai.md} body is never blank.
+     */
+    private static final class CapturingProvider implements AiGenerationProvider {
+
+        static final String GENERATED_BODY = "CAPTURED_PACKAGE_SUMMARY";
+
+        private final Map<Path, String> sourceTextByFile = new HashMap<>();
+
+        @Override
+        public String generate(final AiGenerationRequest request) {
+            sourceTextByFile.put(request.sourceFile(), request.sourceText());
+            return GENERATED_BODY;
+        }
+
+        String sourceTextFor(final Path file) {
+            return sourceTextByFile.get(file);
+        }
+    }
 }

From 77c5d94f46b521c96325547648b07d4130395d89 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 25 Jun 2026 06:39:55 +0000
Subject: [PATCH 5/6] docs: correct stale PIT scope claim; add policy pointer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

README's TODO claimed PIT targetClasses was 'narrowed to a single class
(AiCompletionParser)' — stale; the pom now gates an explicit 21-class list
(~146 mutations). Update it and add the test-compile invocation + policy link.
Add a 'PIT Mutation Testing' pointer to the workspace policy in CLAUDE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017i6A5bMhgCSbiKibQhxwuz
---
 CLAUDE.md | 7 +++++++
 README.md | 2 +-
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 5103a17..3b0c7c7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -353,6 +353,13 @@ See [`../workspace/policies/jqwik-prompt-injection.md`](../workspace/policies/jq
 
 See [`../workspace/policies/ci-test-diagnostics.md`](../workspace/policies/ci-test-diagnostics.md).
 
+## PIT Mutation Testing
+
+See [`../workspace/policies/pit-mutation-testing.md`](../workspace/policies/pit-mutation-testing.md).
+Run PIT with the lifecycle prefix — `mvn test-compile org.pitest:pitest-maven:mutationCoverage`
+(the bare goal fails with `NoSuchFileException: {argLine}`). The gate covers an explicit
+21-class list at a 100% threshold.
+
 ## Lombok Config
 
 See [`../workspace/policies/lombok-config.md`](../workspace/policies/lombok-config.md).
diff --git a/README.md b/README.md
index d6a768b..d442bb1 100644
--- a/README.md
+++ b/README.md
@@ -178,7 +178,7 @@ src/site/ai/
 - Output quality depends on chosen model
 
 ## TODO
-- **Expand PIT mutation-testing scope.** PIT is wired in `pom.xml` and runs on every CI build with `<mutationThreshold>100</mutationThreshold>`, but `<targetClasses>` is currently narrowed to a single class (`AiCompletionParser`). The intent is to exercise the wiring and gate against regressions on that single class today; widen `<targetClasses>` incrementally as additional classes reach mutation-test parity (i.e., add tests until 100% mutation coverage holds on the candidate class, then add it to the list). Final target: `<param>net.ladenthin.maven.llamacpp.aiindex.*</param>` matching the streambuffer pattern.
+- **Expand PIT mutation-testing scope.** PIT is wired in `pom.xml` and runs on every CI build with `<mutationThreshold>100</mutationThreshold>`. `<targetClasses>` currently lists an explicit **21-class** set (config / document / prompt / provider / support classes verified at 100% mutation parity; ~146 mutations). Widen it incrementally as additional classes reach parity (add tests until 100% mutation coverage holds on the candidate, then add it to the list). Final target: `<param>net.ladenthin.maven.llamacpp.aiindex.*</param>` matching the streambuffer pattern. Run locally with `mvn test-compile org.pitest:pitest-maven:mutationCoverage` (see [PIT policy](../workspace/policies/pit-mutation-testing.md)).
 ## Recommended Models
 - Qwen2.5 Coder (balanced quality and speed)
 - Smaller instruct models for faster indexing

From 71c41c3c4a40bdfef6af3ae6ee5dc913c0360b76 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 25 Jun 2026 07:08:31 +0000
Subject: [PATCH 6/6] =?UTF-8?q?docs:=20unify=20PIT=20=E2=80=94=20generic?=
 =?UTF-8?q?=20content=20to=20workspace=20policy,=20keep=20repo=20specifics?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Slim the CLAUDE.md PIT pointer to the uniform cross-repo form. Trim the README
TODO to the repo-specific scope-expansion roadmap (toward the whole aiindex.*
tree) + a policy link, dropping drift-prone counts and generic mechanics. Trim
the pom PIT comment to a policy pointer plus the repo-specific rationale
(whole-tree targetTests, pure-Java MockAiGenerationProvider) and drop the stale
'pitest-maven 1.25.4'.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017i6A5bMhgCSbiKibQhxwuz
---
 CLAUDE.md |  4 +---
 README.md |  2 +-
 pom.xml   | 10 ++++------
 3 files changed, 6 insertions(+), 10 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 3b0c7c7..dc36e57 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -356,9 +356,7 @@ See [`../workspace/policies/ci-test-diagnostics.md`](../workspace/policies/ci-te
 ## PIT Mutation Testing
 
 See [`../workspace/policies/pit-mutation-testing.md`](../workspace/policies/pit-mutation-testing.md).
-Run PIT with the lifecycle prefix — `mvn test-compile org.pitest:pitest-maven:mutationCoverage`
-(the bare goal fails with `NoSuchFileException: {argLine}`). The gate covers an explicit
-21-class list at a 100% threshold.
+Run PIT with the lifecycle prefix — `mvn test-compile org.pitest:pitest-maven:mutationCoverage`.
 
 ## Lombok Config
 
diff --git a/README.md b/README.md
index d442bb1..4d56359 100644
--- a/README.md
+++ b/README.md
@@ -178,7 +178,7 @@ src/site/ai/
 - Output quality depends on chosen model
 
 ## TODO
-- **Expand PIT mutation-testing scope.** PIT is wired in `pom.xml` and runs on every CI build with `<mutationThreshold>100</mutationThreshold>`. `<targetClasses>` currently lists an explicit **21-class** set (config / document / prompt / provider / support classes verified at 100% mutation parity; ~146 mutations). Widen it incrementally as additional classes reach parity (add tests until 100% mutation coverage holds on the candidate, then add it to the list). Final target: `<param>net.ladenthin.maven.llamacpp.aiindex.*</param>` matching the streambuffer pattern. Run locally with `mvn test-compile org.pitest:pitest-maven:mutationCoverage` (see [PIT policy](../workspace/policies/pit-mutation-testing.md)).
+- **Expand PIT mutation-testing scope.** `<targetClasses>` in `pom.xml` lists an explicit subset of classes verified at 100% mutation parity; widen it incrementally toward the whole `net.ladenthin.maven.llamacpp.aiindex.*` tree (the streambuffer whole-package model) as more classes reach parity. Generic PIT setup and invocation: see the [PIT policy](../workspace/policies/pit-mutation-testing.md).
 ## Recommended Models
 - Qwen2.5 Coder (balanced quality and speed)
 - Smaller instruct models for faster indexing
diff --git a/pom.xml b/pom.xml
index e8010d9..54f8476 100644
--- a/pom.xml
+++ b/pom.xml
@@ -654,12 +654,10 @@ SPDX-License-Identifier: Apache-2.0
             </plugin>
             <plugin>
                 <!--
-                  PIT mutation testing is gated at a 100% threshold on every CI
-                  build over the explicit list of classes that have reached 100%
-                  mutation parity (verified with pitest-maven 1.25.4). Expand the
-                  targetClasses list as more classes reach parity (see README TODO).
-                  targetTests is the whole aiindex tree so any unit test may kill a
-                  mutant; all listed classes are covered by pure-Java tests
+                  Generic PIT policy (version, 100% gate, invocation, expansion rule):
+                  see ../workspace/policies/pit-mutation-testing.md.
+                  Repo-specific: targetTests is the whole aiindex tree (any unit test may
+                  kill a mutant); all gated classes are covered by pure-Java tests
                   (MockAiGenerationProvider — no GGUF model needed).
                 -->
                 <groupId>org.pitest</groupId>