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

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/version-manifest.md

@@ -69,6 +69,66 @@ Copied independent skills should stay independently installable. Matrix wrappers
   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`).
 
+## Native-Copy Writing-Side Contracts (pending release roll-up)
+
+> The `Package:` line above is **not** bumped here. These contracts land with the
+> release that also relocks `skills/reddit-matrix.lock.json`; assigning them a
+> package version before that roll-up would claim a distribution that does not
+> exist yet.
+
+Two new shared references, with **different opt-in status — do not read them as
+one change**:
+
+- The **Persona Card is a default protocol change** for every main post. Any
+  batch that briefs a post now assigns one, and delivery checks it. It is
+  post-only; comments are unaffected.
+- The **NativeCopy profile is an opt-in overlay.** Nothing about it applies unless
+  a batch selects `AcceptanceProfile: NativeCopy`.
+
+- `reddit-strategy-shared/references/persona-card-contract.md` — the **Persona
+  Card**: the per-draft posting context (why this account posts this now, what it
+  may be assumed to know, what it must not display knowledge of, which firsthand
+  experience claims are authorised). It is a **Brief-stage artifact** and the
+  **third `PrewritingControlField`** alongside `AssignedFlair` / `PostingTrigger`;
+  `reddit-phase-brief` owns it and the writer never authors one. Post-only —
+  comments carry `N/A`. Capability fields (`knowledgeAccess`,
+  `permittedExperienceClaims`, `attentionFocus`, `questionIntent`) rather than a
+  role taxonomy; the five familiar role names are optional labels that no gate
+  reads. **`PersonaCardTransportStatus: LocalOnly(ServerContractMissing)`** — Hub
+  has no field for it, both review request schemas are strict, so the Card
+  governs writing only and is never sent, never smuggled into a free-text slot,
+  and never reported as something Hub assessed.
+- `reddit-strategy-shared/references/native-copy-profile.md` — the optional
+  `AcceptanceProfile: Default | NativeCopy` overlay. Client strictness applies
+  **only** under the profile, and each tightening is owned by one stage: the
+  **structural** ones (brand-mention ceiling, restricted `EndingMode` set) are
+  applied by `reddit-phase-brief` **at assignment** and never as a post-hoc edit
+  to a finished draft, because `EndingMode` / `BrandEntryMode` are locked
+  fingerprint fields; the **register** ones (PDP language, fake-Reddit-English,
+  forbidden official product-name strings) are the writer's while drafting.
+  Scoring thresholds are explicitly **not** in scope.
+  Current status is **`Unavailable(ServerContractMissing)`**: the profile needs a
+  server-stated review scope that does not exist yet, so it may not produce a
+  `ReadyForDelivery: Yes`, and it fails closed — never silently downgraded to
+  `Default`, never satisfied by a request weakened until it was accepted.
+
+Also in this version:
+
+- `handoff-schemas.md` — `PrewritingControlFields` goes from two to three;
+  compliance evidence now carries `EvidenceGatheredAt` / `EvidenceValidUntil` and
+  is **re-checked at delivery**, not cleared once; the two unadjudicated Gate 0
+  questions (brand/vendor participation, disclosure requirement) stay in
+  `MissingEvidence` behind a human decision rather than getting a field that makes
+  them look decided.
+- `reddit-delivery-check` — structure checks go from nine to ten (check 10:
+  Persona Card preserved, self-check recorded against the delivered Card
+  version), plus delivery-time evidence freshness, correct `not_assessed`
+  reporting, and the profile eligibility gate.
+
+Version identifiers stay independent: this package version, the profile, and the
+server's review semantics are **not** kept in step, and no skill asserts a
+review-semantics version it expects to see in a response.
+
 ## v2.12.30 Sample-Eligibility Contract
 
 A baseline card may only be built from **real user posts with an intact body**.

package/skills/reddit-subreddit-compliance/SKILL.md

@@ -174,6 +174,12 @@ description: |
 - **敏感内容**：医疗、财务、法律、政治、仇恨、NSFW、安全风险等
 - **bot/banner/sidebar/Installed Apps 信号**：AutoModerator 提示、Installed Apps（如 Bot Bouncer）、版主警告、banner 标语、sidebar 禁令、置顶帖更新
 - **历史删除风险**：如果 `reddit-voc-volume` 或用户材料显示类似内容常被质疑/删除，需要标注
+- **品牌 / vendor 是否被允许参与、是否需要 disclosure —— 这两项目前没有已裁定的答案，
+  不得当成已判定输出。** 版规里的自推广条款是**规则文本**，板块画像里的「品牌友好度」是
+  **文化描述**，采集回来的 evidence 是**未裁定的原始材料**——三者都不是「该板块允许品牌/
+  vendor 发布」或「该板块要求披露」的裁定。缺裁定时的正确做法：写进 `MissingEvidence`，
+  给对应行标上 `PostRisk` / `CommentRisk`，由用户记录人工决定。**不要新造一个字段把未裁定的
+  问题写成已裁定的样子**；也不要因为「版规没写禁止」就当作允许——规则未提及不等于许可。
 
 ### Step 3.5: 账号条件与风控闸门
 
@@ -260,14 +266,30 @@ description: |
 - PinnedEvidenceStatus: Provided / NeedsAcquisition / NotVisible / Unavailable
 - BotBannerEvidenceStatus: Provided / NeedsAcquisition / Unavailable
 - InstalledAppsStatus: Provided / NeedsAcquisition / NotVisible / Unavailable
+- AboutPageEvidenceStatus: Provided / NeedsAcquisition / NotVisible / Unavailable
 - PublicFlairFilterStatus: Provided / NeedsAcquisition / NotVisible / Unavailable
 - DataAcquisition: NotPerformedByThisSkill / ProvidedByUser / ProvidedByRedditVocVolume / ProvidedBySocialHub
+- EvidenceGatheredAt: <ISO 时间戳 / Unknown>   # 交付必需 5 项里**最早**的采集时点
+- EvidenceValidUntil: <ISO 时间戳 / Unknown>   # 其中**最早**的有效期（如 Hub freshUntil）；无声明写 Unknown
 - RiskTriggerSummary: promotional / self-promotion / external links / weekly thread / flair / link-only / account age / comment karma / affiliate / discount code / Unknown
 - WritingOutput: NotProvided
 ```
 
 `RiskTriggerSummary` 要复用用户材料里的关键英文原词，例如 `promotional`、`self-promotion`、`external links`、`weekly thread`、`no link-only posts`、`low comment karma`。若出现 `DM me for discounts`、折扣码、官网链接、product website link、affiliate、UTM 或短链，也要列入并标为导流、促销或外链风险。
 
