@bompus/house-rules 0.0.0-stage → 0.13.0

package/skills/hr-pr-followup/scripts/resolve-pr-thread.ts

@@ -0,0 +1,219 @@
+#!/usr/bin/env bun
+// See ../references/review-helpers.md. One selected thread, dry-run by default, no mutation retries.
+import { parseArgs } from "node:util";
+import { author, date, githubGraphQL, record, text } from "./check-pr-review";
+
+type Selection = { pr: string; thread: string; head: string; reply: string; apply: boolean };
+type Thread = { id: string; isResolved: boolean; isOutdated: boolean; viewerCanResolve: boolean };
+const ACTOR = "{__typename login}";
+const META = `id isResolved isOutdated viewerCanResolve pullRequest{url headRefOid state repository{viewerPermission}}`;
+const COMMENTS = `comments(first:100,after:$cursor){pageInfo{hasNextPage endCursor} nodes{id url body state publishedAt isMinimized author${ACTOR} editor${ACTOR} lastEditedAt replyTo{id}}}`;
+
+function selection(): Selection {
+  const { values, positionals } = parseArgs({
+    options: {
+      thread: { type: "string" },
+      "expect-head": { type: "string" },
+      "reply-url": { type: "string" },
+      apply: { type: "boolean", default: false },
+    },
+    allowPositionals: true,
+  });
+  const [pr] = positionals;
+  if (
+    positionals.length !== 1 ||
+    !pr ||
+    !/^https:\/\/github\.com\/[A-Za-z0-9-]+\/[A-Za-z0-9_.-]+\/pull\/[1-9][0-9]*$/.test(pr) ||
+    !values.thread?.trim() ||
+    !values["expect-head"] ||
+    !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(values["expect-head"]) ||
+    !values["reply-url"]?.startsWith(`${pr}#discussion_r`) ||
+    !/^#discussion_r[1-9][0-9]*$/.test(values["reply-url"].slice(pr.length))
+  ) {
+    throw new Error(
+      "usage: resolve-pr-thread.ts <GitHub PR URL> --thread <id> --expect-head <full SHA> --reply-url <reply URL> [--apply]",
+    );
+  }
+  return {
+    pr,
+    thread: values.thread,
+    head: values["expect-head"],
+    reply: values["reply-url"],
+    apply: values.apply === true,
+  };
+}
+
+function metadata(data: Record<string, unknown>, s: Selection): Thread {
+  const t = record(data.node);
+  const pr = record(t.pullRequest);
+  const permission = record(pr.repository).viewerPermission;
+  if (
+    t.__typename !== "PullRequestReviewThread" ||
+    t.id !== s.thread ||
+    pr.url !== s.pr ||
+    typeof t.isResolved !== "boolean" ||
+    typeof t.isOutdated !== "boolean" ||
+    typeof t.viewerCanResolve !== "boolean" ||
+    !author(data.viewer) ||
+    !(
+      permission === null ||
+      (text(permission) && ["READ", "TRIAGE", "WRITE", "MAINTAIN", "ADMIN"].includes(permission))
+    ) ||
+    !text(pr.state) ||
+    !["OPEN", "CLOSED", "MERGED"].includes(pr.state)
+  ) {
+    throw new Error("malformed or mismatched thread/PR metadata");
+  }
+  if (pr.headRefOid !== s.head) {
+    throw new Error("PR head differs from expected head; stop and re-read");
+  }
+  if (
+    !t.isResolved &&
+    (pr.state !== "OPEN" ||
+      !t.viewerCanResolve ||
+      !["WRITE", "MAINTAIN", "ADMIN"].includes(permission as string))
+  ) {
+    throw new Error("open PR and write/resolve permission required");
+  }
+  return t as unknown as Thread;
+}
+
+function request(s: Selection, comments: boolean, cursor?: string): Record<string, unknown> {
+  const query = `query($thread:ID!${comments ? ",$cursor:String" : ""}){viewer${ACTOR} node(id:$thread){__typename ... on PullRequestReviewThread{${META} ${comments ? COMMENTS : ""}}}}`;
+  return githubGraphQL(query, { thread: s.thread, ...(cursor ? { cursor } : {}) }, "github.com");
+}
+
+function comment(value: unknown): Record<string, unknown> {
+  const c = record(value);
+  if (
+    !text(c.id) ||
+    !text(c.url) ||
+    !text(c.body) ||
+    !text(c.state) ||
+    !["PENDING", "SUBMITTED"].includes(c.state) ||
+    !(c.publishedAt === null || date(c.publishedAt)) ||
+    typeof c.isMinimized !== "boolean" ||
+    !author(c.author) ||
+    !author(c.editor) ||
+    !(c.lastEditedAt === null || date(c.lastEditedAt)) ||
+    !(c.replyTo === null || text(record(c.replyTo).id))
+  ) {
+    throw new Error("malformed thread comment");
+  }
+  return c;
+}
+
+function readSelection(s: Selection): Thread {
+  const seen = new Set<string>();
+  const comments: Record<string, unknown>[] = [];
+  let cursor: string | undefined;
+  let viewer: Record<string, unknown>;
+  for (;;) {
+    const data = request(s, true, cursor);
+    metadata(data, s);
+    viewer = record(data.viewer);
+    const page = record(record(data.node).comments);
+    const info = record(page.pageInfo);
+    if (
+      !Array.isArray(page.nodes) ||
+      typeof info.hasNextPage !== "boolean" ||
+      !(info.endCursor === null || text(info.endCursor))
+    ) {
+      throw new Error("malformed thread comment page");
+    }
+    comments.push(...page.nodes.map(comment));
+    if (!info.hasNextPage) {
+      break;
+    }
+    if (!text(info.endCursor) || !info.endCursor || seen.has(info.endCursor)) {
+      throw new Error("non-advancing thread comment cursor");
+    }
+    seen.add(info.endCursor);
+    cursor = info.endCursor;
+  }
+  const matches = comments.filter((c) => c.url === s.reply);
+  if (matches.length !== 1) {
+    throw new Error("selected reply is missing or ambiguous in this thread");
+  }
+  const reply = matches[0]!;
+  const writer = record(reply.author);
+  const editor = reply.editor === null ? null : record(reply.editor);
+  if (
+    viewer.__typename !== "User" ||
+    writer.__typename !== "User" ||
+    writer.login !== viewer.login ||
+    reply.state !== "SUBMITTED" ||
+    reply.publishedAt === null ||
+    !String(reply.body).trim() ||
+    reply.isMinimized ||
+    reply.replyTo === null ||
+    !comments.some((c) => c.id === record(reply.replyTo).id && c.id !== reply.id) ||
+    (reply.lastEditedAt !== null &&
+      (editor?.__typename !== "User" || editor.login !== viewer.login))
+  ) {
+    throw new Error(
+      "reply must be published, submitted, visible, nonblank, authored by the authenticated human and edited only by that human",
+    );
+  }
+  const final = request(s, false);
+  const currentViewer = record(final.viewer);
+  if (currentViewer.__typename !== viewer.__typename || currentViewer.login !== viewer.login) {
+    throw new Error("authenticated viewer changed during read");
+  }
+  return metadata(final, s);
+}
+
+function resolve(s: Selection): void {
+  const before = readSelection(s);
+  if (before.isResolved) {
+    console.log(`Already resolved: ${s.thread}; no mutation`);
+    return;
+  }
+  if (!s.apply) {
+    console.log(
+      `Dry-run: ready to resolve ${s.thread}${before.isOutdated ? " (outdated)" : ""}; judge the selected reply's explanation before applying`,
+    );
+    return;
+  }
+  let uncertain = false;
+  try {
+    const data = githubGraphQL(
+      "mutation($thread:ID!){resolveReviewThread(input:{threadId:$thread}){thread{id isResolved}}}",
+      { thread: s.thread },
+      "github.com",
+    );
+    const result = record(record(data.resolveReviewThread).thread);
+    if (result.id !== s.thread || result.isResolved !== true) {
+      throw new Error("unverified mutation payload");
+    }
+  } catch {
+    uncertain = true;
+  }
+  // A lost response may hide a successful mutation. Read before any user-initiated retry.
+  let after: Thread;
+  try {
+    after = readSelection(s);
+  } catch (error) {
+    throw new Error(
+      `Mutation attempted once; final verification failed (${error instanceof Error ? error.message : "unknown error"}). Thread may already be resolved; re-read before any retry`,
+      { cause: error },
+    );
+  }
+  if (!after.isResolved) {
+    throw new Error(
+      "thread remains unresolved after mutation attempt; no retry made; re-read before retrying",
+    );
+  }
+  console.log(
+    `Verified resolved: ${s.thread} at ${s.head}${uncertain ? "; mutation response uncertain, fresh state verified" : ""}`,
+  );
+}
+
+if (import.meta.main) {
+  try {
+    resolve(selection());
+  } catch (error) {
+    console.error(`resolve-pr-thread: ${error instanceof Error ? error.message : "failed"}`);
+    process.exitCode = 2;
+  }
+}

