@gobing-ai/knowledge-kit 0.0.36 → 0.1.0

package/plugins/kk/workflows/kk-itc.yaml

@@ -1,733 +1,259 @@
 ---
-"$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
 name: kk-itc
-kind: state-machine
+kind: dag
+version: "2"
 description: >-
-  IT content authoring pipeline using topic/itc-generating, Spur HITL gates, and optional judging;
-  an auto path (auto-picked outline, unslop pass, judge revise loop) ends in a run report
-initialState: prepare
-terminalStates:
-  - done
-  - failed
-failureStates:
-  - failed
+  IT content authoring and publication DAG: prepare -> child authoring FSM -> verify-child-freeze
+  -> illustration/SEO branches -> materialize & plan -> target check -> fan-out send -> reconcile-settle -> report
 
 vars:
+  # Config-backed options default to "" so `workflows.kk-itc` and compiled defaults apply (0303);
+  # the frozen `$work_dir/itc-options.json` is the single source every downstream node reads.
   topic: ""
   input_file: ""
+  from_collect: ""
+  topic_profile: ""
+  run_date: ""
   work_dir: ""
-  writer: "itc-generating"
-  playbook: "generic"
-  research: "false"
-  judge: "false"
-  auto: "false" # auto mode: writer-recommended outline, no draft-review pause, mandatory judge, auto revise loop
-  unslop: "false" # run kk:taste-unslop on the draft before review/judge
-  max_revisions: "2" # cap on the auto revise loop (interactive stays bounded by the existing 3)
+  writer: ""
+  playbook: ""
+  rubric: "tech-accuracy"
   outline: ""
+  research: ""
+  judge: ""
+  auto: ""
+  unslop: ""
   force: "false"
-  rubric: "tech-accuracy"
-  verdictFile: "" # empty -> ${vars.work_dir}/.itc-verdict.json (set by prepare)
-  agent: ""
-  __runId: "" # Engine-injected run id; its presence captures the run for the Board (G8/0254 §9)
-  __definitionDigest: "" # Executed definition digest; the capture compares it with the catalog (G8 §9)
-  __hitlAnswer: ""
-  __hitlInput: ""
-  __verdictFeedback: "" # raw .itc-verdict.json, read by judge so draft-revise can show the feedback
-  publish_targets: "" # comma list of publish plugin names; empty = no publish tail (V1)
-  publish_live: "false" # live instead of draft; launch-only, never implied by auto (V4)
-  source_locale: "en" # locale of the authored draft (en|zh|ja)
-  cover_enabled: "false" # generate a cover via kk:image-authoring — this is the spend approval (R7)
-  inline_images: "false" # also generate inline illustrations — also a spend approval
-  browser_target: "" # internal cursor for the browser publish loop (written by itc-publish-next)
-
-states:
+  max_revisions: ""
+  source_locale: ""
+  publish_targets: ""
+  publish_preset: ""
+  publish_live: ""
+  cover_enabled: ""
+  inline_images: ""
+  seo_mode: ""
+  agent: "inline"
+  __runId: ""
+  __definitionDigest: ""
+
+nodes:
   - id: prepare
