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

package/skills/reddit-strategy-shared/references/persona-card-contract.md

@@ -0,0 +1,210 @@
+# Persona Card Contract
+
+The **Persona Card** is the per-draft posting context: why this account is
+posting this now, what it may legitimately be assumed to know, what it must not
+claim to know, and which firsthand experience claims are authorised.
+
+It is a **Brief-stage artifact**. The writer never authors one.
+
+**Scope: `ArtifactType: Post` only.** Comments, replies, and titles carry no
+Persona Card and no `PersonaCardRef`. The full knowledge-boundary and disclosure
+judgement for comments is a later stage of work; do not let this contract turn
+into a required field on comment rows.
+
+## 1. Why it is not part of the persona record
+
+`personas` / `account_personas` describe **WHO** the account is — archetype, age
+range, occupation, tone, avoid-topics, style guide. Those are stable.
+
+`postingWhy`, this draft's `knows` / `doesNotKnow`, this draft's brand
+relationship, and the facts this draft is allowed to use are **per-submission**.
+Their lifecycle is the draft's, not the persona's. Recording them on the persona
+would make every later draft inherit one draft's context.
+
+`avoidTopics` / `avoidPatterns` say what the account **should not say**. The Card
+says what the account **does not know**. These are different constraints and one
+does not substitute for the other.
+
+## 2. Capability model, not role taxonomy
+
+The Card describes **access and permitted claims**, never a role name.
+
+```markdown
+PersonaCardRef:                 # stable local id, unique per post ContentKey
+PersonaCardVersion:             # integer, incremented by reddit-phase-brief only
+PersonaCardHash:                # sha256 over the normalised Card body
+
+# ── stable capability fields ──
+knowledgeAccess:                # exactly one: research | owned | used | observed | supplied_by_brand
+permittedExperienceClaims:      # subset of the closed set {ownership, delivery, wear, service}; may be empty
+attentionFocus:                 # what this account actually cares about in this category
+questionIntent:                 # what it is actually trying to find out, if anything
+
+# ── per-draft fields ──
+postingWhy:                     # why this account is posting this, now
+knows:                          # list; what it may be assumed to know here
+doesNotKnow:                     # list; what it must not display knowledge of here
+permittedFactRefs:              # references to approved product facts usable in this draft
+brandRelationshipDisclosed:     # Yes | No | NotApplicable — what the draft states, not what is true
+
+# ── provenance ──
+DeclaredBy:                     # who authorised this Card's claims (person or role), not the agent
+ClaimAuthorizationRef:          # the submitted material that authorises permittedExperienceClaims
+
+# ── transport ──
+PersonaCardTransportStatus: LocalOnly(ServerContractMissing)
+PersonaCardAuthorizationStatus: Authorized | DeclaredOnly | NotApplicable
+RoleLabels:                     # optional, non-authoritative; see §3
+```
+
+`knowledgeAccess` is single-valued because it answers "where did this account's
+information come from". `permittedExperienceClaims` is a multi-select closed set
+because one account can legitimately be authorised for some firsthand claims and
+not others — "may say the item arrived" and "may describe wearing it" are
+separate authorisations.
+
+An empty `permittedExperienceClaims` is a valid, common Card. It means the draft
+may discuss the category from research or observation and may **not** claim
+ownership, delivery, wear, or service experience.
+
+## 3. Role names are labels, never judgement
+
+`Researcher` / `Owner` / `GiftBuyer` / `CategoryEnthusiast` / `LifestyleUser` may
+appear in `RoleLabels` as a convenience for humans reading the Brief. They are
+**not** a classification, **not** exhaustive, and **never** the basis of any
+check.
+
+One account is legitimately both an Owner and a CategoryEnthusiast. No role name
+can express "may this draft say the parcel arrived" — only
+`permittedExperienceClaims` can. Any check that reads `RoleLabels` instead of the
+capability fields is wrong.
+
+Likewise, do not derive a rule such as "a gift buyer must not discuss
+specifications". Buying a gift for a technical hobbyist makes specifications the
+core of the post.
+
+## 4. Lifecycle: assigned, never improvised
+
+The Card is the **third** `PrewritingControlField`, alongside `AssignedFlair` and
+`PostingTrigger`. Same discipline as those two:
+
+| Stage                    | Duty                                                                            |
+| ------------------------ | ------------------------------------------------------------------------------- |
+| `reddit-phase-brief`     | **Owns** the Card. Creates it, versions it, writes `PersonaCardRef` per post Key |
+| `reddit-content-writing` | Reads it. Writes within it. May not author, extend, or reinterpret it           |
+| `reddit-content-rewrite` | Reads it. Preserves `PersonaCardRef`. May not author or edit one                 |
+| `reddit-delivery-check`  | Verifies the delivered row's `PersonaCardRef` / `PersonaCardHash` match the Brief |
+
+A draft that needs a knowledge boundary the Card does not grant is a
+`BlockingGap` back to `reddit-phase-brief` for a new Card version — not a local
+edit and not a Card the writer fills in. Letting the writer author the Card
+re-opens exactly the bypass that pre-assignment exists to close: the writer would
+grant itself whatever boundary the draft it already wrote happens to need.
+
+Changing the Card bumps `PersonaCardVersion` and invalidates `PersonaCardHash`
+downstream: any row already checked against the old hash must be re-checked.
+
+## 5. What the Card does **not** establish
+
+- **It does not verify identity.** In ContentOnly / persona-less work the Card is
+  a *declared, auditable posting context* and nothing more. Never report it as a
+  confirmed account persona check, and never let its presence imply the posting
+  account was resolved.
+- **It does not prove any experience is real.** No local check and no model can
+  establish that a parcel actually arrived. The Card records what is
+  **authorised**, and authorisation comes from the submitted context, not from
+  inference about the relationship.
+- **A Card without provenance records a declaration, not an authorisation.**
+  `PersonaCardHash` makes a Card tamper-evident; it says nothing about who granted
+  the claims in it. `DeclaredBy` + `ClaimAuthorizationRef` are what make
+  `permittedExperienceClaims` auditable. A Card carrying `permittedExperienceClaims`
+  with neither field is describing what the Brief asserted, and must be reported
+  that way — never as an authorised claim set. The generating agent is never a
+  valid `DeclaredBy`.
+
+  This distinction must survive the handoff, or it is unauditable: a downstream
+  reader seeing only "self-check passed" and "reference preserved" cannot tell an
+  authorised claim set from an asserted one. So the Brief sets
+  `PersonaCardAuthorizationStatus` and every stage carries it through:
+
+  | Value           | Meaning                                                                              |
+  | --------------- | ------------------------------------------------------------------------------------ |
+  | `Authorized`    | `permittedExperienceClaims` non-empty, with both `DeclaredBy` and `ClaimAuthorizationRef` |
+  | `DeclaredOnly`  | `permittedExperienceClaims` non-empty, provenance incomplete — a Brief assertion       |
+  | `NotApplicable` | `permittedExperienceClaims` empty — there is no experience claim to authorise          |
+
+  `DeclaredOnly` does not by itself block: the local boundary check still runs and
+  the Hub gate is unchanged. It does mean no output may describe the claim set as
+  authorised, and it is the honest state to report to a client asking on what
+  basis a firsthand claim was permitted. Like the rest of the Card, this status is
+  local and is never sent to Hub.
+- **A brand relationship does not by itself make a firsthand claim false.** A
+  partner may genuinely own the product. The only self-evident contradiction is a
+  draft asserting an experience type the Card did not authorise.
+
+## 6. Firsthand markers are evidence, not violations
+
+Phrases such as "mine arrived", "I've had it since", "after a month of wearing
+it" are **markers**, not offences. `mine arrived` is unremarkable when
+`permittedExperienceClaims` includes `delivery`.
+
+A marker matters only when it contradicts the Card: the draft claims an
+experience type the Card did not authorise, or displays knowledge listed in
+`doesNotKnow`. Report the contradiction, cite both the phrase and the Card field
+it contradicts, and route back to Brief. Never flag a marker on its own.
+
+## 7. Transport boundary — the Card stays local
+
+**`PersonaCardTransportStatus` is `LocalOnly(ServerContractMissing)`.**
+
+Social Hub has no field for the Card on the post-review or content-review
+request, and both request schemas are strict: an extra field is a request
+rejection, not an ignored key. Do not add the Card, any of its fields, or a
+Card-derived score to a Hub review call. Do not restructure the Card into an
+existing free-text field (`subredditRules`, thread context) to smuggle it
+through — that injects planner text into a prompt slot reserved for other
+evidence.
+
+So the Card governs **writing**: Brief assigns the boundary, the writer stays
+inside it, delivery verifies the reference was preserved. Hub review runs
+unchanged alongside it, and the Card changes nothing about how a Hub verdict is
+read or reported.
+
+The local boundary check therefore reports only what it is: a local check.
+`ClaimEvidenceStatus` (`references/evidence-policy.md`) remains the authority on
+whether a claim may appear in publishable text; the Card adds *who may claim it*
+on top of *whether it is sourced*. Do not describe a local Card check as a review,
+a verdict, a dimension, or a pass.
+
+## 8. Local boundary self-check (writing side)
+
+Before handing a draft to Hub review, for each post row:
+
+1. Every firsthand experience claim in the draft maps to an entry in
+   `permittedExperienceClaims`.
+2. Nothing in the draft displays knowledge listed in `doesNotKnow`.
+3. Every substantive product claim still satisfies `ClaimEvidenceStatus`
+   (`Cited` or `ExternallyVerified`) — the Card never relaxes this.
+4. The draft's stated relationship matches `brandRelationshipDisclosed`.
+5. `postingWhy` is consistent with the assigned `PostingTrigger`. These are
+   different fields and neither replaces the other: `PostingTrigger` is the
+   controlled five-value reason the post is worth making now
+   (`references/content-diversity-contract.md`), `postingWhy` is this account's
+   own reason for making it. A draft whose `postingWhy` cannot coexist with the
+   assigned `PostingTrigger` is a `BlockingGap` back to Brief.
+
+Record the outcome as `PersonaCardSelfCheck: Pass | BlockingGap`, with the
+contradicting phrase and Card field for every gap. This is a local pre-submission
+check. It never substitutes for Hub review and never produces a score.
+
+## 9. Deferred Hub mapping
+
+The plan `docs/reddit-native-copy-integration-plan.md` (§2, §3.4, §6.4) intends a
+server-side knowledge-boundary judgement that would consume a persisted,
+snapshotted version of this Card. That contract does not exist yet: there is no
+request field, no persisted snapshot, and no corresponding review dimension.
+
+This note is informational. Until such a contract ships and its capability is
+echoed by the server, no skill may name a knowledge-boundary review dimension,
+report a knowledge-boundary review status, or claim any part of the Card was
+assessed by Hub.