package/skills/hr-pr-followup/scripts/verify-landed.sh

@@ -0,0 +1,184 @@
+#!/usr/bin/env bash
+# Post-merge landing checks: containment, local-default state, leftover remote branches.
+# Fetches and verifies both remote containment and local-default equality. A stale local default
+# fails even when the remote contains the commit. Never resets, switches or deletes.
+# With --ff it updates a default checked out nowhere or here with a clean tree.
+# --idle-primary <path> additionally permits a fast-forward of this repository's primary checkout:
+# use existing ownership evidence or the operator's standing idle direction, unless current
+# evidence contradicts it. Git preserves
+# unrelated local edits and refuses a fast-forward that would overwrite them. It moves the
+# primary to the verified remote commit with `merge --ff-only <sha>` rather than `pull`, because
+# `pull` re-fetches into the shared FETCH_HEAD, which a concurrent fetch in the same checkout can
+# overwrite ("Cannot fast-forward to multiple branches"). Other linked worktrees
+# remain their owners' responsibility. After a blocked post-merge check, rerun this script,
+# not merge-pr.sh: the PR is already merged.
+# --preflight checks synchronization eligibility before landing, without moving local branches.
+# It requires --ff and rejects dirty or diverged targets and unconfirmed checkout ownership,
+# even when the local default is current. The caller must keep the target idle until landing
+# finishes; this check cannot establish session ownership or prevent another process starting.
+# Usage:
+#   bash scripts/verify-landed.sh --commit <sha> [--default <branch>]
+#     [--branch <merged-head>] [--remote <name>] [--ff [--idle-primary <path>]]
+#   bash scripts/verify-landed.sh --preflight --ff [--default <branch>]
+#     [--remote <name>] [--idle-primary <path>]
+set -euo pipefail
+
+REMOTE=origin
+DEFAULT=""
+COMMIT=""
+BRANCH=""
+FF=0
+IDLE_PRIMARY=""
+PREFLIGHT=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --commit) COMMIT="${2:?}"; shift 2;;
+    --default) DEFAULT="${2:?}"; shift 2;;
+    --branch) BRANCH="${2:?}"; shift 2;;
+    --remote) REMOTE="${2:?}"; shift 2;;
+    --ff) FF=1; shift;;
+    --idle-primary) IDLE_PRIMARY="${2:?}"; shift 2;;
+    --preflight) PREFLIGHT=1; shift;;
+    *) echo "unknown argument: $1" >&2; exit 2;;
+  esac
+done
+if [ "$PREFLIGHT" = 1 ]; then
+  [ "$FF" = 1 ] && [ -z "$COMMIT$BRANCH" ] \
+    || { echo "--preflight requires --ff and excludes --commit/--branch" >&2; exit 2; }
+else
+  [ -n "$COMMIT" ] || { echo "missing --commit <sha>" >&2; exit 2; }
+fi
+if [ -n "$IDLE_PRIMARY" ]; then
+  [ "$FF" = 1 ] || { echo "--idle-primary requires --ff" >&2; exit 2; }
+  PRIMARY="$(git worktree list --porcelain | sed -n '1s/^worktree //p')"
+  IDLE_PRIMARY="$(git -C "$IDLE_PRIMARY" rev-parse --show-toplevel)"
+  [ "$IDLE_PRIMARY" = "$PRIMARY" ] \
+    || { echo "--idle-primary is not this repository's primary checkout: $IDLE_PRIMARY" >&2; exit 2; }
+fi
+
+if [ -z "$DEFAULT" ]; then
+  # The remote's own answer wins; the cached origin/HEAD goes stale when the default branch changes.
+  DEFAULT="$(git ls-remote --symref "$REMOTE" HEAD 2>/dev/null | sed -n 's#^ref: refs/heads/\([^[:space:]]*\).*#\1#p' || true)"
+  if [ -z "$DEFAULT" ]; then
+    DEFAULT="$(git symbolic-ref "refs/remotes/$REMOTE/HEAD" 2>/dev/null | sed "s#^refs/remotes/$REMOTE/##" || true)"
+  fi
+  [ -n "$DEFAULT" ] || { echo "cannot resolve remote default branch; pass --default" >&2; exit 2; }
+fi
+
+git fetch "$REMOTE" "+refs/heads/$DEFAULT:refs/remotes/$REMOTE/$DEFAULT" >/dev/null 2>&1 \
+  || { echo "fetch failed: $REMOTE $DEFAULT" >&2; exit 1; }
+
+WTLS="$(git worktree list --porcelain)"
+HOLDER="$(printf '%s\n' "$WTLS" | awk -v want="branch refs/heads/$DEFAULT" '
+  /^worktree / { path = substr($0, 10) }
+  $0 == want { print path; exit }
+')"
+HERE="$(git rev-parse --show-toplevel)"
+
+if [ "$PREFLIGHT" = 1 ]; then
+  # A rebase or bisect detaches HEAD while still reserving its original branch.
+  if [ -z "$HOLDER" ]; then
+    while IFS= read -r RECORD; do
+      case "$RECORD" in worktree\ *) CHECKOUT="${RECORD#worktree }";; *) continue;; esac
+      [ -d "$CHECKOUT" ] || continue
+      for ASSOCIATION in rebase-merge/head-name rebase-apply/head-name BISECT_START; do
+        ASSOCIATION_PATH="$(git -C "$CHECKOUT" rev-parse --path-format=absolute --git-path "$ASSOCIATION")"
+        if [ -f "$ASSOCIATION_PATH" ]; then
+          IFS= read -r ASSOCIATED_BRANCH < "$ASSOCIATION_PATH"
+          if [ "$ASSOCIATED_BRANCH" = "refs/heads/$DEFAULT" ] || [ "$ASSOCIATED_BRANCH" = "$DEFAULT" ]; then
+            HOLDER="$CHECKOUT"
+            break 2
+          fi
+        fi
+      done
+    done <<< "$WTLS"
+  fi
+  if [ -n "$HOLDER" ]; then
+    if [ "$HOLDER" != "$HERE" ] && [ "$HOLDER" != "$IDLE_PRIMARY" ]; then
+      echo "sync blocked at $HOLDER: that checkout has the default branch. If nothing is using it, rerun with --idle-primary <primary-path>" >&2
+      exit 1
+    fi
+    STATUS="$(git -C "$HOLDER" status --porcelain)" \
+      || { echo "sync blocked at $HOLDER: cannot inspect working tree" >&2; exit 1; }
+    [ -z "$STATUS" ] \
+      || { echo "sync blocked at $HOLDER: working tree dirty; leave it for its owner" >&2; exit 1; }
+    for OPERATION in MERGE_HEAD CHERRY_PICK_HEAD REVERT_HEAD rebase-merge rebase-apply sequencer BISECT_START; do
+      OPERATION_PATH="$(git -C "$HOLDER" rev-parse --path-format=absolute --git-path "$OPERATION")"
+      [ ! -e "$OPERATION_PATH" ] \
+        || { echo "sync blocked at $HOLDER: unfinished Git operation: $OPERATION" >&2; exit 1; }
+    done
+  fi
+  if git show-ref --verify --quiet "refs/heads/$DEFAULT"; then
+    git merge-base --is-ancestor "$DEFAULT" "$REMOTE/$DEFAULT" \
+      || { echo "sync blocked: $DEFAULT cannot fast-forward to $REMOTE/$DEFAULT" >&2; exit 1; }
+  fi
+  echo "synchronization preflight passed: $DEFAULT (${HOLDER:-not checked out})"
+  exit 0
+fi
+
+FAIL=0
+
+if git merge-base --is-ancestor "$COMMIT" "$REMOTE/$DEFAULT" 2>/dev/null; then
+  echo "contained: $COMMIT in $REMOTE/$DEFAULT"
+else
+  echo "NOT CONTAINED: $COMMIT missing from $REMOTE/$DEFAULT" >&2
+  FAIL=1
+fi
+
+if git show-ref --verify --quiet "refs/heads/$DEFAULT"; then
+  LOCAL="$(git rev-parse "$DEFAULT")"
+  UPSTREAM="$(git rev-parse "$REMOTE/$DEFAULT")"
+  if [ "$LOCAL" = "$UPSTREAM" ]; then
+    echo "local $DEFAULT: current ($LOCAL)"
+  elif git merge-base --is-ancestor "$LOCAL" "$UPSTREAM" 2>/dev/null; then
+    BEHIND="$(git rev-list --count "$LOCAL..$UPSTREAM")"
+    if [ -z "${HOLDER:-}" ]; then
+      if [ "$FF" = 1 ] && [ "$FAIL" = 0 ]; then
+        git update-ref -m "verify-landed: fast-forward $DEFAULT" "refs/heads/$DEFAULT" "$UPSTREAM" "$LOCAL"
+        echo "local $DEFAULT: fast-forwarded $BEHIND commit(s) to $UPSTREAM (not checked out anywhere)"
+      else
+        echo "local $DEFAULT: $BEHIND behind, not checked out anywhere — safe: git fetch $REMOTE $DEFAULT:$DEFAULT"
+      fi
+    elif [ "$HOLDER" != "$HERE" ]; then
+      if [ "$FF" = 1 ] && [ "$FAIL" = 0 ] && [ "$HOLDER" = "$IDLE_PRIMARY" ]; then
+        [ "$(git -C "$HOLDER" symbolic-ref --quiet --short HEAD)" = "$DEFAULT" ] \
+          || { echo "primary checkout changed branches; refusing update" >&2; exit 1; }
+        git -C "$HOLDER" merge --quiet --ff-only "$UPSTREAM"
+        echo "local $DEFAULT: fast-forwarded $BEHIND commit(s) in confirmed idle primary $HOLDER"
+      else
+        echo "local $DEFAULT: $BEHIND behind, checked out at $HOLDER (not here) — leave for its owner; if you know it is idle: git -C $HOLDER merge --ff-only $UPSTREAM"
+        echo "If nothing is using that checkout, rerun verify-landed.sh with --ff --idle-primary <primary-path>." >&2
+      fi
+    elif [ -n "$(git status --porcelain)" ]; then
+      echo "local $DEFAULT: $BEHIND behind but working tree dirty — report, do not touch"
+    elif [ "$FF" = 1 ] && [ "$FAIL" = 0 ]; then
+      git merge --quiet --ff-only "$UPSTREAM"
+      echo "local $DEFAULT: fast-forwarded $BEHIND commit(s) to $UPSTREAM (checked out here)"
+    else
+      echo "local $DEFAULT: $BEHIND behind, clean, checked out here — safe to fast-forward"
+    fi
+  else
+    echo "local $DEFAULT: diverged from $REMOTE/$DEFAULT — report, do not touch"
+  fi
+  if [ "$(git rev-parse "$DEFAULT")" != "$(git rev-parse "$REMOTE/$DEFAULT")" ]; then
+    echo "LOCAL DEFAULT NOT CURRENT: $DEFAULT differs from $REMOTE/$DEFAULT; landing incomplete" >&2
+    FAIL=1
+  fi
+else
+  echo "local $DEFAULT: no local branch (nothing to update)"
+fi
+
+if [ -n "$BRANCH" ]; then
+  if ! REMOTE_REFS="$(git ls-remote --heads "$REMOTE" "$BRANCH" 2>/dev/null)"; then
+    echo "remote branch lookup failed: $REMOTE $BRANCH" >&2
+    FAIL=1
+  elif [ -n "$REMOTE_REFS" ]; then
+    echo "leftover branch: $REMOTE/$BRANCH still exists after merge" >&2
+    FAIL=1
+  else
+    echo "no leftover branch: $REMOTE/$BRANCH gone"
+  fi
+fi
+
+exit "$FAIL"