-    description: "mkdir work_dir, 2-outline; validate XOR topic/input_file; write brief.md"
-    onEnter:
-      - kind: shell
-        options:
-          command: >-
-            kbin="$(command -v kk 2>/dev/null)";
-            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
-            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
-            bun "$st" prepare-itc "${vars.work_dir}" "${vars.topic}" "${vars.input_file}" "${vars.force}" &&
-            { [ -z "${vars.__runId}" ] || [ -z "${vars.__definitionDigest}" ] || kk board capture --workflow kk-itc --run "${vars.__runId}" --work-dir "${vars.work_dir}" --stamp "$(date +%Y%m%d)" --definition-digest "${vars.__definitionDigest}" --setting research="${vars.research}" --setting judge="${vars.judge}" --setting auto="${vars.auto}" --setting unslop="${vars.unslop}" --setting force="${vars.force}" --setting publish_live="${vars.publish_live}" --setting cover_enabled="${vars.cover_enabled}" --setting inline_images="${vars.inline_images}" --setting max_revisions="${vars.max_revisions}" --setting source_locale="${vars.source_locale}" || echo "kk-itc: Board capture skipped (workspace is not a trusted-root child); previews disabled" >&2; }
-
-  - id: research
-    description: "Conduct preliminary topic research via storm-research (agent.run)"
-    onEnter:
-      - kind: agent.run
-        options:
-          role: scribe
-          agent: ${vars.agent}
-          input: |
-            Invoke the kk:storm-research skill.
-            Run storm-research on the topic or input file specified in the brief at ${vars.work_dir}/brief.md.
-
-  - id: outline-write
-    description: "Generate outline options a, b (and optional c) via writer skill (agent.run)"
-    onEnter:
-      - kind: agent.run
-        options:
-          role: scribe
-          agent: ${vars.agent}
-          input: |
-            Invoke the kk:${vars.writer} skill.
-            Generate outline options (outline-option-a.md, outline-option-b.md, and optionally outline-option-c.md) in ${vars.work_dir}/2-outline/ from the brief at ${vars.work_dir}/brief.md using playbook ${vars.playbook}.
-            When auto mode is on (auto=true), also write 2-outline/outline-recommendation.json as {"pick": "a|b|c", "rationale": "<why this option is strongest>"} recommending the option you would commit.
-            Do not wait for operator selection; write the option files.
-          expectFile: ${vars.work_dir}/2-outline/outline-option-a.md
-      - kind: shell
-        options:
-          command: >-
-            test -f "${vars.work_dir}/2-outline/outline-option-b.md" || { echo "missing required outline-option-b.md" >&2; exit 1; }
-
-  - id: outline-select
-    description: "Operator selects preferred outline option"
-    pause: true
-    onEnter:
-      - kind: hitl.select
-        options:
-          prompt: "Select an approved outline option from ${vars.work_dir}/2-outline/ (outline-option-a.md, outline-option-b.md, or outline-option-c.md):"
-          options:
-            - a
-            - b
-            - c
-          var: __hitlAnswer
-
-  - id: outline-autopick
-    description: "Auto mode — validate the writer's outline-recommendation.json and bind the pick as the selected outline"
-    onEnter:
-      - kind: shell
-        options:
-          command: >-
-            kk stage itc-outline-pick "${vars.work_dir}"
-      - kind: file.read.into-var
-        options:
-          path: ${vars.work_dir}/2-outline/.auto-pick
-          var: outline
-
-  - id: outline-commit
-    description: "Copy selected outline to outline-approved.md"
-    onEnter:
-      - kind: shell
-        options:
-          command: >-
-            sel="${vars.outline}";
-            if [ -z "$sel" ]; then sel="${vars.__hitlAnswer}"; fi;
-            if [ -z "$sel" ]; then sel="a"; fi;
-            src="${vars.work_dir}/2-outline/outline-option-$sel.md";
-            if [ ! -f "$src" ]; then
-              echo "selected outline file not found: $src" >&2; exit 1;
-            fi;
-            cp "$src" "${vars.work_dir}/2-outline/outline-approved.md";
-
-  - id: draft-write
-    description: "Author full technical draft from approved outline (agent.run)"
-    onEnter:
-      - kind: agent.run
-        options:
-          role: scribe
-          agent: ${vars.agent}
-          input: |
-            Invoke the kk:${vars.writer} skill.
-            Author the technical draft at ${vars.work_dir}/3-draft-draft-article.md based on approved outline ${vars.work_dir}/2-outline/outline-approved.md and brief ${vars.work_dir}/brief.md using playbook ${vars.playbook}.
-            Revision feedback: ${vars.__hitlInput}
-          expectFile: ${vars.work_dir}/3-draft-draft-article.md
-
-  - id: unslop
-    description: "De-slop pass — kk:taste-unslop line-edits the draft (writes a new file, then the swap makes it in place)"
-    onEnter:
-      - kind: agent.run
-        options:
-          role: scribe
-          agent: ${vars.agent}
-          input: |
-            Invoke the kk:taste-unslop skill.
-            Read ${vars.work_dir}/3-draft-draft-article.md and write the line-edited version to ${vars.work_dir}/3-draft-draft-article.new.md, removing slop (AI-tell phrasing, filler, hedging) while preserving the technical claims, code blocks, links, and the approved outline's structure. Do not modify or delete the original file; the pipeline swaps the edited file in.
-          expectFile: ${vars.work_dir}/3-draft-draft-article.new.md
-      - kind: shell
-        options:
-          command: mv -f "${vars.work_dir}/3-draft-draft-article.new.md" "${vars.work_dir}/3-draft-draft-article.md"
-
-  - id: draft-review
-    description: "Operator reviews and approves or requests revision on draft-article.md"
-    pause: true
-    onEnter:
-      - kind: hitl.confirm
-        options:
-          prompt: "Review draft at ${vars.work_dir}/3-draft-draft-article.md. Approve?"
-          var: __hitlAnswer
-
-  - id: draft-revise
-    description: "Collect revision feedback from operator (bounded by 3 rounds)"
-    pause: true
-    onEnter:
-      - kind: shell
-        options:
-          command: >-
-            n=$(cat "${vars.work_dir}/.revise-count" 2>/dev/null || echo 0);
-            echo $((n + 1)) > "${vars.work_dir}/.revise-count";
-      - kind: hitl.input
-        options:
-          prompt: "Judge feedback (from ${vars.work_dir}/.itc-verdict.json): ${vars.__verdictFeedback}\nProvide specific revision feedback for ${vars.work_dir}/3-draft-draft-article.md:"
-          var: __hitlInput
-
-  - id: draft-autorevise
-    description: "Auto mode — apply the judge feedback[] to the draft and consume one revision from the budget"
-    onEnter:
-      - kind: shell
-        options:
-          command: >-
-            n=$(cat "${vars.work_dir}/.auto-revise-count" 2>/dev/null || echo 0);
-            echo $((n + 1)) > "${vars.work_dir}/.auto-revise-count";
-      - kind: agent.run
-        options:
-          role: scribe
-          agent: ${vars.agent}
-          input: |
-            Invoke the kk:${vars.writer} skill.
-            Read the draft at ${vars.work_dir}/3-draft-draft-article.md and write a revised version to ${vars.work_dir}/3-draft-draft-article.new.md, applying every item of feedback[] in ${vars.work_dir}/.itc-verdict.json. Do not modify or delete the original file; the pipeline swaps the revised file in.
-          expectFile: ${vars.work_dir}/3-draft-draft-article.new.md
-      - kind: shell
-        options:
-          command: mv -f "${vars.work_dir}/3-draft-draft-article.new.md" "${vars.work_dir}/3-draft-draft-article.md"
-
-  - id: publish-entry
-    description: "Publish tail entry — targets are set; route into illustration/materialization"
-
-  - id: illustrate
-    description: "Optional cover/inline illustrations via kk:image-authoring — entered only when a spend var is on (R7)"
-    onEnter:
-      - kind: agent.run
-        options:
-          role: scribe
-          agent: ${vars.agent}
-          input: |
-            Invoke the kk:image-authoring skill with KK_NONINTERACTIVE=1 and KK_IMAGE_AUTO_CONFIRM=1 (non-interactive, auto-confirm — the operator approved spend via the cover_enabled/inline_images vars).
-            Create ${vars.work_dir}/4-illustrations/ and generate the cover illustration into it as cover.png (cover.jpg acceptable), sized for an article hero image.
-            When inline_images=true, also generate inline figures for the draft's key sections as inline-<slug>.png in the same directory.
-            Print each written path as the last line of stdout.
-      - kind: shell
-        options:
-          command: >-
-            test "${vars.cover_enabled}" = "true" || exit 0;
-            ls "${vars.work_dir}"/4-illustrations/cover.* >/dev/null 2>&1 || { echo "cover_enabled=true but no 4-illustrations/cover.* in ${vars.work_dir}" >&2; exit 1; }
-
-  - id: materialize
-    description: "Materialize the approved draft to 4-publish/content.json"
-    onEnter:
-      - kind: shell
-        options:
-          command: >-
-            kk stage itc-materialize "${vars.work_dir}" "${vars.publish_live}"
-
-  - id: publish-plan
-    description: "Split targets into fan-out groups and browser targets (4-publish/publish-plan.json)"
-    onEnter:
-      - kind: shell
-        options:
-          command: >-
-            kk stage itc-publish-plan "${vars.work_dir}" "${vars.publish_targets}" "${vars.source_locale}" "${vars.publish_live}"
-
-  - id: adapt
-    description: "Write one adapted Content file per plan variant with adapt:true — kk:article-adapt (R9)"
-    onEnter:
-      - kind: agent.run
-        options:
-          role: scribe
-          agent: ${vars.agent}
-          input: |
-            Invoke the kk:article-adapt skill.
-            Read ${vars.work_dir}/4-publish/publish-plan.json and, for every entry in variants with adapt=true, read the source ${vars.work_dir}/4-publish/content.json and write ${vars.work_dir}/4-publish/<entry.file>: translate title and body to the variant locale, apply the entry's limits, and keep code blocks, URLs and references unchanged.
-            Set format to the variant key's format suffix. Never set metadata.published, metadata.publishStatus or metadata.operation — itc-publish-fanout stamps the draft/live switches at send time.
-      - kind: shell
-        options:
-          command: >-
-            kk stage itc-adapt-verify "${vars.work_dir}"
-
-  - id: publish-gate
-    description: "Route to the operator confirm unless auto publishes drafts"
-
-  - id: publish-confirm
-    description: "Operator confirms the send — every target, draft or live mode"
-    pause: true
-    onEnter:
-      - kind: hitl.confirm
-        options:
-          prompt: >-
-            Send to targets [${vars.publish_targets}] in ${vars.publish_live} mode (false = draft,
-            true = LIVE)? Review ${vars.work_dir}/4-publish/publish-plan.json first.
-          var: __hitlAnswer
-      - kind: shell
-        options:
-          command: >-
-            test "${vars.__hitlAnswer}" = "yes" || printf declined > "${vars.work_dir}/4-publish/.publish-declined"
-
-  - id: publish-fanout
-    description: "Send each fan-out group through kk executor fan-out — target failures are data"
-    onEnter:
-      - kind: shell
-        options:
-          command: >-
-            kk stage itc-publish-fanout "${vars.work_dir}"
-
-  - id: publish-retry
-    description: "Re-send failed fan-out groups once through --retry-from (V5)"
-    onEnter:
-      - kind: shell
-        options:
-          command: >-
-            n=$(cat "${vars.work_dir}/.publish-retry-count" 2>/dev/null || echo 0);
-            echo $((n + 1)) > "${vars.work_dir}/.publish-retry-count";
-            kk stage itc-publish-fanout "${vars.work_dir}" --retry
-
-  - id: publish-agent
-    description: "Publish one pending browser target via kk:publish — file-cursor loop bounded by the plan"
-    onEnter:
-      - kind: file.read.into-var
-        options:
-          path: ${vars.work_dir}/4-publish/.next-browser
-          var: browser_target
-      - kind: agent.run
-        options:
-          role: scribe
-          agent: ${vars.agent}
-          input: |
-            Invoke the kk:publish skill for the browser target ${vars.browser_target}.
-            Read ${vars.work_dir}/4-publish/publish-plan.json, find the browser entry whose target is ${vars.browser_target}, and use that variant's file under ${vars.work_dir}/4-publish/ as the Content input.
-            When the plan's live is true pass the skill's --live flag; otherwise publish as a draft (V4).
-            Always write the Result to ${vars.work_dir}/4-publish/result.${vars.browser_target}.json, including {ok: false, error: ...} when the publish fails.
-          expectFile: ${vars.work_dir}/4-publish/result.${vars.browser_target}.json
-      - kind: shell
-        options:
-          command: 'kk stage itc-publish-next "${vars.work_dir}"'
-
-  - id: judge
-    description: "Evaluate technical draft with content-judge (agent.run)"
-    onEnter:
-      - kind: agent.run
-        options:
-          role: reviewer
-          agent: ${vars.agent}
-          input: |
-            Invoke the kk:content-judge skill.
-            Evaluate the draft at ${vars.work_dir}/3-draft-draft-article.md against the ${vars.rubric} rubric.
-            Research evidence: if ${vars.work_dir}/docs.json exists, read it and weigh it when judging.
-            Write the verdict JSON to ${vars.work_dir}/.itc-verdict.json per the skill's verdict contract.
-            Print the verdict path as the last line of stdout.
-          expectFile: ${vars.work_dir}/.itc-verdict.json
-      - kind: file.read.into-var
-        options:
-          path: ${vars.work_dir}/.itc-verdict.json
-          var: __verdictFeedback
-
-  - id: report
-    description: "Write the run report, then route to done or failed on its outcome"
-    onEnter:
-      - kind: shell
-        options:
-          command: >-
-            kk stage itc-report "${vars.work_dir}" "${vars.max_revisions}"
-
-  - id: done
-    description: "Terminal — IT content draft generated and approved successfully"
-  - id: failed
-    description: "Terminal — IT content workflow failed or rejected"
-
-transitions:
-  - from: prepare
-    to: research
-    description: "Research enabled -> proceed to storm-research"
-    guard:
-      kind: shell
-      options:
-        command: 'test "${vars.research}" = "true"'
-
-  - from: prepare
-    to: outline-write
-    description: "Research disabled -> proceed directly to outline generation"
-    guard:
-      kind: shell
-      options:
-        command: 'test "${vars.research}" != "true"'
-
-  - from: research
-    to: outline-write
-    description: "Research completed -> proceed to outline generation"
-    guard:
-      kind: always
-
-  - from: outline-write
-    to: outline-autopick
-    description: "Auto mode with no pre-selected outline -> validate the writer recommendation and bind it"
-    guard:
-      kind: shell
-      options:
-        command: 'test "${vars.auto}" = "true" -a -z "${vars.outline}"'
-
-  - from: outline-write
-    to: outline-select
-    description: "Interactive mode with no pre-selected outline -> pause for operator selection"
-    guard:
-      kind: shell
-      options:
-        command: 'test "${vars.auto}" != "true" -a -z "${vars.outline}"'
-
-  - from: outline-write
-    to: outline-commit
-    description: "Outline pre-selected -> skip interactive selection"
-    guard:
-      kind: shell
-      options:
-        command: 'test -n "${vars.outline}"'
-
-  - from: outline-select
-    to: outline-commit
-    description: "Outline selected -> commit approved outline"
-    guard:
-      kind: always
-
-  - from: outline-autopick
-    to: outline-commit
-    description: "Writer recommendation validated and bound -> commit approved outline"
-    guard:
-      kind: always
-
-  - from: outline-commit
-    to: draft-write
-    description: "Approved outline committed -> write draft"
-    guard:
-      kind: always
-
-  - from: draft-write
-    to: unslop
-    description: "Unslop enabled -> de-slop the fresh draft"
-    guard:
-      kind: shell
-      options:
-        command: 'test "${vars.unslop}" = "true"'
-
-  - from: draft-write
-    to: draft-review
-    description: "Interactive mode without unslop -> pause for operator review"
-    guard:
-      kind: shell
-      options:
-        command: 'test "${vars.auto}" != "true" -a "${vars.unslop}" != "true"'
-
-  - from: draft-write
-    to: judge
-    description: "Auto mode without unslop -> straight to the judge"
-    guard:
-      kind: shell
-      options:
-        command: 'test "${vars.auto}" = "true" -a "${vars.unslop}" != "true"'
-
-  - from: unslop
-    to: judge
-    description: "Auto mode -> the de-slopped draft goes to the judge"
-    guard:
-      kind: shell
-      options:
-        command: 'test "${vars.auto}" = "true"'
-
-  - from: unslop
-    to: draft-review
-    description: "Interactive mode -> pause for operator review of the de-slopped draft"
-    guard:
+    description: "Freeze the effective options (itc-prepare) bound to this run, then prepare the brief"
+    action:
+      kind: shell
+      options:
+        # The entry normally freezes itc-options.json before launch (a collected topic must be
+        # chosen first); a direct launch freezes it here. A snapshot from another run is refused.
+        command: |
+          wd="${vars.work_dir}"; run="${vars.__runId}"; o="$wd/itc-options.json"
+          test -n "$wd" || { echo "work_dir is required (derive it with kk stage run itc-prepare)" >&2; exit 1; }
+          if [ ! -f "$o" ]; then
+            req="$(mktemp)"
+            jq -n --arg topic "${vars.topic}" --arg inputFile "${vars.input_file}" --arg fromCollect "${vars.from_collect}" \
+              --arg topicProfile "${vars.topic_profile}" --arg runDate "${vars.run_date}" --arg workDir "$wd" --arg parentRunId "$run" \
+              --arg writer "${vars.writer}" --arg playbook "${vars.playbook}" --arg sourceLocale "${vars.source_locale}" \
+              --arg publishTargets "${vars.publish_targets}" --arg publishPreset "${vars.publish_preset}" --arg seo "${vars.seo_mode}" \
+              --arg maxRevisions "${vars.max_revisions}" --arg research "${vars.research}" --arg judge "${vars.judge}" \
+              --arg auto "${vars.auto}" --arg unslop "${vars.unslop}" --arg force "${vars.force}" --arg publishLive "${vars.publish_live}" \
+              --arg coverEnabled "${vars.cover_enabled}" --arg inlineImages "${vars.inline_images}" \
+              '$ARGS.named | with_entries(select(.value != ""))
+                | with_entries(if (.key | IN("research","judge","auto","unslop","force","publishLive","coverEnabled","inlineImages"))
+                    then .value = (.value == "true") else . end)
+                | if has("maxRevisions") then .maxRevisions |= tonumber else . end' > "$req" || { rm -f "$req"; exit 1; }
+            kk stage run itc-prepare --request "$req" > /dev/null; rc=$?; rm -f "$req"; test "$rc" -eq 0 || exit 1
+          fi
+          test -f "$o" || { echo "a collected topic must be chosen before launch: run the entry's intake, then itc-prepare --chosen" >&2; exit 1; }
+          pr=$(jq -r '.parentRunId' "$o")
+          if [ "$pr" != "$run" ] && [ "${vars.force}" != "true" ]; then
+            echo "$o belongs to run '$pr', not '$run'; pass force=true to adopt it" >&2; exit 1
+          fi
+          kind=$(jq -r '.sourceKind' "$o"); val=$(jq -r '.sourceValue' "$o")
+          case "$kind" in
+            input_file) kk stage run prepare-itc "$wd" "" "$val" "${vars.force}" ;;
+            from_collect) kk stage run prepare-itc "$wd" "$(jq -r '.displayTitle' "$o")" "" "${vars.force}" ;;
+            *) kk stage run prepare-itc "$wd" "$val" "" "${vars.force}" ;;
+          esac
+
+  - id: child-author
+    description: "Run child authoring state machine (outline -> draft -> unslop -> review/judge)"
+    dependsOn:
+      - prepare
+    action:
+      kind: shell
+      options:
+        # The child id is derived from the parent before launch, so an interrupted parent queries
+        # and continues the SAME child instead of starting a second one; a paused child stays a
+        # distinct non-success for the parent until it is answered and reaches done. The child
+        # runs as an owned process: a cancelled parent signals it and cancels its run.
+        command: |
+          cid="${vars.__runId}-author"
+          v=$(jq -c --arg wd "${vars.work_dir}" --arg agent "${vars.agent}" --arg rubric "${vars.rubric}" --arg outline "${vars.outline}" \
+            --arg run "${vars.__runId}" --arg dd "${vars.__definitionDigest}" \
+            '{work_dir:$wd, agent:$agent, rubric:$rubric, outline:$outline, writer:.writer, playbook:.playbook,
+              auto:(.auto|tostring), unslop:(.unslop|tostring), judge:(.judge|tostring), max_revisions:(.maxRevisions|tostring),
+              parent_run_id:$run, child_run_id:($run + "-author"), definition_digest:$dd, options_digest:.optionsDigest}' \
+            "${vars.work_dir}/itc-options.json") || exit 1
+          owned() {
+            env -u SPUR_WORKFLOW_RUN_ACTIVE -u SPUR_EXPECTED_DEFINITION_DIGEST "$@" &
+            pid=$!
+            trap 'kill -TERM "$pid" 2>/dev/null; spur workflow cancel "$cid" >/dev/null 2>&1; exit 143' TERM INT HUP
+            wait "$pid"; rc=$?
+            trap - TERM INT HUP
+            return "$rc"
+          }
+          st=$(spur workflow trace "$cid" --json 2>/dev/null | jq -r '.run.status // empty')
+          case "$st" in
+            done) exit 0 ;;
+            paused) owned spur workflow continue "$cid" --yes ;;
+            "") owned spur workflow run plugins/kk/workflows/kk-itc-author.yaml --run-id "$cid" --vars "$v" ;;
+            *) echo "child $cid is $st; refusing to relaunch it" >&2; exit 1 ;;
+          esac
+          st=$(spur workflow trace "$cid" --json 2>/dev/null | jq -r '.run.status // empty')
+          if [ "$st" = paused ]; then echo "child $cid paused: answer it with spur workflow continue $cid, then resume this run" >&2; exit 1; fi
+          test "$st" = done || { echo "child $cid ended $st" >&2; exit 1; }
+
+  - id: verify-child-freeze
+    description: "Verify child authoring completion receipt and freeze draft/outline digests"
+    dependsOn:
+      - child-author
+    action:
       kind: shell
       options:
