knowz-flush

/knowz-flush — Process pending captures

Drain the canonical project-root knowz-pending.md queue into Knowz vaults. Each queued block declares an Operation (create, amend, or update) and an Idempotency Key. Never replay an amend/update as create.

If enterprise.json exists in the project root, use its brand value instead of "Knowz" in user-facing text.

If Knowz MCP tools are unavailable, stop after reporting the queue count and: "{brand} MCP not connected. In Grok Bot Plugins or Cursor Marketplace, search Knowz → Add → Authorize. Do not paste API keys in chat."

Instructions

1. Read both queue locations before doing anything:
   • Canonical: knowz-pending.md in the project root.
   • Legacy migration source: knowzcode/pending_captures.md. If neither contains a ----delimited capture block, report that there is nothing to flush and stop.
2. Normalize and migrate legacy blocks without loss:
   • Treat any keyless block in project-root knowz-pending.md as a legacy producer block. Normalize it in place before replay; do not reject queues produced by older /knowz save, /knowz amend, or /knowz auto versions.
   • Map Target Vault Type to canonical Target Vault; the value remains a routing token resolved through knowz-vaults.md.
   • If Payload is missing but legacy Content exists, map Content to Payload. A block with neither is malformed and remains untouched.
   • Preserve Operation, KnowledgeId, Semantic Key, Intent, Category, Source, title, and payload exactly.
   • Preserve an existing Idempotency Key. If absent, create a stable migration key from the exact operation, KnowledgeId or semantic key, target-vault token, intent, source, and title. Never include migration time or attempt number.
   • If that key already exists canonically with identical mutation content, treat the legacy block as an already-migrated duplicate. If the same key has different operation, target, identity, or payload, leave both blocks untouched and report IDEMPOTENCY_KEY_COLLISION.
   • For a keyless canonical-root block, insert and confirm the derived key before any MCP call. For a nested legacy block, append a converted block to knowz-pending.md before removing its legacy source block. Remove the legacy block only after the canonical append is confirmed. Keep the legacy file itself as a deprecation notice when empty.
3. Parse canonical blocks. Required fields are Operation, Idempotency Key, Target Vault, and Payload; KnowledgeId is additionally required for amend/update. Queue Status defaults to pending; superseded blocks are preserved but MUST NOT be written. Semantic Key, Intent, Category, and Source are optional metadata. A missing Operation may migrate as create only when the legacy block has no KnowledgeId, no amend/update action, and contains a complete create payload; otherwise leave it queued as malformed.
4. Group blocks by Idempotency Key:
   • Byte-equivalent logical mutations are one retry group and are executed at most once.
   • A key reused for different operation, identity, target, or payload is a collision. Execute none of that group.
5. Read knowz-vaults.md and resolve Target Vault as an explicit ID/name or configured routing token. Empty or ambiguous resolution leaves the block queued.
6. Verify the MCP tools required by the queued operations before processing them. Create replay also requires a Knowz search capability; amend/update replay requires get_knowledge_item plus the matching mutation tool. If a required tool is unavailable, leave that operation queued rather than weakening replay safety.
7. Preflight every retry group before mutation:
   • create: search the resolved vault by the exact title and compare content/semantic identity. One materially identical item means the operation already succeeded; count it as idempotently reconciled. No match permits create. A similar-title item with conflicting content or multiple plausible matches is ambiguous and remains queued.
   • amend: fetch KnowledgeId. If missing, leave queued as MISSING_AMEND_TARGET; never create. If the requested delta is already reflected exactly, count it as reconciled. If applicability is ambiguous, leave queued for review; otherwise call amend once.
   • update: fetch KnowledgeId. If missing, leave queued as MISSING_UPDATE_TARGET; do not silently create during replay. If the full replacement is already reflected, count it as reconciled; otherwise call update once.
8. After a confirmed success or idempotent reconciliation, remove every byte-equivalent block in that retry group from both queue files. If mutation succeeds but queue cleanup cannot be confirmed, stop and report the exact key so the next run performs the preflight again.
9. Report newly created/amended/updated counts, idempotently reconciled counts, migrated legacy count, superseded/quarantined count, and every remaining key grouped by collision, malformed block, ambiguous target, missing target, unavailable tool, or MCP failure.