added Slack functionality and template

Author: jcklpe

docs/runbook-weekly-summary.md

@@ -14,6 +14,8 @@ A short, human-readable summary of current org state:
 
 The draft is written to `snapshot/weekly-summary.md` so review and Slack posting use the same text. `snapshot/` is gitignored, so this file is temporary working output.
 
+For Slack posting, render that draft to `snapshot/weekly-summary.blocks.json` with Block Kit `rich_text_list` blocks so Slack shows real bullets instead of plain hyphen text.
+
 Use `docs/templates/weekly-summary-template.md` for the message shape. Final approved summaries are archived in `docs/weekly-review-archive/` so future summaries can reference recent context.
 
 Optionally posted to Slack. Always shown in the conversation first for review.
@@ -45,20 +47,22 @@ Always summarize from the fresh snapshot. The archive is useful context, not sou
 
 ### 3. Produce the summary draft
 
-Write the summary to `snapshot/weekly-summary.md`, following `docs/templates/weekly-summary-template.md`. Use Slack-friendly `mrkdwn`: short headings, manual bullets, and plain text. Avoid tables and avoid composing the Slack message inline in a shell command.
+Write the summary to `snapshot/weekly-summary.md`, following `docs/templates/weekly-summary-template.md`. This markdown file is the human-review draft, the input to the Block Kit renderer, and the plain-text fallback. Use Slack-friendly `mrkdwn`: short headings, `-` markers with line breaks for list structure, and plain text. Avoid tables and avoid composing the Slack message inline in a shell command. Do not use `*` as a bullet marker in this text fallback; in Slack `mrkdwn`, `*text*` means bold.
+
+For true Slack bullet rendering, render and post a Block Kit payload with `rich_text` / `rich_text_list` blocks. Incoming webhooks support `blocks`, and `tools/notify/post.sh` can send a rendered payload with `--payload`.
 
-When naming issues, link only the issue number and put the title in plain text after it:
+When naming issues, put the issue title first, then link only the issue number:
 
 ```text
-<https://github.com/open-austin/org/issues/123|#123> Issue title
+Issue title | <https://github.com/open-austin/org/issues/123|#123>
 ```
 
 Do not use full-title links or standard Markdown links such as `[Issue title](https://...)`; Slack renders incoming webhook text more predictably with angle-bracket links.
 
 The summary should cover:
 
 **Teams with active issues:**
-List each team that has open issues. Use one parent bullet per team and one indented child bullet per issue. Add assignment details inline only when useful, such as `(assigned: lianilychee)`. Omit `Assigned: none`.
+List each team that has open issues. Use one parent bullet per team and one indented child bullet per issue. Include assignment status on every issue because unowned work is useful signal: `(assigned: none)` or `(assigned: lianilychee)`.
 
 **Board state:**
 Org Kanban column counts. Put counts and issue lists on separate nested bullets so the Slack post does not become a dense paragraph. Flag anything that's been In Progress for a long time without update.
@@ -81,15 +85,35 @@ Show the contents of `snapshot/weekly-summary.md` in the conversation. Ask:
 
 ### 5. Post to Slack (if confirmed)
 
+Render the reviewed markdown draft into a Slack Block Kit payload:
+
+```bash
+tools/notify/render_weekly_summary_blocks.py snapshot/weekly-summary.md --output snapshot/weekly-summary.blocks.json
+```
+
+Preview the payload without posting:
+
+```bash
+tools/notify/post.sh SLACK_WEBHOOK_ORG --payload snapshot/weekly-summary.blocks.json --dry-run
+```
+
+Then post the payload after approval:
+
 ```bash
 set -a
 source .env
 set +a
-tools/notify/post.sh SLACK_WEBHOOK_ORG < snapshot/weekly-summary.md
+tools/notify/post.sh SLACK_WEBHOOK_ORG --payload snapshot/weekly-summary.blocks.json
 ```
 
 For a general all-org channel, use the appropriate webhook variable from `.env`.
 
