docs(mcp): add /correct-shipped-build skill + document closed-record correction non-coverage

Two follow-ups to the closed-record correction tools shipped in #536:

1. New `/correct-shipped-build` skill orchestrates `correct_manufacturing_order`
   + `correct_sales_order` (and the future `split_via_bom` from #543) for the
   originating workflow: a customer received different items than Katana
   recorded, and the operator needs to walk MO → SO → optional inventory
   split with operator-judgment gates between phases. Includes a deferral
   fallback for the split phase so the skill is usable today even with #543
   still open.

2. Help-resource note explaining why `correct_purchase_order` and
   `correct_stock_transfer` aren't in the pattern: PO receipts are
   append-only at the row level (#532 has the workaround design); stock
   transfers have no completion timestamp + immutable rows so the close-
   state pattern adds no value (#533 — operators should use
   `create_stock_adjustment` / `delete_stock_transfer` + recreate /
   `modify_stock_transfer` for header metadata instead).

Skills under `.claude/skills/` are auto-discovered by name, so the skill is
immediately usable in-repo. `.harness-lock.json` records its provenance as
`source: local` for harness-kit drift tracking.

Closes #533. Implements #534.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dougborg

.claude/skills/correct-shipped-build/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: correct-shipped-build
+description: >-
+  Resolve a shipped-order discrepancy — customer received different items than
+  Katana recorded. Pull the customer-facing record, locate the linked Katana
+  SO/MO, decide whether a BOM-driven split is needed (when an assembled good
+  shipped as its component parts), then apply correct_manufacturing_order +
+  correct_sales_order with operator-judgment gates between phases. Verify
+  against the source of truth at the end.
+argument-hint: "[order id from source-of-truth system]"
+allowed-tools:
+  - mcp__katana-erp__get_sales_order
+  - mcp__katana-erp__get_manufacturing_order
+  - mcp__katana-erp__get_manufacturing_order_recipe
+  - mcp__katana-erp__list_sales_orders
+  - mcp__katana-erp__correct_manufacturing_order
+  - mcp__katana-erp__correct_sales_order
+  - mcp__katana-erp__modify_manufacturing_order
+  - mcp__katana-erp__modify_sales_order
+  - mcp__katana-erp__check_inventory
+  - mcp__katana-erp__create_stock_adjustment
+---
+
+# /correct-shipped-build — shipped-order discrepancy resolution
+
+## PURPOSE
+
+When a customer received different items than Katana recorded — wrong
+ingredient on a finished good, wrong line item on a sales order, or a
+finished good that shipped as its components — restore Katana to ground
+truth without losing the original close-state metadata (`done_date`,
+`picked_date`, per-production timestamps, fulfillment tracking).
+
+## CRITICAL
+
+- **Ground truth is the customer-facing record, not Katana.** Pull the
+  Shopify / e-commerce / fulfillment-system order first; treat it as
+  authoritative. Don't assume Katana's recorded fulfillment is right —
+  this skill exists because it isn't.
+- **Preview every correction before applying.** Both `correct_manufacturing_order`
+  and `correct_sales_order` default to `preview=true` for a reason. The
+  operator should read the planned action list and confirm before any
+  mutations land.
+- **Both MO and SO may need correction, in this order.** When a finished
+  good's recipe was wrong (consumed the wrong ingredient), fix the MO
+  first — that's the upstream truth. Then fix the SO if its line items
+  also drifted. SO line items can reference variants the MO produced, so
+  MO-first is the safer order.
+- **Inventory side-effects belong to a separate decision.** If the
+  finished good was disassembled mid-fulfillment — i.e. an assembled
+  good was broken into its BOM components and shipped as parts — the
+  MO/SO corrections alone don't reshuffle inventory. That's
+  `split_via_bom`'s job. Don't conflate the two; decide explicitly
+  whether a split is needed.
+
+## STANDARD PATH
+
+### Phase 1 — Pull the source-of-truth record
+
+Ask the operator for the source-system order id (Shopify order, etc.).
+Read the customer-facing record and write down what actually shipped:
+SKUs, quantities, condition / assembly state. This is the **expected
+state** every later phase compares against.
+
+If you have a Chrome tab or other tool already open on the order, use it.
+Otherwise the operator may need to open it manually and read off the
+relevant fields.
+
+### Phase 2 — Locate the linked Katana SO and MO
+
+```
+list_sales_orders(customer_id=..., delivered_after=..., delivered_before=...)
+```
+
+Filter by customer name + delivery date window to find the candidate SO.
+Once you have the SO id:
+
+```
+get_sales_order(order_id=...)
+```
+
+Inspect:
+- SO line items — what Katana thinks shipped
+- `linked_manufacturing_order_id` on each row — the upstream MO, if any
+
+If a row has a linked MO:
+
+```
+get_manufacturing_order(order_id=...)
+```
+
+Note the MO's `variant_id` (the finished good) and the status (`DONE` /
+`PARTIALLY_COMPLETED`).
+
+`get_manufacturing_order` defaults to `include_rows="blocking"`, which
+hides recipe rows whose ingredients are in stock. To inspect the *full*
+recipe before deciding what to correct, fetch the dedicated recipe view:
+
+```
+get_manufacturing_order_recipe(manufacturing_order_id=...)
+```
+
+This returns every recipe row regardless of ingredient-availability
+status — that's what you want when figuring out which row consumed the
+wrong variant.
+
+### Phase 3 — Decide whether a split is needed
+
+A **split** means: the finished good produced by the MO was disassembled
+into its BOM components before shipment, and the customer received the
+components instead of the assembled good.
+
+Operator-judgment criteria:
+
+- The customer-confirmed item list (phase 1) lists individual component
+  SKUs instead of the assembled SKU.
+- The MO produced a single assembled good, but the SO's line item now
+  needs to reference component SKUs.
+- The warehouse / fulfillment notes confirm the split.
+
+If yes, plan to use `split_via_bom` in phase 6. If no, skip phase 6.
+
+If `split_via_bom` is not yet shipped (issue #543 still open at the time
+of writing), document the intended split — finished-good variant id,
+location id, quantity, and the timing — and proceed without it. The
+MO/SO corrections still land cleanly; the inventory reshuffling can be
+applied as a follow-up when the tool ships.
+
+### Phase 4 — Correct the MO (if the recipe was wrong)
+
+If the MO consumed the wrong ingredient (e.g., the wrong variant of a
+component, or an incorrect quantity per unit):
+
+```
+correct_manufacturing_order(
+    id=...,
+    ingredient_changes=[
+        {
+            old_variant_id: <variant currently on the recipe row>,
+            new_variant_id: <variant that was actually consumed>,
+            planned_quantity_per_unit: <if changed; otherwise omit>,
+        },
+        ...
+    ],
+    preview=true,
+)
+```
+
+Review the planned action sequence — revert → recipe edit → recreate
+production → re-close with backdated done_date / production_date.
+Confirm the captured close-state matches reality. Then re-call with
+`preview=false`.
+
+The tool requires the MO to be in `DONE` or `PARTIALLY_COMPLETED`
+status. If it's still `IN_PROGRESS`, use `modify_manufacturing_order`
+directly — there's no close-state to preserve.
+
+### Phase 5 — Correct the SO (if line items were wrong)
+
+If the SO's line items don't match what the customer received:
+
+```
+correct_sales_order(
+    id=...,
+    line_changes=[
+        {
+            old_variant_id: <variant currently on the row>,
+            new_variant_id: <variant actually shipped>,
+            quantity: <if changed; must be ≥ already-fulfilled qty>,
+            price_per_unit: <if changed>,
+        },
+        ...
+    ],
+    preview=true,
+)
+```
+
+Preview surfaces the planned action sequence — delete fulfillments →
+revert → row edits → re-add fulfillments with original `picked_date` →
+re-close. Confirm and re-call with `preview=false`.
+
+`correct_sales_order` only updates rows in place. If you need to **add
+or remove** a line item entirely, use `modify_sales_order` directly —
+the close-state restore would otherwise lose the row-id mapping the
+fulfillments depend on.
+
+### Phase 6 — Apply the BOM-driven split (if decided in phase 3)
+
+> **Status: deferred.** The `split_via_bom` tool isn't shipped yet
+> (issue #543). It's intentionally **not** listed in this skill's
+> `allowed-tools` so the skill can load and run today; when the tool
+> ships, add `mcp__katana-erp__split_via_bom` to the allowlist and
+> remove this status callout.
+
+When `split_via_bom` ships, the call shape will be:
+
+```
+split_via_bom(
+    variant_id=<finished good>,
+    location_id=<where the inventory transformation happened>,
+    quantity=<how many were split>,
+    stock_adjustment_date=<just before the customer's delivery date>,
+    preview=true,
+)
+```
+
+It generates a single mixed-sign stock adjustment: `-quantity` of the
+finished good, `+(quantity × planned_quantity_per_unit)` of each BOM
+ingredient, cost-balanced to net zero.
+
+**Until then:** file a follow-up issue documenting the intended split
+parameters (finished-good variant id, location id, quantity, timing)
+and skip this phase. The MO/SO corrections still leave the records in
+the right shape; only the inventory reshuffling is deferred.
+
+### Phase 7 — Verify
+
+Re-fetch the corrected records:
+
+```
+get_manufacturing_order(order_id=...)
+get_sales_order(order_id=...)
+```
+
+Confirm the close-state restored cleanly: status back to its original
+value, dates backdated to the originals, no new "today" timestamps
+sneaking in.
+
+Sanity-check inventory on the affected SKUs:
+
+```
+check_inventory(skus_or_variant_ids=[...])
+```
+
+Expected vs. actual stock levels should reconcile against the customer-
+confirmed shipment. Negative availability is a red flag — it means the
+correction over-corrected somewhere.
+
+### Phase 8 — Summarize
+
+Report to the operator:
+
+- **Source-system order id** — what was being corrected.
+- **Katana SO and MO ids** — links to the corrected records.
+- **Changes applied** — MO recipe rows swapped (with variants), SO line
+  items updated, split applied (yes/no, with parameters).
+- **Inventory delta** — affected SKUs and the qty change at each.
+- **Verification** — the inventory-check result and any flagged
+  anomalies.
+- **Deferred work** — if `split_via_bom` wasn't available, the
+  follow-up issue or manual adjustment that's still needed.
+
+## EDGE CASES
+
+- **No linked MO on the SO** — the SO is for a purchased finished good,
+  not a manufactured one. Skip phase 4 entirely; only the SO needs
+  correction.
+- **MO is `IN_PROGRESS`** — `correct_manufacturing_order` will refuse.
+  The MO hasn't shipped yet, so there's no close-state to preserve. Use
+  `modify_manufacturing_order` directly.
+- **Same variant appears on multiple recipe rows / SO rows** — the
+  correction tools refuse on ambiguity. Use `modify_manufacturing_order`
+  / `modify_sales_order` with the explicit row id, or split the
+  correction into two passes that disambiguate by other means.
+- **New row quantity below the already-fulfilled quantity** —
+  `correct_sales_order` preflight refuses. Either keep the original
+  quantity, or fix the fulfillment record manually first.
+- **Inventory goes negative after corrections** — the corrections
+  over-shot. Likely cause: the MO/SO drift was only a partial
+  representation of what shipped, and the rest needs a stock adjustment
+  or a parallel correction on a sibling SO. Don't paper over with a
+  goodwill stock adjustment without understanding the root cause.
+- **Customer received a superset (got extras)** — corrections alone
+  won't capture this. Either confirm a picking-error / goodwill add-on
+  with the warehouse, or treat the extras as a separate incident.
+
+## RELATED
+
+- PR #536 — `correct_manufacturing_order`, `correct_sales_order`
+- Issue #543 — `split_via_bom` (BOM-driven inventory split, pending)
+- Issue #523 — Closed-record corrections umbrella
+- Issue #532 — `correct_purchase_order` (separate workflow; not used here)

.harness-lock.json

@@ -44,6 +44,10 @@
       "source": "local",
       "note": "Migrated from .claude/commands/pre-commit.md"
     },
+    ".claude/skills/correct-shipped-build/SKILL.md": {
+      "source": "local",
+      "note": "Orchestrates correct_manufacturing_order + correct_sales_order + split_via_bom for shipped-order discrepancies; tracked under #534. Migrate to plugin distribution when #525 lands."
+    },
     ".claude/skills/review/SKILL.md": {
       "source": "local",
       "note": "Migrated from .claude/commands/review.md; delegates to code-reviewer agent"

katana_mcp_server/src/katana_mcp/resources/help.py

@@ -151,6 +151,27 @@
 - The same variant appears on multiple rows and you want to disambiguate
   with the explicit row ID.
 
+**No `correct_purchase_order` or `correct_stock_transfer`** — those entity
+types don't fit the pattern:
+
+- **Purchase orders** — Katana's receipt records are append-only at the row
+  level. `modify_purchase_order` can patch a row's `received_date` (when
+  already set), but it **cannot zero out a row's `received_quantity`** —
+  there's no unreceive endpoint, and `quantity` / `variant_id` on a row are
+  only updatable when `received_date` is null. So a clean reopen path
+  doesn't exist (tracked in #532). For inventory-level recovery today:
+  `create_stock_adjustment` at the original cost basis to undo the
+  receipt's stock effect — this fixes inventory, but the PO record's
+  received quantities remain historically incorrect until Katana exposes an
+  unreceive / reset mechanism. Plan for the audit trail to show the
+  original receipt + the compensating adjustment, not a corrected receipt.
+- **Stock transfers** — no completion timestamp on the model and rows are
+  immutable, so the close-state pattern adds no value. For corrections:
+  `create_stock_adjustment` at the destination location for quantity
+  discrepancies; `delete_stock_transfer` + `create_stock_transfer` for wrong
+  variants; `modify_stock_transfer` for header metadata (works on RECEIVED
+  transfers as-is).
+
 ## Output Format
 
 Every list/get/search and reporting tool accepts a shared `format` parameter: