@rubytech/create-maxy-code 0.1.177 → 0.1.181

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.
 
@@ -156,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.
@@ -167,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. |