+If Block Kit rendering fails, fall back to the plain-text message:
+
+```bash
+tools/notify/post.sh SLACK_WEBHOOK_ORG < snapshot/weekly-summary.md
+```
+
 If no Slack webhook is configured yet, just deliver the summary in the conversation.
 
 ### 6. Archive the final summary
@@ -124,6 +148,7 @@ This is manually triggered — no cron. Run it when the user asks. Once a week i
 
 - `tools/sync/run.sh` — sync command
 - `tools/notify/post.sh` — Slack post command
+- `tools/notify/render_weekly_summary_blocks.py` — renders weekly summary markdown to Slack Block Kit JSON
 - `docs/templates/weekly-summary-template.md` — weekly summary template
 - `docs/weekly-review-archive/` — final weekly summary archive
 - `AGENTS.md` — agent rules and write safety

docs/templates/weekly-summary-template.md

@@ -7,42 +7,42 @@ Use this template when drafting `snapshot/weekly-summary.md` for the weekly org
 
 *Active Issues by Team*
 - *Finance* ({count}):
-  - <https://github.com/open-austin/org/issues/{number}|#{number}> {Issue title}
-  - <https://github.com/open-austin/org/issues/{number}|#{number}> {Issue title} (assigned: {names})
+  - {Issue title} | <https://github.com/open-austin/org/issues/{number}|#{number}> (assigned: none)
+  - {Issue title} | <https://github.com/open-austin/org/issues/{number}|#{number}> (assigned: {names})
 - *Fundraising* ({count}):
-  - <https://github.com/open-austin/org/issues/{number}|#{number}> {Issue title} (assigned: {names})
-  - <https://github.com/open-austin/org/issues/{number}|#{number}> {Issue title}
+  - {Issue title} | <https://github.com/open-austin/org/issues/{number}|#{number}> (assigned: {names})
+  - {Issue title} | <https://github.com/open-austin/org/issues/{number}|#{number}> (assigned: none)
 - *Communications* ({count}):
-  - <https://github.com/open-austin/org/issues/{number}|#{number}> {Issue title}
+  - {Issue title} | <https://github.com/open-austin/org/issues/{number}|#{number}> (assigned: none)
 - *Engagement* ({count}):
-  - <https://github.com/open-austin/org/issues/{number}|#{number}> {Issue title} (assigned: {names})
+  - {Issue title} | <https://github.com/open-austin/org/issues/{number}|#{number}> (assigned: {names})
 - *Education* ({count}):
-  - <https://github.com/open-austin/org/issues/{number}|#{number}> {Issue title}
-  - <https://github.com/open-austin/org/issues/{number}|#{number}> {Issue title}
-  - <https://github.com/open-austin/org/issues/{number}|#{number}> {Issue title}
+  - {Issue title} | <https://github.com/open-austin/org/issues/{number}|#{number}> (assigned: none)
+  - {Issue title} | <https://github.com/open-austin/org/issues/{number}|#{number}> (assigned: none)
+  - {Issue title} | <https://github.com/open-austin/org/issues/{number}|#{number}> (assigned: none)
 - *Infrastructure* ({count}):
-  - <https://github.com/open-austin/org/issues/{number}|#{number}> {Issue title}
-  - <https://github.com/open-austin/org/issues/{number}|#{number}> {Issue title} (assigned: {names})
+  - {Issue title} | <https://github.com/open-austin/org/issues/{number}|#{number}> (assigned: none)
+  - {Issue title} | <https://github.com/open-austin/org/issues/{number}|#{number}> (assigned: {names})
 - *Community* ({count}):
-  - <https://github.com/open-austin/org/issues/{number}|#{number}> {Issue title}
+  - {Issue title} | <https://github.com/open-austin/org/issues/{number}|#{number}> (assigned: none)
 - *Board* ({count}):
-  - <https://github.com/open-austin/org/issues/{number}|#{number}> {Issue title}
-  - <https://github.com/open-austin/org/issues/{number}|#{number}> {Issue title} (assigned: {names})
+  - {Issue title} | <https://github.com/open-austin/org/issues/{number}|#{number}> (assigned: none)
+  - {Issue title} | <https://github.com/open-austin/org/issues/{number}|#{number}> (assigned: {names})
 
 *Board Health*
 - Org Kanban:
   - {done_count} Done
   - {in_progress_count} In Progress
   - {todo_count} To Do
 - In Progress:
-  - <https://github.com/open-austin/org/issues/{number}|#{number}> {Issue title} (assigned: {names}; stale {days}d)
-  - <https://github.com/open-austin/org/issues/{number}|#{number}> {Issue title} (assigned: {names}; stale {days}d)
+  - {Issue title} | <https://github.com/open-austin/org/issues/{number}|#{number}> (assigned: {names}; stale {days}d)
+  - {Issue title} | <https://github.com/open-austin/org/issues/{number}|#{number}> (assigned: {names}; stale {days}d)
 - Notable To Do:
-  - <https://github.com/open-austin/org/issues/{number}|#{number}> {Issue title}
-  - <https://github.com/open-austin/org/issues/{number}|#{number}> {Issue title}
+  - {Issue title} | <https://github.com/open-austin/org/issues/{number}|#{number}> (assigned: {names or none})
+  - {Issue title} | <https://github.com/open-austin/org/issues/{number}|#{number}> (assigned: {names or none})
 
 *Needs Attention*
-- <https://github.com/open-austin/org/issues/{number}|#{number}> {Issue title}: {why it matters or what decision is needed}.
+- {Issue title} | <https://github.com/open-austin/org/issues/{number}|#{number}>: {why it matters or what decision is needed}.
 - {Brief blocker/staleness note, only if it needs human attention.}
 
 *Summary*
@@ -51,12 +51,15 @@ Use this template when drafting `snapshot/weekly-summary.md` for the weekly org
 
 ## Style Rules
 
-- Use Slack `mrkdwn` links, not standard Markdown links: `<https://github.com/open-austin/org/issues/123|#123> Issue title`.
-- Link only the issue number. Keep the issue title as plain text after the link.
+- Use Slack `mrkdwn` links, not standard Markdown links: `Issue title | <https://github.com/open-austin/org/issues/123|#123>`.
+- Put the issue title first as plain text, then link only the issue number.
 - Omit teams with no active in-scope issues.
+- This markdown is both the human-review draft and the input format for `tools/notify/render_weekly_summary_blocks.py`. Use `-` markers and two-space indentation consistently so the renderer can create Block Kit `rich_text_list` blocks.
+- In the plain-text fallback path, `-` markers plus line breaks mimic lists. Do not use `*` as bullets because `*text*` is Slack bold formatting.
+- For true Slack bullet rendering, post the rendered Block Kit payload with `tools/notify/post.sh SLACK_WEBHOOK_ORG --payload snapshot/weekly-summary.blocks.json`.
 - Use nested bullets so each issue gets its own line. Do not pack multiple issue links into one semicolon-separated sentence.
-- Keep issue metadata short and inline: `(assigned: name)` or `(assigned: name; stale 123d)`.
-- Omit empty/default metadata such as `Priority: none` and `Assigned: none`.
+- Keep assignment status on each issue because unowned work is useful signal: `(assigned: none)`, `(assigned: name)`, or `(assigned: name; stale 123d)`.
+- Omit empty/default priority metadata such as `Priority: none`.
 - Do not include Open Roles or recruiting tickets unless the user explicitly asks for them.
 - Do not include internal repo TODOs or tooling status unless they directly affect the org-facing work being summarized.
 - Keep Slack formatting simple: bold section headers, bullets, no tables.

tools/notify/post.sh

@@ -5,29 +5,75 @@ set -euo pipefail
 # Usage:
 #   tools/notify/post.sh <webhook_env_var> <message>
 #   cat message.txt | tools/notify/post.sh <webhook_env_var>
+#   tools/notify/post.sh <webhook_env_var> --payload payload.json
+#   tools/notify/post.sh <webhook_env_var> --payload payload.json --dry-run
 #
 # Example:
 #   tools/notify/post.sh SLACK_WEBHOOK_ENGAGEMENT "Weekly summary text here"
 #   echo "Hello" | tools/notify/post.sh SLACK_WEBHOOK_ENGAGEMENT
