@gobing-ai/knowledge-kit 0.0.37 → 0.1.0

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]