@golden-frijoles/kit 0.7.0 → 0.9.0

package/dist/routines/weekly-recap.prompt.md

@@ -0,0 +1,95 @@
+<!--
+  weekly-recap.prompt.md — Routine weekly-recap (the weekly Telegram exec recap/retro), the Claude-
+  Routines prompt.
+
+  This is the prompt for a WEEKLY Claude Code *Routine* (cloud session, research preview) on the
+  monorepo-root repo (<root-repo>), running as the product owner — the longer-horizon complement to
+  the nightly `ops-nightly` standup. Added by Sprint 3 of the ops-routines-reporting epic. Mirrors
+  ops-nightly's shape (a load-bearing Telegram post is the routine's actual output, not an optional
+  failure-ping) but on a weekly cadence, and mirrors Routine C's precedent (a dedicated weekly routine,
+  not a day-of-week-gated step folded into a nightly one).
+
+  Reuse, don't rebuild (the `weekly-recap` skill comes from the `golden-frijoles` plugin, golden-frijoles
+  marketplace — invoke by name, not a repo-local
+  `skills/<name>/SKILL.md` path, which no longer exists in this repo):
+    - `weekly-recap` skill → scripts/weekly-recap.mjs (the gathering, message-building, and the
+      actual Telegram send + weekly-recaps.log commit — this routine just invokes it and reports back)
+    - gh CLI (every configured repo), git log -p on epic READMEs (status: SSOT), the same configured repo list
+      scripts/standup.mjs already uses.
+
+  Stand-up + guardrails: scripts/routines/README.md. Decision: made in the origin project — see this directory's README preamble. (skill conventions) and 09-platform-infra/ops-routines-reporting/
+  sprint-3.md (this story's scope).
+
+  The HTML comment above is not part of the prompt; a routine runs everything below the first `---`.
+-->
+
+---
+
+You are a weekly **weekly-recap** Claude Code Routine on the root repo (`<root-repo>`),
+running as the product owner. Your job is one step, then stop: post the week's executive recap to Telegram.
+Everything you do is **advisory/observability only** — read-only aggregation plus one Telegram post and
+one log-commit; you never merge, approve, block, or touch any repo's code.
+
+## The one step — `weekly-recap`, written by YOU in three phases
+
+The recap is no longer a tally: **you write it, as the CPO persona, and a mechanical guard checks
+your draft before it posts.** Same rail as the nightly standup, one altitude higher.
+
+**You must write the prose yourself, in this session. Do NOT call `devin`, `agy`, `codex`, or
+`prose-draft.mjs`** — none of them is authenticated here, and reaching for one produces no report at
+all rather than an obvious failure. This is the single most important line in this file.
+
+Config/secrets first: the committed `reporting.config.json` (repos and signals) plus the chat id — from the
+`TELEGRAM_CHAT_ID` env var in this unattended session (a gitignored `reporting.config.local.json` exists
+only on a local machine, never here). If `TELEGRAM_CHAT_ID` is unset (and nothing is configured), that's a
+hard stop — use the failure ping below; never `AskUserQuestion`, no interactive human is present.
+`TELEGRAM_BOT_TOKEN` must be set.
+
+**Phase 1 — get the brief.**
+```
+node scripts/weekly-recap.mjs --brief
+```
+It prints your persona, the accumulated lessons, and the week's evidence — **shipped and closed epics
+first, with excerpts from their retrospectives**, then merged-PR volume as corroboration. It writes
+nothing and sends nothing. **If it returns the "Nothing to report" brief**, do NOT write prose — run
+`node scripts/weekly-recap.mjs --post --quiet` instead. It posts the one-line quiet-week message
+**and advances the window log**; stopping without it leaves `windowEnd` unmoved and the next run
+double-counts. Do not manufacture content.
+
+**Phase 2 — write the prose.** Answer one question: *what is now possible that was not possible on
+Monday, and what is still owed?* Group by **theme**, never by commit or by repository — a list of
+merges is not a report, and the word budget is not permission to enumerate. Name the decision that
+shaped the week if there was one. State what is owed; a weekly that quietly omits a known gap is the
+one unforgivable error here. Save your draft to a temp file.
+
+**Phase 3 — guard, then post.**
+```
+node scripts/weekly-recap.mjs --post --prose-file <your-file>
+```
+- **Exit 0** → posted.
+- **Non-zero exit** → it prints a numbered revision note. Rewrite the draft in full against every
+  point, then re-run once with `--force-post`. A flagged-but-posted report beats a missing one, and
+  the label tells a human it did not converge.
+- One revision, then post. Do not loop further.
+
+Report the result afterwards (merged-PR / shipped-epic counts, whether the guard passed clean).
+
+## Nothing else
+No PR, no comment, no code change of your own — the Telegram post (plus the `scripts/weekly-recaps.log`
+commit `weekly-recap.mjs` makes itself) is the routine's entire output. **Advisory only** — not a gate,
+not a merge, not a status check. If the week was genuinely quiet (nothing merged, nothing shipped),
+that's still a fully successful run — the script itself collapses to a one-line "quiet week" message; do
+not manufacture extra content to pad it out.
+
+## If the run can't complete (optional failure ping)
+A healthy run reaches the product owner via the recap's Telegram post — no extra notice needed. But a run that
+**fails to complete** (missing `TELEGRAM_BOT_TOKEN`, missing/unconfigured chat id, `gh` unauthenticated,
+the script erroring out, the log push failing) would otherwise be silent. So, **only on a blocking
+failure**, if **both** `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` are set in the environment,
+best-effort POST a one-line alert:
+`curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage" -d chat_id="$TELEGRAM_CHAT_ID" --data-urlencode text="⚠️ Routine weekly-recap failed: <one-line reason>"`
+If either var is unset (or `api.telegram.org` isn't allow-listed), skip it silently — never block on it,
+and **never** ping after a run that completed successfully, even a fully quiet one.
+
+Note: `TELEGRAM_CHAT_ID` here is both the failure-ping target and what `weekly-recap.mjs` posts the recap
+to — one variable, both call sites.

package/dist/slack-notify.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+// slack-notify.mjs — the CI/CD Slack ping, structured the same way as scripts/telegram-notify.mjs.
+//
+// Used by .github/workflows/notify-telegram.yml's push-notification and deploy-notification jobs,
+// alongside (not instead of) the existing Telegram calls:
+//   node scripts/slack-notify.mjs --icon 📦 --sha "$GITHUB_SHA" --subject "$COMMIT_MSG" \
+//        --meta "by @$AUTHOR" --url "$DIFF_URL" --link-label "view diff"
+//
+// ── Why Incoming Webhook and not a bot token + chat.postMessage ────────────────────────────────
+// Same reasoning this repo already applied to Telegram (no VERCEL_API_TOKEN when a push-based
+// signal existed instead — see notify-telegram.yml's header): one fewer credential to mint, store
+// and rotate. An Incoming Webhook URL is itself the channel-scoped credential — there is no
+// separate bot token, channel ID, or OAuth scope to manage for this feature. If a future need
+// requires posting to a channel chosen at runtime (rather than the one fixed at webhook-creation
+// time), that is the point to move to `chat.postMessage` with a bot token — not before.
+//
+// ── Response handling is NOT the same shape as Telegram's — this is the one real gotcha ───────
+// Telegram's sendMessage returns JSON ({ok: bool, ...}) regardless of outcome. Slack's Incoming
+// Webhook endpoint does NOT: on success it returns the literal string "ok" (200, `text/plain`); on
+// failure it returns a short plain-text error token (e.g. "invalid_payload", "channel_not_found",
+// "no_service") with a non-200 status. Parsing the body as JSON here would throw on every single
+// call, success or failure. So `send()` reads the body as text and treats HTTP status as the
+// primary success signal — see Slack's own webhook error-handling docs if this ever needs
+// re-verifying against a live change.
+//
+// ── Escaping is mrkdwn, not HTML, but the substitution table is identical ──────────────────────
+// See scripts/lib/slack-text.mjs's header for why escapeMrkdwn and Telegram's escapeHtml do the
+// same three replacements. Links use Slack's `<url|label>` syntax rather than `<a href>`; inline
+// code uses single backticks rather than `<code>`.
+//
+// House style carried over unchanged: secrets only from GitHub Secrets, a 10s request timeout, and
+// a repo with the secret unset gets a clean skip (not a failure) — see main() below.
+
+import { escapeMrkdwn, escapeToFit, SLACK_LIMIT } from './lib/slack-text.mjs';
+import { die, need } from './lib/cross-agent-cli.mjs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Assemble the Incoming Webhook payload.
+ *
+ * The subject is the only field given a length budget, same rule as Telegram's buildNotification:
+ * the sha, status, icon and link are structural, and truncating them to make room for a runaway
+ * commit message would discard exactly the parts a reader needs.
+ *
+ * Pure, and exported, so a test exercises the real assembler rather than a paraphrase of it.
+ */
+export function buildNotification({ repo, sha, icon, subject, meta, status, url, linkLabel }) {
+  const shortSha = String(sha ?? '').slice(0, 7);
+
+  // Chrome first, measured rather than estimated — same reasoning as Telegram's version: a
+  // hardcoded guess here is how a "safe" cap stops being safe once a line is added below.
+  const head = `${escapeMrkdwn(repo)} · ${icon} · \`${escapeMrkdwn(shortSha)}\``;
+  const tail = `<${escapeMrkdwn(url)}|${escapeMrkdwn(linkLabel)}>`;
+  const metaLine = meta ? escapeMrkdwn(meta) : null;
+  // `status` is our own literal ("✅ READY"), never external input — not escaped, same as Telegram's
+  // version, so the emoji and casing survive.
+  const statusLine = status || null;
+
+  const chrome = [head, metaLine, statusLine, tail].filter(Boolean).join('\n').length + 1;
+
+  // First line only: a commit body belongs behind the link, not in a notification.
+  const firstLine = String(subject ?? '').split('\n')[0];
+  const safeSubject = escapeToFit(firstLine, Math.max(1, SLACK_LIMIT - chrome - 16));
+
+  const lines = [head, safeSubject];
+  if (metaLine) lines.push(metaLine);
+  if (statusLine) lines.push(statusLine);
+  lines.push(tail);
+
+  return {
+    text: lines.join('\n'),
+    // Belt-and-suspenders alongside Telegram's disable_web_page_preview: without this a commit or
+    // deployment link can unfurl into a big preview card that buries the next message.
+    unfurl_links: false,
+    unfurl_media: false,
+  };
+}
+
+/**
+ * POST it. Returns { ok, status, body } — never throws.
+ *
+ * Slack's webhook response is PLAIN TEXT ("ok" on success, a short error token on failure), not
+ * JSON like Telegram's — see this file's header. An accepted webhook is the conjunction Slack
+ * documents: a 2xx response and the literal plain-text body `ok`.
+ */
+export async function send(webhookUrl, payload, fetchImpl = fetch) {
+  try {
+    const res = await fetchImpl(webhookUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(10_000),
+    });
+    const body = await res.text().catch(() => '');
+    return { ok: res.ok && body.trim() === 'ok', status: res.status, body };
+  } catch (err) {
+    return { ok: false, status: 0, body: `request failed: ${err?.message ?? err}` };
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const opt = {};
+  for (let i = 0; i < args.length; i++) {
+    const k = args[i];
+    if (!k.startsWith('--')) die(`unexpected argument ${k}`);
+    opt[k.slice(2)] = need(args[++i], k);
+  }
+
+  const webhookUrl = process.env.SLACK_WEBHOOK_URL?.trim();
+  if (!webhookUrl) {
+    // Same clean-skip stance as telegram-notify.mjs: a repo without the secret configured is a
+    // configuration state, not a failure.
+    process.stderr.write(
+      'SLACK_WEBHOOK_URL not set — skipping cleanly.\n' +
+        '  Set it as a GitHub Secret on this repo to turn Slack notifications on.\n'
+    );
+    return;
+  }
+
+  const payload = buildNotification({
+    repo: opt.repo ?? 'golden-beans',
+    sha: opt.sha ?? '',
+    icon: opt.icon ?? '📦',
+    subject: opt.subject ?? '',
+    meta: opt.meta ?? '',
+    status: opt.status ?? '',
+    url: opt.url ?? '',
+    linkLabel: opt['link-label'] ?? 'view',
+  });
+
+  if (payload.text.length > SLACK_LIMIT) {
+    // Should be unreachable — escapeToFit bounds the only unbounded field. Checked anyway, same
+    // stance as telegram-notify.mjs.
+    die(`assembled text is ${payload.text.length} chars, over the ${SLACK_LIMIT}-char budget`);
+  }
+
+  const result = await send(webhookUrl, payload);
+  if (result.ok) {
+    process.stderr.write(`✓ ping delivered (${payload.text.length} chars)\n`);
+    return;
+  }
+
+  // Loud, same policy as Telegram: an observer workflow with a rejected message and no visible
+  // failure is a rail with no monitoring at all.
+  process.stderr.write(
+    `::error title=Slack ping NOT delivered::status=${result.status} body=${result.body}\n`
+  );
+  process.exitCode = 1;
+}
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@golden-frijoles/kit",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "The scripts the Golden Frijoles skills run, packaged so they work in any repo: planning, build-order, reporting and verification rails. Zero dependencies.",
   "type": "module",
   "bin": {