+#   tools/notify/post.sh SLACK_WEBHOOK_ORG --payload snapshot/weekly-summary.blocks.json
 #
 # The webhook URL is read from the environment variable name you pass.
 # Load your .env first: source .env
 
 WEBHOOK_VAR="${1:-}"
 MESSAGE="${2:-}"
+PAYLOAD_FILE=""
+DRY_RUN=false
 
 if [ -z "$WEBHOOK_VAR" ]; then
   echo "Usage: tools/notify/post.sh <WEBHOOK_ENV_VAR> [message]" >&2
+  echo "       tools/notify/post.sh <WEBHOOK_ENV_VAR> --payload <payload.json>" >&2
+  echo "       Add --dry-run to print the payload without posting." >&2
   echo "  Or pipe message via stdin." >&2
   exit 1
 fi
 
-# Resolve the webhook URL from the env var name
-WEBHOOK_URL="${!WEBHOOK_VAR:-}"
-if [ -z "$WEBHOOK_URL" ]; then
-  echo "Error: environment variable '$WEBHOOK_VAR' is not set." >&2
-  echo "Did you source your .env file?" >&2
-  exit 1
+if [ "$MESSAGE" = "--dry-run" ]; then
+  DRY_RUN=true
+  MESSAGE="${3:-}"
+fi
+
+if [ "$MESSAGE" = "--payload" ]; then
+  PAYLOAD_FILE="${3:-}"
+  if [ -z "$PAYLOAD_FILE" ]; then
+    echo "Error: --payload requires a JSON payload file." >&2
+    exit 1
+  fi
+  if [ ! -f "$PAYLOAD_FILE" ]; then
+    echo "Error: payload file not found: $PAYLOAD_FILE" >&2
+    exit 1
+  fi
+  if [ "${4:-}" = "--dry-run" ]; then
+    DRY_RUN=true
+  fi
+fi
+
+if [ -n "$PAYLOAD_FILE" ]; then
+  jq -e 'type == "object" and (.text | type == "string")' "$PAYLOAD_FILE" >/dev/null
+
+  if [ "$DRY_RUN" = true ]; then
+    cat "$PAYLOAD_FILE"
+    echo "✓ Dry run: Slack payload rendered but not posted ($WEBHOOK_VAR)" >&2
+    exit 0
+  fi
+
+  # Resolve the webhook URL from the env var name
+  WEBHOOK_URL="${!WEBHOOK_VAR:-}"
+  if [ -z "$WEBHOOK_URL" ]; then
+    echo "Error: environment variable '$WEBHOOK_VAR' is not set." >&2
+    echo "Did you source your .env file?" >&2
+    exit 1
+  fi
+
+  curl -s -X POST "$WEBHOOK_URL" \
+    -H 'Content-type: application/json' \
+    --data-binary "@$PAYLOAD_FILE" \
+    --fail
+
+  echo "" >&2
+  echo "✓ Posted Slack payload ($WEBHOOK_VAR)" >&2
+  exit 0
 fi
 
 # Read message from arg or stdin
@@ -42,10 +88,25 @@ fi
 
 # Escape for JSON
 ESCAPED=$(echo "$MESSAGE" | jq -Rs .)
+PAYLOAD="{\"text\": $ESCAPED}"
+
+if [ "$DRY_RUN" = true ]; then
+  echo "$PAYLOAD" | jq .
+  echo "✓ Dry run: Slack text payload rendered but not posted ($WEBHOOK_VAR)" >&2
+  exit 0
+fi
+
+# Resolve the webhook URL from the env var name
+WEBHOOK_URL="${!WEBHOOK_VAR:-}"
+if [ -z "$WEBHOOK_URL" ]; then
+  echo "Error: environment variable '$WEBHOOK_VAR' is not set." >&2
+  echo "Did you source your .env file?" >&2
+  exit 1
+fi
 
 curl -s -X POST "$WEBHOOK_URL" \
   -H 'Content-type: application/json' \
-  --data "{\"text\": $ESCAPED}" \
+  --data "$PAYLOAD" \
   --fail
 
 echo "" >&2