-        command: 'test "${vars.auto}" != "true"'
-
-  - from: draft-review
-    to: judge
-    description: "Draft approved and judge enabled -> evaluate quality"
-    guard:
-      kind: shell
-      options:
-        command: '{ test -z "${vars.__hitlAnswer}" || test "${vars.__hitlAnswer}" = "yes"; } && test "${vars.judge}" = "true"'
-
-  - from: draft-review
-    to: done
-    description: "Draft approved, judge disabled, no publish targets -> complete workflow"
-    guard:
-      kind: shell
-      options:
-        command: '{ test -z "${vars.__hitlAnswer}" || test "${vars.__hitlAnswer}" = "yes"; } && test "${vars.judge}" != "true" && test -z "${vars.publish_targets}"'
-
-  - from: draft-review
-    to: publish-entry
-    description: "Draft approved, judge disabled, targets set -> enter the publish tail"
-    guard:
-      kind: shell
-      options:
-        command: '{ test -z "${vars.__hitlAnswer}" || test "${vars.__hitlAnswer}" = "yes"; } && test "${vars.judge}" != "true" && test -n "${vars.publish_targets}"'
-
-  - from: draft-review
-    to: draft-revise
-    description: "Draft rejected with revision budget remaining -> collect feedback"
-    guard:
-      kind: shell
-      options:
-        command: 'test "${vars.__hitlAnswer}" = "no" && test "$(cat "${vars.work_dir}/.revise-count" 2>/dev/null || echo 0)" -lt 3'
-
-  - from: draft-review
-    to: failed
-    terminalReason: failed-guard
-    description: "Draft rejected with revision budget exhausted -> fail"
-    guard:
-      kind: shell
-      options:
-        command: 'test "${vars.__hitlAnswer}" = "no" && test "$(cat "${vars.work_dir}/.revise-count" 2>/dev/null || echo 0)" -ge 3'
-
-  - from: draft-revise
-    to: draft-write
-    description: "Feedback collected -> rewrite draft"
-    guard:
-      kind: always
+        command: >-
+          kk stage run itc-author-complete "${vars.work_dir}" "${vars.__runId}"
 