package/skills/reddit-strategy-shared/references/prerequisites/README.md

@@ -0,0 +1,57 @@
+# prerequisites/ — 归档区索引
+
+| 路径                    | AgentReadPolicy                            |
+| ----------------------- | ------------------------------------------ |
+| `prerequisites/archive/`| **DoNotRead** — 仅供人工查阅               |
+| 本文件 `README.md`      | 可读，但**不是必读**；它只是索引，不含规则 |
+
+`archive/` **不属于任何 skill 的运行上下文**。全流程任务（orchestrator → research →
+planning → brief → writing → delivery）在任何阶段都**不得**读取 `archive/` 下的文件，
+也不得把其中任何内容当作 gate、schema、字段清单、结构规则或写作规范。本 README 本身
+只做「谁是权威」的转发和缺口登记，读它不会把 legacy 规则带进上下文。
+
+## 为什么
+
+`archive/` 下的四份文件归档前共 1,994 行（现为 2,026 行，多出的是本轮加的归档 banner），全部标注 `LegacyStatus: Superseded`，
+文件自己声明「不得执行其中的任何 gate / schema / 结构规则」。但它们的正文与
+active 契约**逐条重复**（2:8 配比、P-NB→C-B 互补、编号预分配、板块 ≤40%、
+品牌词聚合验证、外部评论 URL 规程等），模型无法区分「声明不作数」与
+「内容看起来是硬规则」，结果是 Phase 0 之前先吞 2,488 行（shared 契约 5 份 494 行 + 本目录 1,994 行）、其中 80.1% 是噪声。
+这些重复的规则在 active 文件里都有权威版本（见下表），legacy 版本只是复述。
+
+## 现在谁是权威
+
+| 主题                          | 权威文件（active）                                                        |
+| ----------------------------- | ------------------------------------------------------------------------- |
+| 结构 / 帖型 / StructureFamily | `reddit-strategy-shared/references/content-type-routing-contract.md`      |
+| 执行表 19 列 + 门禁           | `reddit-phase-planning/references/phase4-execution-table.md` + `scripts/phase406_verify.py` |
+| 编号预分配 / 板块分布 / 品牌词聚合 | `reddit-phase-planning/references/phase4-planning.md`                  |
+| 21 板 Master Canvas           | `reddit-phase-planning/references/phase3-master-canvas.md`                |
+| VOC 四维采样 / 缺口矩阵       | `reddit-phase-research/references/phase01-research.md`                    |
+| 品牌词互补 / 2:8              | `reddit-content-writing/references/phase4-post-rules.md`                  |
+| 逐帖终检                      | `reddit-content-rewrite` 三层终检清单                                     |
+| 证据与验证边界                | `reddit-strategy-shared/references/evidence-policy.md`                    |
+| 板块研究画像（SRP）           | `reddit-strategy-shared/references/subreddit-research-profile.md`         |
+| 排期决策（板块 / flair / 数量配比） | `reddit-phase-planning/references/scheduling-decision-procedure.md`（D1–D7） |
+| 停下来问人的 12 个决策点      | `reddit-strategy-orchestrator/SKILL.md` §Human Decision Points            |
+
+## ✅ 已回填的规则真空（曾只在 archive，现已有 active 权威版本）
+
+下面两条原本**只**存在于 archive，已按原意搬进 active 文件（未扩写、未新增规则）。
+**权威版本在 active，本表只做溯源**；archive 仍然不读。
+
+| 原缺口                   | archive 出处                            | 现在的 active 权威位置                                                                 | 状态 |
+| ------------------------ | --------------------------------------- | -------------------------------------------------------------------------------------- | ---- |
+| 「量」换算与总盘子       | `reddit-strategy-reuse-playbook.md` §8.2 | `reddit-phase-planning/references/phase4-planning.md` 步骤 **4.0.0.0**（+ Phase 4.0.0 门禁一条；启动变量登记在 `context-contract.md`） | 已回填 |
+| 外部评论的 A/B readout 口径 | `reddit-strategy-reuse-playbook.md` §8.3 / §12 | `reddit-phase-planning/references/phase4-planning.md` Phase **4.0.5** A/B 口径框（`context-contract.md` 启动变量记默认值） | 已回填 |
+
+另有一条**疑似已废弃**、不确定是否还要：playbook §8.4 要求 B 组唯一变量同时包含
+**Ahrefs query** 与 **ChatGPT fanout**；active（`reddit-phase-planning/references/phase4-planning.md`）
+只保留了 fanout。若现行设计就是 fanout-only，这是有意收窄，不是真空。
+
+## 什么时候人可以看 archive/
+
+只在做 SOP 考古时：想知道某条规则**当初为什么这么定**、某个数字（如 9+3、
+2:8）的历史来源、或者对比 v1 → v2 的演进。**人**读，**agent** 不读。
+需要把 archive 里的某条规则重新变成硬规则时，正确做法是把它**搬进上表的
+active 文件**并走版本号，而不是恢复对本目录的强制阅读。

