@geoly-ai/social-hub-cli 0.3.18 → 0.3.19

package/skills/reddit-strategy-shared/references/subreddit-research-profile.md

@@ -0,0 +1,514 @@
+# SubredditResearchProfile（SRP）契约
+
+板块级研究画像的**唯一契约源**。research / compliance / brief / planning 四个阶段直接消费它，
+writing 侧**只间接消费 Brief 传下来的结果**（writing 是 baseline-first，不得临场拿 SRP 改结构）。
+因为消费者跨阶段，它住在 shared 层——放进任一阶段的 references 会造成 owner 争夺（现有两份分叉的
+`reddit-phase-planning/references/phase4-execution-table.md` 就是这么来的）。
+
+本文件定义 **schema、采样帧规则、分母不变量、分字段 TTL、置信度状态机、S1–S9 标准作业步骤、
+校验规则**。**具体板块的画像实例不放在 skill 里**——实例存 Hub，运行时由 CLI 拉取并校验
+`schemaVersion` 与 freshness（见 §9）。
+
+---
+
+## 1. SRP 回答什么、不回答什么
+
+SRP 回答：**这个板块整体是什么样、数据覆盖到什么程度、哪些进入方式有证据支持、有哪些风险信号。**
+
+**SRP 不做发布放行。** 板块资格（eligibility）仍然只由 `reddit-subreddit-compliance` 的输出决定；
+这与 `references/evidence-policy.md` 的 Source Layers 一致，SRP 不改这条。SRP 为 compliance 提供
+统计证据与风险信号，但**不得自行宣布「允许 / 禁止 / 可以进」**。
+
+### 1.1 三层不合表（与 `docs/subreddit-ops-data-and-post-style-design.md` 的三层不合表要求同源）
+
+| 层 | 回答 | 粒度 | 治理 | 不承担 |
+|---|---|---|---|---|
+| **SRP**（本文件） | 板块整体是什么样、覆盖度多少、进入方式有哪些证据 | subreddit × 时间窗 | Hub 实例 + HITL 审批 | 发布放行、替代 compliance、写作模板 |
+| **baseline 卡**（`reddit-content-writing/references/phase4-writing.md` W-1.b） | **这个 flair** 的帖该怎么写 | subreddit × `AssignedFlair` | Brief 阶段产出，新鲜期默认 60 天 | 板块整体分布、合规裁决 |
+| **`subreddit_style_profiles`**（`packages/contracts/src/subreddit-style-profile.ts`） | 审核门 prompt 的 tone/style/taboo **soft enrich** | subreddit（+ brand override） | 四眼 propose/approve/retire | 研究统计、发布资格 |
+
+**三者不合并、不互相覆盖、不互相绕过：**
+
+- SRP 的 `flairDistribution` **不能**替代 baseline 卡；baseline 卡 60 天新鲜期门禁不因为 SRP 是
+  `Verified`（TTL 90 天）而放宽。SRP 是 baseline 的**研究输入**，不是它的替代品。
+- `subreddit_style_profiles` 很薄（`tone` / `stylePoints` / `taboos` / `brandFriendliness`），且其
+  生成器只取**近 30 天 score Top N**（`apps/worker/src/handlers/subreddit-style-profile-generation.ts`）。
+  **它的取样帧在方法上就不能作为 SRP 的全窗口分母**，SRP 不得复用它的 status，也不得把 SRP JSON
+  塞进它的 `profile` 字段。
+- `brandFirstMentionHistogram` 在 SRP 与 baseline 卡里都存在：**SRP 记板块整体，baseline 卡记单
+  flair / 单内容功能**。两处都必须标明统计层级；层级不同的直方图不得互相覆盖或平均。
+- `contentTypes[]` 必须是对既有**帖子级分类**（`content_classification_runs` 的输出）的
+  **板块级投影**，**不得另造一套 taxonomy**。`subreddit_post_annotations` 是 1–5 分的人工评价，
+  **不是** content type 来源（详见 §5.2）。
+
+### 1.2 为什么需要 SRP：top-N 采样产不出全板占比
+
+现有研究 SOP（`reddit-phase-research/references/phase01-research.md` 步骤 0.5.5「板块内容深度分析」）用
+`--sort top --limit 50` 采样。**top-N 是按 score 排序的偏差样本，统计上不可能产出可信的全板块占比。**
+标杆产物的核心资产是**全窗口的 flair 分布**——分母明确的全量占比。这个方法论差距由 §4 的采样帧
+硬规则制度化：**采样帧决定一张卡能声称什么，而不是由作者的措辞决定。**
+
+---
+
+## 2. 头部字段（identity / 采样帧 / 分母 / 治理）
+
+```yaml
+# --- identity（实例身份，不是 schema 身份）---
+profileId:            # Hub 侧不可变实例 id
+revisionId:           # 同一 profileId 的修订号；内容变更即新 revision
+schemaVersion:        # 本契约的版本（如 srp/1）。schemaVersion ≠ 实例版本
+subreddit:            # 规范化：剥 r/ 前缀、trim、小写
+
+# --- 采样帧 ---
+windowStart:          # ISO8601，内容时间（created_utc）口径，非观测时间
+windowEnd:
+samplingFrame:        # FullWindow | TimeStratified | TopN
+timeStratification:   # 仅 TimeStratified：切片粒度 + 每片是否全量 + 加权方法
+provider:             # 采集通道（hub_cache | hub_dispatch | emergency_local | arctic ...）
+
+# --- 分母三件套（缺一不可，见 §3）---
+fetchedN:             # 抓到的原始条数（未去重）
+dedupedN:             # 去重后条数
+eligibleN:            # 资格过滤后、进入统计的分母
+excludedByReason:     # {Removed, Deleted, ModPost, AutoMod, TemplateDuplicate, Unresolved}
+                      # Unresolved = 无法判定是否合资格；必须显式计数，不得蒸发
+unknownFlairN:        # eligibleN 的子集：无 flair 或 flair 不可判定
+
+# --- 治理 ---
+confidence:           # Verified | Provisional | Insufficient（见 §7）
+computedAt:
+fieldTtls:            # 见 §6
+effectiveFreshUntil:  # 见 §6.2，派生值
+approvalStatus:       # Draft | InReview | Approved | Superseded | Rejected
+approvedBy:
+approvedAt:
+supersedes:           # 被本卡取代的 profileId/revisionId
+lineage:              # 见 §2.1，必填
+```
+
+### 2.1 `lineage`：可追溯性不能只靠 `provider`
+
+`provider` 只说明「走的哪条通道」，**不足以复现**。`lineage` 必须能把每一项派生统计指回 Hub 的
+真实记录：
+
+```yaml
+lineage:
+  evidenceRefs: []    # subreddit_evidence 的记录引用（含 evidenceType/status/capturedAt/expiresAt）
+  runIds: []          # 采集 run
+  sampleSetIds: []    # 帖子样本集合（与 baseline 卡的 SampleSetID 同命名空间）
+  derivationNotes:    # 分片边界、去重键、加权方法等复现所需说明
+```
+
+**原始版规 / flair / about / pinned 证据一律来自 `subreddit_evidence`**（它已带
+`status/provider/runId/capturedAt/expiresAt`）。**不要**用 team-scoped 的 `subreddit_rule_caches`
+生成系统级 SRP——租户作用域不同，会把某个团队的缓存冒充成板块事实。
+
+---
+
+## 3. 分母不变量（机械可校验，不是修辞）
+
+分母是 SRP 的全部可信度所在，因此写成不变量：
+
+1. `fetchedN ≥ dedupedN ≥ eligibleN`。
+2. `dedupedN = eligibleN + Σ excludedByReason[*]`，其中 `Unresolved`（无法判定）是**受控的排除
+   原因之一**，不得让未知样本在等式里蒸发。
+3. `excludedByReason` 的各 reason **互斥**：一帖多因命中时按固定优先级归一
+   `Removed > Deleted > ModPost > AutoMod > TemplateDuplicate > Unresolved`，并在 `derivationNotes`
+   记优先级版本。
+   `TemplateDuplicate` 是**语义/模板重复**过滤（同一模板反复发的帖），发生在 `dedupedN` 之后；
+   `fetchedN → dedupedN` 的是**物理去重**（同一 post id）。两者不得重复计数。
+4. `unknownFlairN ⊆ eligibleN`（是 eligibleN 的子集，不是它之外的另一堆）。
+5. **flair 占比的分母显式声明**：默认分母是 `eligibleN`，且 `Unknown` 作为**显式 bucket** 出现在
+   `flairDistribution[]` 里。若改用 `eligibleN - unknownFlairN` 作分母，必须在字段上标注，且
+   `Unknown` 不得同时再作为 bucket 出现（否则占比和 > 100%）。
+6. 去重键必须写明（推荐 reddit post id；跨源合并时记合并规则）。
+
+任一不变量不成立 → 该卡 `confidence: Insufficient`，不得发布派生占比。
+
+---
+
+## 4. 采样帧硬规则与 `claimScope`
+
+### 4.1 硬规则：`samplingFrame: TopN` 不得填 `flairDistribution`
+
+`samplingFrame: TopN` 的 SRP **不得填写 `flairDistribution`**，只能标 `confidence: Insufficient`
+并进 HITL。这是 §1.2 那个症结的制度化：top-N 样本按 score 排序，其 flair 构成是「高分帖的 flair
+构成」，**不是板块的 flair 构成**，两者不可互换。
+
+### 4.2 `claimScope`：每个统计字段自带声称范围
+
+禁填 `flairDistribution` 还不够——`contentTypes` / `removalStats` / `engagementPercentiles` 在
+TopN 下同样会被误读成全板块总体结论。因此**每个统计字段必带**：
+
+```yaml
+claimScope: Population | SampleOnly
+```
+
+| `samplingFrame` | 允许的 `claimScope` | 说明 |
+|---|---|---|
+| `FullWindow` | `Population` 或 `SampleOnly` | 窗口内全量，可作总体声称 |
+| `TimeStratified` | `Population`（每片全量时）/ `SampleOnly`（片内抽样时） | 片内抽样必须给权重与估计方法，否则只能 `SampleOnly` |
+| `TopN` | **只能 `SampleOnly`** | 且 `flairDistribution` 禁填 |
+
+`claimScope: SampleOnly` 的字段**不得**在下游被表述为「板块里 X% 的帖……」；只能表述为
+「本样本中 X 条…（样本口径：<采样帧>）」。
+
+### 4.3 `TimeStratified` 的额外义务
+
+必须说明每个时间片是**全量抓取**还是**片内抽样**：
+
+- 每片全量 → 可 `Population`。
+- 片内抽样 → 必须给出每片权重与估计方法（含估计量与区间口径），否则整卡降 `SampleOnly`。
+
+---
+
+## 5. 主体字段
+
+### 5.1 `flairDistribution[]`
+
+```yaml
+- flair:              # 原始 flair 文本；"Unknown" 为显式 bucket（见 §3 第 5 条）
+  count:
+  share:              # count / 声明的分母
+  ci:                 # 置信区间（给出区间与方法名，如 Wilson 95%）
+  claimScope:
+```
+
+### 5.2 `contentTypes[]` —— 给样本，不给形容词
+
+标杆产物的隐性方法论是：**不总结成形容词，给真实样本。**
+
+```yaml
+taxonomy:             # 必填：所复用的既有 taxonomy 名 + spec/版本
+                      # 权威源是 content_classification_runs 的分类结果
+                      # (packages/contracts/src/content-classification.ts)
+aggregationMode:      # Primary | MultiLabel
+sampledN:             # 本字段实际统计的样本基数（必须与 claimScope 一致：
+                      # claimScope=Population 且 FullWindow 时 sampledN = eligibleN；
+                      # SampleOnly 时 sampledN 是样本基数，**不得**拿 eligibleN 参与运算）
+classifiedN:          # sampledN 中被成功分类的条数
+unclassifiedN:        # sampledN - classifiedN，必须显式给出
+items:
+  - typeKey:          # 取值来自上面声明的 taxonomy，**不新造**
+    count:
+    share:            # 分母 = classifiedN（在字段上写明；与 sampledN 同一采样帧）
+    exampleTitles: [] # 5 条真实标题原文（verbatim，禁止改写/意译/清洗）
+    claimScope:
+```
+
+**`aggregationMode: MultiLabel` 时 share 之和可以超过 100%**（`content_forms` 就是多标签轴），
+必须在卡上显式声明，否则下游会把它当互斥占比读。
+
+**`subreddit_post_annotations` 不是 content type 来源**——那张表存的是帖子对板块/品牌的 1–5 分
+**人工评价**（`style_fit` / `brand_friendliness`），不是内容 taxonomy。若要消费它作为质量参考，
+只允许系统全局行（`team_id IS NULL`），且必须与 `contentTypes` 分开字段呈现。
+
+`exampleTitles` 要求 **5 条真实标题原文**，例如
+`Just picked up a new 6mm right curb from Lirys.` 这种原样抄录。
+**不足 5 条时诚实少给，禁止补齐**——不得用模型生成、改写、或从别的板块借来的标题凑数；
+少给的原因写进 `dataQualityCaveats`。
+
+### 5.3 `topPosts[]`
+
+```yaml
+- title:
+  permalink:
+  postedAt:
+  score:
+  sourceScoreStatus:  # 原样保留来源状态，合法值仅四个：
+                      # Backfilled | VerifiedLive | StaleArchive | Unverified
+                      # （ArchivedSnapshot 是**评论/板块指标**的状态，不是本字段的合法值）
+  scoreUsable:        # 派生布尔：sourceScoreStatus ∈ {Backfilled, VerifiedLive}
+  urlStatus:          # G3 存活状态字段，见 references/evidence-policy.md
+```
+
+**只有 `scoreUsable: true` 的条目可以参与按 score 的排序与汇总。**
+`StaleArchive` / `Unverified` 的 score 禁止排序汇总（评论侧的 `ArchivedSnapshot` 指标同理；与
+`reddit-voc-volume/scripts/reddit_voc_volume.py` 的既有告警同则：那类条目的 `num_comments` /
+`upvote_ratio` 有回填可用，score 不可用）。这类条目**可以留在清单里**（`scoreUsable: false`），
+但不得进入任何 score 派生统计——保留原始状态而不是丢弃，是为了让下游能自己判断而不是被动信任。
+
+### 5.4 `engagementPercentiles`
+
+```yaml
+metric:               # 必填：score | num_comments | upvote_ratio（逐指标一组分位数）
+denominatorN:         # 必填：参与计算的条数
+scoreUsableOnly:      # metric=score 时必须为 true（stale score 不得污染分位数）
+percentiles:          # p50 / p75 / p90 / p95 ...
+claimScope:
+```
+
+**跨板块只比 percentile，不比 raw score**——不同板块的 score 基数不可比，把 raw score 跨板块
+对比是无意义的。
+
+### 5.5 `titleStyle`
+
+标题句式分布（陈述结论 / 问句 / 场景 / 数字背书 / 时长锚定 …）与标题长度分布，**带 `claimScope`
+与分母**。与 baseline 卡的同名维度**层级不同**（这里是板块整体，那里是单 flair），互不覆盖。
+
+### 5.6 `brandFirstMentionHistogram`
+
+```yaml
+buckets:              # 恰好四档：标题 / 首段 / 中段 / 结论（分母 = BrandMentionSampleCount）
+ComparableSampleCount:    # 必填：可比样本总数
+BrandMentionSampleCount:  # 必填：其中出现品牌提及的样本数
+NoBrandMentionRate:       # 必填：不出现品牌的比例（= 1 - BrandMentionSampleCount / ComparableSampleCount）
+claimScope:
+```
+
+> **「不出现」不是直方图的一档**，由 `NoBrandMentionRate` 单独表示——与 baseline 卡、
+> G2 `BrandPlacementGate` 的口径完全一致（`reddit-phase-brief/references/brand-SKU-PGC-rules.md` §2.5）。
+> 把「不出现」并进四档会稀释各档分母，让 G2 读出错误的位置结论。
+
+`ComparableSampleCount` / `BrandMentionSampleCount` **是必填项**，因为 writing 侧的
+`BrandPlacementGate`（G2）把本直方图列为 `BrandPlacementBasis` 的备选来源，其拦截判据要读这两个
+计数（见 `reddit-content-writing/references/phase4-writing.md` W-1.b-brand）。缺这两个计数的直方图不得作为
+`BrandPlacementBasis`。
+
+这个机制已存在于 baseline 卡（用于校准 `BrandEntryMode`）；SRP 把它**提到板块层并持久化**，
+让 planning 阶段在还没有单 flair baseline 时也有依据。**下游取值优先级：同 flair 的 baseline 卡 >
+SRP 板块层。**
+
+### 5.7 `removalStats` —— 必须拆分 mod 与用户
+
+```yaml
+removalStats:
+  denominatorN:       # 必填：分母是哪一批，且必须与 claimScope 同帧——
+                      # Population(FullWindow) 通常用 dedupedN（Removed/Deleted 已被排除出
+                      # eligibleN）；SampleOnly 时用样本基数，不得借用全窗口分母
+  removedByMod:       # [removed]：版主/自动化移除——**仅当来源明确给出 removalKind 时才可计入**
+  deletedByAuthor:    # [deleted]：作者自删——同上
+  unknown:            # 来源未给出 removalKind、或不可判定，一律进这里
+  claimScope:
+```
+
+**合并值不得解释为「品牌导致」。** 作者自删与版主移除是完全不同的信号；把两者相加然后归因给
+「品牌内容被打压」是标准的误读。任何据 `removalStats` 得出的归因结论，必须分别引用
+`removedByMod` 与 `deletedByAuthor`。
+
+### 5.8 `selfPromoPolicy`
+
+```yaml
+selfPromoPolicy:
+  value:              # Prohibited | Conditional | Allowed | Unknown
+                      # **证据派生的观察值，不是 compliance verdict**——
+                      # 最终的允许/禁止仍由 reddit-subreddit-compliance 裁决
+  dependsOnEvidence: []  # 必填：本字段依赖哪几类证据（通常 rules / wiki / submit_text）
+  evidenceRefs: []
+```
+
+**本字段所依赖的证据 `status=failed` 时必须填 `Unknown`，不得当作「无限制」。**
+判定只看 `dependsOnEvidence` 列出的那几类——`pinned` / `flair` / `installed_apps` 采集失败
+**不**使 `selfPromoPolicy` 变 `Unknown`（那会把无关失败误升成阻断）。
+这与证据层的既有语义一致：`failed` ≠「没有规则」；只有页面明确显示不存在（`not_visible`）才是
+负证据。`Unknown` 不是放行，下游按 fail-closed 处理（见 `references/evidence-policy.md` G6）。
+
+### 5.9 `boardUniqueFlows[]` —— 「独有」必须反向检索确认
+
+板块特有的互动流程/仪式（如某种固定的求助格式、每周固定帖、特定 flair 的隐性用法）。
+
+**写「独有」之前必须做反向检索确认**（在可比板块集合里检索同一流程是否存在）。未做或未确认时
+**只能写「本样本未观察到」**，不得写「该板块独有」。
+
+```yaml
+- flow:
+  evidenceRefs: []
+  uniquenessCheck:    # Confirmed | NotChecked
+  comparedAgainst: [] # uniquenessCheck=Confirmed 时必填：反向检索覆盖了哪些板块
+```
+
+### 5.10 `flairBoundaryNotes[]`
+
+flair 之间的边界模糊处、易混淆对、版主实际执行与字面定义的差异。
+
+### 5.11 `lowSignalFlairs[]`
+
+样本量过小、不足以支撑任何占比结论的 flair。**必须写明判定阈值**（如 `count < 10` 或 CI 宽度
+超过某值）。列出来是为了**防止下游把小基数百分比当结论**；这些 flair 在 `flairDistribution` 里
+仍然出现，但其 `claimScope` 只能是 `SampleOnly`。
+
+### 5.12 `dataQualityCaveats[]` —— 负证据必须显式记录
+
+**负证据不得静默丢弃。** 抓取失败的片段、被限流的时间窗、无法解析的 flair、少给的样本、
+未做的反向检索——全部显式记录在这里。一张没有 caveats 的卡，只有在确实没有 caveat 时才合法；
+「没写」不等于「没有」，HITL 复核会追问。
+
+---
+
+## 6. 分字段 TTL
+
+TTL **不是整卡一个**，因为各字段的变化速率差一个数量级。
+
+| 字段族 | TTL |
+|---|---|
+| 版规**派生**结论（`selfPromoPolicy` 等） | 30 天 |
+| `flairDistribution` / `contentTypes` | 90 天 |
+| `topPosts` / `engagementPercentiles` | 30 天 |
+| `removalStats` | 30 天 |
+| 静态结构性知识（板块 identity、schema 语义、长期稳定的板块定位） | 180 天 |
+| 动态板块行为（`titleStyle` / `boardUniqueFlows` / `flairBoundaryNotes`） | 90 天 |
+
+> **180 天只给静态项。** 标题风格、板块特有流程、内容类型构成、互动习惯都可能在数周到数月内变化，
+> 因此它们归「动态板块行为」的 90 天，不享受 180 天。超过 TTL 的旧数据只能作历史参考，
+> **不得满足执行锁定**。
+
+### 6.1 与证据层 TTL 的关系（不冲突，但要分清）
+
+上表是 **SRP 派生字段**的 TTL，**不是原始证据的 TTL**。原始证据 TTL 由证据层自己定义
+（`social-hub-intelligence`：rules/wiki/about/submit_text 30 天、pinned 24 小时、
+flair/page_signals/installed_apps 7 天）。两套 TTL 并存不矛盾——一个管「结论多久要重算」，
+一个管「原料多久要重采」。
+
+### 6.2 `effectiveFreshUntil`：取两者的较早者
+
+```
+effectiveFreshUntil = min(该字段 TTL 到期时刻, 其所有依赖证据的 expiresAt)
+```
+
+否则一个依赖 `pinned`（24 小时）或 `flair`（7 天）证据的「版规派生结论」，会在原始证据早已过期后
+仍显示 `Verified`。**字段级计算，整卡取最小值作为卡级 `effectiveFreshUntil`。**
+
+**并非所有依赖都有 `expiresAt`。** `subreddit_evidence` 的 `expiresAt` 可空——**为空时按
+`evidenceType` 的既有 TTL 从 `capturedAt` 派生**（rules/wiki/about/submit_text 30 天、pinned 24 小时、
+flair/page_signals/installed_apps 7 天），不得视为无期限，也不得因此直接判该字段不可 `Verified`。
+帖子样本集（hot-post 快照、分类 run、样本集合）目前没有统一的过期契约。对这类依赖：在 `lineage` 里记下其
+`capturedAt`，按本表的字段 TTL 从 `capturedAt` 起算作为替代到期时刻，并在 `derivationNotes` 注明
+用的是替代口径——**不得因为「它没有 expiresAt」就当作永不过期**。
+
+### 6.3 过期的后果
+
+任一**必需字段**过期 → **整卡降 `Provisional`**：可读、可作研究参考，
+**但不得用于锁定执行表**（Phase 4 执行表锁定要求 `Verified`）。
+
+---
+
+## 7. `confidence` 状态机与 `approvalStatus` 的关系
+
+| `confidence` | 条件 | 允许用途 |
+|---|---|---|
+| `Verified` | 分母不变量全成立 + 采样帧支持所声称的 `claimScope` + 所有必需字段在 `effectiveFreshUntil` 内 + HITL 已复核 + `approvalStatus: Approved` | 板块级结论可作**执行表锁定的必要输入**（不是充分条件，见下） |
+| `Provisional` | 结构完整但有字段过期、或部分 `claimScope: SampleOnly`、或停止条件未满足 | 研究参考、planning 输入；**不得锁定执行表** |
+| `Insufficient` | 分母不变量不成立、或 `TopN` 帧却需要总体结论、或关键证据 `failed` | 只能作线索；必须进 HITL 补采 |
+
+**`Verified` 不等于可以锁执行表。** `Verified` 只说明「这张卡的板块统计站得住」。执行表锁定仍必须
+**独立**通过既有各门：baseline 卡（`Fresh` + 10 维 + `AssignedFlair` + `FlairCoverageStatus`）、
+Brief、compliance 裁决、`BrandPlacementGate`（G2）。SRP 是这些门的输入，**不是它们的替代品，也不能
+免除任何一门**。
+
+**`approvalStatus: Approved` 不能提升 `confidence`。** 一张 `Provisional` 的卡即使被审批通过，
+仍然不得作为执行表锁定的输入——审批解决的是「这张卡可以被消费」，不是「这张卡的统计可信到可以锁
+执行」。两个维度正交，不得互相顶替；反过来，`Verified` 机械要求 `approvalStatus: Approved`，
+不存在 `Verified + Draft` 的组合。
+
+---
+
+## 8. 标准作业步骤 S1–S9
+
+**S1 · 声明窗口与目标决策。** 先写下 `windowStart` / `windowEnd` 与**这张卡要支持哪个决策**
+（如「该板块本月排几帖、分到哪些 flair」）。目标决策决定 S5 的停止条件，不能事后补。
+
+**S2 · 拉证据层 8 类。** about / rules / wiki / submit_text / pinned / flair / page_signals /
+installed_apps，来源为 `subreddit_evidence`（**不要**用 team-scoped 的 `subreddit_rule_caches`）。
+逐类记 `status`；**依赖该证据的字段**遇 `failed` 不得当作「无限制」（如 `selfPromoPolicy: Unknown`，
+判定范围见 §5.8）。先走 Hub cache，缺口按 `reddit-voc-volume/references/hub-first.md` 的
+L1→L2→L3 派发。
+
+**S3 · 全窗口分片抓取。** 按时间窗切片累积、**逐片去重**，而不是一次 top-N 拉一把。
+分片边界与去重键写进 `lineage.derivationNotes`。这一步是 SRP 与旧 SOP 0.5.5 的方法论分水岭。
+
+**S4 · 帖子/样本资格过滤**（注意：这是**样本**是否进入统计，与 subreddit 的 eligibility 无关，
+后者是 compliance 的裁决）。按 §3 的互斥优先级逐条判定，累计 `excludedByReason`（含 `Unresolved`），
+校验分母不变量。
+
+**S5 · 停止条件是决策驱动，不是统一 N。**
+
+> 继续扩窗/扩片，直到 **关键分布的置信区间不再改变 S1 声明的那个目标决策的离散取值**为止。
+
+最常见的形态是排期分配：如果把 flair 占比取到区间上下界，排期的整数分配（几帖分到哪个 flair）
+都不变，那么样本已经足够——不需要更多。**目标决策不是排期分配时，S1 必须同时声明该决策的离散
+判据**（如「是否进入该板块」的阈值、「是否需要单独 baseline」的门限），停止条件对着那个判据算；
+S1 没声明可判定的离散判据 → 不得用 S5 停止，只能按固定预算跑并标 `Provisional`。
+
+若扩到通道上限仍不满足 → `confidence: Provisional` + HITL，**不得用「差不多了」自行放行**。
+
+**S6 · 派生统计。** 计算 §5.1–5.8 各统计字段，逐字段标 `claimScope` 与分母。
+
+**S7 · 板块特有层。** `boardUniqueFlows`（含反向检索确认）、`flairBoundaryNotes`、
+`lowSignalFlairs`、`dataQualityCaveats`。
+
+**S8 · URL 存活状态字段。** 卡内的**证据 URL、历史样本 URL、当期排期 URL** 按
+`references/evidence-policy.md` 的 G3 补齐存活状态字段（纯导航 URL 按 G3 豁免）。
+排期对标帖走 G3 的 current-planning 口径；**注意 `CurrentStatus: Live` 不等于「可评论」**——
+外部评论目标仍须过 `reddit-ext-post-audit` 的可评论性检查，G3 不替代它。
+
+**S9 · HITL 复核后写 Hub。** 人工复核分母、采样帧与 `claimScope` 的自洽性、caveats 是否诚实，
+通过后写 Hub 并置 `approvalStatus: Approved`。**未经 HITL 的卡最高只能是 `Provisional`。**
+
+---
+
+## 9. 存哪里：skill 冻结契约，Hub 存实例
+
+| 内容 | 位置 | 理由 |
+|---|---|---|
+| schema、采样帧规则、分母不变量、TTL、S1–S9、校验规则 | **本 skill reference**（随 CLI vendor 冻结） | 规则要跟 skill 版本一起冻结，才能保证同一版 CLI 的行为一致 |
+| **具体板块的画像实例** | **Hub** | 改一个板块的画像**不需要发 CLI 版本**；实例有 identity/审批/lineage，天然属于服务端 |
+
+运行时：CLI 从 Hub 拉取实例 → 校验 `schemaVersion` 与 `effectiveFreshUntil` → 不匹配或过期则按 §6.3
+降级处理。
+
+**Hub 侧不要塞进 `subreddit_insight_snapshots`**（`packages/db/src/schema.ts`）：它虽有表级主键，
+但**不具备 SRP 所需的 identity/revision、`schemaVersion`、TTL、lineage 与审批语义**——只是一个
+无 schema 的通用 payload 快照，塞进去等于把 SRP 的全部治理丢掉。
+同理不复用 `subreddit_style_profiles`（§1.1）。SRP 的落库形态由后续 Hub 侧变更定义，本文件只定义契约。
+
+---
+
+## 10. 校验规则（命名检查点）
+
+下列检查点在 SRP 被消费前逐条判定；**任一 FAIL → 该卡不得用于其声称的用途**。
+
+| 规则 | 判据 | 失败后果 |
+|---|---|---|
+| `SRP-C1` 分母自洽 | §3 六条不变量全成立 | `Insufficient` |
+| `SRP-C2` 采样帧一致 | `TopN` 无 `flairDistribution`；`claimScope` 与 `samplingFrame` 匹配（§4.2） | `Insufficient` |
+| `SRP-C3` 样本诚实 | `exampleTitles` 全部 verbatim；不足 5 条时有对应 caveat | 该 `contentTypes` 项作废 |
+| `SRP-C3b` taxonomy 未新造 | `contentTypes.taxonomy` + `aggregationMode` + `classifiedN` 齐全，取值来自既有 taxonomy | 该字段作废 |
+| `SRP-C4` score 可信 | 只有 `scoreUsable: true`（`sourceScoreStatus ∈ {Backfilled, VerifiedLive}`）的条目参与排序/汇总 | 该条目退出统计（可留清单） |
+| `SRP-C5` removal 已拆分 | `removalStats` 三项分列，无合并归因 | 该字段作废 |
+| `SRP-C6` failed≠无限制 | 证据 `failed` 对应字段为 `Unknown` | `Insufficient` |
+| `SRP-C7` 独有已确认 | `boardUniqueFlows[].uniquenessCheck=Confirmed` 才允许「独有」措辞 | 降为「本样本未观察到」 |
+| `SRP-C8` freshness | 每字段 `effectiveFreshUntil > now`（§6.2） | 整卡降 `Provisional` |
+| `SRP-C8b` 治理自洽 | `Verified` ⇒ `approvalStatus: Approved`（§7） | 降 `Provisional` |
+| `SRP-C9` lineage 完整 | `lineage.evidenceRefs` / `runIds` / `sampleSetIds` 能指回真实记录 | `Insufficient` |
+| `SRP-C10` URL 三字段 | 卡内的**证据 URL / 历史样本 URL / 当期排期 URL** 过 G3（纯导航 URL 豁免） | 剔除该 URL |
+
+这些是**规则名**，不是已存在的可执行 validator——runtime validator 与 gold fixtures 属于后续变更。
+下游 skill 引用检查点时用规则名（如 `SRP-C2`），不要引用尚不存在的脚本路径。
+
+---
+
+## 11. 输出卡模板
+
+```markdown
+## SubredditResearchProfile
+- ProfileId / RevisionId / SchemaVersion:
+- Subreddit:
+- Window: <start> → <end>
+- SamplingFrame:            # FullWindow | TimeStratified | TopN
+- Denominators: fetchedN= / dedupedN= / eligibleN= / unknownFlairN=
+- ExcludedByReason:
+- Confidence:               # Verified | Provisional | Insufficient
+- EffectiveFreshUntil:
+- ApprovalStatus:
+- FailedChecks:             # SRP-C1..C10（含 C3b / C8b）中未通过的
+- AllowedUses:              # 是否可锁定执行表
+- DataQualityCaveats:
+```
+
+## 12. Handoff
+
+SRP 作为 research → planning/brief 的交付物时，随 `HandoffContract` 一并给出，并在
+`RequiredFieldsProvided` 里点名 `Confidence` 与 `AllowedUses`。
+`Confidence: Insufficient` 的 SRP 进入下游即构成阻断：`HandoffContract` 记 `BlockingGaps`、
+`ReadyForNextSkill: No`；走 Hub handoff 时对应 `readyForNextSkill=false` 且 `blockingIssues` 非空。
+不得以「先用着」放行（见 `references/evidence-policy.md` G6）。

