newsjack 0.1.5

package/skills/angle-generator/rubric.md

@@ -0,0 +1,219 @@
+# Angle Generator Rubric
+
+Use this rubric to evaluate an `angle-generator` output before it leaves the agent. Every criterion is scored 0-2.
+
+- **0** - Missing, broken, or actively unsafe.
+- **1** - Present but weak, generic, or partially unsupported.
+- **2** - Solid, specific, and faithful to the skill.
+
+Total possible: 20 points.
+
+| Points | Verdict |
+|--------|---------|
+| 18-20 | **ship** |
+| 14-17 | **revise** |
+| 8-13 | **regenerate** |
+| 0-7 | **refuse / ask for better input** |
+
+---
+
+## 1. Input Completeness And Now Anchor
+
+**Source trace:** `Prompt scaffolding > Process`, `Hard rules`, `Decay reasoning`; `Rubric / checks / banned lists > Decay sanity check`.
+
+The output must respect the input contract. `context.current_time` is required; the agent cannot infer "now" from model memory.
+
+**Score 0:** Missing `current_time` is ignored, weak facts are padded into angles, or the output proceeds on generic input like "new UI" without asking questions.
+
+**Score 1:** Anchors on `current_time` but still produces thin angles from thin facts.
+
+**Score 2:** Refuses or narrows the output when facts are insufficient; uses `current_time` and supplied signals as the only basis for urgency.
+
+Red flags:
+
+- "Today" or "this week" with no supplied timestamp.
+- Generic facts treated as news.
+- Calendar or signal hooks force-fit to unrelated updates.
+
+---
+
+## 2. Fact Traceability / Hallucination Gate
+
+**Source trace:** `Hard rules > You do not invent facts`; `Rubric / checks / banned lists > Hallucination gate`.
+
+Every angle must identify which user-supplied facts it uses. Missing evidence belongs in `required_proof`, not in the headline or rationale.
+
+**Score 0:** Invents statistics, named people, organizations, customer results, market claims, or regulatory details.
+
+**Score 1:** Mostly grounded but includes unsupported context as if factual, or `facts_used` is vague.
+
+**Score 2:** Every substantive claim traces to `update.facts`, provided links, company fields, or explicit signal payloads; missing evidence is cleanly flagged.
+
+Red flags:
+
+- `facts_used` is empty.
+- A statistic appears that was not in the input.
+- "Research shows" or "analysts say" with no provided source.
+
+---
+
+## 3. Structural Distinctness
+
+**Source trace:** `Hard rules > You enforce structural distinctness`; `Rubric / checks / banned lists > Distinctness check`; `Sample I/O > Example 4`.
+
+The set must contain different story shapes, not rephrasings for different inboxes.
+
+**Score 0:** Multiple angles share the same headline frame, protagonist, story type, and journalist shape.
+
+**Score 1:** Some distinction exists, but the set still contains filler variants or beat-swapped clones.
+
+**Score 2:** Each kept angle has a distinct protagonist, beat, story type, proof path, or timing frame; duplicates are killed and logged.
+
+Red flags:
+
+- "Another angle" is the main differentiator.
+- Same `story_type` plus same `beat_description`.
+- More than 65% conceptual overlap between headline frames.
+
+---
+
+## 4. Journalist Shape
+
+**Source trace:** `Journalist-shape rubric`; `Hard rules > You do not invent journalists`; `Pains addressed > Pitch volume + irrelevance`.
+
+An angle is not real until a plausible beat can be named. The skill names the shape, not a specific journalist.
+
+**Score 0:** Uses generic targets like "tech journalist" or names specific journalists without verification.
+
+**Score 1:** Beat is present but broad; `evidence_they_care` is generic or could apply to any outlet.
+
+**Score 2:** Beat, outlet archetype, timely reason, and `do_not_target` are specific enough to guide the next skill.
+
+Red flags:
+
+- "This would appeal to journalists who care about startups."
+- No `do_not_target`.
+- Named journalists appear in the output.
+
+---
+
+## 5. Why-Now And Decay
+
+**Source trace:** `Decay reasoning`; `Hard rules > You tag every angle with decay`; `Rubric / checks / banned lists > Decay sanity check`.
+
+The output must be honest about urgency.
+
+**Score 0:** Claims breaking urgency without a supplied signal, or omits decay.
+
+**Score 1:** Decay is present but generic; `why_now` is a vague trend or repeats the update date.
+
+**Score 2:** `why_now` names the real time hook or says `EVERGREEN, NOT TIME-PRESSURED`; decay matches the source of urgency.
+
+Red flags:
+
+- `30min` or `4hr` with no `signal_from_newsjack_detector`.
+- `evergreen` on a company update without an uncomfortable question.
+- "In today's market" as the peg.
+
+---
+
+## 6. Anti-Slop Pass
+
+**Source trace:** `Banned words and structures`; `Rubric / checks / banned lists > Anti-slop regex pass`; `Secondary signal - Reads like a bot wrote it`.
+
+The output must reject AI-marketing language before the user sees it.
+
+**Score 0:** Kept angles contain banned terms or press-release framing.
+
+**Score 1:** Mostly clean but one field still leans on puffery or generic phrasing.
+
+**Score 2:** Headline frames, `why_now`, `distinctness_check`, and `evidence_they_care` are concrete and free of banned structures.
+
+Red flags:
+
+- "innovative platform", "future of X", "game-changing", "excited to announce".
+- "It's not just X, it's Y."
+- Placeholder leftovers such as `[COMPANY]`.
+
+---
+
+## 7. Required Proof
+
+**Source trace:** `What "an angle" means`; `Hard rules > You ask uncomfortable questions`; `Rubric / checks / banned lists > Per-angle proof requirement`.
+
+The skill must show what evidence makes the angle pitchable.
+
+**Score 0:** Proof is absent, generic, or asks for evidence after already making the claim.
+
+**Score 1:** Proof exists but is not specific enough to guide the user.
+
+**Score 2:** Each angle lists concrete proof; `data`, `customer-story`, `contrarian`, and `exec-spotlight` angles have at least one required proof item.
+
+Red flags:
+
+- "Need more data" with no description of what data.
+- Contrarian angle with no stated conventional wisdom to challenge.
+- Customer story with no customer proof requirement.
+
+---
+
+## 8. Refused Angles
+
+**Source trace:** `Hard rules > You output the refused angles`; `Refusal patterns`; `Sample I/O`.
+
+Refusal is part of the product. The user should see what died and why.
+
+**Score 0:** No `refused_angles` field, or bad angles are kept instead of killed.
+
+**Score 1:** Refused angles are listed but reasons are vague or outside the allowed values.
+
+**Score 2:** Refused angles use allowed reasons and teach the user what not to pitch.
+
+Allowed refusal reasons:
+
+- `duplicate`
+- `slop`
+- `hallucinated_fact`
+- `no_journalist_shape`
+- `no_why_now_but_required`
+- `off-beat`
+
+---
+
+## 9. Uncomfortable Questions And Next Skill
+
+**Source trace:** `Hard rules > You ask uncomfortable questions`; `When to call other skills`; `Open questions / risks > brand risk of being too refusenik`.
+
+The skill should be tough without stranding the user.
+
+**Score 0:** No questions when proof gaps are obvious, or the output ends without a next move.
+
+**Score 1:** Questions exist but are broad, soft, or disconnected from the angles.
+
+**Score 2:** Questions expose the exact missing facts that determine whether the angles are real; `follow_up_suggestions` names the right next skill or `null`.
+
+Red flags:
+
+- "Can you provide more details?"
+- Recommending `meanest-editor` before there is an angle or draft.
+- Calling a media-list skill before journalist shapes exist.
+
+---
+
+## 10. Output Contract
+
+**Source trace:** `Output schema`; `Prompt scaffolding > Output format`.
+
+The final output must be machine-usable.
+
+**Score 0:** Prose summary instead of JSON, missing top-level keys, or invalid JSON.
+
+**Score 1:** JSON is valid but fields are missing, renamed, or filled with vague placeholders.
+
+**Score 2:** Valid JSON with `angles`, `refused_angles`, `uncomfortable_questions`, and `follow_up_suggestions`; each angle includes all required fields.
+
+Red flags:
+
+- Preamble such as "Here are your angles."
+- Markdown bullets instead of the schema.
+- `anti_slop_pass` omitted or set without actual anti-slop compliance.