package/skills/reddit-strategy-shared/references/prerequisites/{reddit-master-canvas-agent-prompt-template.md → archive/reddit-master-canvas-agent-prompt-template.md}

@@ -1,5 +1,12 @@
 # Reddit Master Canvas Agent Prompt 模板
 
+> ## ⛔ ARCHIVED — AgentReadPolicy: DoNotRead
+>
+> 本文件已移出 skill 运行上下文，**仅供人工查阅 SOP 历史背景**。
+> agent 在任何阶段都不得读取本文件，也不得引用其中任何内容作为
+> gate / schema / 字段清单 / 结构规则 / 写作规范。权威来源见
+> `../README.md` 的对照表。
+
 **结论：** 这份模板的目标，是让任意一个 agent 在更换 topic、产品、关键词和数据源后，仍然能稳定产出与当前 Soundcore Reddit master canvas 同构的总控文档。**建议用法：** 先填写任务变量区，再把后面的标准 Agent Prompt 整段复制给下一个 agent。**主要风险：** 如果输入数据不完整，agent 很容易跳过证据层直接写策略，导致框架还在，但可信度不足。
 
 ## 模板目标

package/skills/reddit-strategy-shared/references/prerequisites/{reddit-sop-v2-universal.md → archive/reddit-sop-v2-universal.md}