-  - from: draft-autorevise
-    to: unslop
-    description: "Unslop enabled -> de-slop the auto-revised draft"
-    guard:
+  - id: illustrate
+    description: "Optional cover/inline illustrations via kk:image-authoring — entered only when a spend var is on (R7)"
+    dependsOn:
+      - verify-child-freeze
+    condition:
       kind: shell
       options:
-        command: 'test "${vars.unslop}" = "true"'
-
-  - from: draft-autorevise
-    to: judge
-    description: "Auto mode without unslop -> back to the judge"
-    guard:
-      kind: shell
+        command: 'jq -e ".coverEnabled or .inlineImages" "${vars.work_dir}/itc-options.json" >/dev/null'
+    action:
+      kind: agent.run
       options:
-        command: 'test "${vars.auto}" = "true" -a "${vars.unslop}" != "true"'
+        role: scribe
+        agent: ${vars.agent}
+        input: |
+          Invoke the kk:image-authoring skill with KK_NONINTERACTIVE=1 and KK_IMAGE_AUTO_CONFIRM=1 (non-interactive, auto-confirm — the operator approved spend via the cover_enabled/inline_images vars).
+          Create ${vars.work_dir}/4-illustrations/ and generate the cover illustration into it as cover.png (cover.jpg acceptable), sized for an article hero image.
+          When inline_images=true, also generate inline figures for the draft's key sections as inline-<slug>.png in the same directory.
+          Print each written path as the last line of stdout.
 
