@gobing-ai/knowledge-kit 0.0.14 → 0.0.16

package/plugins/kk/{workflows → scripts}/validate-voicescript.ts

@@ -2,10 +2,10 @@
 /**
  * Runtime VoiceScript checker for kk-solo-podcast.
  *
- * Copied with the workflow YAML into $KK_WORKFLOWS_DIR (default
- * ~/.config/kk/workflows). Node/Bun builtins only — no @gobing-ai/* and no
- * relative imports into generations/voice-gen (those paths do not exist next
- * to the runtime copy).
+ * Resolved from the kk package (`plugins/kk/scripts/`) by `kk-workflow-stages.ts`,
+ * or from an explicit runtime override ($KK_WORKFLOWS_DIR / ~/.config/kk/workflows)
+ * when one exists. Node/Bun builtins only — no @gobing-ai/* and no relative imports
+ * into generations/voice-gen (those paths do not exist outside the package).
  *
  * SYNC: plugins/generations/voice-gen/src/voicescript.ts (validateVoiceScript
  * + engine/language enums + text/instruct/chunk/crossfade caps). Keep error

package/plugins/kk/{workflows → scripts}/wrap-voicescript-doc.ts

@@ -2,13 +2,14 @@
 /**
  * Runtime VoiceScript→Doc[] wrapper for kk-solo-podcast.
  *
- * Copied with the workflow YAML into $KK_WORKFLOWS_DIR (default
- * ~/.config/kk/workflows). Node/Bun builtins only — no @gobing-ai/* and no
- * relative imports (those paths do not exist next to the runtime copy).
+ * Resolved from the kk package (`plugins/kk/scripts/`) by `kk-workflow-stages.ts`,
+ * or from an explicit runtime override ($KK_WORKFLOWS_DIR / ~/.config/kk/workflows)
+ * when one exists. Node/Bun builtins only — no @gobing-ai/* and no relative imports
+ * (those paths do not exist outside the package).
  *
- * SYNC: plugins/kk/workflows/kk-solo-podcast.yaml (wrap-docs state shells this
- * script with scriptPath, outPath, voiceProfile argv). The wrap shape must stay
- * a single-Doc array with sha256(file://scriptPath)[0:16] id — voice-gen and
+ * SYNC: plugins/kk/scripts/kk-workflow-stages.ts (its `wrap` verb delegates here with the
+ * scriptPath, outPath, voiceProfile argv the kk-solo-podcast wrap-docs state passes). The wrap
+ * shape must stay a single-Doc array with sha256(file://scriptPath)[0:16] id — voice-gen and
  * tests depend on it.
  */
 import { createHash } from 'node:crypto';

package/plugins/kk/skills/audio-authoring/SKILL.md

@@ -65,13 +65,12 @@ directly.
 | Artifact | Path | Written by |
 | --- | --- | --- |
 | Brief (input) | `brief.md` | supplied before invocation — topic phrase or Markdown brief |
-| Briefing | `1-briefing/briefing.md` | `briefing` — thesis, takeaways, audience, duration, tone |
+| Briefing | `1-briefing-briefing.md` | `briefing` — thesis, takeaways, audience, duration, tone |
 | Outline options | `2-outline/outline-option-a.md`, `outline-option-b.md`, `outline-option-c.md` | `outline` — always two or three (a and b required; c optional) |
 | Approved outline | `2-outline/outline-approved.md` | `outline` — after explicit operator selection |
-| VoiceScript | `3-script/voicescript.yaml` | `script` — from the approved outline only |
+| VoiceScript | `3-script-voicescript.yaml` | `script` — from the approved outline only |
 
-Each operation creates the directory it writes into (`1-briefing/`, `2-outline/`,
-`3-script/`) when absent. No other files are created — no metadata, no JSON
+Each operation creates the directory it writes into (`2-outline/`) when absent; single-file stages write `<step>-<name>` at the workspace root. No other files are created — no metadata, no JSON
 manifests, no templates, no placeholders.
 
 ## Modes
@@ -101,7 +100,7 @@ from any existing approved artifact:
 2. **Outline** — if `2-outline/outline-approved.md` is missing, run the `outline`
    semantics (write options, selection gate). If it exists, reuse it — do not
    regenerate.
-3. **Script** — if `3-script/voicescript.yaml` is missing, run the `script` semantics
+3. **Script** — if `3-script-voicescript.yaml` is missing, run the `script` semantics
    (write + review gate). If it exists and is approved, report it as final — do not
    rewrite.
 4. **Report** the final artifact paths and stop. Never re-run a completed step; never