package/skills/reddit-strategy-shared/references/version-manifest.md

@@ -1,6 +1,9 @@
 # Version Manifest
 
-Package: `reddit-skill-sop-v2.12.30`
+Package: `reddit-skill-sop-v2.12.31`
+
+> 该包自 v2.12.30 起在本仓库 `skills/reddit-*` 直接维护；`skills/reddit-matrix.lock.json`
+> 的 `version` 字段记的是 vendor 基线归档版本（2.12.30），与本行的内容版本各自独立，不必相等。
 
 | Skill | Status | Source |
 |---|---|---|
@@ -23,7 +26,7 @@ Copied independent skills should stay independently installable. Matrix wrappers
 
 ## Restored Legacy References
 
-- `reddit-strategy-shared/references/prerequisites/` contains the four legacy startup/prerequisite files for background SOP context.
+- `reddit-strategy-shared/references/prerequisites/archive/` 存放四份 legacy startup/prerequisite 文件，仅供**人工**查阅历史背景；`AgentReadPolicy: DoNotRead`，不进 agent 上下文（见同目录 `README.md`）。
 - `reddit-phase-planning/references/phase3-master-canvas.md` restores the 21-board Master Canvas prompt and gate.
 - `reddit-content-writing/references/comp-mention-strategy.md` restores the competitor mention helper reference.
 - `reddit-content-writing/references/` restores Phase 4 writing examples, post templates, PGC strategy, post rules, and execution-table reference.