@@ -1,5 +1,12 @@
 # Reddit GEO 策略 SOP v2 — 任意品牌通用入口
 
+> ## ⛔ ARCHIVED — AgentReadPolicy: DoNotRead
+>
+> 本文件已移出 skill 运行上下文，**仅供人工查阅 SOP 历史背景**。
+> agent 在任何阶段都不得读取本文件，也不得引用其中任何内容作为
+> gate / schema / 字段清单 / 结构规则 / 写作规范。权威来源见
+> `../README.md` 的对照表。
+
 > Path note: shell examples use macOS/Linux `~/.cursor/skills/...`. On Windows PowerShell, use `$HOME\.cursor\skills\...` or `$SkillsRoot = Join-Path $HOME ".cursor\skills"`, replace `python3` with `py -3`, and replace line-continuation `\` with backtick `` ` ``.
 >
 > v2.12.19 authority note: Phase 0 is **three-source collaboration**: eclickkb fact verification + KG markdown positioning narrative + client information sheet. The current authoritative execution details live in `reddit-phase-research/references/phase01-research.md`; if this legacy universal entry is less specific, follow the matrix research skill and shared contracts.

package/skills/reddit-strategy-shared/references/prerequisites/{reddit-strategy-prerequisites-read.md → archive/reddit-strategy-prerequisites-read.md}