package/skills/hr-progress-report/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: hr-progress-report
+description: "Report the current task's activity, completion evidence and remaining wall-clock time. Use for task status, progress, completion percentage or ETA requests. Session-roster and liveness checks belong to the available coordination tools."
+---
+
+# Progress report
+
+Produce a dated snapshot of the requested task. A status request does not
+cancel authorized work or authorize new work. Resume work after the report
+under the governing continuation and offer rules.
+
+1. Identify the task's goal, selected scope and completion criteria. Read
+   the relevant plan and latest results. Name the records checked and any
+   missing coverage. Keep unrelated backlog items outside this task report.
+2. Verify current activity with available job state or recent results.
+   Distinguish working, waiting, blocked and idle. Say when activity cannot
+   be verified; a saved task description alone does not establish current work.
+3. Reconcile completed and remaining milestones against the completion
+   criteria. Include validation and landing when they belong to the selected
+   scope. List blockers and who or what can resolve each one.
+4. State the basis for a completion percentage. Use bounded work units or
+   milestone weights recorded before this report. Label a simple milestone
+   count as milestone completion, not a share of remaining time. During
+   open-ended investigation, report percentage unknown and the evidence gathered.
+   Explain scope changes that alter an earlier percentage. Report full
+   completion only when every selected completion criterion is satisfied.
+5. Show elapsed wall-clock time and remaining ETA under the governing
+   estimate policy. Without one, use comparable finished runs or observed
+   job progress and name the basis. Include tests, CI, review and fix rounds,
+   integration and dependency waits. Give a range and confidence when the
+   evidence supports them. Mark missing evidence or unbounded external waits
+   unknown or unmeasured. Give a running job's finish forecast separately
+   from the whole-task ETA. Include the timezone for clock-time forecasts.
+6. Lead with the task's state and current action, followed by a compact
+   table. Separate verified facts, session estimates and unknowns. End with
+   the next action or required decision using the governing offer format.
+
+| Field                  | Report                                                       |
+| ---------------------- | ------------------------------------------------------------ |
+| Task / state           | Goal, selected scope; working, waiting, blocked or idle      |
+| Current action         | Action and supporting job state or recent result             |
+| Progress               | Completed milestones, percentage basis or unknown            |
+| Remaining              | Unfinished milestones, including checks and integration      |
+| Elapsed / ETA          | Wall-clock time, evidence, confidence and waiting conditions |
+| Blockers / next action | Dependency, owner or decision needed                         |
+
+This is a snapshot, not independent proof of another session's activity.
+Use existing tools and records. Do not start watchers, ping other sessions
+or change schedules merely to produce the report.