@@ -42,6 +45,30 @@ Copied independent skills should stay independently installable. Matrix wrappers
   fields, hard prohibitions, soft distribution targets, rolling window,
   exception rules, `SampleSetID`, draft hash, and producer/consumer duties.
 
+## v2.12.31 New Contracts
+
+- `reddit-strategy-shared/references/subreddit-research-profile.md` — the
+  **SubredditResearchProfile (SRP)** contract: schema, sampling-frame hard rules
+  (`samplingFrame: TopN` may not carry `flairDistribution`), per-field `claimScope`
+  (`Population` | `SampleOnly`), the denominator invariants, per-field TTL and
+  `effectiveFreshUntil`, the `confidence` × `approvalStatus` state machine, the S1–S9
+  procedure, and the `SRP-C1..C10` check names. It lives in shared because research,
+  compliance, planning, and brief all consume it. **The skill freezes the contract; Hub
+  stores the instances** (§9). SRP never decides subreddit eligibility —
+  `reddit-subreddit-compliance` still does.
+- `reddit-phase-planning/references/scheduling-decision-procedure.md` — the **D1–D7
+  scheduling decision procedure**: how the fixed brand quotas land on board × SKU × flair
+  × lifecycle stage. It defines `SRPMode` (`Full` / `Provisional` / `Fallback` /
+  `Insufficient`), `ProposedFlair`, `LifecycleStage`, `SearchAnchors[]`, `capacityMax` /
+  `brandEntryAllowedSet`, the D6 solver split (mechanical hard constraints vs. the
+  weighting a human must lock), the 0-post / 1-post exploration-slot criteria, and the
+  per-post `memory/phase4-排期决策台账.md` ledger. Item numbers are **not** execution
+  order — the real order is **D1 → D5 → D2 → D3 → D4 → D6 → D7**. It replaces the three
+  hardcoded heuristics (single-board share ≤ 40% / core board ≤ 8 posts / ≥ 4 boards
+  covered), which now apply as hard constraints only under `SRPMode: Fallback` and as
+  warning-level sanity checks under `SRPMode: Full` / `Provisional`; the first two are
+  per-board, the coverage count is plan-level (hard only when every board is `Fallback`).
+
 ## v2.12.30 Sample-Eligibility Contract
 
 A baseline card may only be built from **real user posts with an intact body**.