package/skills/coverage-tracker/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: coverage-tracker
+description: "Run a Google Alerts-style keyword coverage tracker. Uses news-search for recent keyword queries, lets the LLM dedupe and classify real features versus junk, stores decisions in SQLite, and alerts only on new real coverage."
+when_to_use: "User wants to run coverage alerts, check new mentions, track press coverage, monitor brand/company keyword coverage, or execute a previously configured coverage tracker."
+---
+
+# Coverage Tracker
+
+Track whether configured keywords appeared in real coverage. Keep this simple: `news-search` collects dated article evidence, you dedupe and judge with the keyword's meaning snippet, and the CLI only stores config plus seen/alert state.
+
+This is not `newsjack-detector`. Do not score newsjacking opportunities, generate angles, assess standing, or use monitor profiles.
+
+## Workflow
+
+1. **Find the tracker.**
+   - If the user gave a slug, run `newsjack coverage status <slug>`.
+   - If working in a source checkout, prefer `bin/newsjack`.
+   - If no slug is given, ask which tracker to run unless local context makes it obvious.
+   - Read the returned `config_path`.
+
+2. **Search each keyword.**
+   - Read the current date from the system (e.g. run `date`); do not recall it from memory. Compute `since_date` as that date minus `lookback_days` from the config, defaulting to `2`.
+   - For each keyword, call `news-search` with exactly:
+
+     ```text
+     "keyword" after:YYYY-MM-DD
+     ```
+
+   - If the keyword has aliases, search each alias the same way, but keep the original keyword entry attached.
+   - Keep dated, attributed article fields from `news-search`: `title`, `url`, `outlet`, `author`, `published_at`, and snippet/summary when available.
+
+3. **Dedupe and check stored decisions before using the LLM.**
+   - Dedupe exact canonical URLs first, then obvious same-article duplicates by title/outlet/date.
+   - Create a minimal candidate JSON file only because the CLI helper consumes a file. Put it in a temporary location, or in a timestamped run folder if your harness normally keeps run artifacts:
+
+     ```json
+     {
+       "items": [
+         {
+           "keyword": "profound",
+           "title": "Article title",
+           "url": "https://...",
+           "outlet": "Outlet",
+           "author": "Author or null",
+           "published_at": "2026-06-05T12:00:00Z",
+           "snippet": "Search snippet or summary"
+         }
+       ]
+     }
+     ```
+
+   - Run:
+
+     ```bash
+     newsjack coverage check <slug> --input candidates.json
+     ```
+
+   - Do not reclassify `known_items` unless the user explicitly asks for a fresh review. Use their `prior_decision` to count filtered/known results and suppress repeat alerts.
+   - Classify only `unknown_items`.
+
+4. **LLM classify unknown items.**
+   - Use the keyword's `means` field as the authority for entity matching.
+   - Reject generic-word usage and wrong entities, especially for ambiguous keywords like `profound`.
+   - Do not alert from title/snippet keyword presence alone. When the snippet leaves the verdict unclear, read the article before deciding.
+
+   Use these verdicts:
+
+   - `real_feature`: the article is substantially about the intended entity/product/person. Alert.
+   - `substantive_mention`: meaningful paragraph-level mention, but not a feature. Save, normally no alert.
+   - `passing_mention`: brief mention only. Save, no alert.
+   - `wrong_entity`: the keyword refers to something else. Save, no alert.
+   - `junk`: SEO, scraper, duplicate landing page, job post, docs/help page, or non-news. Save, no alert.
+   - `uncertain`: insufficient evidence. Save, no alert.
+
+5. **Record only newly classified unknown items.**
+   If there are no `unknown_items`, skip `coverage record` and report from the `coverage check` result.
+
+   If you classified new items, write the minimum `decisions.json` needed by the CLI:
+
+   ```json
+   {
+     "items": [
+       {
+         "keyword": "profound",
+         "title": "Article title",
+         "url": "https://...",
+         "outlet": "Outlet",
+         "author": "Author or null",
+         "published_at": "2026-06-05T12:00:00Z",
+         "verdict": "real_feature",
+         "confidence": "high",
+         "alert": true,
+         "rationale": "Why this is about the intended keyword."
+       }
+     ]
+   }
+   ```
+
+   Include every newly classified unknown item, not only alerts. Saving rejects lets future runs skip them through `coverage check`.
+
+6. **Persist decisions and suppress repeat alerts.**
+
+   ```bash
+   newsjack coverage record <slug> --input decisions.json
+   ```
+
+   Add `--run-dir RUN_DIR` only when you already created a run folder for harness provenance. Read the command's JSON stdout directly. Do not write `record.json` unless the user or harness explicitly wants artifacts. Only articles in `new_alerts` are newly alertable; previously alerted URLs must not be re-alerted.
+
+7. **Deliver the result to the user.**
+   SQLite is the durable record. Do not write a separate report file; compose a short, readable message straight to the user from `coverage check` and, when run, `coverage record`:
+   - If `new_alerts` is non-empty, lead with the new real coverage items.
+   - If there are no new alerts, say there is no new confirmed coverage.
+   - Include a short run summary: keywords searched, since date, candidate count, skipped-known count, newly judged count, new alert count.
+   - Include a quiet "Filtered" line with counts by verdict, including prior decisions from known items, not a dump of every junk item.
+   - Use clickable links.
+
+   This skill is meant to run unattended on a schedule, so the message must stand alone — the user should not have to open any file to understand the run.
+
+## Output Discipline
+
+- Do not invent publication dates, outlets, or authors. If `news-search` cannot recover a date, classify cautiously.
+- Do not use story-origin or freshness gates; this is not a newsjack opportunity scan.
+- Do not call `angle-generator`, `journalist-fit-check`, or `meanest-editor`.
+- Do not install native cron. Recurrence belongs to the agent harness.