-  - from: judge
-    to: done
-    description: "Interactive mode, verdict PASS with a valid confidence (or empty in dry-run), no publish targets -> complete workflow"
-    guard:
+  - id: materialize-plan
+    description: "Materialize content.json and resolve publication targets into publish-plan.json"
+    dependsOn:
+      - verify-child-freeze
+      - illustrate
+    action:
       kind: shell
       options:
         command: >-
-          { test "${vars.auto}" != "true"; } &&
-          { v="$(jq -r 'if (.verdict // "") == "PASS" then (.verdict + (if ((.confidence // "") | test("^(HIGH|MEDIUM|LOW)$")) then "" else "!" end)) else (.verdict // "") end' ${vars.work_dir}/.itc-verdict.json 2>/dev/null)";
-          test -z "$v" -o "$v" = PASS; } &&
-          test -z "${vars.publish_targets}"
+          kk stage run itc-materialize-plan "${vars.work_dir}"
 
-  - from: judge
-    to: publish-entry
-    description: "Verdict PASS with a valid confidence and targets set -> enter the publish tail (auto runs report after the tail)"
-    guard:
+  - id: adapt
+    description: "Prepare per-platform variant Content files via kk:article-adapt — runs only for adapt:true variants (R9)"
+    dependsOn:
+      - materialize-plan
+    action:
+      kind: agent.run
+      options:
+        role: scribe
+        agent: ${vars.agent}
+        input: |
+          Invoke the kk:article-adapt skill.
+          Read ${vars.work_dir}/4-publish/publish-plan.json and, for each entry in variants with adapt=true, read ${vars.work_dir}/4-publish/content.json and write the variant Content file to ${vars.work_dir}/4-publish/<variant.file>.
+          Apply the plan's variant limits and translate title and body into the variant's locale. Never set metadata.published; the publishing states set switches.
+          Print each written variant file path as the last line of stdout.
+
+  - id: adapt-verify
+    description: "Verify adapted variant content files"
+    dependsOn:
+      - adapt
+    action:
       kind: shell
       options:
         command: >-