+`EvidenceGatheredAt` / `EvidenceValidUntil` 存在是因为**本报告是时点快照，不是长期通行证**。
+排期与发布都发生在报告写完之后，版规会改、置顶会换。两个字段是**批次级最坏值**：
+`EvidenceGatheredAt` 取交付必需证据里**最早**的采集时点，`EvidenceValidUntil` 取其中**最早**
+的有效期；各项差异大到一对最坏值会掩盖某项已过期时，须补记逐项时间。下游
+`reddit-delivery-check` 会在**交付时**按这两个字段重新核验新鲜度，过期即 hold 对应行重新采集重判。
+⚠️ **`Unknown` 不算 fresh**：任一交付必需项的采集时点未知或来源未声明有效期，就不能靠这两个
+标量放行。
+⚠️ 时间戳只能**重新打开**一个问题，永远不能**回答**它：新鲜度只适用于「已采集的证据」，
+不适用于「从未裁定过的许可」。品牌/vendor 参与许可与 disclosure 要求若没有人工裁定，
+再新的时间戳也不构成放行。
+⚠️ 过期证据只能重采重判，**不得顺延**：过期的版规快照写 `NeedsAcquisition`。风格类软判断缺来源
+可以降级放行，**合规裁定不行**——「没查到」不等于「允许」。
+
 `RedditVocVolumeEvidenceRole` 用来防止把采样结果误当版规。帖子样本只能写 `PreferenceSignalOnly`；但 `subreddit_rules`、`wiki_page`、`subreddit_about.submit_text_excerpt/settings`、`pinned_post`、`subreddit_about_page.installed_apps[]` 可按对应公开来源进入 `EvidenceSources`。没有使用 VOC 时写 `NotProvided`。
 
 `WritingOutput` 对本 skill 永远是 `NotProvided`；如果用户混合要求写标题/正文，`TaskRoute` 用 `NeedsWritingSkillAfterCompliance`，但本 skill 仍然不输出写作内容。
@@ -287,8 +309,11 @@ description: |
 - `PinnedEvidenceStatus`
 - `BotBannerEvidenceStatus`
 - `InstalledAppsStatus`
+- `AboutPageEvidenceStatus`
 - `PublicFlairFilterStatus`
 - `DataAcquisition`
+- `EvidenceGatheredAt`
+- `EvidenceValidUntil`
 - `RiskTriggerSummary`
 - `WritingOutput`: NotProvided
 - `MissingEvidence`
@@ -336,7 +361,7 @@ description: |
 
 ## 输出前自检
 
-提交前检查：不生成/改写帖子、评论、标题；不自行写脚本或调用 `.json`、curl、浏览器抓 Reddit；数据需求交给 `reddit-voc-volume` 或用户材料；标明证据来源、缺口、规则/bot/sidebar/置顶帖信号、账号条件；输出 `RulesEvidenceStatus`、`PinnedEvidenceStatus`、`BotBannerEvidenceStatus`、`InstalledAppsStatus`、`PublicFlairFilterStatus`、`DataAcquisition`、`Fit`、`OverallRisk`、`EvidenceCompleteness`、`AccountGate`；不承诺“不会被删帖/不会封号”。
+提交前检查：不生成/改写帖子、评论、标题；不自行写脚本或调用 `.json`、curl、浏览器抓 Reddit；数据需求交给 `reddit-voc-volume` 或用户材料；标明证据来源、缺口、规则/bot/sidebar/置顶帖信号、账号条件；输出 `RulesEvidenceStatus`、`PinnedEvidenceStatus`、`BotBannerEvidenceStatus`、`InstalledAppsStatus`、`AboutPageEvidenceStatus`、`PublicFlairFilterStatus`、`DataAcquisition`、`EvidenceGatheredAt`、`EvidenceValidUntil`、`Fit`、`OverallRisk`、`EvidenceCompleteness`、`AccountGate`；未裁定的品牌/vendor 许可与 disclosure 要求留在 `MissingEvidence`，不写成已判定；不承诺“不会被删帖/不会封号”。
 
 ## HandoffContract
 
@@ -356,6 +381,8 @@ description: |
 - AboutPageEvidenceStatus:
 - PublicFlairFilterStatus:
 - AccountGate:
+- EvidenceGatheredAt:
+- EvidenceValidUntil:
 - MissingEvidence:
 - ReadyForNextSkill: Yes / No
 ```