research: X social discovery harvest run (candidate claims only, public URLs, date precision)

AGENTS.md

@@ -16,6 +16,11 @@ House style: ASCII punctuation only, no em dashes; operator-first, skeptical, no
 hype. Cite the primary source on the claim-bearing words. Every claim carries a
 receipt or it does not ship.
 
+For reader-facing prose, use the repo-local [humanizer skill](./skills/humanizer/SKILL.md):
+the public copy should sound like a sharp person explaining the idea clearly,
+with traceability and research-process details pushed into quieter source
+layers.
+
 Validate before you push:
 
     npm --prefix site run build            # regenerates pages + internal link check

CONTRIBUTING.md

@@ -61,6 +61,17 @@ window-anchoring; the maintainers decide whether it rises to a signal. See the
 A coverage gap must carry the same receipt and in-window date as a correction,
 plus which artifact should have caught it (which window's digest, which profile).
 
+For public X/social discovery that may become a coverage gap later, use the
+[X Social Harvest Workflow](./docs/x-social-harvest-workflow.md). Social harvests
+are candidate inputs only; product/version claims still need source-contract
+cross-checks before promotion.
+
+For deeper public-conversation work, including static tweet-like receipt cards
+and ecosystem-drama cataloging, use the
+[Deep Social Research Loop](./docs/deep-social-research-loop.md). The loop keeps
+cards repo-local and treats social posts as context until source contracts
+support promotion.
+
 ### 3. New-source proposals
 
 A proposal to add a watchlist source contract (a new provider) or an

docs/deep-social-research-loop.md

@@ -0,0 +1,114 @@
+# Deep Social Research Loop
+
+This workflow turns public X/social material into a richer research layer for
+Bitter Frontier without relaxing the evidence floor for product claims.
+
+The loop has three roles:
+
+- Scout: mines public social posts for interesting facts, public exchanges,
+  adoption signals, user pain, maintainer intent, benchmark discourse, and
+  ecosystem drama.
+- Critic: challenges the scout packet for overclaiming, missing counter-posts,
+  weak source attribution, and unclear operator relevance.
+- Editor: stores only reproducible artifacts in the repo, writes cautious
+  summaries, and decides what remains social context versus what deserves a
+  later source-contract verification pass.
+
+The role names are generic. Do not record private session identifiers, model
+transcripts, raw API payloads, local paths, private prompts, reviewer names, or
+credentials in public artifacts.
+
+## Output Shape
+
+A social research run may include:
+
+```text
+runs/<run-id>/
+  manifest.yml
+  editorial.yml
+  harvest/*.md
+  social-cards/*.yml
+  research-journal.md
+  verify/*.md
+  qa.md
+```
+
+`harvest/*.md` keeps structured candidate claims. `social-cards/*.yml` stores
+static post artifacts the site can embed inside editorial. `editorial.yml` is
+the public reading experience: argument first, evidence woven into the essay,
+with traceability pushed into source links or a collapsed source trail.
+`research-journal.md` records editorial decisions, open loops, and what the next
+scout pass should investigate.
+
+## Publication Rule
+
+The public page should read like a finished editorial, not a research binder.
+Use X/social material to sharpen the story, show the public conversation, and
+surface questions a release-note-only workflow would miss. Do not lead with raw
+receipts, card grids, QA notes, claim tables, or artifact inventories.
+
+Traceability remains mandatory, but it belongs in the background: source links
+on the embedded post figure, collapsed evidence notes, repo artifacts, and the
+Git history. A reader should be able to audit the piece without having the audit
+machinery interrupt the piece.
+
+## Static Social Cards
+
+Social cards simulate the useful parts of an embedded post while keeping runtime
+independent from X. They are source material for editorial embeds, not the
+primary public artifact:
+
+```yaml
+schema_version: bitter.frontier_social_cards.v0
+run_id: 2026-06-24-x-social-harvest-2026-06-24-frontier-v0
+cards:
+  - id:
+    title:
+    kind: capability_announcement | maintainer_intent | user_pain | adoption_signal | benchmark_discourse | ecosystem_drama | public_exchange | governance_or_affiliation | meme_or_positioning
+    status: candidate | social_context | single_source_unconfirmed | needs_primary_crosscheck | verified_secondary | refuted | superseded
+    date: YYYY-MM-DD
+    date_precision: day | month_only | year_only | unknown
+    date_note:
+    source_ids: []
+    authors: []
+    source_urls: []
+    excerpt:
+    summary:
+    why_it_matters:
+    verification_needed:
+    confidence:
+    caveats:
+    tags: []
+```
+
+Use short excerpts only. Prefer a neutral summary plus a source link over long
+quoted text.
+
+## Evidence Boundaries
+
+- A social card can make the journal more grounded and readable.
+- A social card is not, by itself, a finding, signal, digest claim, or profile
+  claim.
+- Product/version/capability claims still need source-contract verification
+  before promotion.
+- A secondary receipt upgrades only the exact bounded claim it proves. Do not
+  let a real release tag or PR validate a different claim from the same project.
+- Drama, public exchanges, rankings, benchmark chatter, and user pain may be
+  cataloged as ecosystem context when clearly labeled.
+- If a claim depends on a thread or reply chain, keep enough public source URLs
+  to let a reader reconstruct the exchange.
+- Reputational or conduct claims about named people or organizations stay
+  journal-only unless supported by direct primary receipts.
+- User-pain and drama clusters should include counterweight searches: fixes,
+  maintainer replies, disconfirming posts, issue threads, or release notes.
+
+## Loop Cadence
+
+1. Scout one slice: a project, theme, or date window.
+2. Critic pass: reject weak items, ask for missing context, and identify
+   follow-up searches.
+3. Editor pass: write or revise social cards, journal notes, and caveats.
+4. Repeat until the remaining open questions are specific verification tasks,
+   not broad social discovery gaps.
+5. Run `git diff --check`, `node site/scripts/check-integrity.mjs`, and the site
+   build before publishing.

docs/x-social-harvest-workflow.md

@@ -0,0 +1,155 @@
+# X Social Harvest Workflow
+
+This workflow captures public X/social signals as discovery input for Bitter
+Frontier. It does not create findings, signals, digests, or profile updates by
+itself. Promotion happens only in a later source-contract pass.
+
+## When to use it
+
+Use this workflow when X/social posts may reveal maintainer intent, public
+adoption, ecosystem tension, or feature announcements that are not yet obvious
+from releases and changelogs.
+
+Do not use it to publish claims directly. A social post can seed a candidate; it
+does not satisfy the evidence floor for product/version claims unless the source
+contract explicitly accepts that evidence kind.
+
+## Run shape
+
+Create a run directory:
+
+```text
+runs/YYYY-MM-DD-x-social-harvest-YYYY-MM-DD-frontier-v0/
+  manifest.yml
+  editorial.yml
+  harvest/<source>.md
+  social-cards/<cluster>.yml
+  research-journal.md
+  verify/x-post-dates.md
+  qa.md
+```
+
+Keep the run public and reproducible. Do not mention local paths, session IDs,
+private prompts, private API payloads, reviewer names, or internal coordination.
+
+`editorial.yml` is the public reading surface for a social harvest. It should
+read like a finished essay: thesis first, human stakes second, evidence embedded
+tastefully where it clarifies the argument. The rest of the run is supporting
+infrastructure. Do not make readers begin with receipt grids, harvest tables,
+QA notes, or artifact inventories.
+
+## Harvest fields
+
+Each claim record should include these fields:
+
+```text
+claim_id:
+source:
+claim:
+primary_url:
+author:
+observed_at: YYYY-MM-DD
+event_date: YYYY-MM-DD
+date_precision: day | month_only | year_only | unknown
+date_note:
+evidence_kind: maintainer_authored_post | official_account_post | community_discussion | community_account_post
+channel: x.com
+status: candidate | needs_primary_crosscheck | single-source-unconfirmed | refuted | superseded
+secondary_receipts:
+crosscheck_status: verified_primary | verified_secondary | needs_primary_crosscheck | single_source_unconfirmed | social_only | refuted | superseded
+release_channel: tagged-release | main-unreleased | preview-or-beta | social_only | not_applicable | mixed
+operator_consequence:
+notes:
+```
+
+`secondary_receipts` is optional. When present, use public URLs such as GitHub
+release tags, commits, pull requests, changelog entries, or official docs.
+
+## Evidence rules
+
+- Persist exact public post URLs, not paraphrased search results.
+- Resolve post dates to full ISO `YYYY-MM-DD` when possible.
+- If only month or year is available, record `date_precision` and explain the
+  limitation in `date_note`.
+- Use cautious `operator_consequence` language. Social evidence can suggest what
+  to investigate; it should not tell operators to upgrade, migrate, or trust a
+  feature.
+- Mark product/version claims `needs_primary_crosscheck` until checked against
+  the relevant source contract.
+- Mark drama, adoption, benchmark, and ranking claims
+  `single-source-unconfirmed` unless independently supported.
+
+For richer public context, use the
+[Deep Social Research Loop](./deep-social-research-loop.md). It defines the
+static social-card format used to render tweet-like figures inside the editorial
+from repo data without loading X at runtime.
+
+## Cross-check pass
+
+For each product/version/capability claim, check the public source contract
+surface before promotion:
+
+- GitHub releases or tags
+- commit or pull request receipts
+- official docs or changelog
+- reproducible local probe, when appropriate
+
+Record the result as `crosscheck_status`. If the claim is only social evidence,
+leave it as `needs_primary_crosscheck` or `single_source_unconfirmed`.
+
+When upgrading a claim to `verified_secondary`, record the receipt-to-claim map.
+The secondary receipt must prove the same bounded claim, not merely a nearby
+claim in the same project. Narrow the claim text when the receipt verifies only
+part of the social post.
+
+Examples:
+
+- A release tag that includes an Antigravity transition banner and migration
+  commands can verify transition/migration support, but not a broader social
+  claim about a hard cutoff or quota pain.
+- A release PR that adds an ACP settings UI can partially support an ACP post,
+  but it should not verify every SDK, cloud, or product-surface claim unless the
+  receipt names those surfaces.
+- A release that contains adjacent orchestration or adapter work should not
+  verify an aspirational maintainer post unless it names the same shipped
+  feature.
+
+For drama, affiliation, takedown, funding, hiring, or motive claims naming
+people or organizations, keep the item as journal context until direct
+participant posts, public organization records, or other primary receipts
+support the exact claim. Date precision alone is not enough.
+
+When a social cluster is user pain or drama, look for counterweight before
+publishing the run: maintainer replies, release fixes, docs, issue threads, or
+changelog entries that show remediation or disconfirmation.
+
+## QA checklist
+
+Before opening or updating a PR:
+
+- Every claim has a public `primary_url`.
+- Every claim has `observed_at`, `event_date`, `date_precision`, and `date_note`.
+- Every product/version claim has `crosscheck_status`.
+- Every `verified_secondary` claim has a public receipt-to-claim explanation.
+- Reputational or conduct claims remain journal-only unless exact primary
+  evidence supports them.
+- User-pain clusters include counterweight search notes where public releases,
+  issues, or maintainer replies exist.
+- No claim is promoted into `content/digests`, `content/profiles`, or
+  `signals/frontier-signals.yml`.
+- `verify/x-post-dates.md` explains how dates were resolved.
+- `qa.md` lists what was checked, what remains unchecked, and the discovery-only
+  boundary.
+- `git diff --check` passes.
+- `node site/scripts/check-integrity.mjs` passes.
+
+## PR language
+
+Describe the PR as a discovery harvest, not a verified digest. A good summary is:
+
+```text
+Public X/social discovery harvest for candidate Frontier claims. The run records
+public post URLs, exact or qualified dates, evidence kind, status, and
+cross-check state. No claims are promoted to findings, signals, digests, or
+profiles.
+```