-          { v="$(jq -r 'if (.verdict // "") == "PASS" then (.verdict + (if ((.confidence // "") | test("^(HIGH|MEDIUM|LOW)$")) then "" else "!" end)) else (.verdict // "") end' ${vars.work_dir}/.itc-verdict.json 2>/dev/null)";
-          test -z "$v" -o "$v" = PASS; } &&
-          test -n "${vars.publish_targets}"
+          test -f "${vars.work_dir}/4-publish/publish-plan.json" || exit 0;
+          kk stage run itc-adapt-verify "${vars.work_dir}"
 
-  - from: judge
-    to: report
-    description: "Auto mode -> the run ends in the report (valid PASS without targets, FAIL, or exhausted NEEDS_REVISION)"
-    guard:
+  - id: check-targets
+    description: "Check readiness probes for plannable publish targets"
+    dependsOn:
+      - materialize-plan
+    action:
       kind: shell
       options:
         command: >-
-          { test "${vars.auto}" = "true"; } &&
-          { v="$(jq -r 'if (.verdict // "") == "PASS" then (.verdict + (if ((.confidence // "") | test("^(HIGH|MEDIUM|LOW)$")) then "" else "!" end)) else (.verdict // "") end' ${vars.work_dir}/.itc-verdict.json 2>/dev/null)";
-          c="$(cat "${vars.work_dir}/.auto-revise-count" 2>/dev/null || echo 0)";
-          { test -z "$v" -o "$v" = PASS; } || test "$v" = FAIL || { test "$v" = NEEDS_REVISION -a "$c" -ge "${vars.max_revisions}"; }; }
-
-  - from: judge
-    to: draft-autorevise
-    description: "Auto mode, NEEDS_REVISION with revise budget left -> apply feedback and re-judge"
-    guard:
-      kind: shell
-      options:
-        command: '{ test "${vars.auto}" = "true"; } && { v="$(jq -r .verdict ${vars.work_dir}/.itc-verdict.json 2>/dev/null)"; c="$(cat "${vars.work_dir}/.auto-revise-count" 2>/dev/null || echo 0)"; test "$v" = NEEDS_REVISION -a "$c" -lt "${vars.max_revisions}"; }'
-
-  - from: judge
-    to: draft-revise
-    description: "Interactive mode, NEEDS_REVISION with revise budget left -> collect revision with the feedback shown"
-    guard:
-      kind: shell
-      options:
-        command: '{ test "${vars.auto}" != "true"; } && { v="$(jq -r .verdict ${vars.work_dir}/.itc-verdict.json 2>/dev/null)"; c="$(cat "${vars.work_dir}/.revise-count" 2>/dev/null || echo 0)"; test "$v" = NEEDS_REVISION -a "$c" -lt 3; }'
-
-  - from: judge
-    to: failed
-    terminalReason: failed-guard
-    description: "Interactive mode, verdict FAIL or revise budget exhausted -> fail"
-    guard:
-      kind: shell
-      options:
-        command: '{ test "${vars.auto}" != "true"; } && { v="$(jq -r .verdict ${vars.work_dir}/.itc-verdict.json 2>/dev/null)"; c="$(cat "${vars.work_dir}/.revise-count" 2>/dev/null || echo 0)"; test "$v" = FAIL || { test "$v" = NEEDS_REVISION -a "$c" -ge 3; }; }'
-
-  # --- 0151 publish tail: materialize -> plan -> gate -> confirm/fanout -> retry -> browser loop ---
-
-  - from: publish-entry
-    to: illustrate
-    description: "Cover or inline images approved -> run the illustration step (R7: no image spend while both vars are false)"
-    guard:
-      kind: shell
-      options:
-        command: 'test "${vars.cover_enabled}" = "true" -o "${vars.inline_images}" = "true"'
-
-  - from: publish-entry
-    to: materialize
-    description: "No illustration spend approved -> materialize directly"
-    guard:
+          test -f "${vars.work_dir}/4-publish/publish-plan.json" || exit 0;
+          kk stage run itc-check-targets "${vars.work_dir}"
+
+  - id: send-confirm
+    description: >-
+      Operator approval of a LIVE send: `pause: true` stops the run and RESUME is the approval
+      (no action); cancelling is the rejection. Skipped for draft-only or empty plans.
+    dependsOn:
+      - adapt-verify
+      - check-targets
+    pause: true
+    condition:
       kind: shell
       options:
-        command: 'test "${vars.cover_enabled}" != "true" -a "${vars.inline_images}" != "true"'
-
-  - from: illustrate
-    to: materialize
-    description: "Illustrations written -> materialize the final draft (metadata.coverImage picks up 4-illustrations/cover.*)"
-    guard:
-      kind: always
+        command: 'jq -e ".live == true and (.targets // [] | length) > 0" "${vars.work_dir}/4-publish/publish-plan.json" >/dev/null 2>&1'
 
-  - from: materialize
-    to: publish-plan
-    description: "content.json written -> split targets into groups"
-    guard:
-      kind: always
-
-  - from: publish-plan
-    to: adapt
-    description: "The plan has at least one adapt:true variant -> write the adapted variant files (R9)"
-    guard:
+  - id: fanout-send
+    description: "Dispatch target payloads via executor fan-out and record receipts"
+    dependsOn:
+      - send-confirm
+    action:
       kind: shell
       options:
         command: >-
-          v="$(jq '[.variants[] | select(.adapt == true)] | length' "${vars.work_dir}/4-publish/publish-plan.json" 2>/dev/null)";
-          test -n "$v" -a "$v" -gt 0
-
-  - from: publish-plan
-    to: publish-gate
-    description: "Nothing needs adaptation -> route through the send gate"
-    guard:
-      kind: always
+          test -f "${vars.work_dir}/4-publish/publish-plan.json" || exit 0;
+          kk stage run itc-send-targets "${vars.work_dir}"
 
-  - from: adapt
-    to: publish-gate
-    description: "Variant files verified (itc-adapt-verify) -> route through the send gate"
-    guard:
-      kind: always
-
-  - from: publish-gate
-    to: publish-confirm
-    description: "Interactive run or live publish -> pause for the operator answer (V4)"
-    guard:
+  - id: fanout-recovery
+    description: "Retry safe effect-none target failures once within budget"
+    dependsOn:
+      - fanout-send
+    action:
       kind: shell
       options:
         command: >-