@@ -1,5 +1,12 @@
 # Reddit 策略启动前必读
 
+> ## ⛔ ARCHIVED — AgentReadPolicy: DoNotRead
+>
+> 本文件已移出 skill 运行上下文，**仅供人工查阅 SOP 历史背景**。
+> agent 在任何阶段都不得读取本文件，也不得引用其中任何内容作为
+> gate / schema / 字段清单 / 结构规则 / 写作规范。权威来源见
+> `../README.md` 的对照表。
+
 **结论：** 只提供 Playbook 不够。Playbook 是「怎么做的 SOP」，品牌、地域、型号、Geoly、关键词文件等仍须你（或业务方）按 Playbook 第 15 节提供；缺 P0 时，Agent 只能写框架或标「无法验证」，没法做出与 soundcore 那套同等级数据型策略。
 
 ## 你最少还要准备什么（对齐 Playbook 第 15.1 P0）

package/skills/reddit-strategy-shared/references/prerequisites/{reddit-strategy-reuse-playbook.md → archive/reddit-strategy-reuse-playbook.md}

@@ -1,5 +1,12 @@
 # Reddit 策略复用 Playbook（跨品牌 SOP v2）
 
+> ## ⛔ ARCHIVED — AgentReadPolicy: DoNotRead
+>
+> 本文件已移出 skill 运行上下文，**仅供人工查阅 SOP 历史背景**。
+> agent 在任何阶段都不得读取本文件，也不得引用其中任何内容作为
+> gate / schema / 字段清单 / 结构规则 / 写作规范。权威来源见
+> `../README.md` 的对照表。
+
 > Path note: shell examples use macOS/Linux `~/.cursor/skills/...`. On Windows PowerShell, use `$HOME\.cursor\skills\...` or `$SkillsRoot = Join-Path $HOME ".cursor\skills"`, replace `python3` with `py -3`, and replace line-continuation `\` with backtick `` ` ``.
 >
 > v2.12.19 authority note: Phase 0 is now **three-source collaboration**: eclickkb fact verification + KG markdown positioning narrative + client information sheet. If this legacy playbook sounds like "语料库 + 知识图谱" only, follow `reddit-phase-research/references/phase01-research.md` and the shared contracts instead. Client brief fields are Phase 0 required inputs, not Phase 1.5 optional follow-up.