@moda-ai/cli 1.27.0 → 1.27.1

package/dist/cli.js

@@ -391,6 +391,7 @@ var FIX_USAGE = [
   "       moda fix verify <fix_id> [--prompt-file=PATH] [--no-wait] [--timeout=ms]",
   "       moda fix checkout <fix_id>",
   "       moda fix submit <fix_id> --pr | --local-ref=<branch>",
+  "       moda fix mark-applied <fix_id> [--note=TEXT]",
   "       moda fix dismiss <fix_id> --reason=TEXT"
 ].join(`
 `);
@@ -454,6 +455,8 @@ async function runFixCommand(context) {
       return runFixCheckout(context, profileOptions, tenantId);
     case "submit":
       return runFixSubmit(context, profileOptions, tenantId);
+    case "mark-applied":
+      return runFixMarkApplied(context, profileOptions, tenantId);
     case "dismiss":
       return runFixDismiss(context, profileOptions, tenantId);
     default:
@@ -645,6 +648,9 @@ async function runFixCheckout(context, profileOptions, tenantId) {
     throw new CliInputError("<fix_id> is required", "Usage: moda fix checkout <fix_id>");
   }
   const fix = await getFix(tenantId, fixId, profileOptions);
+  if (isArtifactFix(fix)) {
+    throw new CliInputError(`Fix MODA-FIX-${fix.shortRef} is a ${fix.fixType} fix — its candidate is applied in your own stack, not checked out. Run \`moda fix ${fixId} --packet\` for the candidate (written as local artifacts), apply it, then confirm with \`moda fix mark-applied ${fixId}\`.`);
+  }
   if (!fix.targetSourcePath) {
     throw new CliInputError(`Fix MODA-FIX-${fix.shortRef} has no target source path — ${fix.fixType} fixes are packet-only. Run \`moda fix ${fixId} --packet\` for the diagnosis packet.`);
   }
@@ -752,6 +758,38 @@ async function runFixSubmit(context, profileOptions, tenantId) {
   });
   return EXIT_OK;
 }