package/skills/coverage-tracker-setup/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: coverage-tracker-setup
+description: "Set up a lightweight Google Alerts-style coverage tracker for any number of keywords. Creates a tracker config with each keyword and what it actually means, then hands recurrence to the user's agent harness."
+when_to_use: "User wants to create, configure, or update coverage alerts, brand/company mention tracking, Google Alert-style monitoring, or keyword coverage tracking. Use this instead of newsjack-monitor-setup when the job is to track coverage of the user's own keywords rather than find newsjacking opportunities."
+---
+
+# Coverage Tracker Setup
+
+Create a simple keyword tracker for `coverage-tracker`. This workflow is intentionally separate from newsjack monitor profiles: coverage tracking answers "did my keyword get real coverage?", not "can this client newsjack a broader story?"
+
+## Inputs
+
+Ask only for missing facts:
+
+- tracker name
+- any number of keywords
+- one short `means` snippet per keyword: what entity/product/person the keyword should refer to
+- optional exclusions for ambiguous terms
+- cadence preference for the agent harness: daily morning, twice daily, or hourly
+
+Do not ask for standing, spokespeople, competitors, proof assets, RSS feeds, target beats, or PR angles. Those belong to newsjacking, not coverage tracking.
+
+## Setup Workflow
+
+1. Build a tiny tracker JSON:
+
+   ```json
+   {
+     "name": "Profound",
+     "lookback_days": 2,
+     "keywords": [
+       {
+         "keyword": "profound",
+         "means": "Profound, the AI search analytics company.",
+         "exclude_hints": ["generic adjective uses"]
+       }
+     ]
+   }
+   ```
+
+   `keywords` may contain any number of entries. Keep each `means` field concrete enough that a later LLM pass can reject wrong-entity and generic mentions.
+
+2. Save it with the CLI:
+
+   ```bash
+   newsjack coverage init <slug> --config tracker.json
+   ```
+
+   In a source checkout, prefer `bin/newsjack` from the repo root. Use `--force` only when the user explicitly wants to overwrite the existing tracker config.
+
+3. Set up recurrence in the agent harness, not native cron. If the runtime exposes a scheduling feature, schedule this prompt:
+
+   ```text
+   Use the coverage-tracker skill for <slug>.
+   ```
+
+   If no scheduling tool is available, tell the user exactly which prompt to schedule in Claude, Codex, Hermes, OpenClaw, or their chosen harness. Do not install system cron, launchd, systemd timers, or other native schedulers.
+
+4. Run once immediately if the user asked for a working setup, or if this is an end-to-end setup flow. Use `coverage-tracker` for the new slug and relay its first-run result to the user.
+
+## Updating Existing Trackers
+
+Run:
+
+```bash
+newsjack coverage status <slug>
+```
+
+Read the `config_path`, edit the tracker JSON, then re-run:
+
+```bash
+newsjack coverage init <slug> --config tracker.json --force
+```
+
+Only change the keyword aperture or meaning snippet. Alert decisions are stored in SQLite by `coverage-tracker`; do not edit those by hand.
+
+## Output
+
+When setup is complete, tell the user:
+
+- tracker slug
+- config path
+- schedule prompt/cadence
+- first-run result if you ran it