-          test "${vars.auto}" != "true" -o "${vars.publish_live}" = "true"
-
-  - from: publish-gate
-    to: publish-fanout
-    description: "Auto draft run -> send without pausing (ADR-022)"
-    guard:
-      kind: always
-
-  - from: publish-confirm
-    to: publish-fanout
-    description: "Operator confirmed -> send"
-    guard:
-      kind: shell
-      options:
-        command: 'test "${vars.__hitlAnswer}" = "yes"'
+          test -f "${vars.work_dir}/4-publish/publish-plan.json" || exit 0;
+          kk stage run itc-send-targets "${vars.work_dir}" --retry
 
-  - from: publish-confirm
-    to: report
-    description: "Operator declined (or dry-run left no answer) -> report without any publish call"
-    guard:
+  - id: reconcile-settle
+    description: "Reconcile target receipts and settle store selection"
+    dependsOn:
+      - fanout-recovery
+    action:
       kind: shell
       options:
         command: >-
-          test -z "${vars.__hitlAnswer}" -o "${vars.__hitlAnswer}" = "no"
+          kk stage run itc-reconcile-receipts "${vars.work_dir}"
 
-  - from: publish-fanout
-    to: publish-retry
-    description: "A fan-out group has ok:false and the retry budget is untouched -> re-send once (V5)"
-    guard:
+  - id: seo
+    description: "Export SEO prepublish request and published pages handoffs"
+    dependsOn:
+      - verify-child-freeze
+    action:
       kind: shell
       options:
         command: >-
-          test "$(cat "${vars.work_dir}/.publish-retry-count" 2>/dev/null || echo 0)" -lt 1
-          -a -s "${vars.work_dir}/4-publish/.fanout-failed"
-
-  - from: publish-fanout
-    to: publish-agent
-    description: "A browser target has no result.<target>.json -> run the kk:publish loop"
-    guard:
-      kind: shell
-      options:
-        # .next-browser cursor: seeded by itc-publish-fanout, recomputed after each kk:publish step
-        command: 'test -s "${vars.work_dir}/4-publish/.next-browser"'
+          kk stage run itc-export-seo "${vars.work_dir}" "$(jq -r '.seo' "${vars.work_dir}/itc-options.json")"
 
-  - from: publish-fanout
-    to: report
-    description: "Otherwise -> report the per-target outcomes"
-    guard:
-      kind: always
-
-  - from: publish-retry
-    to: publish-agent
-    description: "Retry done, a browser target is still pending -> run the kk:publish loop"
-    guard:
-      kind: shell
-      options:
-        # .next-browser cursor: seeded by itc-publish-fanout, recomputed after each kk:publish step
-        command: 'test -s "${vars.work_dir}/4-publish/.next-browser"'
-
-  - from: publish-retry
-    to: report
-    description: "Otherwise -> report (remaining fan-out failures are terminal data)"
-    guard:
-      kind: always
-
-  - from: publish-agent
-    to: publish-agent
-    description: "A browser target is still pending -> next cursor iteration (bounded by the plan, V5)"
-    guard:
-      kind: shell
-      options:
-        # .next-browser cursor: seeded by itc-publish-fanout, recomputed after each kk:publish step
-        command: 'test -s "${vars.work_dir}/4-publish/.next-browser"'
-
-  - from: publish-agent
-    to: report
-    description: "Browser list exhausted -> report"
-    guard:
-      kind: always
-
-  - from: report
-    to: done
-    description: "Report outcome done or declined (empty outcome = done in dry-run, mirroring the empty-verdict PASS convention)"
-    guard:
-      kind: shell
-      options:
-        command: 'o="$(jq -r .outcome ${vars.work_dir}/5-report/report.json 2>/dev/null)"; test -z "$o" -o "$o" = done -o "$o" = declined'
-
-  - from: report
-    to: failed
-    terminalReason: failed-guard
-    description: "Report outcome failed -> fail"
-    guard:
-      kind: shell
-      options:
-        command: 'o="$(jq -r .outcome ${vars.work_dir}/5-report/report.json 2>/dev/null)"; test -n "$o" -a "$o" != done'
-
-  - from: judge
-    to: failed
-    terminalReason: failed-guard
-    description: "Catch-all: an out-of-contract verdict string fails the run instead of deadlocking the machine (0149 review P3); a PASS whose confidence is missing or outside HIGH/MEDIUM/LOW reads as `PASS!` and lands here"
-    guard:
+  - id: report
+    description: "Produce final run report summary"
+    # Mandatory freeze plus every branch: a skipped optional branch still satisfies the edge,
+    # so an all-skipped publication reports, but a report never races an unfinished send.
+    dependsOn:
+      - verify-child-freeze
+      - reconcile-settle
+      - seo
+    action:
       kind: shell
       options:
         command: >-
-          v="$(jq -r 'if (.verdict // "") == "PASS" then (.verdict + (if ((.confidence // "") | test("^(HIGH|MEDIUM|LOW)$")) then "" else "!" end)) else (.verdict // "") end' ${vars.work_dir}/.itc-verdict.json 2>/dev/null)";
-          test -n "$v" -a "$v" != PASS -a "$v" != FAIL -a "$v" != NEEDS_REVISION
+          kk stage run itc-report-summary "${vars.work_dir}" "$(jq -r '.maxRevisions' "${vars.work_dir}/itc-options.json")"