@gobing-ai/knowledge-kit 0.0.37 → 0.1.1

package/plugins/kk/skills/smart-seo/references/operations.md

@@ -0,0 +1,209 @@
+# Smart SEO — operations
+
+Setup, run, progress, and failure handling for the `kk-smart-seo` audit. The workflow is the
+orchestrator; `kk` owns every step (ADR-007). Nothing here mutates a site.
+
+## 1. Resolve the KK package root
+
+Both the stages and the decision catalogs live in the **installed** package, not in a checkout:
+
+```bash
+# The real path of the executable that is actually running (follows symlinks):
+readlink -f "$(command -v kk)"          # -> <pkg>/dist/index.js
+PKG_ROOT="$(dirname "$(dirname "$(readlink -f "$(command -v kk)")")")"
+```
+
+`kk stage run` resolves `plugins/kk/scripts/kk-workflow-stages.ts` next to its own entry: a real
+checkout uses the checked-in runner, an installed entry always uses its own package copy. An
+unrelated ancestor `plugins/` directory is never selected, so a run from an unrelated cwd is safe.
+
+## 2. Register the SEO decision catalogs (required for the integrated workflow)
+
+`decisions.paths` in the consumer project config (`.spur/config.yaml`) is the whole search path.
+**Append** one entry — never replace the list:
+
+```yaml
+decisions:
+  paths:
+    - <existing entry>                     # keep every existing entry
+    - <PKG_ROOT>/plugins/kk/decisions       # appended: the 4 SEO catalogs, 22 decisions
+  maker: <existing maker>                   # keep the maker and makers: mapping untouched
+```
+
+`seo-preflight` with `require_decisions=true` (the workflow's own call) fails with this pointer
+when the catalogs are not served:
+
+```text
+seo-preflight: SEO decision catalogs are not served — missing catalog file(s): kk-seo-site.yaml, ...
+Registration fix: append `<kk-package-root>/plugins/kk/decisions` to the project config `decisions.paths`
+(.spur/config.yaml), preserving every existing entry and maker setting, then re-run preflight.
+```
+
+Verify without dispatching a maker (configuration evidence, never model health):
+
+```bash
+spur decision list --json     # must serve the 22 kk-seo-* ids
+spur decision show kk-seo-page-type --json   # -> catalog, layer, effective maker + source
+spur decision status --json   # -> load errors, duplicate ids, per-decision effective maker
+```
+
+Collection-only stage use (`require_decisions=false`) and the explicit offline fixture mode need
+no catalogs. Do not run an audit that silently writes user-global configuration; the append above
+is a one-time operator setup, and it is repeated only when an upgrade changes the resolved
+package root.
+
+Every decision in those catalogs declares exactly two parameters — `subject_id` and `locale`
+(plus `candidates` on `kk-seo-keyword-page`). Spur treats a declared parameter with no default as
+required and rejects an undeclared one, so a direct probe like `spur decision run
+kk-seo-page-type --param subject_id=…` is an input rejection before any maker runs, not a
+judgment. Pass both parameters, and never invent a third (`url`, for example, is carried inside
+the compact evidence packets, not as a parameter).
+
+**The catalogs' declared schema must resolve from where they live.** Each shipped SEO catalog
+declares `$schema: "@gobing-ai/spur/schemas/decision-catalog.schema.json"`, and Spur resolves that
+schema through the module tree above the catalog's own directory. A global install satisfies this
+by construction (both packages are siblings in the global tree); with a project-local KK install,
+keep `spur` resolvable from the installed package's location or `decision status --json` reports
+the catalogs as `loadErrors` (`Cannot resolve package schema …`) and preflight fails. A load error
+is a setup defect to fix, never a reason to fall back to a maker default silently.
+
+## 3. Options file
+
+Write a UTF-8 JSON object (≤ 64 KiB, strict schema — unknown keys are refused) and pass its path
+as data, never as shell source:
+
+```json
+{
+  "url": "https://example.com",
+  "locale": "en-US",
+  "business_context": "",
+  "max_pages": 60,
+  "max_depth": 5,
+  "max_requests": 200,
+  "deadline_seconds": 600,
+  "semantic_pages": 20,
+  "max_pairs": 10,
+  "max_keywords": 10,
+  "max_decision_calls": 320,
+  "performance": false,
+  "visibility_file": "",
+  "fixture": ""
+}
+```
+
+| Field | Meaning and bounds |
+| --- | --- |
+| `url` | Required HTTP(S) URL or bare domain (bare becomes HTTPS). Userinfo, nonstandard ports, local/reserved addresses and malformed hostnames are refused. |
+| `locale` | BCP-47; describes the report audience and the imported query market. It never assumes the site's language. |
+| `business_context` | Optional operator context ≤ 2,000 UTF-16 units. It is context, not website evidence. |
+| `max_pages` / `max_depth` | 60 / 5 by default; maxima 200 / 10. The page quota counts every attempt, including blocked, redirect and error records. |
+| `max_requests` / `deadline_seconds` | 200 / 600 by default; maxima 500 / 1800. One shared quota and deadline covers robots, sitemaps, pages, probes and link targets. |
+| `semantic_pages` / `max_pairs` / `max_keywords` | 20 / 10 / 10 by default; maxima 60 / 40 / 30. Selection is deterministic (homepage, observed depth/inlinks, URL tie break). |
+| `max_decision_calls` | 320 by default, maximum 1000. Every attempt consumes one; there is no retry on an unknown-charge call. Exhaustion is an explicitly partial assessment. |
+| `performance` | `false` by default. `true` requests PSI mobile/desktop and CrUX for at most 3 selected pages; the stage shares a 300 s deadline and a 12-call cap. |
+| `visibility_file` | Optional normalized local JSON snapshot (§4). Never an arbitrary provider dump. |
+| `fixture` | Explicit offline fixture **directory**. With a fixture, network access and real maker dispatch are forbidden. Production never falls back to fixture data. |
+
+## 4. Audit scope — the submitted host plus its exact `www` toggle
+
+Scope is the normalized submitted hostname with **one** leading `www.` removed when present, or
+added when absent — nothing else. `shop.example.com` admits `shop.example.com` and
+`www.shop.example.com` only: no registrable apex, no sibling subdomains, and default ports stay
+origin-specific. Off-scope redirects and links are recorded, never followed; `www`/non-`www` and
+HTTP/HTTPS transitions are observations, not defects. There is no browser rendering and no outbound
+external-link fetching in this version: state that assessment as **not collected** rather than
+assuming a result.
+
+## 5. Imported visibility snapshot
+```json
+{
+  "schemaVersion": 1,
+  "siteOrigin": "https://example.com",
+  "locale": "en-US",
+  "source": "search-console-export|analytics-export|manual",
+  "collectedAt": "2026-10-01T00:00:00Z",
+  "measurementKind": "measured",
+  "rows": [{ "query": "example query", "url": "https://example.com/a", "clicks": 4, "impressions": 120, "position": 8.5, "citations": 2, "sampleCount": 500, "platform": "chatgpt" }]
+}
+```
+
+Maximum 1 MiB / 500 rows; strings bounded; counts are finite nonnegative numbers; `position` ≥ 1;
+`citations` ≤ `sampleCount` with `platform` required; any `url` must belong to the audit scope.
+Unknown properties, a conflicting locale or site identity, a future timestamp, or evidence older
+than 90 days fails validation before use. Keywords come from this data — never invented volumes.
+
+## 6. Run the workflow
+
+```bash
+spur workflow run <PKG_ROOT>/plugins/kk/workflows/kk-smart-seo.yaml \
+  --vars '{"options_file":"/abs/path/options.json"}' --quiet
+```
+
+Leave `work_dir` empty: `seo-preflight` allocates `.works/kk-smart-seo/<UTC-stamp>-<runId>` with
+create-new semantics (an existing non-empty directory is refused) and writes the resolved absolute
+path to `.spur/run/<runId>-seo-work-dir.txt`, which the workflow reads back into `work_dir` before
+collection. A fixed `work_dir` must name an absent or empty directory.
+
+Stages: `preflight → collect → check → enrich → judge → score → narrative → report`, terminal
+`done | partial | failed`. `done` means every requested stage assessed its eligible evidence — not
+that the site has no SEO issues. `partial` is successful artifact delivery with missing requested
+evidence (an unavailable optional PSI/CrUX/typed-decision input is never a failure). `failed` is the
+sole failure state.
+
+Individual stages stay independently callable for review and re-scoring:
+
+```bash
+kk stage run seo-preflight <work_dir> <options_file> [run_id] [require_decisions]
+kk stage run seo-collect <work_dir>
+kk stage run seo-check <work_dir>
+kk stage run seo-enrich <work_dir>
+kk stage run seo-judge <work_dir>
+kk stage run seo-score <work_dir> [new_revision_dir]
+kk stage run seo-report <work_dir>
+```
+
+## 7. Progress
+
+- `spur workflow trace <run-id>` — the action trace; the state id tells you which stage is running.
+- `.spur/run/<runId>-seo-work-dir.txt` — the run-bound workspace path (never guess it).
+- `.spur/memory/runs/<run-id>.md` — the two-file run record.
+- Stage progress goes to stderr and is captured in the run record; long collection stages are
+  bounded by `max_requests`/`deadline_seconds`, so a run always terminates.
+
+Artifacts under the work dir, one run id shared by all of them: `options.json`, `manifest.json`,
+`crawl.json`, `checks.json`, `judgments.json`, `performance.json`, `visibility.json`, `audit.json`,
+`digest.md`, `narrative.json` (optional), `report.json`, `report.md`. Every JSON object carries
+`schemaVersion`, `methodVersion`, `runId`, `createdAt`, `inputDigest` and predecessor digests;
+wrong run, version or digest is a hard error. Writes are sibling temp file + rename, so a reader
+never sees a partially written value. The saved audit is durable under `.works/`, not volatile
+`.spur/run/`.
+
+## 8. Failure handling
+
+| Symptom | Handling |
+| --- | --- |
+| Missing/unserved SEO catalogs | Apply §2, re-run. Preflight failure text names the missing files/ids. |
+| Invalid options | Fix the named field; the file is validated before any collection. |
+| `work_dir` already populated | Use the run's own bound directory, or a new empty one. Never clear a directory from a previous run — preflight never deletes it. |
+| Network policy refusal (local/reserved address, peer mismatch, redirect off-scope) | The collected observation is recorded as unavailable/blocked. Do not work around it: an off-scope or non-public target is out of the audit's trust boundary. |
+| Budget exhaustion (`limits.hitLimit`) | Report it as a limit. Never present an exhausted crawl as a complete one. |
+| Optional evidence unavailable (no PSI/CrUX key, insufficient sample, 429, timeout) | Recorded as an availability outcome; the report is `partial`, never failed and never a zero score. |
+| Maker fallback / low confidence | The judgment stays `unknown`/`review`. It is not a site defect and not a measurement. |
+| Malformed predecessor artifact | Hard error, nonzero exit — malformed input is never reinterpreted as an empty result. |
+| Narrative absent or rejected | The report is still delivered with `narrativeStatus: omitted|rejected` and a deterministic summary; an optional agent failure is not an audit failure. |
+| Cancellation | Active sockets and decision children are aborted, completed artifacts are preserved with a cancellation marker, and no new requests or decisions start. |
+
+## 9. Offline rescoring
+
+Score a saved audit again without touching the network or the source run:
+
+```bash
+kk stage run seo-score <saved-work_dir> <new-revision_dir>   # revision dir must be absent/empty
+kk stage run seo-report <new-revision_dir>
+```
+
+The revision copies the validated bounded inputs (`options.json`, `manifest.json`, `crawl.json`,
+`checks.json`) beside a fresh `audit.json`, keeps the original `runId` and adds a new `revisionId`.
+Source artifacts stay immutable, so a comparison between revisions reads two durable directories.
+Do not compare scores across runs with different coverage: `coverage` records the denominators,
+and the score is undefined (`null`) when no row of that category is applicable.

package/plugins/kk/skills/smart-seo/references/seo-geo-sources.md

@@ -0,0 +1,90 @@
+# Smart SEO — sources, crawler policy and GEO limits
+
+Every rule row carries the primary `sourceUrl` and the `sourceCheckedAt` date that justified it, and
+the report header prints the method version's checked-at date. This reference is the refresh
+procedure and the per-source limits — not a license to restate a source as a measurement.
+
+## 1. Primary sources (checked 2026-10-14)
+
+| Source | What it owns | Limit / unknown |
+| --- | --- | --- |
+| [Google AI optimization guide](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide) | Original, useful content plus technical access are what matter for Google AI surfaces. Special AI files, rigid chunking and schema are not eligibility requirements. | It promises no citation, ranking or inclusion. |
+| [Google AI features](https://developers.google.com/search/docs/appearance/ai-features) | Snippet eligibility and indexing are prerequisites; crawl observations cannot verify inclusion. | Reporting surface is described inconsistently across Google pages and depends on the account; never freeze an availability claim. |
+| [Google common crawlers](https://developers.google.com/crawling/docs/crawlers-fetchers/google-common-crawlers) | `Google-Extended` controls separate uses and does not control Search inclusion. | Robots groups express the site owner's **declared** policy only. |
+| [OpenAI crawler documentation](https://developers.openai.com/api/docs/bots) | `OAI-SearchBot` is for search, `GPTBot` for training, `ChatGPT-User` is user-triggered with different semantics. | Blocking training is not a search defect; no OpenAI behavior is observable from the audit. |
+| [Google Search updates](https://developers.google.com/search/updates) | Dated change log; FAQ rich results were fully retired on 2026-05-07 (eligibility had already been restricted to authoritative government/health sites in Aug/Sep 2023). | Any removal date must be re-read from this page, not from memory. |
+| [PSI API notice](https://developers.google.com/speed/docs/insights/v5/get-started) | PSI setup and the announced CrUX removal from PSI. | The removal is announced, not completed — do not report it as done. |
+| [Web Vitals](https://web.dev/articles/vitals) | Field p75 LCP ≤ 2.5 s, INP ≤ 200 ms, CLS ≤ 0.1 defines a Core Web Vitals pass. | Lab TBT cannot substitute for INP; a missing field sample is `unknown`, never zero. |
+
+Supporting rule-level sources (RFC 9309 for robots matching, Google canonicalization and robots-meta
+docs, sitemap docs) are recorded per row in `plugins/kk/scripts/seo-rules.ts` (`sourceUrl`).
+
+## 2. Crawler policy — keep the three purposes separate
+
+The audit reads the site's declared crawler policy and the audit's own requests. It cannot observe
+what any other crawler did. When you explain crawler findings, name the purpose explicitly:
+
+| Purpose | Typical user agents (as documented by their owners) | What a block means |
+| --- | --- | --- |
+| **Search / answer-surface indexing** | `Googlebot`, `Bingbot`, `OAI-SearchBot` | Affects eligibility for search and AI answer surfaces that use a search index. Operator intent required: a deliberate restriction is a decision, not a defect. |
+| **Model training corpus** | `GPTBot`, `Google-Extended`, `ClaudeBot`, `CCBot` | A policy choice about training data. Blocking training is **not** a search defect, and allowing it is not a ranking or citation strategy. |
+| **User-triggered fetch** | `ChatGPT-User` and similar on-demand fetchers | Different robots semantics: the fetch serves a user's explicit request. A block limits that user's session, not search eligibility. |
+
+Rules the audit uses here: `robots_blocks_site` (adapted, critical), `ai_bots_blocked` and
+`llms_txt_missing` (informational), `js_dependent` (informational). Report the observed directive,
+the path it applies to and the operator-intent caveat — never "AI crawlers cannot see your site".
+
+Also state what the audit itself did: its own crawl honors robots.txt, the declared `Crawl-delay`
+and one shared page/request/byte/deadline budget, and it sends no credentials or cookies.
+
+## 3. Source refresh procedure
+
+Do this before changing a rule, re-publishing a rubric statement, or answering a question whose
+answer depends on current engine behavior:
+
+1. Open the rule's `sourceUrl` from the failing row (or the table above) and re-read the relevant
+   section. Do not refresh from a summary, a vendor README or a search-result snippet.
+2. Record today's date as the new `sourceCheckedAt` for that rule and update `sourceUrl` if the
+   owner moved the page. Never silently keep an old checked-at date.
+3. If the source contradicts the rule's current rationale, treat that as a **rule defect**: the
+   rationale, disposition and severity all change together, and the change is a method-version
+   change — not an in-run edit of a saved audit.
+4. If two sources disagree, keep the more conservative reading, report the uncertainty, and say
+   which pages disagree. Vendor self-reported model agreement is not human calibration.
+5. Never re-state an announced-but-incomplete change as shipped (for example the PSI/CrUX notice).
+
+Audits stay reproducible: a saved `audit.json` keeps the `sourceCheckedAt` it was produced with,
+and offline rescoring reuses the saved check rows rather than re-reading live sources.
+
+## 4. GEO (generative-engine) diagnostics and their limits
+
+GEO work in this method is **editorial diagnostics with explicit uncertainty**: intent
+satisfaction, first-hand specificity, verifiable provenance, entity consistency and self-contained
+answer-first facts. They are model judgments (`source: model`) with a maker and confidence, or
+heuristic content checks — never measurements of an answer engine's behavior. The two `geo`
+category rules and the page-level semantic decisions feed the action list exactly like other rows.
+
+What this means in practice:
+
+- Never state or imply that a change will produce citations, mentions, rankings or traffic.
+- No synthetic visibility percentage is generated from a quality score. A visibility number exists
+  only when the operator supplied an imported snapshot (§5 of `operations.md`), and it is reported
+  with its source, window, platform and denominator.
+- Locale-specific query and citation samples are dated snapshots, not live data. A missing
+  platform, denominator or sample count makes the row unusable — drop it rather than guess.
+- "Answer-first" (heading fit, self-contained answer, next step) is an editorial rubric applied to
+  the observed page text. It is not a snippet or citation predictor.
+- Where the evidence does not exist (a specific engine's answer for a specific query, an actual
+  citation rate, a training-corpus inclusion), say that it is unknown and name what would be needed
+  to know it. Live provider integration, rank tracking and Search Console OAuth are out of scope in
+  this version.
+
+## 5. Vendors and third-party code
+
+`vendors/` is reference-only: it is excluded from runtime and install resolution, and nothing may
+be read or copied out of it into a shipped file. The audit is native Bun/TypeScript — no Python
+path, no browser/rendering runtime, no bundled font assets. Vendor rule identities are retained for
+traceability, but their behavior reflects the dispositions in `plugins/kk/references/smart-seo-attribution.md`
+(shipped beside this skill), not the vendor's weighted grades or relative impact scale. The full vendor
+review lives in the source repository at `docs/plans/2026-10-14-smart-seo-vendor-review.md`; it is
+design-time context and is not installed, so never resolve a runtime path through it.

package/plugins/kk/workflows/feature-verification.yaml

@@ -10,8 +10,20 @@
 #
 # Run: spur workflow run feature-verification.yaml --vars '{"featureId":"D63"}'
 #
-# Shape: verify -> done | failed. The onEnter step runs the standard script
-# `feature-verification-steps.ts` (no public CLI verb, D63 task 0915): it
+# No project-side override is required (task 1185, A33). Since the pass moved into the
+# application (1176 / efd78f058) the bundled definition owns it end to end, so a
+# project-layer copy of this file (plus a rooted port under `.spur/scripts/`) is a
+# leftover — the port was written against an entry export contract that has since
+# changed. Remove the override so this definition applies, or migrate the port to the
+# current app-owned operation `runFeatureVerification` (the generated inline bundle's
+# export). If a stale consumer is still reached, feature-lifecycle's `verifying` entry
+# names it: the override path, the consumer script, the export it requires that the
+# shipped entry no longer provides, and the entry path. Reinstalling or upgrading the
+# plugin cannot supply a retired export — only the two remedies above can.
+#
+# Shape: verify -> done | failed. The onEnter step runs `spur feature verify`
+# (D63 task 0915; script-absorption PR-5 retired the feature-verification-steps
+# plugin script): it
 # resolves this very definition for the verifier identity (name, source path,
 # layer, definition digest), records the RUNNING receipt (run-scoped +
 # feature-latest copies), registers the run-scoped receipt as a run artifact,
@@ -40,36 +52,28 @@ vars:
   featureId: "X"
   spurBin: "spur"
   verificationCmd: "bun run spur-check"
+  # Operator-declared confidence level; empty derives it from the pass (HIGH when the selected
+  # definition's own command exited 0 with an unchanged proof-input digest, MEDIUM under a caller
+  # `--cmd` override, LOW otherwise). The completion boundary refuses a PASS carrying no level or
+  # LOW unless the receipt records the acknowledgement below.
+  confidence: ""
+  # Operator acknowledgement of a LOW level. It rides the receipt, so the transition reads it from
+  # the evidence rather than from whatever flags a later command happens to pass.
+  ackLowConfidence: "false"
   __runId: ""
 
 states:
   - id: verify
     description: >
-      Resolve this run's installed sp script root via Superskill, then run the
-      pinned installed verifier with Bun against the repo-wide check set. The
-      verifier records the bound evidence receipt (verifier identity,
-      checked-input digest, run identity) and the coarse status file. Both
-      actions fail closed — a locator/script failure, an unresolved or
-      non-installed root, an absent verifier, or a failing check yields a
-      non-PASS status — and always exit 0, so the transition guard routes
-      missing/corrupt/FAIL to `failed`.
+      Run the repo-wide check set via `spur feature verify`, which
+      records the bound evidence receipt (verifier identity, checked-input
+      digest, run identity) and the coarse status file, always exit 0 so the
+      transition guard routes missing/corrupt/FAIL to `failed`.
     onEnter:
       - kind: shell
         options:
           command: >-
-            S="$(superskill script path sp script-root.mjs 2>/dev/null)" || S="";
-            if [ -n "$S" ] && [ -f "$S" ]; then node "$S" --run-id "$__runId" --spur-bin "$spurBin";
-            else echo "script-root failed closed — run 'superskill install sp --marketplace gobing-ai/spur'" >&2;
-            fi;
-            exit 0
-      - kind: shell
-        options:
-          command: >-
-            mkdir -p .spur/run;
-            DIR="$(jq -r 'select(.mode == "installed" and (.dir | type == "string") and .dir != "") | .dir' ".spur/run/$__runId-script-root.json" 2>/dev/null)" || DIR="";
-            [ -n "$DIR" ] && [ -f "$DIR/feature-verification-steps.mjs" ] && S="$DIR/feature-verification-steps.mjs";
-            [ -f "$S" ] && bun "$S" verify --feature-id "$featureId" --run-id "$__runId" --spur-bin "$spurBin" || printf 'FAIL feature-verification failed closed — unresolved root or verifier failure\n' > ".spur/run/$__runId-feature-verification.status";
-            exit 0
+            mkdir -p .spur/run; ACK=""; [ "$ackLowConfidence" = "true" ] && ACK="--ack-low-confidence"; $spurBin feature verify "$featureId" --run-id "$__runId" --confidence "$confidence" $ACK --no-logo || printf 'FAIL feature-verification failed closed — spur feature verify exited nonzero\n' > ".spur/run/$__runId-feature-verification.status"; exit 0
 
   - id: done
     description: Terminal — repo-wide checks passed and the receipt is bound.
@@ -80,7 +84,7 @@ states:
 transitions:
   - from: verify
     to: done
-    description: Repo-wide checks passed — the script completed the receipt with PASS.
+    description: Repo-wide checks passed — `spur feature verify` completed the receipt with PASS.
     guard:
       kind: shell
       options:

package/plugins/kk/workflows/kk-daily-ai-voice2.yaml

@@ -22,10 +22,13 @@ vars:
   window: "24h"
   language: "zh"
   voice_profile: "robin-news"
-  # Voice driver switch — voicebox (voice-gen) | ominivoice (omni-voice-gen) | gemini (gemini-tts)
-  # | voxcpm (voxcpm-tts, opt-in; ADR-036; provisional 5.6 字/秒 estimate). Same default as
-  # kk-daily-ai-voice: gemini-tts (20260929 operator override, verified live).
-  vdriver: "gemini"
+  # Voice driver switch — voxcpm (voxcpm-tts) | gemini (gemini-tts) | voicebox (voice-gen)
+  # | ominivoice (omni-voice-gen). The generate tier below mirrors the fallback order, and the
+  # fit/duration gates take their spoken-char rate from this var — switching drivers here is enough.
+  # 2026-10-15 production test (operator decision): voxcpm first, then gemini, then omni. voxcpm
+  # rendered that episode in 21.8 min at a measured 5.19 字/秒 (fitted at 5.2); if the audio verdict
+  # is good this is the standing order, otherwise revert this default to "gemini".
+  vdriver: "voxcpm"
   intro_music: ".works/kk-daily-ai-voice/AI每日资讯_8秒播客片头.mp3"
   surfdash_root: "/Users/robin/xprojects/surfdash"
   title: ""
@@ -258,7 +261,7 @@ nodes:
         command: >-
           kk store pool-count "${vars.work_dir}/21-plan/${vars.run_date}_04_quality-control-content_candidates.json" --min 1
           && test "${vars.plan_translate_enabled}" = "true"
-          && ! test -s "${vars.work_dir}/21-plan/${vars.run_date}_03_plan_plan.json"
+          && ! jq -e --argjson n "$(jq '.metadata.docs|length' "${vars.work_dir}/21-plan/${vars.run_date}_04_quality-control-content_candidates.json")" 'type=="array" and length==$n and all(.[];type=="object")' "${vars.work_dir}/21-plan/${vars.run_date}_03_plan_plan.json"
     action:
       kind: agent.run
       # 0238 R2: a stochastic executor no-op must not end the run here — the retry sibling decides.
@@ -268,21 +271,28 @@ nodes:
         agent: ${vars.agent}
         # ADR-115 error tier: keep this prompt <= 1000 chars (0133 R3; 0138 R4a copy discipline).
         # The anchor is shared with plan-translate-retry so the two attempts cannot drift apart.
+        # 20261015 forensics: headless agy's terminal sandbox denies workspace writes for EVERY
+        # shell command (command() rules are promptless-but-sandboxed; unsandboxed() is dead), so
+        # the producer must deliver via the file-write tool; and the condition gate checks JSON
+        # validity (array, length == candidates docs, all objects) because a pi token-cap staged
+        # write once flowed 4/12 items downstream. Keep both when editing prompt or condition.
         input: &plan-translate-input |
-          Read ${vars.work_dir}/21-plan/${vars.run_date}_04_quality-control-content_candidates.json — metadata.docs (Doc[]) is the plan; don't edit it.
-          For needsTranslation items, adapt "title", "body" and "metadata.brief" into spoken simplified Chinese — full coverage, not a summary: keep every fact, number, name, quote and hedge (口播全长改编，不摘要不省略), body ≈0.6–0.7× the source.
-          Titles read as a news event; keep product/model names verbatim, preserve body URLs, use 「」 not ASCII double quotes.
-          Copy discipline: reader-facing news copy — no scaffold labels (「可做角度」「为什么现在值得注意」「社区讨论」「背景」「潜在影响」「影响」), no duplicated labels or hedging (「读者宜另行核实」「仍待验证」) — merge their substance into prose or drop.
-          Keep other fields (id, sourceUri, mediaType, metadata) as-is; no comments or trailing commas.
-          Output strictly valid JSON — a same-length, same-order array — to ${vars.work_dir}/21-plan/${vars.run_date}_03_plan_plan.json.
+          Read ${vars.work_dir}/21-plan/${vars.run_date}_04_quality-control-content_candidates.json; metadata.docs (Doc[]) is the plan.
+          For needsTranslation items adapt "title", "body" and "metadata.brief" into spoken simplified Chinese — keep every fact, number, name, quote, hedge (口播全长改编，不摘要不省略), body ≈0.6–0.7× source.
+          Titles read as news; keep product/model names and body URLs verbatim, use 「」 not ASCII quotes.
+          Copy discipline: reader-facing news copy — no scaffold labels (「可做角度」「为什么现在值得注意」「社区讨论」「背景」「潜在影响」「影响」), no hedging labels (「读者宜另行核实」「仍待验证」) — merge or drop.
+          Keep id/sourceUri/mediaType/metadata as-is; no comments/trailing commas.
+          Deliver with your file-write tool (headless agy sandbox blocks shell writes); the file must end as ONE valid JSON array — no split markers/placeholders.
+          Output the JSON array — same length and order — to ${vars.work_dir}/21-plan/${vars.run_date}_03_plan_plan.json.
         expectFile: ${vars.work_dir}/21-plan/${vars.run_date}_03_plan_plan.json
         allowAppend: false
 
   - id: plan-translate-retry
     description: >-
-      Bounded recovery for plan-translate (0238 R2): runs only when the primary settled without its
-      expectFile, retries the same input on a different tier, and carries NO onError — a second miss
-      fails the run loudly instead of letting an untranslated plan flow downstream.
+      Bounded recovery for plan-translate (0238 R2): runs only when the primary settled without a
+      VALID expectFile (missing or contract-violating JSON), retries the same input on a different
+      tier, and carries NO onError — a second miss fails the run loudly instead of letting an
+      untranslated or truncated plan flow downstream.
     dependsOn: [plan-translate]
     condition:
       kind: shell
@@ -290,7 +300,7 @@ nodes:
         command: >-
           kk store pool-count "${vars.work_dir}/21-plan/${vars.run_date}_04_quality-control-content_candidates.json" --min 1
           && test "${vars.plan_translate_enabled}" = "true"
-          && ! test -s "${vars.work_dir}/21-plan/${vars.run_date}_03_plan_plan.json"
+          && ! jq -e --argjson n "$(jq '.metadata.docs|length' "${vars.work_dir}/21-plan/${vars.run_date}_04_quality-control-content_candidates.json")" 'type=="array" and length==$n and all(.[];type=="object")' "${vars.work_dir}/21-plan/${vars.run_date}_03_plan_plan.json"
     action:
       kind: agent.run
       options:
@@ -535,7 +545,7 @@ nodes:
           kk stage daily-wrap-docs "${vars.work_dir}" "${vars.run_date}" "${vars.voice_profile}"
 
   - id: generate
-    description: "Invoke the voice driver plugin (vdriver: gemini -> gemini-tts, voxcpm -> voxcpm-tts) to generate the audio"
+    description: "Voice tier, primary driver (vars.vdriver — voxcpm while the 2026-10-15 production test runs). onError: continue — the fallback siblings below are the loud chain (same pattern as 0238 R2)."
     # wrap-docs is a data dependency, not a sibling: daily-generate reads its _10_wrap-docs_docs.json
     # as the TTS input. Without this edge the two nodes race in the same wave (0212 dogfood finding).
     dependsOn: [script, safety, review, wrap-docs]
@@ -547,18 +557,76 @@ nodes:
     action:
       kind: shell
       options:
+        onError: continue
         command: >-
           OMNIVOICE_SPEED=1.06 kk stage daily-generate "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}" "${vars.transcode_mp3}" "${vars.vdriver}" "1" "${vars.episode_max_minutes}"
 
+  # Driver fallback chain (2026-10-15, operator decision): voxcpm -> gemini -> omni. Each sibling
+  # runs the same stage with a pinned driver; its condition re-checks the pool AND that NO upstream
+  # driver left a valid, passing whole-document Content (the stage stamps metadata.generator with
+  # its plugin id and the cache ignores foreign-driver sections, so a failed attempt can neither be
+  # relabeled nor mix voices). Non-final siblings continue on error; the last one is loud.
+  - id: generate-fallback
+    description: "Voice tier fallback 1: gemini (gemini-tts) when the primary driver left no valid Content"
+    dependsOn: [generate]
+    condition:
+      kind: shell
+      options:
+        command: >-
+          kk store pool-count "${vars.work_dir}/21-plan/${vars.run_date}_04_quality-control-content_candidates.json" --min 1
+          && ! jq -e '(.metadata.generator == "kk:voxcpm-tts" or .metadata.generator == "kk:gemini-tts") and .metadata.qc.passed == true' "${vars.work_dir}/30-audio/${vars.run_date}_11_generate_content.json"
+    action:
+      kind: shell
+      options:
+        onError: continue
+        command: >-
+          kk stage daily-generate "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}" "${vars.transcode_mp3}" "gemini" "1" "${vars.episode_max_minutes}"
+
+  - id: generate-fallback2
+    description: "Voice tier fallback 2 (last, loud): omni-voice-gen when neither voxcpm nor gemini delivered"
+    dependsOn: [generate-fallback]
+    condition:
+      kind: shell
+      options:
+        command: >-
+          kk store pool-count "${vars.work_dir}/21-plan/${vars.run_date}_04_quality-control-content_candidates.json" --min 1
+          && ! jq -e '(.metadata.generator == "kk:voxcpm-tts" or .metadata.generator == "kk:gemini-tts" or .metadata.generator == "kk:omni-voice-gen") and .metadata.qc.passed == true' "${vars.work_dir}/30-audio/${vars.run_date}_11_generate_content.json"
+    action:
+      kind: shell
+      options:
+        command: >-
+          OMNIVOICE_SPEED=1.06 kk stage daily-generate "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}" "${vars.transcode_mp3}" "ominivoice" "1" "${vars.episode_max_minutes}"
+
   - id: intro
     description: "Prepend the 8s intro sting (intro_music var; empty = skip), update duration/audioPath"
-    dependsOn: [generate]
+    dependsOn: [generate, generate-fallback, generate-fallback2]
     action:
       kind: shell
       options:
         command: >-
           kk stage daily-intro "${vars.work_dir}" "${vars.run_date}" "${vars.intro_music}"
 
+  # ---- advisory voice audit (2026-10-16): never fails the run ----
+  # The 20261015 episode shipped 59 different speakers because an instruct-mode profile pins none,
+  # and nothing but a human listening caught it. This grades the final render by per-segment median
+  # F0 (a speaker change swings it tens of Hz) and prints the table plus a PASS/FAIL line. It is
+  # deliberately advisory: `|| true` keeps its non-zero exit out of the run, and onError covers a
+  # missing venv (the check needs librosa from the voxcpm plugin's environment).
+  - id: voice-audit
+    description: "Advisory speaker-consistency audit of the joined episode (warn-only, never fails the run)"
+    dependsOn: [intro]
+    condition:
+      kind: shell
+      options:
+        command: >-
+          test -f "${vars.work_dir}/30-audio/${vars.run_date}_11_generate_content.json"
+    action:
+      kind: shell
+      options:
+        command: >-
+          kk stage daily-voice-audit "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}"
+        onError: continue
+
   - id: duration
     description: "Measured duration gate: under episode_min_minutes the run refuses and closes as no-content (refusal artifact + emptied candidates, exit 0 — 0266); above episode_max_minutes it still fails loud. Duration is authoritative."
     dependsOn: [intro]