@firatcand/roster 0.1.0 → 1.0.0

package/templates/scaffold/scripts/audit-repo.sh

@@ -0,0 +1,218 @@
+#!/usr/bin/env bash
+# audit-repo.sh — full workspace audit; runs agent audits and repo-level checks
+# Usage: bash scripts/audit-repo.sh
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+source "$ROOT/scripts/lib/functions.sh"
+
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+RUN_TIME=$(date +%Y-%m-%d-%H%M)
+LOG_DIR="$ROOT/chief-of-staff/logs/$(date +%Y-%m)"
+mkdir -p "$LOG_DIR"
+REPORT="$LOG_DIR/audit-repo-$RUN_TIME.md"
+
+REPO_FAILURES=()
+REPO_WARNINGS=()
+REPO_PASSED=()
+
+# === Repo-level checks ===
+
+# Universal .mcp.json
+if [ ! -f "$ROOT/.mcp.json" ]; then
+  REPO_WARNINGS+=("[.mcp.json] universal MCP config missing")
+elif command -v python3 >/dev/null 2>&1; then
+  if ! python3 -c "import json; json.load(open('$ROOT/.mcp.json'))" 2>/dev/null; then
+    REPO_FAILURES+=("[.mcp.json] invalid JSON")
+  else
+    REPO_PASSED+=("[.mcp.json] valid")
+  fi
+fi
+
+# Universal .claude/settings.json
+if [ ! -f "$ROOT/.claude/settings.json" ]; then
+  REPO_WARNINGS+=("[.claude/settings.json] universal settings missing")
+elif command -v python3 >/dev/null 2>&1; then
+  if ! python3 -c "import json; json.load(open('$ROOT/.claude/settings.json'))" 2>/dev/null; then
+    REPO_FAILURES+=("[.claude/settings.json] invalid JSON")
+  else
+    REPO_PASSED+=("[.claude/settings.json] valid")
+  fi
+fi
+
+# Required root files
+for f in CLAUDE.md conventions.md README.md; do
+  if [ ! -f "$ROOT/$f" ]; then
+    REPO_FAILURES+=("[$f] missing at repo root")
+  else
+    REPO_PASSED+=("[$f] present")
+  fi
+done
+
+# config/project.yaml — workspace identity (v1 shape)
+if [ ! -f "$ROOT/config/project.yaml" ]; then
+  REPO_FAILURES+=("[config/project.yaml] missing — workspace identity required")
+elif command -v python3 >/dev/null 2>&1; then
+  if ! python3 -c "import yaml; yaml.safe_load(open('$ROOT/config/project.yaml'))" 2>/dev/null; then
+    REPO_FAILURES+=("[config/project.yaml] YAML parse error")
+  else
+    REPO_PASSED+=("[config/project.yaml] valid")
+  fi
+fi
+
+# guidelines/ — cross-agent substrate
+if [ ! -d "$ROOT/guidelines" ]; then
+  REPO_FAILURES+=("[guidelines/] missing — workspace substrate dir required")
+else
+  REPO_PASSED+=("[guidelines/] present")
+  for f in voice.md messaging.md brand-book.md asset-links.md; do
+    if [ ! -f "$ROOT/guidelines/$f" ]; then
+      REPO_WARNINGS+=("[guidelines/$f] missing — required substrate file")
+    fi
+  done
+  if [ ! -d "$ROOT/guidelines/icps" ] || [ -z "$(find "$ROOT/guidelines/icps" -maxdepth 1 -name '*.md' -type f 2>/dev/null | head -1)" ]; then
+    REPO_WARNINGS+=("[guidelines/icps/] empty or missing — at least one persona file required")
+  fi
+fi
+
+# Build a regex of registered functions for matching grandparent dirs.
+REGISTERED_FNS_PIPE=$(read_functions 2>/dev/null | tr '\n' '|' | sed 's/|$//')
+
+# Registered function should have a folder
+while IFS= read -r fn; do
+  [ -z "$fn" ] && continue
+  if [ ! -d "$ROOT/$fn" ]; then
+    REPO_FAILURES+=("[$fn] registered in .config/functions.yaml but folder does not exist")
+    REPO_FAILURES+=("  → Suggested fix: mkdir $fn && cp <stub README>, OR remove from .config/functions.yaml")
+  fi
+done < <(read_functions 2>/dev/null || true)
+
+# has_expert: true → EXPERT.md must exist
+while IFS=$'\t' read -r slug has_expert; do
+  [ -z "$slug" ] && continue
+  if [ "$has_expert" = "true" ] && [ ! -f "$ROOT/$slug/EXPERT.md" ]; then
+    REPO_WARNINGS+=("[$slug/EXPERT.md] registry says has_expert=true but file missing")
+  fi
+done < <(read_functions_with_metadata 2>/dev/null || true)
+
+# HITL channel env vars: every function should have SLACK_HITL_CHANNEL_<FN> in .env.example
+ENV_EXAMPLE="$ROOT/.env.example"
+if [ -f "$ENV_EXAMPLE" ]; then
+  while IFS= read -r fn; do
+    [ -z "$fn" ] && continue
+    var="SLACK_HITL_CHANNEL_$(echo "$fn" | tr '[:lower:]-' '[:upper:]_')"
+    if ! grep -q "^${var}=" "$ENV_EXAMPLE"; then
+      REPO_WARNINGS+=("[.env.example] missing $var (function '$fn' has no HITL channel env var)")
+    fi
+  done < <(read_functions 2>/dev/null || true)
+  if ! grep -q "^SLACK_HITL_CHANNEL_ADMIN=" "$ENV_EXAMPLE"; then
+    REPO_WARNINGS+=("[.env.example] missing SLACK_HITL_CHANNEL_ADMIN (used by dreamer + chief-of-staff)")
+  fi
+fi
+
+# Function-shaped top-level dirs not in the registry
+KNOWN_NON_FUNCTIONS="dreamer chief-of-staff scripts logs _archive"
+for dir in "$ROOT"/*/; do
+  basename=$(basename "$dir")
+  [[ "$basename" == .* ]] && continue
+  echo "$KNOWN_NON_FUNCTIONS" | grep -qw "$basename" && continue
+  if [ -n "$REGISTERED_FNS_PIPE" ] && echo "$basename" | grep -qE "^($REGISTERED_FNS_PIPE)\$"; then
+    continue
+  fi
+  if find "$dir" -maxdepth 2 -name 'agent.md' -type f 2>/dev/null | head -1 | grep -q .; then
+    REPO_WARNINGS+=("[$basename/] looks function-shaped but not registered in .config/functions.yaml")
+    REPO_WARNINGS+=("  → Suggested fix: add to registry via 'bash scripts/create-function.sh $basename' (or remove if intended)")
+  fi
+done
+
+# === Run audit-agent for each agent ===
+AGENTS=()
+while IFS= read -r fn; do
+  [ -z "$fn" ] && continue
+  if [ -d "$ROOT/$fn" ]; then
+    while IFS= read -r path; do
+      AGENTS+=("$fn:$(basename "$path")")
+    done < <(find "$ROOT/$fn" -maxdepth 1 -mindepth 1 -type d 2>/dev/null || true)
+  fi
+done < <(read_functions 2>/dev/null || true)
+
+AGENT_RESULTS=()
+for entry in "${AGENTS[@]:-}"; do
+  FN="${entry%%:*}"
+  AGENT="${entry##*:}"
+  RESULT=$(bash "$ROOT/scripts/audit-agent.sh" "$FN" "$AGENT" 2>&1 | head -5 || echo "  (audit failed)")
+  AGENT_RESULTS+=("### $FN/$AGENT")
+  AGENT_RESULTS+=("\`\`\`")
+  while IFS= read -r line; do
+    AGENT_RESULTS+=("$line")
+  done <<< "$RESULT"
+  AGENT_RESULTS+=("\`\`\`")
+  AGENT_RESULTS+=("")
+done
+
+# === Status ===
+if [ ${#REPO_FAILURES[@]} -gt 0 ]; then
+  STATUS="fail"
+elif [ ${#REPO_WARNINGS[@]} -gt 0 ]; then
+  STATUS="warn"
+else
+  STATUS="pass"
+fi
+
+# Write report
+{
+  echo "---"
+  echo "operation: audit-repo"
+  echo "ran: $TIMESTAMP"
+  echo "status: $STATUS"
+  echo "---"
+  echo ""
+  echo "# Repo Audit"
+  echo ""
+  echo "## Summary"
+  echo "- Agents audited: ${#AGENTS[@]}"
+  echo "- Repo-level passed: ${#REPO_PASSED[@]}"
+  echo "- Repo-level warnings: ${#REPO_WARNINGS[@]}"
+  echo "- Repo-level failures: ${#REPO_FAILURES[@]}"
+  echo ""
+  if [ ${#REPO_FAILURES[@]} -gt 0 ]; then
+    echo "## Repo-level Failures"
+    for line in "${REPO_FAILURES[@]}"; do
+      echo "- $line"
+    done
+    echo ""
+  fi
+  if [ ${#REPO_WARNINGS[@]} -gt 0 ]; then
+    echo "## Repo-level Warnings"
+    for line in "${REPO_WARNINGS[@]}"; do
+      echo "- $line"
+    done
+    echo ""
+  fi
+  if [ ${#REPO_PASSED[@]} -gt 0 ]; then
+    echo "## Repo-level Passed"
+    for line in "${REPO_PASSED[@]}"; do
+      echo "- $line"
+    done
+    echo ""
+  fi
+  echo "## Agent audits (summaries)"
+  echo ""
+  for line in "${AGENT_RESULTS[@]:-}"; do
+    echo "$line"
+  done
+  echo ""
+  echo "Individual audit reports are in $LOG_DIR/"
+} > "$REPORT"
+
+# Print summary
+echo "Repo audit: $STATUS"
+echo "  Agents: ${#AGENTS[@]}"
+echo "  Repo-level: ${#REPO_PASSED[@]} passed, ${#REPO_WARNINGS[@]} warnings, ${#REPO_FAILURES[@]} failures"
+[ ${#REPO_FAILURES[@]} -gt 0 ] && {
+  echo "Repo failures:"
+  for line in "${REPO_FAILURES[@]}"; do echo "  $line"; done
+}
+echo "Full report: $REPORT"

package/templates/scaffold/scripts/create-function.sh

@@ -0,0 +1,267 @@
+#!/usr/bin/env bash
+# create-function.sh — register a new function category and scaffold its folder
+# Usage: bash scripts/create-function.sh <slug> [--description "..."] [--with-expert] [--no-confirm]
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+CONFIG="$ROOT/.config/functions.yaml"
+
+source "$ROOT/scripts/lib/functions.sh"
+
+usage() {
+  cat <<EOF
+Usage: $0 <slug> [--description "..."] [--with-expert] [--no-confirm]
+
+  <slug>           required, lowercase kebab-case, ^[a-z][a-z0-9-]*\$
+  --description    one-line description (prompted if omitted in TTY)
+  --with-expert    scaffold EXPERT.md stub and set has_expert: true
+  --no-confirm     skip the interactive proliferation prompt
+
+Environment:
+  AGENT_TEAM_NO_CONFIRM=1   equivalent to --no-confirm
+EOF
+}
+
+if [ $# -lt 1 ]; then
+  usage >&2
+  exit 1
+fi
+
+SLUG=""
+DESCRIPTION=""
+WITH_EXPERT=""        # "" | "true" | "false"; "" means unresolved (will prompt)
+DESC_PROVIDED=0
+NO_CONFIRM=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --description)
+      [ $# -lt 2 ] && { echo "ERROR: --description requires a value" >&2; exit 1; }
+      DESCRIPTION="$2"
+      DESC_PROVIDED=1
+      shift 2
+      ;;
+    --description=*)
+      DESCRIPTION="${1#--description=}"
+      DESC_PROVIDED=1
+      shift
+      ;;
+    --with-expert)
+      WITH_EXPERT="true"
+      shift
+      ;;
+    --no-confirm)
+      NO_CONFIRM=1
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    --*)
+      echo "ERROR: unknown flag '$1'" >&2
+      usage >&2
+      exit 1
+      ;;
+    *)
+      if [ -z "$SLUG" ]; then
+        SLUG="$1"
+        shift
+      else
+        echo "ERROR: unexpected positional arg '$1'" >&2
+        exit 1
+      fi
+      ;;
+  esac
+done
+
+if [ "${AGENT_TEAM_NO_CONFIRM:-0}" = "1" ]; then
+  NO_CONFIRM=1
+fi
+
+if [ -z "$SLUG" ]; then
+  echo "ERROR: <slug> is required" >&2
+  usage >&2
+  exit 1
+fi
+
+# 1. Validate slug format
+if ! [[ "$SLUG" =~ ^[a-z][a-z0-9-]*$ ]]; then
+  echo "ERROR: slug '$SLUG' is invalid. Must be lowercase, start with a letter, and only contain a-z, 0-9, and hyphens." >&2
+  exit 1
+fi
+
+# 2. Check config exists and is parseable
+if [ ! -f "$CONFIG" ]; then
+  echo "ERROR: $CONFIG not found or unreadable" >&2
+  exit 1
+fi
+if ! read_functions >/dev/null 2>&1; then
+  echo "ERROR: failed to read $CONFIG (malformed YAML or unreadable)" >&2
+  read_functions >/dev/null  # re-run to surface stderr
+  exit 1
+fi
+
+# 3. Check slug not already in registry
+if is_valid_function "$SLUG"; then
+  echo "ERROR: function '$SLUG' is already registered in $CONFIG" >&2
+  exit 1
+fi
+
+# 4. Check folder doesn't exist
+TARGET="$ROOT/$SLUG"
+if [ -e "$TARGET" ]; then
+  echo "ERROR: '$TARGET' already exists on disk" >&2
+  exit 1
+fi
+
+# 5. Resolve description
+is_tty() { [ -t 0 ] && [ -t 1 ]; }
+
+if [ $DESC_PROVIDED -eq 0 ]; then
+  if is_tty; then
+    printf "Description (one line, e.g. 'Research — discovery, market analysis'): " >&2
+    IFS= read -r DESCRIPTION
+  fi
+  if [ -z "$DESCRIPTION" ]; then
+    echo "ERROR: --description not provided and not running interactively" >&2
+    exit 1
+  fi
+fi
+
+# Strip trailing whitespace
+DESCRIPTION="${DESCRIPTION%"${DESCRIPTION##*[![:space:]]}"}"
+if [ -z "$DESCRIPTION" ]; then
+  echo "ERROR: description is empty" >&2
+  exit 1
+fi
+
+# 6. Resolve has_expert
+if [ -z "$WITH_EXPERT" ]; then
+  if is_tty; then
+    printf "Does this function need an expert? (y/N): " >&2
+    IFS= read -r ANS
+    case "$ANS" in
+      y|Y|yes|YES) WITH_EXPERT="true" ;;
+      *) WITH_EXPERT="false" ;;
+    esac
+  else
+    WITH_EXPERT="false"
+  fi
+fi
+
+# 7. Soft proliferation reminder
+if [ "$NO_CONFIRM" -eq 0 ] && is_tty; then
+  cat >&2 <<EOF
+About to create function: $SLUG
+Reminder: function categories should map to how you mentally divide work.
+Will you have at least 2-3 agents in this function within ~90 days?
+If not, the agent likely fits an existing function. Press Ctrl-C to abort,
+or any key to proceed.
+EOF
+  read -r -n 1 _ || true
+  echo "" >&2
+fi
+
+# === Mutations begin here ===
+# Track what we created so we can roll back on failure.
+CREATED_PATHS=()
+CONFIG_BACKUP="$(mktemp -t functions-yaml-backup.XXXXXX)" || {
+  echo "ERROR: could not create backup tempfile" >&2
+  exit 1
+}
+cp "$CONFIG" "$CONFIG_BACKUP"
+
+rollback() {
+  echo "Rolling back partial changes..." >&2
+  for p in "${CREATED_PATHS[@]:-}"; do
+    [ -e "$p" ] && rm -rf "$p"
+  done
+  cp "$CONFIG_BACKUP" "$CONFIG"
+}
+trap 'rollback; rm -f "$CONFIG_BACKUP"' ERR
+
+# 8. Append entry to YAML
+{
+  printf '  - slug: %s\n' "$SLUG"
+  printf '    description: %s\n' "$DESCRIPTION"
+  printf '    has_expert: %s\n' "$WITH_EXPERT"
+} >> "$CONFIG"
+
+# 9. Create folder
+mkdir -p "$TARGET"
+CREATED_PATHS+=("$TARGET")
+
+# 10. Stub README.md
+README_PATH="$TARGET/README.md"
+{
+  printf '# Global %s agents\n\n' "$SLUG"
+  printf '%s\n\n' "$DESCRIPTION"
+  printf 'No agents yet. Add via:\n\n'
+  printf '```bash\n'
+  printf 'bash scripts/new-agent.sh %s <agent-name>\n' "$SLUG"
+  printf '```\n\n'
+  printf "When you add the first agent here, see \`gtm/sdr/\` as the canonical example of an agent's directory layout.\n"
+} > "$README_PATH"
+
+# 11. Optional EXPERT.md stub
+if [ "$WITH_EXPERT" = "true" ]; then
+  EXPERT_PATH="$TARGET/EXPERT.md"
+  cat > "$EXPERT_PATH" <<EOF
+# $SLUG Expert
+
+<!--
+This is a stub. Fill in the expert system prompt for this function.
+
+Experts shape SUBSTRATE (project guidelines), not artifacts. They critique
+and generate guideline files in \`guidelines/\` at the workspace root.
+
+Required sections (see other EXPERT.md files for examples once they exist):
+- Identity (1 paragraph)
+- Scope (guide / critique / generate guidelines)
+- Skill routing (table)
+- Practitioner panel (optional, only if it adds value)
+- Read-first protocol
+- Output rules (what writes where, what doesn't)
+- Stage filter (early-stage constraints)
+
+Keep it concise. Lean on skills rather than restating their content here.
+-->
+
+# Stub: replace with the function's expert system prompt.
+EOF
+fi
+
+# 12. Append to operation log
+LOG_DIR="$ROOT/chief-of-staff/logs/$(date +%Y-%m)"
+mkdir -p "$LOG_DIR"
+LOG_FILE="$LOG_DIR/operations-$(date +%Y-%m-%d).md"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+{
+  echo ""
+  echo "## $TIMESTAMP — create-function: $SLUG"
+  echo "Description: $DESCRIPTION"
+  echo "has_expert: $WITH_EXPERT"
+} >> "$LOG_FILE"
+
+# Success — disarm rollback trap
+trap - ERR
+rm -f "$CONFIG_BACKUP"
+
+echo ""
+echo "✓ Function '$SLUG' created."
+echo "  Folder:      $TARGET/"
+echo "  README:      $README_PATH"
+[ "$WITH_EXPERT" = "true" ] && echo "  EXPERT.md:   $TARGET/EXPERT.md (stub)"
+echo "  Registry:    $CONFIG (entry appended)"
+echo "  Log:         $LOG_FILE"
+echo ""
+SLUG_ENV=$(echo "$SLUG" | tr '[:lower:]-' '[:upper:]_')
+
+echo "Reminders for the new function:"
+echo "  1. HITL routing — agents in this function will route to #${SLUG}"
+echo "     - Create the Slack channel #${SLUG}"
+echo "     - Add to .env: SLACK_HITL_CHANNEL_${SLUG_ENV}=#${SLUG}"
+[ "$WITH_EXPERT" = "true" ] && echo "  2. Fill in $TARGET/EXPERT.md with the expert system prompt"
+echo "  $([ "$WITH_EXPERT" = "true" ] && echo 3 || echo 2). Add the first agent: bash scripts/new-agent.sh $SLUG <agent-name>"

package/templates/scaffold/scripts/lib/README.md

@@ -1,12 +1,17 @@
 # Shared script libraries
 
-Helper functions for use across scripts. Empty for now — add as scripts grow.
+Helper functions for use across scripts.
 
 Conventions:
 - Bash: `<n>.sh`, sourced via `source "$(dirname $0)/lib/<n>.sh"`
 - Python: `<n>.py` if needed (use `pip install --break-system-packages`)
 - Keep functions narrow
 
+## Current inhabitants
+
+- `functions.sh` — read/validate the function registry at `.config/functions.yaml`. Pure bash + falls back to `python3` + `pyyaml` when available for safer YAML parsing.
+- `bindings-prompt.sh` — **disabled in v1.0**. Phase 2 will rebuild this around the env-merge loader (config.yaml `tools:` metadata + `/.env` values). Until then, invocation aborts with manual-configuration instructions (edit agent.md `## Tools and bindings` → mirror the YAML block into `<agent>/config.yaml` → add env-var values to `/.env`). The file remains in the tarball + executable so smoke continues to assert presence; the runtime behavior is the guard message.
+
 Example future additions:
 - `lib/lesson.sh` — read/write lesson files, validate schema
 - `lib/run.sh` — append to run files, format frontmatter

package/templates/scaffold/scripts/lib/bindings-prompt.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# bindings-prompt.sh — DISABLED in v1.0 (ROS-78).
+#
+# Pre-v1.0 behavior: read `## Tools and bindings` from agent.md (legacy
+# two-level `tool: key: {required, description}` schema), prompt the user
+# for binding values, and append a `tools:` block to a project-instance
+# config at `projects/<inst>/config/default.yaml`.
+#
+# Both inputs change in v1.0:
+#   1. The shipped `## Tools and bindings` block in agent.md is now a flat
+#      schema (`tool: { env_var, required, description }` per
+#      conventions.md). The legacy parser silently emits an empty
+#      `tools.<tool>:` block when it encounters scalar values where it
+#      expects a mapping.
+#   2. The instance-config target is gone — agent config lives at
+#      `<function>/<agent>/config.yaml`, and env-var values belong in
+#      workspace `/.env` (overridable in `<agent>/.env`).
+#
+# The proper v1.0 flow (read agent.md flat schema → write metadata to
+# config.yaml `tools:` block → prompt for required env-var values and
+# append to `/.env`) requires the env-merge loader that ships in Phase 2.
+# Rather than ship a script whose advertised behavior is broken against
+# the new schema, this script aborts with manual-configuration instructions
+# (edit agent.md schema → mirror to config.yaml → fill /.env).
+#
+# Tracking: re-enable as part of the Phase 2 cli-plumbing reshape
+# (env-merge loader + doctor checks 13-15).
+
+set -euo pipefail
+
+cat >&2 <<'MSG'
+bindings-prompt.sh is disabled in Roster v1.0.
+
+The legacy two-level schema parser this script uses is incompatible with
+the flat ## Tools and bindings schema documented in conventions.md
+("Tool bindings" section). The Phase 2 reshape (env-merge loader +
+config.yaml/.env split) will rebuild this flow.
+
+Until Phase 2 lands, configure tool bindings by hand:
+
+  1. Open <function>/<agent>/agent.md and confirm the ## Tools and
+     bindings YAML block lists each tool with env_var, required, and
+     description fields (see conventions.md § "Tool bindings").
+  2. Mirror that block as the tools: mapping in
+     <function>/<agent>/config.yaml.
+  3. Add the corresponding env var values to workspace /.env (or, for
+     agent-scoped overrides, <function>/<agent>/.env).
+
+(The chief-of-staff guided create-agent flow shipped in v0.4 is also on
+the pre-v1 shape; it will be updated alongside the env-merge loader.)
+MSG
+
+exit 2

package/templates/scaffold/scripts/lib/functions.sh

@@ -20,7 +20,8 @@ read_functions() {
   fi
   if _have_pyyaml; then
     python3 -c "
-import yaml, sys
+import yaml, re, sys
+SLUG_RE = re.compile(r'^[a-z][a-z0-9-]*\$')
 try:
     with open('$config') as f:
         data = yaml.safe_load(f) or {}
@@ -29,12 +30,23 @@ except yaml.YAMLError as e:
     sys.exit(1)
 for fn in data.get('functions', []):
     slug = fn.get('slug', '')
-    if slug:
-        print(slug)
+    if not slug:
+        continue
+    if not SLUG_RE.match(slug):
+        sys.stderr.write(\"ERROR: malformed slug '\" + slug + \"' in $config — must match ^[a-z][a-z0-9-]*\$\n\")
+        sys.exit(1)
+    print(slug)
 " || return 1
   else
-    grep -E '^[[:space:]]*-[[:space:]]*slug:[[:space:]]*' "$config" \
-      | sed -E 's/^[[:space:]]*-[[:space:]]*slug:[[:space:]]*//; s/[[:space:]]*$//'
+    local slug
+    while IFS= read -r slug; do
+      if ! [[ "$slug" =~ ^[a-z][a-z0-9-]*$ ]]; then
+        echo "ERROR: malformed slug '$slug' in $config — must match ^[a-z][a-z0-9-]*\$" >&2
+        return 1
+      fi
+      printf '%s\n' "$slug"
+    done < <(grep -E '^[[:space:]]*-[[:space:]]*slug:[[:space:]]*' "$config" \
+      | sed -E 's/^[[:space:]]*-[[:space:]]*slug:[[:space:]]*//; s/[[:space:]]*$//')
   fi
 }