@rubytech/create-maxy-code 0.1.179 → 0.1.182

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

@@ -25,6 +25,7 @@
  */
 import neo4j from "neo4j-driver";
 import { getSession } from "../lib/neo4j.js";
+import { notTrashed } from "../lib/voice-corpus.js";
 import {
   VOICE_CORPUS_WHERE,
   voiceCorpusWhereWithFormat,
@@ -61,21 +62,44 @@ export interface VoiceDistilProfileParams {
   userId: string;
   force?: boolean;
   /**
-   * Writing format to distil. When omitted, enumerates distinct format
-   * values in the corpus and distils each that fires the cadence guard.
+   * Writing format to distil. When omitted on `sample`, enumerates distinct
+   * format values in the corpus and distils each that fires the cadence
+   * guard. Required on `amend` and `write`.
    */
   format?: VoiceFormat;
   /**
-   * Operation mode (Task 424):
-   *   - `'sample'` (default) — read the corpus + feedback intents and return
-   *     them. No write. The calling agent composes the style-card YAML
-   *     in-turn from the returned exemplars.
-   *   - `'write'` — persist the style card the agent produced. Requires
-   *     `styleCardYaml`.
+   * Operation mode:
+   *   - `'sample'` (default, Task 424) — walk the full per-format corpus and
+   *     return exemplars + feedback intents. No write. The calling agent
+   *     composes the style-card YAML in-turn.
+   *   - `'write'` (Task 424) — persist the style card the agent produced.
+   *     Requires `styleCardYaml`. Optional `amendedFromNodeIds` adds
+   *     `LEARNED_FROM` edges to the named nodes (additive — MERGE preserves
+   *     prior edges).
+   *   - `'amend'` (Task 472) — operator-initiated incremental update from
+   *     one or more named documents. Reads only those nodes plus the
+   *     existing `:VoiceProfile.styleCard` so the agent can decide whether
+   *     the document moves the profile. Format predicate is dropped on the
+   *     read (the operator picked the docs); `authorshipMode` + trashed +
+   *     label predicates still apply per-document. Cadence guard does not
+   *     apply.
    */
-  mode?: "sample" | "write";
+  mode?: "sample" | "write" | "amend";
   /** Required when `mode='write'`. The style-card YAML produced by the agent. */
   styleCardYaml?: string;
+  /**
+   * Required when `mode='amend'`. ElementIds of the documents to fold into
+   * the profile. Each id is eligibility-checked; ineligible ones are
+   * reported in the return payload (the agent surfaces them to the operator).
+   */
+  nodeIds?: string[];
+  /**
+   * Optional on `mode='write'` after an `amend` sample. ElementIds the
+   * agent decided moved the profile. Each becomes a `LEARNED_FROM` edge
+   * from the persisted `:VoiceProfile`. Additive — pre-existing edges
+   * remain via `MERGE`.
+   */
+  amendedFromNodeIds?: string[];
 }
 
 export interface VoiceCorpusExemplar {
@@ -95,12 +119,27 @@ export interface VoiceDistilProfileResult {
     | "recent"
     | "empty-corpus"
     | "missing-style-card"
-    | "no-format-tagged-content";
+    | "no-format-tagged-content"
+    | "amend-no-eligible-documents";
   errorReason?: string;
-  /** Present when `mode='sample'`: corpus exemplars for the agent to read. */
+  /** Present when `mode='sample'` or `mode='amend'`: corpus exemplars for the agent to read. */
   exemplars?: VoiceCorpusExemplar[];
-  /** Present when `mode='sample'`: operator-edit intents to fold into the style card. */
+  /** Present when `mode='sample'` or `mode='amend'`: operator-edit intents to fold into the style card. */
   feedbackIntents?: string[];
+  /**
+   * Present when `mode='amend'`: the current `:VoiceProfile.styleCard` (or
+   * null if no profile exists yet) so the agent can compare the named
+   * documents against the prior card and decide update-or-skip.
+   */
+  existingStyleCard?: string | null;
+  /** Present when `mode='amend'`: count of input nodeIds that passed eligibility. */
+  eligible?: number;
+  /**
+   * Present when `mode='amend'`: per-input-id ineligibility records. Each
+   * entry names the nodeId and the first failing predicate so the agent
+   * can tell the operator which documents were rejected and why.
+   */
+  ineligible?: { nodeId: string; reason: string }[];
 }
 
 // The agent produces a YAML style card with at minimum these keys:
@@ -205,8 +244,10 @@ async function distilForFormat(
        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
+         AND ${notTrashed("parent")}
        WITH n, ts, parent
        OPTIONAL MATCH (n)-[:HAS_SECTION]->(s:Section)
+       WHERE ${notTrashed("s")}
        WITH n, ts, parent, s ORDER BY s.position
        WITH n, ts, parent, collect(s.body) AS sectionBodies
        WITH n, ts, parent,
@@ -336,6 +377,293 @@ async function distilForFormat(
   }
 }
 
+/**
+ * Single-document amend (Task 472).
+ *
+ * Operator-initiated incremental update: the operator names one or more
+ * documents (`nodeIds`), the tool reads only those plus the existing
+ * `:VoiceProfile.styleCard` for the format, and the calling agent decides
+ * whether the documents move the profile or don't. Same body-resolution
+ * and trashed/authorshipMode/label predicates as the full-corpus sample;
+ * the corpus-wide format predicate is dropped (the operator picked the
+ * docs); the cadence guard does not apply.
+ */
+async function amendForFormat(params: {
+  accountId: string;
+  userId: string;
+  format: VoiceFormat;
+  nodeIds: string[];
+}): Promise<VoiceDistilProfileResult> {
+  const { accountId, userId, format, nodeIds } = params;
+  const session = getSession();
+
+  try {
+    // 1. Existing profile (may be absent — first-time amend with no prior card).
+    const profileRow = await session.run(
+      `MATCH (a:AdminUser {accountId: $accountId, userId: $userId})
+       OPTIONAL MATCH (a)-[:HAS_VOICE_PROFILE]->(p:VoiceProfile {accountId: $accountId, userId: $userId, format: $format})
+       RETURN elementId(p) AS profileId,
+              p.styleCard AS styleCard,
+              p.corpusSize AS corpusSize,
+              p.generatedAt AS generatedAt`,
+      { accountId, userId, format },
+    );
+    const prow = profileRow.records[0];
+    const prevProfileId = (prow?.get("profileId") as string | null) ?? null;
+    const existingStyleCard = (prow?.get("styleCard") as string | null) ?? null;
+    const prevCorpusSize = toJsNumber(prow?.get("corpusSize")) ?? 0;
+    const prevGeneratedAt = (prow?.get("generatedAt") as string | null) ?? null;
+
+    // 2. Per-document eligibility classification. Each input id gets a
+    //    verdict; the first failing predicate wins. The predicate set mirrors
+    //    VOICE_CORPUS_WHERE except `format` is dropped (operator picked the
+    //    docs) and conversation-section sub-pattern is inlined for the
+    //    per-document case.
+    const eligibilityResult = await session.run(
+      `UNWIND $nodeIds AS nid
+       OPTIONAL MATCH (n) WHERE elementId(n) = nid
+       WITH nid, n,
+            CASE
+              WHEN n IS NULL THEN 'node-not-found'
+              WHEN n.accountId <> $accountId THEN 'wrong-account'
+              WHEN NOT coalesce(n.authorshipMode, '') IN ['human-only', 'human-led-agent-assisted']
+                THEN 'ineligible-authorship-mode'
+              WHEN n:Trashed OR n.deletedAt IS NOT NULL THEN 'trashed'
+              WHEN NOT (
+                any(lbl IN labels(n) WHERE lbl IN ['KnowledgeDocument', 'Message', 'SocialPost'])
+                OR ('Section' IN labels(n) AND EXISTS {
+                  MATCH (parent:KnowledgeDocument)-[:HAS_SECTION]->(n)
+                  WHERE parent.conversationIdentity IS NOT NULL
+                    AND ${notTrashed("parent")}
+                })
+              ) THEN 'ineligible-label'
+              ELSE 'ok'
+            END AS verdict
+       RETURN nid, verdict`,
+      { accountId, nodeIds },
+    );
+
+    const eligibleIds: string[] = [];
+    const ineligible: { nodeId: string; reason: string }[] = [];
+    for (const r of eligibilityResult.records) {
+      const nid = r.get("nid") as string;
+      const verdict = r.get("verdict") as string;
+      if (verdict === "ok") eligibleIds.push(nid);
+      else ineligible.push({ nodeId: nid, reason: verdict });
+    }
+
+    // 3. Feedback intents (same as sample) — agent benefits even on a no-op
+    //    amend ("you've already corrected this voice tic ten times").
+    const feedback = await session.run(
+      `MATCH (e:VoiceEdit {userId: $userId, accountId: $accountId, format: $format})
+       RETURN e.intent AS intent ORDER BY e.occurredAt DESC LIMIT 50`,
+      { accountId, userId, format },
+    );
+    const feedbackIntents = feedback.records
+      .map((r) => r.get("intent") as string | null)
+      .filter((x): x is string => typeof x === "string" && x.length > 0);
+
+    if (eligibleIds.length === 0) {
+      process.stderr.write(
+        `[voice-distil] mode=amend userId=${userId} format=${format} nodeIds=${nodeIds.length} ` +
+          `existingProfile=${prevProfileId ?? "none"} eligible=0 ineligible=${ineligible.length}\n`,
+      );
+      return {
+        profileId: prevProfileId,
+        corpusSize: prevCorpusSize,
+        generatedAt: prevGeneratedAt,
+        feedbackEntries: feedbackIntents.length,
+        skipped: true,
+        skipReason: "amend-no-eligible-documents",
+        existingStyleCard,
+        eligible: 0,
+        ineligible,
+        exemplars: [],
+        feedbackIntents,
+      };
+    }
+
+    // 4. Body walk for eligible ids — identical body resolution to the
+    //    full-corpus sample path: KD-with-Section-children concatenates child
+    //    bodies in `position` order (trashed sections filtered); other labels
+    //    fall through to the COALESCE chain.
+    const bodyResult = await session.run(
+      `UNWIND $eligibleIds AS nid
+       MATCH (n) WHERE elementId(n) = nid
+       OPTIONAL MATCH (parent:KnowledgeDocument)-[:HAS_SECTION]->(n)
+       WHERE 'Section' IN labels(n) AND parent.conversationIdentity IS NOT NULL
+         AND ${notTrashed("parent")}
+       WITH n, parent
+       OPTIONAL MATCH (n)-[:HAS_SECTION]->(s:Section)
+       WHERE ${notTrashed("s")}
+       WITH n, parent, s ORDER BY s.position
+       WITH n, parent, collect(s.body) AS sectionBodies
+       WITH n, 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,
+              body,
+              usedSectionWalk,
+              parent.conversationIdentity IS NOT NULL AS isConversationChunk`,
+      { eligibleIds },
+    );
+
+    const exemplars: VoiceCorpusExemplar[] = [];
+    let charBudget = SAMPLE_CHAR_CAP;
+    let sectionWalkCount = 0;
+    let nBodyCount = 0;
+    for (const r of bodyResult.records) {
+      const body = (r.get("body") as string | null) ?? "";
+      if (body.length === 0) continue;
+      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) =>
+            ["KnowledgeDocument", "Message", "SocialPost"].includes(l),
+          ) ?? labels[0] ?? "Unknown");
+      const trimmed = body.length > charBudget ? body.slice(0, charBudget) : body;
+      exemplars.push({ id: r.get("id") as string, label, body: trimmed });
+      if (usedSectionWalk) sectionWalkCount += 1;
+      else nBodyCount += 1;
+      charBudget -= trimmed.length;
+      if (charBudget <= 0) break;
+    }
+
+    process.stderr.write(
+      `[voice-distil] mode=amend userId=${userId} format=${format} nodeIds=${nodeIds.length} ` +
+        `existingProfile=${prevProfileId ?? "none"} eligible=${eligibleIds.length} ineligible=${ineligible.length} ` +
+        `exemplars=${exemplars.length} sample-body-source=section-walk:${sectionWalkCount} n.body:${nBodyCount}\n`,
+    );
+
+    // `skipped: false` because the function DID deliver value — exemplars
+    // + existingStyleCard for the agent to act on. The agent decides
+    // whether to compose new YAML (calls `mode='write'`) or replies "no
+    // material delta"; either is a valid amend outcome, neither is a
+    // "skip" in the cadence-guard sense.
+    return {
+      profileId: prevProfileId,
+      corpusSize: prevCorpusSize,
+      generatedAt: prevGeneratedAt,
+      feedbackEntries: feedbackIntents.length,
+      skipped: false,
+      existingStyleCard,
+      eligible: eligibleIds.length,
+      ineligible,
+      exemplars,
+      feedbackIntents,
+    };
+  } finally {
+    await session.close();
+  }
+}
+
+/**
+ * Amend write (Task 472). Persists the agent-composed style card after an
+ * `amend` sample. Bypasses the cadence guard and the full corpus walk; the
+ * only `LEARNED_FROM` edges added are to `amendedFromNodeIds`. Pre-existing
+ * `LEARNED_FROM` edges remain via `MERGE`. `corpusSize` on the profile is
+ * untouched — the amend doesn't change the operator's qualifying corpus,
+ * only the styleCard's interpretation of it.
+ */
+async function amendWriteForFormat(params: {
+  accountId: string;
+  userId: string;
+  format: VoiceFormat;
+  styleCardYaml: string;
+  amendedFromNodeIds: string[];
+}): Promise<VoiceDistilProfileResult> {
+  const { accountId, userId, format, styleCardYaml, amendedFromNodeIds } = params;
+  const session = getSession();
+  const nowIso = new Date().toISOString();
+  try {
+    // 1. Pre-resolve the amend ids and refuse if none survive. The write
+    //    Cypher SETs `p` before the UNWIND/MATCH on amend ids, so if every
+    //    id is stale the profile would be mutated then the function would
+    //    throw — leaving a silently advanced styleCard the operator never
+    //    confirmed. Resolving here means the SET never runs on an empty
+    //    target list, and stale ids surface as a structured error before
+    //    any write commits. Code-review pass-1 fix.
+    const resolve = await session.run(
+      `UNWIND $amendIds AS sid
+       MATCH (s) WHERE elementId(s) = sid
+       RETURN elementId(s) AS id`,
+      { amendIds: amendedFromNodeIds },
+    );
+    const resolvedAmendIds = resolve.records.map(
+      (r) => r.get("id") as string,
+    );
+    if (resolvedAmendIds.length === 0) {
+      throw new Error(
+        `voice-mirror: none of amendedFromNodeIds=${JSON.stringify(amendedFromNodeIds)} ` +
+          `resolved to live nodes. Confirm the named docs exist and are accessible.`,
+      );
+    }
+
+    const feedback = await session.run(
+      `MATCH (e:VoiceEdit {userId: $userId, accountId: $accountId, format: $format})
+       RETURN count(e) AS c`,
+      { accountId, userId, format },
+    );
+    const feedbackEntries = toJsNumber(feedback.records[0]?.get("c")) ?? 0;
+
+    const result = await session.run(
+      `MATCH (a:AdminUser {accountId: $accountId, userId: $userId})
+       MERGE (a)-[:HAS_VOICE_PROFILE]->(p:VoiceProfile {accountId: $accountId, userId: $userId, format: $format})
+         ON CREATE SET p.createdAt = $now, p.corpusSize = 0
+       SET p.styleCard = $styleCard,
+           p.generatedAt = $now,
+           p.feedbackEntries = $feedbackEntries,
+           p.updatedAt = $now
+       WITH p
+       UNWIND $amendIds AS sid
+       MATCH (s) WHERE elementId(s) = sid
+       MERGE (p)-[:LEARNED_FROM]->(s)
+       WITH p
+       RETURN elementId(p) AS profileId, p.corpusSize AS corpusSize`,
+      {
+        accountId,
+        userId,
+        format,
+        styleCard: styleCardYaml,
+        now: nowIso,
+        feedbackEntries,
+        amendIds: resolvedAmendIds,
+      },
+    );
+    if (result.records.length === 0) {
+      throw new Error(
+        `voice-mirror: :AdminUser {accountId='${accountId}', userId='${userId}'} not found. ` +
+          `Onboarding must promote the operator to :AdminUser before distillation.`,
+      );
+    }
+    const profileId = result.records[0].get("profileId") as string;
+    const corpusSize = toJsNumber(result.records[0].get("corpusSize")) ?? 0;
+
+    process.stderr.write(
+      `[voice-distil] mode=write userId=${userId} format=${format} amended=true ` +
+        `amendedFromNodeIds=${amendedFromNodeIds.length} corpusSize=${corpusSize} ` +
+        `generatedAt=${nowIso} feedbackEntries=${feedbackEntries}\n`,
+    );
+
+    return {
+      profileId,
+      corpusSize,
+      generatedAt: nowIso,
+      feedbackEntries,
+      skipped: false,
+    };
+  } finally {
+    await session.close();
+  }
+}
+
 export async function voiceDistilProfile(
   params: VoiceDistilProfileParams,
 ): Promise<VoiceDistilProfileResult | VoiceDistilProfileResult[]> {
@@ -344,6 +672,53 @@ export async function voiceDistilProfile(
     throw new Error("voice-distil-profile: accountId and userId required");
   }
 
+  // Amend sample (Task 472): operator-initiated single-document update.
+  if (params.mode === "amend") {
+    if (!params.format) {
+      throw new Error("voice-distil-profile: mode='amend' requires format");
+    }
+    const nodeIds = params.nodeIds ?? [];
+    if (nodeIds.length === 0) {
+      throw new Error(
+        "voice-distil-profile: mode='amend' requires nodeIds (at least one)",
+      );
+    }
+    return amendForFormat({
+      accountId,
+      userId,
+      format: params.format,
+      nodeIds,
+    });
+  }
+
+  // Amend write (Task 472): persist after the agent composed from an amend
+  // sample. Triggered by `mode='write'` + non-empty `amendedFromNodeIds`.
+  // Distinct from the full-corpus write — bypasses cadence + corpus walk.
+  if (
+    params.mode === "write" &&
+    params.amendedFromNodeIds &&
+    params.amendedFromNodeIds.length > 0
+  ) {
+    if (!params.format) {
+      throw new Error(
+        "voice-distil-profile: mode='write' with amendedFromNodeIds requires format",
+      );
+    }
+    const styleCardYaml = (params.styleCardYaml ?? "").trim();
+    if (!styleCardYaml) {
+      throw new Error(
+        "voice-distil-profile: mode='write' requires styleCardYaml (the YAML you composed from the amend-sample response).",
+      );
+    }
+    return amendWriteForFormat({
+      accountId,
+      userId,
+      format: params.format,
+      styleCardYaml,
+      amendedFromNodeIds: params.amendedFromNodeIds,
+    });
+  }
+
   // Single-format path.
   if (params.format !== undefined) {
     return distilForFormat({ ...params, format: params.format, force });

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

@@ -25,6 +25,7 @@
  * calling drafting skill falls back to its existing default register.
  */
 import { getSession } from "../lib/neo4j.js";
+import { notTrashed } from "../lib/voice-corpus.js";
 import {
   VOICE_CORPUS_WHERE,
   voiceCorpusWhereWithFormat,
@@ -112,6 +113,7 @@ export async function voiceRetrieveConditioning(
 
     const bodyComputeBlock = `WITH n, coalesce(n.dateSent, n.datePublished, n.firstMessageAt, n.dateCreated, n.createdAt) AS ts
          OPTIONAL MATCH (n)-[:HAS_SECTION]->(s:Section)
+         WHERE ${notTrashed("s")}
          WITH n, ts, s ORDER BY s.position
          WITH n, ts, collect(s.body) AS sectionBodies
          WITH n, ts, CASE

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

@@ -153,6 +153,25 @@ A re-run within the 30-day window with <20% growth is a no-op — the tool retur
 
 The triggering surface is the skill, not a scheduled job. Distillation runs on demand: at the end of a backfill batch, when the email composer notices stale-profile narration, or when the operator says "rebuild my voice profile".
 
+### Amend mode (single-document update)
+
+Activate when the operator names one or more specific documents and wants them folded into their voice profile right now — e.g. **"I just published this new article, take that into account"**, **"that thread to Sarah is a good example of how I write — fold it in"**, or **"add this essay to my voice profile"**. The full-corpus distil cadence is wrong for "this specific document, now" — the operator's signal is the document choice, not the cadence guard.
+
+Call `voice-distil-profile` with:
+
+- `mode: 'amend'`
+- `format: <VoiceFormat>` — required; the operator's per-format profile
+- `nodeIds: [<elementId>, ...]` — the documents the operator picked (one or more)
+
+The tool returns `{existingStyleCard, exemplars[], feedbackIntents[], eligible, ineligible}`. Compare the named exemplars against the prior card and the recent edit intents, then choose:
+
+- **Material delta** — compose an updated YAML and call `mode: 'write'` with `styleCardYaml` and `amendedFromNodeIds: [<elementId>, ...]` listing the documents that actually moved the card. The write bypasses the cadence guard and adds `LEARNED_FROM` edges to those documents (pre-existing edges remain).
+- **No material delta** — reply to the operator in-turn ("nothing in that article shifts your voice card; the prior profile still applies"). Do not call `mode: 'write'`. `generatedAt` only advances on a write.
+
+When `eligible=0` (every named document failed the predicate) surface the `ineligible[]` payload to the operator naming the per-id reason (`node-not-found`, `wrong-account`, `ineligible-authorship-mode`, `trashed`, `ineligible-label`) rather than silently no-op. Most commonly this means the documents are tagged as `agent-only` and need re-tagging via `voice-tag-content` before they can amend a profile.
+
+Amend mode does not apply to the SessionEnd auto-ingest path. Session-text ingest stays on the full-corpus path; amend is operator-initiated only.
+
 ## Per-operator scope
 
 One `:VoiceProfile` per `(accountId, userId, format)`. Multi-author accounts (an agency with several operators) get one profile per person per format. Identity is the `(accountId, userId, format)` triple, enforced by the schema constraint.
@@ -164,6 +183,8 @@ One `:VoiceProfile` per `(accountId, userId, format)`. Multi-author accounts (an
 | `[voice-tag] mode=<mode> format=<format> nodeId=<id> count=<n>` | Every tag write. |
 | `[voice-distil] userId=<id> format=<format> corpusSize=<n> generatedAt=<iso> feedbackEntries=<n>` | Each distillation. |
 | `[voice-distil] skip reason=<below-threshold\|recent> format=<format>` | When the cadence guard fires. |
+| `[voice-distil] mode=amend userId=<id> format=<format> nodeIds=<count> existingProfile=<elementId\|none> eligible=<n> ineligible=<n> exemplars=<n>` | Each amend-mode call. `eligible=0` means surface `ineligible[]` to the operator, never silently no-op. |
+| `[voice-distil] mode=write userId=<id> format=<format> amended=true amendedFromNodeIds=<count> ...` | Amend-write fired (operator-initiated update persisted). |
 | `[voice-retrieve] task=<topic> format=<format> styleCardBytes=<n> exemplarCount=<k> tokenBudget=<n>` | Each retrieval. |
 | `[voice-record-feedback] userId=<id> format=<format> intent="<haiku-summary>" diffBytes=<n>` | Each feedback write. |
 | `[voice-session-end-hook] trigger sessionId=<id>` | Hook fires for an eligible session. |