@rubytech/create-maxy-code 0.1.177 → 0.1.179

package/payload/premium-plugins/writer-craft/mcp/src/index.ts

@@ -55,7 +55,7 @@ const zFormat = z.enum([...FORMAT_VALUES] as [string, ...string[]]).describe(
 
 server.tool(
   "voice-tag-content",
-  "Stamp authorshipMode (and optionally format) on one or many content nodes (:KnowledgeDocument | :Message | :SocialPost) the operator owns. Email threads live as :KnowledgeDocument {source:'email'} since Task 321. Valid modes: human-only, human-led-agent-assisted, agent-led-human-reviewed, agent-only, unknown. Valid formats: text, email, social-post, article, marketing-copy, note. When format is omitted, it is derived per-node from labels and source property.",
+  "Stamp authorshipMode and format on one or many content nodes (:KnowledgeDocument | :Message | :SocialPost) the operator owns. Email threads live as :KnowledgeDocument {source:'email'} since Task 321. Valid modes: human-only, human-led-agent-assisted, agent-led-human-reviewed, agent-only, unknown. Valid formats: text, email, social-post, article, marketing-copy, note. format is editorial — the operator chooses it per node; the tool does not infer it.",
   {
     nodeIds: z.array(z.string()).min(1).describe("Element IDs of nodes to tag"),
     mode: z
@@ -67,8 +67,8 @@ server.tool(
         "unknown",
       ])
       .describe("Authorship mode to apply"),
-    format: zFormat.optional().describe(
-      "Writing format. When omitted, derived from each node's labels and source property.",
+    format: zFormat.describe(
+      "Writing format. Required — the operator's editorial classification of the content.",
     ),
   },
   async ({ nodeIds, mode, format }) => {
@@ -78,13 +78,13 @@ server.tool(
         nodeIds,
         mode: mode as AuthorshipMode,
         accountId,
-        format: format as import("./lib/voice-corpus.js").VoiceFormat | undefined,
+        format: format as import("./lib/voice-corpus.js").VoiceFormat,
       });
       return {
         content: [
           {
             type: "text" as const,
-            text: `voice-tag: mode=${mode} format=${format ?? "derived"} updated=${result.updated} skipped=${result.skipped}`,
+            text: `voice-tag: mode=${mode} format=${format} updated=${result.updated} skipped=${result.skipped}`,
           },
         ],
       };

package/payload/premium-plugins/writer-craft/mcp/src/lib/voice-corpus.ts

@@ -59,7 +59,10 @@ export const TAGGABLE_PRIMARY_LABELS = [
  * Closed enum of writing-format values. One `:VoiceProfile` exists per
  * `(accountId, userId, format)`. Adding a new value is a separate task.
  *
- * `marketing-copy` has no auto-derivation path — operator-tagged only.
+ * Format is an editorial classification set by the operator at tag time.
+ * The only auto-tagged path is `voice-ingest-session-text`, which hard-codes
+ * `format='text'` on `:Message` because chat turns are unambiguously text and
+ * the operator is not in the loop on session end.
  */
 export const FORMAT_VALUES = [
   "text",
@@ -84,43 +87,3 @@ export type VoiceFormat = (typeof FORMAT_VALUES)[number];
 export function voiceCorpusWhereWithFormat(format: VoiceFormat): string {
   return `${VOICE_CORPUS_WHERE}\n  AND n.format = $format`;
 }
-
-/**
- * Derives the default writing format for a corpus node from its labels
- * and properties. Used by ingest writers and `voice-tag-content` when the
- * operator does not specify a format explicitly.
- *
- * Derivation rules (first match wins):
- *
- *   | Node shape                                                  | format        |
- *   |-------------------------------------------------------------|---------------|
- *   | :Message                                                    | 'text'        |
- *   | :SocialPost                                                 | 'social-post' |
- *   | :KnowledgeDocument {source:'email'}                         | 'email'       |
- *   | :ConversationArchive {source:'email'}                        | 'email'       |
- *   | :KnowledgeDocument (non-email), body.length > 1500          | 'article'     |
- *   | :KnowledgeDocument (non-email), body.length ≤ 1500          | 'note'        |
- *   | :Section (conversation-document chunk)                      | 'text'        |
- *   | fallback                                                    | 'text'        |
- *
- * `marketing-copy` has no auto-derivation path.
- */
-export function deriveFormat(
-  labels: string[],
-  source?: string | null,
-  body?: string | null,
-): VoiceFormat {
-  if (labels.includes("Message")) return "text";
-  if (labels.includes("SocialPost")) return "social-post";
-  if (
-    (labels.includes("KnowledgeDocument") || labels.includes("ConversationArchive")) &&
-    source === "email"
-  ) {
-    return "email";
-  }
-  if (labels.includes("KnowledgeDocument")) {
-    return (body?.length ?? 0) > 1500 ? "article" : "note";
-  }
-  // :Section (conversation-document chunk) and any other label → text.
-  return "text";
-}

package/payload/premium-plugins/writer-craft/mcp/src/tools/voice-distil-profile.ts

@@ -187,15 +187,39 @@ async function distilForFormat(
     }
 
     // 4. Sample corpus bodies up to the char cap. Pick recent first.
+    //
+    // Body resolution (Task 471):
+    //   - For a :KnowledgeDocument with HAS_SECTION children, concatenate
+    //     child :Section bodies in `position` order — KD.body itself is
+    //     null after the Task 465 server-slicing change.
+    //   - Other labels (:Message, :SocialPost, :Section chat chunks) read
+    //     n.body directly via the existing COALESCE fallback chain.
+    //
+    // `collect(s.body)` is null-skipping in Cypher, so KDs with no children
+    // produce sectionBodies = [] and fall through to the COALESCE branch
+    // correctly. The `usedSectionWalk` flag is returned for per-exemplar
+    // observability.
     const sampled = await session.run(
       `MATCH (n)
        WHERE ${corpusWhere}
        WITH n, coalesce(n.dateSent, n.datePublished, n.firstMessageAt, n.dateCreated, n.createdAt) AS ts
        OPTIONAL MATCH (parent:KnowledgeDocument)-[:HAS_SECTION]->(n)
        WHERE 'Section' IN labels(n) AND parent.conversationIdentity IS NOT NULL
+       WITH n, ts, parent
+       OPTIONAL MATCH (n)-[:HAS_SECTION]->(s:Section)
+       WITH n, ts, parent, s ORDER BY s.position
+       WITH n, ts, parent, collect(s.body) AS sectionBodies
+       WITH n, ts, parent,
+            'KnowledgeDocument' IN labels(n) AND size(sectionBodies) > 0 AS usedSectionWalk,
+            CASE
+              WHEN 'KnowledgeDocument' IN labels(n) AND size(sectionBodies) > 0
+                THEN reduce(acc = '', b IN sectionBodies | acc + b + '\n\n')
+              ELSE coalesce(n.body, n.abstract, n.subject, n.title, n.summary, '')
+            END AS body
        RETURN elementId(n) AS id,
               labels(n) AS labels,
-              coalesce(n.body, n.abstract, n.subject, n.title, n.summary, '') AS body,
+              body,
+              usedSectionWalk,
               parent.conversationIdentity IS NOT NULL AS isConversationChunk,
               ts
        ORDER BY ts IS NULL, ts DESC
@@ -203,11 +227,14 @@ async function distilForFormat(
       { accountId, format },
     );
     const samples: { id: string; label: string; body: string }[] = [];
+    let sectionWalkCount = 0;
+    let nBodyCount = 0;
     let charBudget = SAMPLE_CHAR_CAP;
     for (const r of sampled.records) {
       const body = (r.get("body") as string | null) ?? "";
       const labels = (r.get("labels") as string[]) ?? [];
       const isConversationChunk = Boolean(r.get("isConversationChunk"));
+      const usedSectionWalk = Boolean(r.get("usedSectionWalk"));
       const label = isConversationChunk
         ? "Conversation"
         : (labels.find((l) =>
@@ -216,6 +243,8 @@ async function distilForFormat(
       if (body.length === 0) continue;
       const trimmed = body.length > charBudget ? body.slice(0, charBudget) : body;
       samples.push({ id: r.get("id") as string, label, body: trimmed });
+      if (usedSectionWalk) sectionWalkCount += 1;
+      else nBodyCount += 1;
       charBudget -= trimmed.length;
       if (charBudget <= 0) break;
     }
@@ -235,7 +264,8 @@ async function distilForFormat(
     if (mode === "sample") {
       process.stderr.write(
         `[voice-distil] adminUser=${userId} format=${format} mode=sample corpusSize=${corpusSize} ` +
-          `exemplars=${samples.length} feedbackEntries=${feedbackIntents.length}\n`,
+          `exemplars=${samples.length} feedbackEntries=${feedbackIntents.length} ` +
+          `sample-body-source=section-walk:${sectionWalkCount} n.body:${nBodyCount}\n`,
       );
       return {
         profileId: prevProfileId,

package/payload/premium-plugins/writer-craft/mcp/src/tools/voice-retrieve-conditioning.ts

@@ -97,27 +97,47 @@ export async function voiceRetrieveConditioning(
     const styleCard = (profile.records[0]?.get("styleCard") as string | null) ?? null;
 
     // 2. Exemplars — filtered to brief.format. Keyword-aware when topic is set.
+    //
+    // Body resolution (Task 471):
+    //   - For :KnowledgeDocument with HAS_SECTION children, concatenate
+    //     child :Section bodies in `position` order. KD.body is null after
+    //     Task 465 server-slicing.
+    //   - Other labels read n.body directly via the COALESCE fallback chain.
+    //
+    // The topic filter runs against the computed body, so a topic that
+    // appears only in n.summary (LLM abstract) no longer matches — by
+    // design: the corpus surfaces verbatim prose, not the abstract.
     const topic = (brief.topic ?? "").trim();
     const usesTopic = topic.length > 0;
 
+    const bodyComputeBlock = `WITH n, coalesce(n.dateSent, n.datePublished, n.firstMessageAt, n.dateCreated, n.createdAt) AS ts
+         OPTIONAL MATCH (n)-[:HAS_SECTION]->(s:Section)
+         WITH n, ts, s ORDER BY s.position
+         WITH n, ts, collect(s.body) AS sectionBodies
+         WITH n, ts, CASE
+           WHEN 'KnowledgeDocument' IN labels(n) AND size(sectionBodies) > 0
+             THEN reduce(acc = '', b IN sectionBodies | acc + b + '\n\n')
+           ELSE coalesce(n.body, n.abstract, n.subject, n.title, n.summary, '')
+         END AS body`;
+
     const cypher = usesTopic
       ? `MATCH (n)
          WHERE ${corpusWhere}
-           AND toLower(coalesce(n.body, n.abstract, n.subject, n.title, n.summary, '')) CONTAINS toLower($topic)
-         WITH n, coalesce(n.dateSent, n.datePublished, n.firstMessageAt, n.dateCreated, n.createdAt) AS ts
+         ${bodyComputeBlock}
+         WHERE toLower(body) CONTAINS toLower($topic)
          RETURN elementId(n) AS id,
                 labels(n) AS labels,
-                coalesce(n.body, n.abstract, n.subject, n.title, n.summary, '') AS body,
+                body,
                 coalesce(n.subject, n.title, n.name, '') AS source,
                 ts
          ORDER BY ts IS NULL, ts DESC
          LIMIT $k`
       : `MATCH (n)
          WHERE ${corpusWhere}
-         WITH n, coalesce(n.dateSent, n.datePublished, n.firstMessageAt, n.dateCreated, n.createdAt) AS ts
+         ${bodyComputeBlock}
          RETURN elementId(n) AS id,
                 labels(n) AS labels,
-                coalesce(n.body, n.abstract, n.subject, n.title, n.summary, '') AS body,
+                body,
                 coalesce(n.subject, n.title, n.name, '') AS source,
                 ts
          ORDER BY ts IS NULL, ts DESC

package/payload/premium-plugins/writer-craft/mcp/src/tools/voice-tag-content.ts

@@ -1,18 +1,16 @@
 /**
- * voice-tag-content — set `authorshipMode` (and optionally `format`) on one
- * or many content nodes.
+ * voice-tag-content — set `authorshipMode` and `format` on one or many
+ * content nodes.
  *
  * The tool routes through neo4j directly with an account-scoped MERGE so
  * the operator can only mutate their own nodes. We do not go through
  * `memory-update` because that tool re-embeds and re-validates on every
  * call — overkill for a single-property authorship stamp.
  *
- * Format stamping (Task 462):
- *   - When `format` is provided: validated against FORMAT_VALUES and written
- *     to `n.format` alongside `authorshipMode`.
- *   - When `format` is omitted: a Cypher CASE expression derives format from
- *     each node's labels and `source` property, matching the `deriveFormat()`
- *     rule table in voice-corpus.ts. This keeps tag and ingest in lockstep.
+ * `format` is an editorial classification only the operator can set; it is
+ * therefore required. The sole hard-coded exception lives in
+ * `voice-ingest-session-text`, which stamps `format='text'` on auto-ingested
+ * `:Message` rows where the operator is not in the loop (Task 471).
  */
 import { getSession } from "../lib/neo4j.js";
 import {
@@ -40,8 +38,8 @@ export interface VoiceTagContentParams {
   nodeIds: string[];
   mode: AuthorshipMode;
   accountId: string;
-  /** Optional format. When omitted, derived from each node's labels. */
-  format?: VoiceFormat;
+  /** Writing format (required). Editorial classification — operator-supplied. */
+  format: VoiceFormat;
 }
 
 export interface VoiceTagContentResult {
@@ -50,18 +48,6 @@ export interface VoiceTagContentResult {
   skippedReasons: Record<string, number>;
 }
 
-// Cypher CASE expression that mirrors deriveFormat() for in-query derivation.
-// Used when the caller does not supply an explicit format.
-const FORMAT_DERIVE_CASE = `CASE
-  WHEN 'Message' IN labels(n) THEN 'text'
-  WHEN 'SocialPost' IN labels(n) THEN 'social-post'
-  WHEN ('KnowledgeDocument' IN labels(n) OR 'ConversationArchive' IN labels(n))
-       AND n.source = 'email' THEN 'email'
-  WHEN 'KnowledgeDocument' IN labels(n) AND size(coalesce(n.body, '')) > 1500 THEN 'article'
-  WHEN 'KnowledgeDocument' IN labels(n) THEN 'note'
-  ELSE 'text'
-END`;
-
 export async function voiceTagContent(
   params: VoiceTagContentParams,
 ): Promise<VoiceTagContentResult> {
@@ -77,7 +63,10 @@ export async function voiceTagContent(
   if (!accountId) {
     throw new Error("voice-tag-content: accountId is required");
   }
-  if (format !== undefined && !(FORMAT_VALUES as readonly string[]).includes(format)) {
+  if (format === undefined || format === null) {
+    throw new Error("voice-tag-content: format is required");
+  }
+  if (!(FORMAT_VALUES as readonly string[]).includes(format)) {
     throw new Error(
       `voice-tag-content: invalid format '${format}'. Valid values: ${FORMAT_VALUES.join(", ")}`,
     );
@@ -97,16 +86,12 @@ export async function voiceTagContent(
     for (let i = 0; i < nodeIds.length; i += BATCH) {
       const batch = nodeIds.slice(i, i + BATCH);
       const result = await session.run(
-        // Tag any of the four primary content labels, or a conversation-
+        // Tag any of the three primary content labels, or a conversation-
         // document :Section chunk (parent :KnowledgeDocument carries
         // `conversationIdentity`). The EXISTS sub-pattern guards against
         // accidentally tagging document-path :Section rows AND parent
         // `:Conversation` / `:AdminConversation` nodes (which are not
         // body-bearing content).
-        //
-        // Format is either the caller-supplied constant ($format is non-null)
-        // or derived per-node via the CASE expression that mirrors
-        // deriveFormat() in voice-corpus.ts.
         `UNWIND $ids AS id
          MATCH (n) WHERE elementId(n) = id AND n.accountId = $accountId
          WITH n
@@ -117,14 +102,14 @@ export async function voiceTagContent(
                })
          SET n.authorshipMode = $mode,
              n.authorshipTaggedAt = $now,
-             n.format = CASE WHEN $format IS NOT NULL THEN $format ELSE ${FORMAT_DERIVE_CASE} END
+             n.format = $format
          RETURN elementId(n) AS id`,
         {
           ids: batch,
           accountId,
           mode,
           now,
-          format: format ?? null,
+          format,
           primaryLabels: [...TAGGABLE_PRIMARY_LABELS],
         },
       );
@@ -141,7 +126,7 @@ export async function voiceTagContent(
   }
 
   process.stderr.write(
-    `[voice-tag] mode=${mode} format=${format ?? "derived"} accountId=${accountId} updated=${updated} skipped=${
+    `[voice-tag] mode=${mode} format=${format} accountId=${accountId} updated=${updated} skipped=${
       nodeIds.length - updated
     }\n`,
   );

package/payload/premium-plugins/writer-craft/skills/voice-mirror/SKILL.md

@@ -11,7 +11,7 @@ The skill is built on five deterministic MCP tools served by the `writer-craft`
 
 | Tool | Purpose |
 |------|---------|
-| `voice-tag-content` | Stamp historical or new content nodes with `authorshipMode` and derived `format`. Bulk-tags arrays of node ids. |
+| `voice-tag-content` | Stamp historical or new content nodes with `authorshipMode` and operator-supplied `format`. Bulk-tags arrays of node ids. |
 | `voice-distil-profile` | Walk the operator's `human-only` corpus for a given `format` and produce a `:VoiceProfile {styleCard, generatedAt, corpusSize, feedbackEntries, format}` node. Without a `format`, enumerates all formats present in the corpus and distils each. |
 | `voice-retrieve-conditioning` | Return `{styleCard, exemplars[]}` for a drafting brief. Requires `brief.format` (one of the six corpus formats). K=5 for short-form, K=15 for long-form. Token-budget bounded. |
 | `voice-record-feedback` | When the operator edits an agent draft, write a `:VoiceEdit {originalText, editedText, intent, occurredAt, format}-[:FEEDBACK_FOR]->(:VoiceProfile {format})` node. The `intent` field is a Haiku-summarised diff. |
@@ -37,16 +37,16 @@ Do **not** activate for:
 
 Voice profiles are segmented by content format. The closed enum is:
 
-| Format | Derived from |
-|--------|-------------|
-| `text` | `:Message` nodes, operator PTY turns (auto-ingested via SessionEnd hook) |
-| `email` | `:KnowledgeDocument {source:'email'}`, `:ConversationArchive {source:'email'}` |
+| Format | Operator picks for |
+|--------|--------------------|
+| `text` | `:Message` nodes; the SessionEnd hook stamps this automatically on operator PTY turns (the sole hard-coded path — chat turns are unambiguously text and the operator is not in the loop on session end) |
+| `email` | Email threads stored as `:KnowledgeDocument {source:'email'}` or `:ConversationArchive {source:'email'}` |
 | `social-post` | `:SocialPost` nodes |
-| `article` | `:KnowledgeDocument` with body > 1,500 chars |
-| `note` | `:KnowledgeDocument` with body ≤ 1,500 chars |
-| `marketing-copy` | No automatic derivation path — tag explicitly via `voice-tag-content` |
+| `article` | Long-form `:KnowledgeDocument` the operator considers an article |
+| `note` | Short-form `:KnowledgeDocument` the operator considers a note |
+| `marketing-copy` | Any node the operator considers marketing copy |
 
-Format is derived automatically when tagging via `voice-tag-content`. Pass `format` explicitly to override the derivation.
+Format is editorial — the operator picks it per node when calling `voice-tag-content`. The tool does not infer it.
 
 ## Flow — backfill review (one-shot session)
 
@@ -63,19 +63,16 @@ Ask the operator which stream to backfill first. Default to chat archives when t
 
 ### 2a. Discrete documents — paginate in batches of 10
 
-Query for `:KnowledgeDocument | :SocialPost | :Message` nodes belonging to this operator's account whose `authorshipMode` is `unknown`. Order by `dateSent | datePublished | dateCreated` descending — most recent first. For each batch, surface a numbered list with: source label, date, recipient or topic, and a one-line preview (first ~120 chars of body). Offer bulk shortcuts:
+Query for `:KnowledgeDocument | :SocialPost | :Message` nodes belonging to this operator's account whose `authorshipMode` is `unknown`. Order by `dateSent | datePublished | dateCreated` descending — most recent first. For each batch, surface a numbered list with: source label, date, recipient or topic, and a one-line preview (first ~120 chars of body). Operator commands name both mode and format:
 
-- `1-10 human-only` — tag every item in the batch as `human-only` with auto-derived format.
-- `1-10 human-only article` — tag the whole batch as `human-only` and force format to `article`.
-- `1,3,7 human-only` — tag a subset.
-- `2 human-led-agent-assisted` — single-item mode override.
-- `5 agent-led-human-reviewed marketing-copy` — single-item mode and format override.
+- `1-10 human-only article` — tag every item in the batch as `human-only` with format `article`.
+- `1,3,7 human-only email` — tag a subset with mode + format.
+- `2 human-led-agent-assisted note` — single-item.
+- `5 agent-led-human-reviewed marketing-copy` — single-item.
 - `skip` — leave the batch as `unknown` and advance.
 - `stop` — exit the backfill; the next session resumes from where the operator left off.
 
-The tool derives `format` automatically from node labels and properties. Show the derived format alongside each item's preview so the operator can spot misclassifications. Append a format token to any batch or single-item command to override the derivation.
-
-Bulk-tag via `voice-tag-content` once per operator response. Emit `[voice-tag] mode=<mode> format=<format> count=<n>` per write.
+`format` is required on every command; the tool will not infer it. If the operator omits the format, ask before tagging. Bulk-tag via `voice-tag-content` once per operator response. Emit `[voice-tag] mode=<mode> format=<format> count=<n>` per write.
 
 ### 2b. Chat archives — paginate per conversation-document parent
 
@@ -86,7 +83,7 @@ For each conversation-document `:KnowledgeDocument` (with `conversationIdentity`
 - `not me` — tag every chunk as `agent-only` (e.g. a Slack channel where the operator only forwarded other people's messages).
 - `skip` / `stop` — same semantics as 2a.
 
-Bulk-tag via `voice-tag-content` with the list of `:Section` element IDs the conversation-document contains. The skill emits `[voice-tag] mode=<mode> format=<format> count=<chunk-count>` once per conversation.
+Bulk-tag via `voice-tag-content` with the list of `:Section` element IDs the conversation-document contains, passing `format='text'` (chat archives are unambiguously text-format). The skill emits `[voice-tag] mode=<mode> format=<format> count=<chunk-count>` once per conversation.
 
 Authorship at conversation granularity is a deliberate UX trade-off: chunks within a conversation almost always share the same operator's voice, and per-chunk tagging at archive scale would burn the operator's attention. The `mixed` opt-in covers the rare case where it matters.