package/skills/reddit-voc-volume/matrix-contract.md

@@ -64,7 +64,7 @@ substitute an archived `stickied` flag.
 - Query:
 - SampleSize:
 - TopSubreddits:
-- TopFlairs:
+- TopFlairs:                 # 采样信号（本次 sample 内的 flair 频次 Top-N），claimScope: SampleOnly
 - SubredditMetricsStatus:
 - Items:
 - RateLimitStatus:
@@ -74,6 +74,21 @@ substitute an archived `stickied` flag.
 ```
 
 
+> **`TopFlairs` 是样本信号，不是板块占比。** 它统计的是**本次采样命中的帖子**里
+> flair 的出现频次（top-N 排序，分母 = 本次 `SampleSize`），因此只能表述为
+> 「样本中 X 条带该 flair」，**不得**说成「板块里 X% 的帖是该 flair」。
+>
+> **不得与 SRP 的 `flairDistribution` 混用、互填或互相校验。** SRP
+> （`reddit-strategy-shared/references/subreddit-research-profile.md`）的
+> `flairDistribution[]` 的分母是 `eligibleN`，且只有在 `samplingFrame: FullWindow`
+> （或 `TimeStratified` 且每个时间片都是全量抓取）时才允许 `claimScope: Population`；
+> 契约 §4.1 更明令 `samplingFrame: TopN` 的卡**根本不许有** `flairDistribution`。
+> 无论 SRP 那张卡的 `claimScope` 是 `Population` 还是 `SampleOnly`，
+> **都不得用 `TopFlairs` 回填、替代或「交叉验证」它**。
+> 把 `TopFlairs` 填进 `flairDistribution`（或反过来拿它当 D2 的 flair 依据）会把一个
+> top-N 偏差样本伪装成全量分布——这正是要靠 SRP 采样帧硬规则堵住的那个错误。
+> `TopFlairs` 的合法用途：选题启发、判断本次采样覆盖到哪些 flair、给 SRP 的 S 步骤当**输入线索**。
+
 ## Hub-First 输出信封(v2.12.25 已自动执行,向后兼容)
 
 所有模式输出在既有结构上追加(不修改既有字段):provenance("social_hub_cache"|"hub_dispatch"|"emergency_local")、runId、fetchedAt、freshUntil(evidence 类)、fingerprint、fallbackReason("hub_failed"|"timeout"|"hub_unreachable"|"self_crawl_forced"|"no_hub_dispatch_path"|null)、writebackStatus("not_applicable"|"done"|"pending"|"failed")。旧下游解析器无需变更;新下游应优先按 provenance 判断数据来源与可信度。