@@ -110,15 +109,15 @@ from any existing approved artifact:
 ### briefing
 
 1. **Prerequisite** (fail loud): `brief.md` missing → stop with recovery ("supply a
-   brief at `<dir>/brief.md` first"). `1-briefing/briefing.md` exists without
+   brief at `<dir>/brief.md` first"). `1-briefing-briefing.md` exists without
    `--force` → stop before replacing.
-2. **Read** `brief.md` and write `1-briefing/briefing.md`: core thesis, key listener
+2. **Read** `brief.md` and write `1-briefing-briefing.md`: core thesis, key listener
    takeaways, audience profile, target spoken duration (`--duration` minutes), tone,
    and what material from the brief to emphasize or cut.
 
 ### outline
 
-1. **Prerequisite** (fail loud): `1-briefing/briefing.md` missing → stop with
+1. **Prerequisite** (fail loud): `1-briefing-briefing.md` missing → stop with
    recovery ("run `briefing` or `create` first").
 2. **Resume**: `2-outline/outline-approved.md` exists → reuse it; without `--force`,
    stop before replacing.
@@ -135,10 +134,10 @@ from any existing approved artifact:
 1. **Prerequisite** (fail loud): `2-outline/outline-approved.md` missing → stop with
    recovery ("run `outline` or `create` first — never script before outline
    approval").
-2. **Resume**: `3-script/voicescript.yaml` exists → without `--force` or `--revise`,
+2. **Resume**: `3-script-voicescript.yaml` exists → without `--force` or `--revise`,
    stop before replacing ("script exists at `<path>`; to revise pass `--revise
    <feedback>`, to replace pass `--force`").
-3. **Write** `3-script/voicescript.yaml` from the approved outline only, obeying the
+3. **Write** `3-script-voicescript.yaml` from the approved outline only, obeying the
    VoiceScript contract and the spoken-budget rule below. Solo mode shape: one
    speaker, **no** `speakers` map, per-segment `profile` omitted. Emit only valid
    YAML — no markdown fences, no repo or docs paths in the file body.
@@ -155,9 +154,9 @@ from any existing approved artifact:
 ## VoiceScript contract
 
 The authoring template lives at **`templates/voicescript.solo.yaml`** (relative to
-this skill file) — read it first when authoring `3-script/voicescript.yaml`; it is a
+this skill file) — read it first when authoring `3-script-voicescript.yaml`; it is a
 valid-YAML skeleton with per-field constraint comments. The executable authority is
-`plugins/kk/workflows/validate-voicescript.ts` (canonical source
+`plugins/kk/scripts/validate-voicescript.ts` (canonical source
 `plugins/generations/voice-gen/src/voicescript.ts`); the template is its
 authoring-time distillation. No other fields are valid authoring targets — do not
 invent fields (no `default_profile`, no required `title`).

package/plugins/kk/skills/itc-generating/SKILL.md

@@ -82,7 +82,7 @@ workspace — it delegates to `topic`, which writes exactly these paths:
 | Brief | `brief.md` | `topic` `init` |
 | Outline options | `2-outline/outline-option-{a,b,c}.md` | `topic` `outline` |
 | Approved outline | `2-outline/outline-approved.md` | `topic` `outline` (after selection gate) |
-| Draft | `3-draft/draft-article.md` | `topic` `draft` (from approved outline, review gate) |
+| Draft | `3-draft-draft-article.md` | `topic` `draft` (from approved outline, review gate) |
 
 ## create sequence
 
@@ -104,7 +104,7 @@ workspace — it delegates to `topic`, which writes exactly these paths:
    show-don't-tell with diagrams/examples, accessibility) plus the platform playbook's constraints
    (e.g. WeChat mobile formatting or English-platform framing). The draft is written by `topic`
    from the approved outline; the method shapes it.
-6. **Optional judge gate** — if `--judge` and `3-draft/draft-article.md` is approved, invoke
+6. **Optional judge gate** — if `--judge` and `3-draft-draft-article.md` is approved, invoke
    `content-judge` with the `tech-accuracy` rubric. A non-`PASS` verdict is reported to the operator; it
    does **not** auto-publish and does not auto-revise past `topic`'s 3-round bound.
 7. **Print** the final artifact paths and stop.

package/plugins/kk/skills/itc-generating/references/generic-craft.md

@@ -74,7 +74,7 @@ all five disciplines while authoring the draft.
 
 ## Applying this in `create`
 
-While drafting `3-draft/draft-article.md` (after `topic`'s outline gate), apply: one goal per
+While drafting `3-draft-draft-article.md` (after `topic`'s outline gate), apply: one goal per
 document enforced at the draft-review gate; the Value Proposition as a scope firewall; explicit
 prerequisites and POLA; show-don't-tell with diagrams/examples; and accessibility. The `--judge`
 gate then verifies technical accuracy against the rubric.

package/plugins/kk/skills/itc-generating/references/platform-english.md

@@ -69,4 +69,4 @@ for the draft — never reimplements publishing.
 
 Load this reference when `--playbook english`. It informs the draft's framing (audience, voice,
 platform-native format) and the distribution plan, but the deliverable stays `topic`'s
-`3-draft/draft-article.md` — this playbook never publishes and never writes a parallel artifact.
+`3-draft-draft-article.md` — this playbook never publishes and never writes a parallel artifact.

package/plugins/kk/skills/itc-generating/references/platform-wechat.md

@@ -56,5 +56,5 @@ compliance constraints — never reimplements registration, publishing, or the A
 
 Load this reference when `--playbook wechat`. It informs the draft's structure (mobile-first
 formatting, Chinese-language expectations, title/abstract limits, review rigor) but the deliverable
-stays `topic`'s `3-draft/draft-article.md` — this playbook never registers an account, never
+stays `topic`'s `3-draft-draft-article.md` — this playbook never registers an account, never
 publishes, and never touches the WeChat API.

package/plugins/kk/skills/storm-research/SKILL.md

@@ -68,7 +68,7 @@ skill is also callable directly as `Skill(skill="storm-research", args="<topic|-
    A question constrains the search and the report; a noun phrase invites scope creep.
 2. **Choose input**: topic sentence, or a markdown file via `--in` (XOR). File mode derives the
    query from the first ATX H1 (`/^#\s+(.+)$/m`), else the basename without extension.
-3. **`work_dir` is the resolved topic directory** `$works_dir/<topic-id>`, computed by the
+3. **`work_dir` is the resolved topic directory** `$works_dir/kk-storm-research/<topic-id>`, computed by the
    invoker (the command or the operator) via the 0056 `topicId()` algorithm — never by the
    workflow. `prepare` only `mkdir` + materializes files into `${vars.work_dir}`.
 4. **Pick fixture vs live** (see below). Default is live (`fixture: "false"`); pass
@@ -95,7 +95,7 @@ skill is also callable directly as `Skill(skill="storm-research", args="<topic|-
 
 ## Works layout (0056, frozen; ADR-013 adds `references/`)
 
-Per-topic workspace at `$works_dir/<topic-id>/`:
+Per-topic workspace at `$works_dir/kk-storm-research/<topic-id>/`:
 
 | File | Written by | Contents |
 | --- | --- | --- |
@@ -108,7 +108,7 @@ Per-topic workspace at `$works_dir/<topic-id>/`:
 | `references/<doc-id>.md` | ingest (live path only) | normalized full content per source (`/v2/scrape` → markitdown); file name = Doc id; audit trail and the citation-resolution target for the report tail (ADR-013) |
 
 Contrast: `topic`'s authoring workspace is `./<kebab-case(topic)>` with `brief.md` /
-`2-outline/` / `3-draft/` and explicitly excludes research. C4 works live under `$works_dir`,
+`2-outline/` / `3-draft-draft-article.md` and explicitly excludes research. C4 works live under `$works_dir`,
 outside any repo.
 
 ## Live vs fixture
@@ -130,8 +130,8 @@ outside any repo.
 | Both `<topic>` and `--in` set, or neither | exit 1, stderr states the XOR rule; no writes | pass exactly one of `topic` / `--in` |
 | `--in` file unreadable (missing / I/O) | exit 1, stderr names the path | fix the path / permissions |
 | Derived query / topic-id empty (no H1 and empty basename) | exit 1, stderr shows the derived value | add an H1 or give the file a real name |
-| Dest `$workflows_dir/<name>.yaml` exists with different bytes | warning, **no overwrite**; run proceeds with the user's copy | re-run with `--force` to replace from the install source |
-| Workflow YAML cannot be resolved from any install source | exit 1, stderr lists the roots searched (`KK_WORKFLOWS_SOURCE`, `plugins/kk/workflows`) | reinstall the package / set `KK_WORKFLOWS_SOURCE` |
+| Resolved YAML is the user override while an installed copy differs | run proceeds with the override (no drift warning) | re-run with `--force` to refresh the override from the install source |
+| Workflow YAML cannot be resolved from any install source | exit 1, stderr lists the roots searched (user override, `KK_WORKFLOWS_SOURCE`, bun/npm global installs, kk package root, `plugins/kk/workflows`) | reinstall the package / set `KK_WORKFLOWS_SOURCE` |
 | `KK_CONFIG` set but unreadable, or config unparseable / invalid types | exit 1, stderr names the key + expected vs actual type | fix the file, or delete it (recreated with defaults next run) |
 | Missing config at `KK_CONFIG` | **not a failure** — create-on-first-run with compiled defaults; an existing file is never overwritten | — |
 | `markitdown` missing from `PATH` (live mode) | ingest exit 1, stderr `web-search failed: markitdown is not on PATH`; probed before any network call, so no `docs.json` write | install markitdown / put it on `PATH`, re-run ingest |

package/plugins/kk/skills/topic/SKILL.md

@@ -64,9 +64,9 @@ All paths are relative to the workspace `--dir`. Every operation uses these exac
 | Brief | `brief.md` | `init` — topic line, or verbatim copy of the supplied brief |
 | Outline options | `2-outline/outline-option-a.md`, `outline-option-b.md`, `outline-option-c.md` | `outline` — always two or three (a and b required; c optional) |
 | Approved outline | `2-outline/outline-approved.md` | `outline` — after explicit operator selection |
-| Draft | `3-draft/draft-article.md` | `draft` — from the approved outline only |
+| Draft | `3-draft-draft-article.md` | `draft` — from the approved outline only |
 
-`init` creates `brief.md`, `2-outline/`, and `3-draft/`. No other files are created — no
+`init` creates `brief.md` and `2-outline/`; `draft` writes `3-draft-draft-article.md` at the workspace root. No other files are created — no
 metadata, no JSON manifests, no templates, no placeholders.
 
 ## Operations
@@ -79,7 +79,7 @@ existing approved artifact (R3):
 1. **Resolve the brief** — topic phrase or `--brief` file; run the `init` semantics.
 2. **Outline** — if `2-outline/outline-approved.md` is missing, run the `outline`
    semantics (write options, selection gate). If it exists, reuse it — do not regenerate.
-3. **Draft** — if `3-draft/draft-article.md` is missing, run the `draft` semantics (write
+3. **Draft** — if `3-draft-draft-article.md` is missing, run the `draft` semantics (write
    + review gate). If it exists and is approved, report it as final — do not rewrite.
 4. **Report** the final artifact paths and stop. Never re-run a completed step; never
    overwrite an existing approved artifact without `--force`.
@@ -94,7 +94,7 @@ existing approved artifact (R3):
    after explicit operator confirmation to replace, or choose a new `--dir`). Never delete
    or overwrite existing content without `--force`.
 3. **Create** `brief.md` (the topic line, or a verbatim copy of the supplied brief),
-   `2-outline/`, and `3-draft/`.
+   `2-outline/`, and the flattened `3-draft-draft-article.md`.
 4. **Print** the workspace layout and the next step (`outline` or `create`).
 
 ### outline
@@ -117,16 +117,16 @@ existing approved artifact (R3):
 
 1. **Prerequisite** (fail loud, R5): `2-outline/outline-approved.md` missing → stop with
    recovery ("run `outline` or `create` first — never draft before outline approval").
-2. **Resume** (R3): `3-draft/draft-article.md` exists → without `--force` or `--revise`,
+2. **Resume** (R3): `3-draft-draft-article.md` exists → without `--force` or `--revise`,
    stop before replacing ("draft exists at `<path>`; to revise pass `--revise <feedback>`,
    to replace pass `--force` after explicit operator approval").
-3. **Write** `3-draft/draft-article.md` from the approved outline only.
+3. **Write** `3-draft-draft-article.md` from the approved outline only.
 4. **Review gate** (R1): present the draft; offer **approve** or **revision**. Bounded
    revision: at most **3 revision rounds**; each round takes `--revise <feedback>`,
    rewrites the draft from the approved outline plus the feedback, and re-presents it.
    After 3 rounds, stop and require an explicit operator decision (approve, restart from
    the outline, or abandon) — never loop past the bound.
-5. **On approval**, the existing `3-draft/draft-article.md` is the approved artifact;
+5. **On approval**, the existing `3-draft-draft-article.md` is the approved artifact;
    record the approval and stop. Print the final draft path.
 
 ## Fail-loud table (R5)