+async function runFixMarkApplied(context, profileOptions, tenantId) {
+  const usage = "Usage: moda fix mark-applied <fix_id> [--note=TEXT]";
+  const fixId = (context.positionals[1] || context.flags["fix-id"] || "").trim();
+  if (!fixId) {
+    throw new CliInputError("<fix_id> is required", usage);
+  }
+  const note = (context.flags.note ?? "").trim();
+  if (note.length > 600) {
+    throw new CliInputError(`--note must be 600 characters or fewer (got ${note.length})`, usage);
+  }
+  const fix = await callControlAPI(`${fixesBase(tenantId)}/${encodeURIComponent(fixId)}/mark-applied`, { method: "POST", body: JSON.stringify(note ? { note } : {}) }, profileOptions, { timeoutMs: 60000, retries: 0 });
+  if (context.outputMode === "human") {
+    process.stderr.write(fix.duplicate === true ? `Fix MODA-FIX-${fix.shortRef} was already confirmed (${fix.status}) — duplicate no-op; the mark_fixed feedback was re-posted.
+` : `Fix MODA-FIX-${fix.shortRef} marked applied (${fix.status}) — mark_fixed feedback posted, monitoring for recurrence.
+`);
+  }
+  context.output.writeData(fix, {
+    summary: {
+      text: fix.duplicate === true ? `Fix MODA-FIX-${fix.shortRef} was already confirmed (${fix.status}); mark-applied was a duplicate no-op.` : `Fix MODA-FIX-${fix.shortRef} marked applied — status ${fix.status}; the problem enters fixed-monitoring.`,
+      confidence: "high"
+    },
+    nextCommands: [
+      {
+        command: `moda fix ${fix.id}`,
+        purpose: "Track confirmation monitoring (HELD after 14 clean days; REGRESSED on reopen).",
+        mutability: "read",
+        requires_approval: false
+      }
+    ]
+  });
+  return EXIT_OK;
+}
 async function runFixDismiss(context, profileOptions, tenantId) {
   const usage = "Usage: moda fix dismiss <fix_id> --reason=TEXT";
   const fixId = (context.positionals[1] || context.flags["fix-id"] || "").trim();
@@ -778,8 +816,16 @@ async function runFixDismiss(context, profileOptions, tenantId) {
 async function runFixDetail(context, profileOptions, tenantId, fixId) {
   if (context.flags.packet === "true") {
     const packet = await callControlAPI(`${fixesBase(tenantId)}/${encodeURIComponent(fixId)}/packet`, { method: "GET" }, profileOptions);
+    const extras = materializePacketCandidates(packet, fixId, context.outputMode === "human");
     context.output.writeData(packet, {
-      summary: { text: `moda.fix_packet.v1 for fix ${fixId}.`, confidence: "high" }
+      summary: {
+        text: `moda.fix_packet.v1 for fix ${fixId}.${extras.summarySuffix}`,
+        confidence: "high"
+      },
+      ...extras.findings.length > 0 ? { findings: extras.findings } : {},
+      ...extras.artifacts.length > 0 ? { artifacts: extras.artifacts } : {},
+      ...extras.warnings.length > 0 ? { warnings: extras.warnings } : {},
+      ...extras.nextCommands.length > 0 ? { nextCommands: extras.nextCommands } : {}
     });
     return EXIT_OK;
   }
@@ -841,6 +887,9 @@ async function driveAdvance(args) {
     announce(fix);
     if (!ADVANCING_STATUSES.has(fix.status))
       break;
+    if (fix.status === "PROPOSED" && /gate (pending|unavailable)/i.test(fix.statusReason ?? "")) {
+      break;
+    }
     await sleep(fix.status === "GATING" ? args.pollIntervalMs : Math.min(STEP_DELAY_MS, args.pollIntervalMs));
   }
   return fix;
@@ -871,6 +920,112 @@ async function fetchPacketFailSoft(tenantId, fixId, profileOptions) {
     return null;
   }
 }
+function isArtifactFix(fix) {
+  return fix.fixType === "TOOL_SCHEMA" || fix.fixType === "SKILL";
+}
+function materializePacketCandidates(packet, fixId, human) {
+  const findings = [];
+  const artifacts = [];
+  const warnings = [];
+  const nextCommands = [];
+  const summaryParts = [];
+  const tool = packet.candidate_tool;
+  const skill = packet.candidate_skill;
+  const hasTool = typeof tool?.proposed_description === "string" && tool.proposed_description !== "";
+  const hasSkill = typeof skill?.skill_md === "string" && skill.skill_md !== "";
+  if (!hasTool && !hasSkill) {
+    return { findings, artifacts, warnings, nextCommands, summarySuffix: "" };
+  }
+  const rawRef = typeof packet.short_ref === "string" && packet.short_ref.trim() ? packet.short_ref : fixId;
+  const ref = rawRef.replace(/[^A-Za-z0-9._-]/g, "").replace(/^\.+/, "").slice(0, 64) || "fix";
+  const w = (line) => process.stderr.write(`${line}
+`);
+  const block = (label, text) => {
+    w(`  ${label}:`);
+    for (const line of (text || "(none)").split(`
+`))
+      w(`    ${line}`);
+  };
+  const writeCandidateFile = (name, content, kind, description) => {
+    const relPath = safeTargetSourcePath(`.moda/fixes/${ref}/${name}`);
+    const absPath = join(process.cwd(), relPath);
+    try {
+      assertRealpathContained(absPath, relPath);
+      writeContainedFile(absPath, relPath, content);
+      artifacts.push({ kind, path: relPath, description });
+      return relPath;
+    } catch (error) {
+      warnings.push(`Could not write ${relPath}: ${error instanceof Error ? error.message : String(error)} — the full candidate text is still in the packet payload.`);
+      return null;
+    }
+  };
+  if (hasTool && tool) {
+    const toolName = typeof tool.tool_name === "string" && tool.tool_name ? tool.tool_name : "unknown-tool";
+    const source = typeof tool.current_description_source === "string" ? tool.current_description_source : "";
+    const paramNotes = (Array.isArray(tool.param_notes) ? tool.param_notes : []).filter((note) => typeof note === "string" && note !== "");
+    const rationale = typeof tool.rationale === "string" ? tool.rationale : "";
+    const currentPath = writeCandidateFile("tool-description.current.md", typeof tool.current_description === "string" ? tool.current_description : "", "fix_tool_description_current", `Current description of tool '${toolName}'${source ? ` (from ${source})` : ""} — the diff base.`);
+    const proposedPath = writeCandidateFile("tool-description.proposed.md", tool.proposed_description ?? "", "fix_tool_description_proposed", `Proposed description for tool '${toolName}' — apply it to your tool definition, then \`moda fix mark-applied ${fixId}\`.`);
+    findings.push({
+      id: "fix:candidate_tool",
+      title: `tool '${toolName}' description candidate${source ? ` (current from ${source})` : ""}`,
+      status: "proposed",
+      severity: "info",
+      ...rationale || paramNotes.length > 0 ? {
+        description: [rationale, ...paramNotes.map((note) => `param note: ${note}`)].filter(Boolean).join(`
+`)
+      } : {}
+    });
+    summaryParts.push(`Includes a tool-description candidate for '${toolName}'.`);
+    if (human) {
+      w("");
+      w(`Tool-description candidate — '${toolName}'${source ? ` (current description from ${source})` : ""}`);
+      block("current ", tool.current_description ?? "");
+      block("proposed", tool.proposed_description ?? "");
+      if (paramNotes.length > 0)
+        block("param notes", paramNotes.join(`
+`));
+      if (rationale)
+        block("rationale", rationale);
+      if (currentPath && proposedPath) {
+        w(`  diff: diff ${currentPath} ${proposedPath}`);
+      }
+    }
+  }
+  if (hasSkill && skill) {
+    const skillName = typeof skill.skill_name === "string" && skill.skill_name ? skill.skill_name : "moda-fix-skill";
+    const skillPath = writeCandidateFile("SKILL.md", skill.skill_md ?? "", "fix_candidate_skill", `Drafted SKILL.md for '${skillName}' — install it (for example .claude/skills/${skillName}/SKILL.md), then \`moda fix mark-applied ${fixId}\`.`);
+    findings.push({
+      id: "fix:candidate_skill",
+      title: `skill '${skillName}' drafted (SKILL.md, ${(skill.skill_md ?? "").length} chars)`,
+      status: "proposed",
+      severity: "info",
+      description: `Install the skill in your agent, then confirm with \`moda fix mark-applied ${fixId}\`. Gating on the replay holdout stays pending until the skill is registered with the skill harness.`
+    });
+    summaryParts.push(`Includes a drafted SKILL.md candidate ('${skillName}').`);
+    if (human) {
+      w("");
+      w(`Skill candidate — '${skillName}'`);
+      if (skillPath)
+        w(`  SKILL.md written to ${skillPath}`);
+      w(`  install it (for example .claude/skills/${skillName}/SKILL.md), then confirm:`);
+      w(`  moda fix mark-applied ${fixId} --note="installed skill ${skillName}"`);
+    }
+  }
+  nextCommands.push({
+    command: `moda fix mark-applied ${fixId} --note="where/how you applied it"`,
+    purpose: "Confirm you applied the candidate in your own stack (no PR) — flips the fix to SHIPPED and starts recurrence monitoring.",
+    mutability: "write",
+    requires_approval: true
+  });
+  return {
+    findings,
+    artifacts,
+    warnings,
+    nextCommands,
+    summarySuffix: summaryParts.length > 0 ? ` ${summaryParts.join(" ")}` : ""
+  };
+}
 function gateFindings(fix) {
   const gateResult = fix.gateResult ?? null;
   if (!gateResult)
@@ -918,8 +1073,24 @@ function passLabel(value) {
   return value ? "pass" : "fail";
 }
 function nextCommandsFor(fix) {
+  const packetCommand = {
+    command: `moda fix ${fix.id} --packet`,
+    purpose: "Read the packet — the tool/skill candidate is written as local artifacts to apply in your own stack.",
+    mutability: "write",
+    requires_approval: false
+  };
+  const markAppliedCommand = {
+    command: `moda fix mark-applied ${fix.id} --note="where/how you applied it"`,
+    purpose: "Confirm you applied the candidate in your own stack (no PR) — flips the fix to SHIPPED and starts recurrence monitoring.",
+    mutability: "write",
+    requires_approval: true
+  };
+  const skillGatePending = fix.fixType === "SKILL" && fix.candidateRef?.kind === "skill" && !fix.candidateRef?.skillId;
   switch (fix.status) {
     case "VERIFIED":
+      if (isArtifactFix(fix)) {
+        return [packetCommand, markAppliedCommand];
+      }
       return [
         {
           command: `moda fix submit ${fix.id} --pr`,
@@ -935,6 +1106,9 @@ function nextCommandsFor(fix) {
         }
       ];
     case "PROPOSED":
+      if (skillGatePending) {
+        return [packetCommand, markAppliedCommand];
+      }
       return [
         {
           command: `moda fix verify ${fix.id}`,
@@ -944,6 +1118,17 @@ function nextCommandsFor(fix) {
         }
       ];
     case "GATE_FAILED":
+      if (isArtifactFix(fix)) {
+        return [
+          {
+            command: `moda fix verify ${fix.id}`,
+            purpose: "Re-gate the stored candidate on the frozen holdout.",
+            mutability: "write",
+            requires_approval: false
+          },
+          packetCommand
+        ];
+      }
       return [
         {
           command: `moda fix checkout ${fix.id}`,
@@ -4692,7 +4877,8 @@ Commands:
 
   Fixes (a fix with proof):
   fixes                            Ranked Fix queue (--status=S --limit=N --cursor=TOKEN)
-  fix <fix_id>                     One Fix: status + gate result; --packet prints moda.fix_packet.v1;
+  fix <fix_id>                     One Fix: status + gate result; --packet prints moda.fix_packet.v1
+                                   (tool/skill candidates are also written under .moda/fixes/<ref>/);
                                    --wait drives a still-running pipeline to rest
   fix start <problem_id>           Draft a Fix from a Problem (--type=auto|prompt); --wait drives
                                    scope -> propose -> gate and prints the packet
@@ -4700,6 +4886,8 @@ Commands:
                                    (exit 0 pass / 1 fail with per-case findings / 3 degraded-inconclusive)
   fix checkout <fix_id>            Write the candidate at its target source path (never runs git)
   fix submit <fix_id>              Deliver: --pr opens a draft PR | --local-ref=<branch> records your branch
+  fix mark-applied <fix_id>        Confirm a candidate you applied in your own stack (--note=TEXT);
+                                   no PR needed — flips to SHIPPED and starts monitoring
   fix dismiss <fix_id>             Reject with --reason=TEXT (feeds problem feedback)
 
 Options:
@@ -4900,7 +5088,8 @@ Examples:
   moda skills pull
   moda fixes
   moda fix start <problem_id> --wait
-  moda fix verify <fix_id> --prompt-file=prompts/agent.prompt.md`);
+  moda fix verify <fix_id> --prompt-file=prompts/agent.prompt.md
+  moda fix mark-applied <fix_id> --note="tool description updated in our agent config"`);
 }
 function printCommandHelp(definition) {
   const lines = [];
@@ -6192,6 +6381,7 @@ var commandRegistry = createCommandRegistry([
       "moda fix verify <fix_id> --prompt-file=prompts/agent.prompt.md",
       "moda fix checkout <fix_id>",
       "moda fix submit <fix_id> --pr",
+      'moda fix mark-applied <fix_id> --note="tool description updated in our agent config"',
       'moda fix dismiss <fix_id> --reason="not actionable"'
     ],
     auth: "none",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moda-ai/cli",
-  "version": "1.27.0",
+  "version": "1.27.1",
   "description": "CLI for Moda - AI agent analytics and observability",
   "type": "module",
   "bin": {

package/skills/integration/index.json

@@ -1,7 +1,7 @@
 {
   "schema_version": "moda.skill_index.v1",
-  "bundled_at": "2026-08-17T23:28:03.271Z",
-  "cli_version": "1.27.0",
+  "bundled_at": "2026-08-19T08:07:44.284Z",
+  "cli_version": "1.27.1",
   "skills": [
     {
       "id": "integration-node-anthropic",

package/skills/moda-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: moda-cli
-version: 2.3.0
+version: 2.4.0
 description: Query Moda's AI agent conversation analytics and manage code-first prompt versions from the terminal — semantic/keyword/hybrid message search, overview KPIs, topic clusters, message context, user frustration detections, tool failures, and moda prompts status/sync/promote. Use when the user asks about moda, modaflows, conversation analytics, prompt management, user frustrations, agent observability, tool failure debugging, wants to find conversations or tool calls about a topic, or wants to investigate how their AI agent is performing.
 ---
 
@@ -621,23 +621,35 @@ replay **gate** that proves it on held-out production evidence. Use this loop
 whenever you are asked to fix a detected Problem, or before hand-editing
 prompt/skill files in a repo that talks to Moda.
 
+Fixes are typed by where the evidence points: `PROMPT` (a managed prompt
+revision — the checkout/verify/submit loop below), `TOOL_SCHEMA` (a proposed
+rewrite of one tool's description), and `SKILL` (a drafted SKILL.md for an
+agent-behavior problem). Tool and skill candidates are not repo files: read
+them from the packet (they are also written locally under
+`.moda/fixes/<SHORTREF>/`), apply them in your own stack, then confirm with
+`moda fix mark-applied` — no GitHub integration required.
+
 The fail-to-pass loop:
 
 ```bash
 moda fixes                                   # ranked queue of fixes with proof
 moda fix <fix_id> --packet                   # moda.fix_packet.v1: cause, target
                                              # file, evidence links, verify cmd,
-                                             # handback + magic word
+                                             # handback + magic word; tool/skill
+                                             # candidates land in .moda/fixes/
 moda fix start <problem_id> --wait           # draft from a Problem and drive
                                              # scope -> propose -> gate
-moda fix checkout <fix_id>                   # write the candidate at its target
-                                             # source path (NEVER runs git)
+moda fix checkout <fix_id>                   # PROMPT fixes: write the candidate
+                                             # at its target source path
+                                             # (NEVER runs git)
 # ...edit the target file...
 moda fix verify <fix_id> --prompt-file=<path>  # re-gate local content on the
-                                               # frozen holdout
+                                               # frozen holdout (PROMPT only)
 # iterate edit -> verify until exit 0, then hand back:
 moda fix submit <fix_id> --pr                # draft PR via the Moda GitHub App
 moda fix submit <fix_id> --local-ref=<branch>  # or record your own branch
+moda fix mark-applied <fix_id> --note="…"    # tool/skill/no-PR path: confirm a
+                                             # candidate you applied yourself
 moda fix dismiss <fix_id> --reason="why"     # reject (feeds problem feedback)
 ```
 
@@ -660,6 +672,15 @@ Rules that keep the proof honest:
 - Fix PRs end with the magic word `Fixes MODA-FIX-<SHORTREF>` in the body —
   Moda-authored PRs carry it automatically; hand-authored PRs must include it
   so the merge confirms the fix and starts production monitoring.
+- `mark-applied` is the confirmation for changes shipped without a PR (tool
+  descriptions, installed skills, hand-applied prompts): it flips the fix to
+  `SHIPPED`, records your `--note`, and starts the same monitoring the merge
+  webhook would. It is idempotent — repeating it is a duplicate no-op.
+- `TOOL_SCHEMA` fixes gate like prompt fixes (both arms pin the same current
+  prompt; the proposed description is the only delta). `SKILL` fixes rest at
+  `PROPOSED` until the skill is registered with the Moda skill harness — an
+  inline drafted SKILL.md cannot enter the gate, so deliver it via the packet
+  and `mark-applied`.
 - The pipeline is advance-on-poll: `--wait` (on `start`, `verify`, or
   `moda fix <fix_id> --wait`) drives it; a fix left `GATING` will not finish
   on its own.
@@ -842,11 +863,12 @@ npx: `npx -p @moda-ai/cli moda <command>`.
 | `moda prompts sync` | Upload changed prompt versions and update lockfile |
 | `moda prompts promote <key>` | Move a remote prompt label |
 | `moda fixes` | Ranked queue of Fixes ("a fix with proof"); `--status=S`, `--limit=N`, `--cursor=TOKEN` |
-| `moda fix <fix_id>` | One Fix: status + gate result; `--packet` prints `moda.fix_packet.v1`; `--wait` drives a running pipeline to rest |
+| `moda fix <fix_id>` | One Fix: status + gate result; `--packet` prints `moda.fix_packet.v1` and writes tool/skill candidates under `.moda/fixes/<ref>/`; `--wait` drives a running pipeline to rest |
 | `moda fix start <problem_id>` | Draft a Fix from a Problem (`--type=auto\|prompt`); `--wait` drives scope → propose → gate |
-| `moda fix verify <fix_id>` | Re-gate on the frozen holdout; `--prompt-file=P` gates local content (exit `0` pass / `1` fail with per-case findings / `3` degraded — never a pass) |
-| `moda fix checkout <fix_id>` | Write the candidate at its target source path (never runs git) |
+| `moda fix verify <fix_id>` | Re-gate on the frozen holdout; `--prompt-file=P` gates local content, PROMPT fixes only (exit `0` pass / `1` fail with per-case findings / `3` degraded — never a pass) |
+| `moda fix checkout <fix_id>` | Write the candidate at its target source path (never runs git; PROMPT fixes only) |
 | `moda fix submit <fix_id>` | Deliver: `--pr` opens a draft PR \| `--local-ref=<branch>` records your branch |
+| `moda fix mark-applied <fix_id>` | Confirm a candidate you applied in your own stack (`--note=TEXT`, ≤600 chars); no PR needed — flips to SHIPPED and starts monitoring |
 | `moda fix dismiss <fix_id>` | Reject with `--reason=TEXT` (feeds problem feedback) |
 
 `moda search` flags: `--mode=keyword|semantic|hybrid` (default `hybrid`),