package/skills/hr-progress-report/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "HR: Progress report"
+  short_description: "Report task progress and remaining wall-clock time"
+policy:
+  allow_implicit_invocation: true

package/skills/hr-read-reddit/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: hr-read-reddit
+description: Read Reddit posts and comments from Reddit's public feeds (output can omit comments) and search subreddits, with links kept inline. Use whenever a task needs Reddit content or needs to collect links posted on Reddit; generic web fetch and reddit.com JSON are blocked for agents. Reddit's RSS support ends November 13, 2026; a partial search fallback remains.
+---
+
+# Read Reddit
+
+Reddit usually answers agent fetches of pages and `.json` with 403, and its
+mirrors are unreliable. Pullpush's archive answers agents with 429 and asks for a
+paid plan, so do not scrape it. The bundled script reads post and comment bodies
+returned by Reddit's public Atom feeds without a key. Feed output can omit
+comments; do not present it as an exhaustive thread.
+
+[Reddit's announcement](https://www.reddit.com/r/modnews/comments/1wubgvt/continuing_our_infrastructure_updates_whats/)
+says RSS support ends November 13, 2026. Until then, try the feeds below and
+report any retrieval failure. After the cutoff, use the partial search fallback
+below rather than assuming the feeds remain supported.
+
+Read feeds with:
+
+```bash
+bun scripts/reddit.ts thread <reddit or redd.it URL>... [--json]
+bun scripts/reddit.ts search <subreddit|all> "<query>" [--pages N] [--since 2026-06-01] [--sort new|relevance|top] [--json]
+```
+
+Run it from this skill's directory. Text output gives each post's title, URL,
+author, date and body, then each comment. Every link appears as
+`text (url)`, so `grep -o` can harvest links. `--json` prints one object per
+entry (`id`, `kind`, `author`, `published`, `title`, `url`, `text`) for scripted
+collection. Search pages hold 100 results. With `--sort new`, `--since` stops
+paging at the first older result.
+
+Limits to state when they matter:
+
+1. Unauthenticated feeds allow about one request per minute. The script waits
+   out Reddit's `x-ratelimit-reset` between requests and retries a 429 twice,
+   so run long searches in the background and keep `--pages` small.
+2. A thread feed is flat: comments come without reply nesting. Images and
+   videos appear only as links.
+3. Search covers what Reddit's own search indexes. A deleted, removed or
+   private thread fails with its HTTP status.
+
+If the feeds are blocked, fall back to the host's web search tool with
+`site:reddit.com`. Say that the results are partial snippets.

package/skills/hr-read-reddit/agents/openai.yaml

@@ -0,0 +1,2 @@
+interface:
+  display_name: "HR: Read Reddit"