knowledge-flush

knowledge-flush — queued insights → verified wiki PR

Turn the ★ Insight candidates harvested from your sessions into a wiki contribution, PR-only — you (the repo owner) review each PR and merge or reject it. This skill NEVER auto-merges and NEVER pushes to main.

The queue lives at ~/.dev-loop/queue/*.jsonl (written by the Stop hook). Each row is a candidate: trigger, directive, why, evidence, domain, tags, content.

Non-negotiable order (a PreToolUse gate enforces it)

hooks/pre-flush-pr-gate.sh blocks gh pr create on a knowledge branch unless an INGEST_REPORT.md with three filled sections exists. So do the work first:

1. Acquire the shared flush lock — before anything else, including the checkout reset in step 1. This skill and the hooks/auto-flush.sh Stop hook are the two entry points that drain the same queue; both serialize through the same lock (scripts/flush-lock.sh, issue #77).

   Generate this run's id once, here, and record it — every later flush-lock.sh call in this flush (the abort-path release below, and step 5's release) must be prefixed with it. This is mandatory, not a style choice: each step in this skill runs in its own fresh shell, so nothing carries between them on its own — an unprefixed call computes a brand-new run id that no longer matches the one that acquired the lock, so release is refused as a foreign caller and the lock leaks for the full TTL.

   RUNID="flush-$(date +%Y%m%d-%H%M%S)-$$"
   echo "$RUNID"          # record this — every later flush-lock.sh call needs it
   export DEV_LOOP_FLUSH_RUN_ID="$RUNID"
   sh "${CLAUDE_PLUGIN_ROOT}/scripts/flush-lock.sh" acquire
   

   Always set the run id with export on its own line immediately before the flush-lock.sh call, in the SAME shell invocation — never as an inline DEV_LOOP_FLUSH_RUN_ID=... sh ... prefix. A headless run (see hooks/auto-flush.sh) auto-approves this call against a fixed allowlist that can match a literal sh .../flush-lock.sh acquire|release command but can never auto-approve an unscoped env-var-prefixed command.

   • Exit 0 → proceed to step 1.
   • Non-zero exit → do not touch ~/.dev-loop/repo. Read the failure line (held <holder-runid> <age>s on stderr) and tell the user: "a flush is already running (holder <holder-runid>, started <age>s ago) — stopping." Then stop. Do not retry, poll, or wait for the lock. The lock is released once, at the very end of step 5 on a successful flush. If you abort or hit an unrecoverable error at any point after acquiring it, release it before stopping — prefixed with the same $RUNID recorded above — so the next run does not wait out the TTL:

   export DEV_LOOP_FLUSH_RUN_ID="<the run id you recorded above>"
   sh "${CLAUDE_PLUGIN_ROOT}/scripts/flush-lock.sh" release