@jenga-ai/agent 1.3.0 → 2.0.0

package/scripts/apply-j-prefix.sh

@@ -0,0 +1,230 @@
+#!/usr/bin/env bash
+# scripts/apply-j-prefix.sh — mechanical j: prefix rename for skill invocation
+#
+# Implements the mechanism decided in docs/skill-authoring.md's "Invocation Convention"
+# section (E50_S01_T01):
+#
+#   1. Frontmatter-only rename. For every skills/<name>/SKILL.md, rewrites the
+#      frontmatter `name:` field from `<name>` to `j:<name>`. Directory names are
+#      left untouched — ":" is not a Windows-safe filename character, and Claude
+#      Code's native skill resolution is a literal-string match against the
+#      discovery-path directory name, independent of frontmatter content (see the
+#      docs section for the full investigation and citation).
+#   2. Bare-form prose rewrite. For every agents/*.md file, rewrites bare
+#      "/<name>" invocation mentions in prose to "j:<name>", for every skill name
+#      discovered in step 1 — longest-name-first, boundary-safe (skill names
+#      contain hyphens, so a naive `\b` regex would misfire — e.g. it would
+#      falsely match "/doc" inside "/doc-sync"; this only rewrites a match when
+#      the character immediately before/after it is not itself an identifier
+#      character: letter, digit, "-", or ":").
+#
+# This script does NOT remove or disable the old bare "/<name>" form. The
+# migration decision recorded alongside the mechanism above is "alias" — both
+# forms keep resolving. This script only ever writes inside skills/ and
+# agents/; it never touches .claude/ or .agents/ (generated mirrors — see
+# CLAUDE.md's Source of Truth rule) and makes no other filesystem change.
+#
+# Usage:
+#   scripts/apply-j-prefix.sh [--dry-run] [--skills-only | --agents-only]
+#
+#   --dry-run       Print the full change list without writing anything.
+#                    Exit code is 0 whether or not changes were found (unless
+#                    --skills-only/--agents-only surface a hard error, e.g. a
+#                    frontmatter `name:` that doesn't match its directory).
+#   --skills-only   Only process skills/*/SKILL.md frontmatter (step 1).
+#   --agents-only   Only process agents/*.md prose (step 2).
+#
+# Idempotent: already-migrated skills (name already starts with "j:") are
+# silently skipped, not re-applied or reported as an error.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/resolve-project-dir.sh
+source "$SCRIPT_DIR/../lib/resolve-project-dir.sh"
+
+PROJECT_DIR="$JENGA_PROJECT_DIR"
+SKILLS_DIR="$PROJECT_DIR/skills"
+AGENTS_DIR="$PROJECT_DIR/agents"
+
+DRY_RUN=0
+DO_SKILLS=1
+DO_AGENTS=1
+
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY_RUN=1 ;;
+    --skills-only) DO_AGENTS=0 ;;
+    --agents-only) DO_SKILLS=0 ;;
+    -h|--help)
+      echo "Usage: $(basename "$0") [--dry-run] [--skills-only | --agents-only]"
+      exit 0
+      ;;
+    *)
+      echo "❌ Unknown argument: $arg" >&2
+      echo "Usage: $(basename "$0") [--dry-run] [--skills-only | --agents-only]" >&2
+      exit 1
+      ;;
+  esac
+done
+
+export DRY_RUN DO_SKILLS DO_AGENTS SKILLS_DIR AGENTS_DIR
+
+python3 - <<'PY'
+import os
+import re
+import sys
+
+skills_dir = os.environ["SKILLS_DIR"]
+agents_dir = os.environ["AGENTS_DIR"]
+dry_run = os.environ["DRY_RUN"] == "1"
+do_skills = os.environ["DO_SKILLS"] == "1"
+do_agents = os.environ["DO_AGENTS"] == "1"
+
+changes = []
+errors = []
+
+# ---- Step 1: discover skills + (optionally) rewrite frontmatter name: field ----
+skill_names = []  # bare directory names, in sorted order
+name_re = re.compile(r'^name:\s*(.+?)\s*$')
+
+if os.path.isdir(skills_dir):
+    for entry in sorted(os.listdir(skills_dir)):
+        skill_path = os.path.join(skills_dir, entry, "SKILL.md")
+        if not os.path.isfile(skill_path):
+            continue  # not a skill dir (e.g. skills/index/ has no SKILL.md)
+
+        with open(skill_path, "r", encoding="utf-8") as f:
+            lines = f.readlines()
+
+        if not lines or lines[0].strip() != "---":
+            errors.append(f"{skill_path}: no frontmatter block found")
+            continue
+
+        close_idx = None
+        for i in range(1, len(lines)):
+            if lines[i].strip() == "---":
+                close_idx = i
+                break
+        if close_idx is None:
+            errors.append(f"{skill_path}: unterminated frontmatter block")
+            continue
+
+        name_idx = None
+        current_name = None
+        for i in range(1, close_idx):
+            m = name_re.match(lines[i])
+            if m:
+                name_idx = i
+                current_name = m.group(1).strip('"\'')
+                break
+
+        if name_idx is None:
+            errors.append(f"{skill_path}: no 'name:' field in frontmatter")
+            continue
+
+        skill_names.append(entry)
+
+        if current_name.startswith("j:"):
+            continue  # already migrated — not an error, nothing to do
+
+        if current_name != entry:
+            errors.append(
+                f"{skill_path}: frontmatter name '{current_name}' does not match "
+                f"directory name '{entry}' — skipped for safety"
+            )
+            continue
+
+        if not do_skills:
+            continue
+
+        new_line = f"name: j:{entry}\n"
+        changes.append({
+            "type": "frontmatter",
+            "file": skill_path,
+            "before": lines[name_idx].rstrip("\n"),
+            "after": new_line.rstrip("\n"),
+        })
+
+        if not dry_run:
+            lines[name_idx] = new_line
+            with open(skill_path, "w", encoding="utf-8") as f:
+                f.writelines(lines)
+elif do_skills:
+    errors.append(f"skills directory not found: {skills_dir}")
+
+# ---- Step 2: rewrite bare "/<name>" prose mentions in agents/*.md ----
+if do_agents and os.path.isdir(agents_dir):
+    # Longest name first so "/jenga-permission-level" is matched (and
+    # consumed) before the shorter "/jenga" gets a chance to.
+    ordered_names = sorted(skill_names, key=len, reverse=True)
+    boundary_chars = set(
+        "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-:"
+    )
+
+    for entry in sorted(os.listdir(agents_dir)):
+        if not entry.endswith(".md"):
+            continue
+        agent_path = os.path.join(agents_dir, entry)
+        if not os.path.isfile(agent_path):
+            continue
+
+        with open(agent_path, "r", encoding="utf-8") as f:
+            text = f.read()
+
+        file_changes = 0
+
+        for name in ordered_names:
+            pattern = re.compile(r"/" + re.escape(name))
+            matches = []
+            for m in pattern.finditer(text):
+                start, end = m.start(), m.end()
+                if start > 0 and text[start - 1] in boundary_chars:
+                    continue  # part of a longer token, e.g. "x/status"
+                if end < len(text) and text[end] in boundary_chars:
+                    continue  # e.g. "/doc" inside "/doc-sync"
+                matches.append((start, end))
+            for start, end in reversed(matches):
+                text = text[:start] + f"j:{name}" + text[end:]
+                file_changes += 1
+
+        if file_changes:
+            changes.append({
+                "type": "agent-prose",
+                "file": agent_path,
+                "count": file_changes,
+            })
+            if not dry_run:
+                with open(agent_path, "w", encoding="utf-8") as f:
+                    f.write(text)
+elif do_agents and not os.path.isdir(agents_dir):
+    errors.append(f"agents directory not found: {agents_dir}")
+
+# ---- report ----
+mode = "DRY RUN — no files written" if dry_run else "APPLIED"
+print(f"apply-j-prefix.sh — {mode}")
+print(f"Skills discovered: {len(skill_names)}")
+print()
+
+if not changes:
+    print("No changes.")
+else:
+    for c in changes:
+        if c["type"] == "frontmatter":
+            print(f"[frontmatter] {c['file']}")
+            print(f"    - {c['before']}")
+            print(f"    + {c['after']}")
+        else:
+            print(f"[agent-prose] {c['file']} — {c['count']} occurrence(s) rewritten")
+    print()
+    print(f"Total: {len(changes)} change group(s)")
+
+if errors:
+    print()
+    print("Errors / skipped:")
+    for e in errors:
+        print(f"  ⚠ {e}")
+    sys.exit(1)
+
+sys.exit(0)
+PY

package/scripts/consume-context-digest.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# scripts/consume-context-digest.sh
+#
+# Read-and-delete helper for the resolved_context digest handoff convention
+# (E49_S01). The receiving subagent (the one whose sender object carries a
+# resolved_context / resolved_context_path pointing at a file under
+# project/queue/context/) calls this once, as part of reading its own sender
+# object, to fetch the digest content and immediately mark the file consumed
+# — mirroring project/queue/handoffs/'s single-use lifecycle rather than
+# leaving cleanup to a convention every receiver has to remember to follow.
+#
+# Atomic claim: before reading, the target file is renamed to a
+# `.claimed.$$` sibling in the same directory (same TOCTOU-safe pattern
+# hooks/on_session_end.sh section 4 already uses when routing
+# project/queue/handoffs/ files). `mv` between two paths on the same
+# filesystem is a rename(2) syscall — the kernel guarantees exactly one
+# concurrent claimer wins. If the rename fails, another process already
+# consumed (or is consuming) this file; this invocation exits 3 without
+# printing anything, rather than risking a double-read of a file that's
+# about to disappear out from under it.
+#
+# This script does NOT sweep for abandoned digests nobody ever consumes —
+# that backstop is scripts/sweep-stale-context-digests.sh, invoked from
+# hooks/on_session_end.sh.
+#
+# Usage:
+#   consume-context-digest.sh <path-to-digest-file>
+#   consume-context-digest.sh --raw <path-to-digest-file>
+#
+# Options:
+#   --raw    print only the digest field's text (not the full JSON envelope)
+#   -h, --help
+#
+# Output (stdout):
+#   the digest file's full JSON envelope (default), or just its `digest`
+#   field's text with --raw
+#
+# Exit codes:
+#   0  digest read and file deleted
+#   1  usage error
+#   2  target file does not exist (already consumed, or never written)
+#   3  target file was claimed by a concurrent consumer first
+#   4  target file is not valid JSON / missing expected fields
+# ---------------------------------------------------------------------------
+
+set -euo pipefail
+
+SELF="$(basename "$0")"
+
+die() {
+  local code="$1"; shift
+  printf '%s: error: %s\n' "$SELF" "$*" >&2
+  exit "$code"
+}
+
+usage() {
+  sed -n '/^# Usage:/,/^# Exit codes:/p' "$0" | sed 's/^# \{0,1\}//' >&2
+  exit 1
+}
+
+command -v jq >/dev/null 2>&1 || die 1 "jq is required but not found on PATH"
+
+RAW=0
+TARGET=""
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --raw)
+      RAW=1; shift ;;
+    -h|--help)
+      usage ;;
+    -*)
+      die 1 "unknown option: $1" ;;
+    *)
+      [ -z "$TARGET" ] || die 1 "unexpected extra argument: $1"
+      TARGET="$1"; shift ;;
+  esac
+done
+
+[ -n "$TARGET" ] || usage
+[ -f "$TARGET" ] || die 2 "digest file not found: $TARGET (already consumed, or never written)"
+
+CLAIMED_FILE="${TARGET}.claimed.$$"
+if ! mv "$TARGET" "$CLAIMED_FILE" 2>/dev/null; then
+  die 3 "digest file '$TARGET' was claimed by a concurrent consumer — skipping"
+fi
+
+# Always attempt to remove the claimed temp file, whether jq succeeds or not,
+# so a malformed digest can't leave a permanent orphan behind.
+cleanup() {
+  rm -f "$CLAIMED_FILE" 2>/dev/null || true
+}
+trap cleanup EXIT
+
+if [ "$RAW" -eq 1 ]; then
+  DIGEST_TEXT=$(jq -r '.digest // empty' "$CLAIMED_FILE" 2>/dev/null) || die 4 "'$TARGET' is not valid digest JSON"
+  [ -n "$DIGEST_TEXT" ] || die 4 "'$TARGET' has no 'digest' field"
+  printf '%s\n' "$DIGEST_TEXT"
+else
+  jq -e '.' "$CLAIMED_FILE" >/dev/null 2>&1 || die 4 "'$TARGET' is not valid JSON"
+  cat "$CLAIMED_FILE"
+fi

package/scripts/postinstall.js

@@ -33,6 +33,7 @@ import { fileURLToPath } from 'node:url';
 
 import { mirror } from '../lib/mirror.js';
 import { generateCopilotInstructions } from '../lib/generate-copilot-instructions.js';
+import { generateSkillAllowList } from '../lib/generate-skill-allow-list.js';
 
 // ESM equivalent of __dirname
 const __filename = fileURLToPath(import.meta.url);
@@ -154,6 +155,30 @@ function main() {
     totalSkipped += result.skipped.length;
   }
 
+  // Regenerate the canonical skill allow-list (E50_S02) from the freshly mirrored
+  // `.agents/skills` BEFORE bootstrapping .github/copilot-instructions.md below — so a consumer
+  // install ships a correct, current allow-list from the very first `npm install`, not
+  // only after a later `/self-sync`. The output is written into this installed package's own
+  // `lib/` (not the consumer root — `lib/` is never duplicated into the consumer per this file's
+  // header comment), matching generateSkillAllowList's own default output location and the path
+  // the MCP router / native routing enforcement (E50_S02_T03/T04) read from at runtime.
+  //
+  // Ordering matters (E50_S02_T04): generateCopilotInstructions() below now renders an
+  // {{ALLOWED_SKILL_IDS}} block by reading this same lib/skill-allow-list.json path. Running
+  // this regeneration first means that render reflects the freshly-mirrored `.agents/skills`
+  // scan from this very postinstall run, not the stale artifact committed at publish time.
+  // Wrapped in a try/catch-and-warn pattern so a generation failure degrades gracefully
+  // (console warning) rather than failing the whole postinstall.
+  try {
+    const result = generateSkillAllowList(
+      path.join(consumerRoot, '.agents', 'skills'),
+      path.join(packageRoot, 'lib', 'skill-allow-list.json')
+    );
+    console.log(`  ✓ lib/skill-allow-list.json regenerated (${result.skill_count} skills)`);
+  } catch (e) {
+    console.log(`  ⚠  Could not regenerate lib/skill-allow-list.json — ${e.message}`);
+  }
+
   // Bootstrap .github/copilot-instructions.md unconditionally, right after the mirror step —
   // no interactive prompts, since postinstall runs unattended during `npm install`. Without
   // this, a consumer whose very first action is a Copilot slash command (before ever running

package/scripts/sweep-stale-context-digests.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# scripts/sweep-stale-context-digests.sh
+#
+# Staleness-cleanup backstop for project/queue/context/ digest files
+# (E49_S01_T02). The PRIMARY cleanup path is scripts/consume-context-digest.sh,
+# called by the receiving subagent once it has read its digest. This script
+# exists for the cases that leaves uncovered:
+#   - a digest whose intended receiving session never starts (e.g. the
+#     dispatch it was written for was abandoned or superseded)
+#   - a receiver that reads the raw file directly instead of going through
+#     consume-context-digest.sh and forgets to delete it
+#
+# Invoked from hooks/on_session_end.sh on every session end (any agent), so
+# it runs far more often than any single digest's realistic lifetime — a
+# digest is meant to be consumed by the very next session dispatched for its
+# task, not to sit for a full day. Age-based (mtime), not consumption-based:
+# unlike project/queue/handoffs/ (routed and deleted deterministically, same
+# hook invocation, by on_session_end.sh section 4), a digest's consumer is a
+# LATER session that hasn't necessarily started yet when an unrelated
+# session's SessionEnd hook fires — so this sweep must not delete a digest
+# just because some other session ended in the meantime. The default
+# threshold (24h) is deliberately generous for that reason.
+#
+# Usage:
+#   sweep-stale-context-digests.sh [--context-dir <dir>] [--max-age-seconds <n>]
+#
+# Options:
+#   --context-dir <dir>       override project/queue/context (default:
+#                             resolved via JENGA_PROJECT_DIR / git toplevel)
+#   --max-age-seconds <n>     override the default 86400s (24h) threshold
+#                             (env: CONTEXT_DIGEST_STALE_SECONDS)
+#   -h, --help
+#
+# Output (stdout): one line per file removed: "removed: <path> (age <n>s)"
+#
+# Exit codes:
+#   0  ran successfully (including the common case of nothing to remove)
+#   1  usage error
+# ---------------------------------------------------------------------------
+
+set -u
+
+SELF="$(basename "$0")"
+
+die() {
+  local code="$1"; shift
+  printf '%s: error: %s\n' "$SELF" "$*" >&2
+  exit "$code"
+}
+
+usage() {
+  sed -n '/^# Usage:/,/^# Exit codes:/p' "$0" | sed 's/^# \{0,1\}//' >&2
+  exit 1
+}
+
+resolve_project_dir() {
+  if [ -n "${JENGA_PROJECT_DIR:-}" ]; then
+    printf '%s\n' "$JENGA_PROJECT_DIR"
+    return 0
+  fi
+  if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
+    printf '%s\n' "$CLAUDE_PROJECT_DIR"
+    return 0
+  fi
+  git rev-parse --show-toplevel 2>/dev/null || pwd
+}
+
+CONTEXT_DIR=""
+MAX_AGE_SECONDS="${CONTEXT_DIGEST_STALE_SECONDS:-86400}"
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --context-dir)
+      [ "$#" -ge 2 ] || die 1 "--context-dir requires a value"
+      CONTEXT_DIR="$2"; shift 2 ;;
+    --context-dir=*)
+      CONTEXT_DIR="${1#--context-dir=}"; shift ;;
+    --max-age-seconds)
+      [ "$#" -ge 2 ] || die 1 "--max-age-seconds requires a value"
+      MAX_AGE_SECONDS="$2"; shift 2 ;;
+    --max-age-seconds=*)
+      MAX_AGE_SECONDS="${1#--max-age-seconds=}"; shift ;;
+    -h|--help)
+      usage ;;
+    *)
+      die 1 "unknown argument: $1" ;;
+  esac
+done
+
+case "$MAX_AGE_SECONDS" in
+  ''|*[!0-9]*) die 1 "--max-age-seconds must be a non-negative integer, got '$MAX_AGE_SECONDS'" ;;
+esac
+
+if [ -z "$CONTEXT_DIR" ]; then
+  PROJECT_DIR="$(resolve_project_dir)"
+  CONTEXT_DIR="$PROJECT_DIR/project/queue/context"
+fi
+
+[ -d "$CONTEXT_DIR" ] || exit 0
+
+# Portable mtime lookup: GNU stat (Linux) uses -c, BSD stat (macOS) uses -f —
+# same fallback pattern as scripts/with-lock.sh's lock_mtime_epoch().
+file_mtime_epoch() {
+  stat -c %Y "$1" 2>/dev/null || stat -f %m "$1" 2>/dev/null
+}
+
+now_epoch() {
+  date +%s
+}
+
+NOW="$(now_epoch)"
+
+for FILE in "$CONTEXT_DIR"/*.json; do
+  [ -e "$FILE" ] || continue
+  # Never sweep a file mid-claim by consume-context-digest.sh — that script
+  # renames its target to a .claimed.$$ sibling before reading it, and this
+  # glob (*.json) doesn't match that suffix, so in-flight claims are already
+  # excluded structurally. This comment documents that rather than adding a
+  # redundant runtime check.
+
+  MTIME="$(file_mtime_epoch "$FILE")" || continue
+  AGE=$(( NOW - MTIME ))
+
+  if [ "$AGE" -ge "$MAX_AGE_SECONDS" ]; then
+    if rm -f "$FILE" 2>/dev/null; then
+      echo "removed: $FILE (age ${AGE}s)"
+    fi
+  fi
+done
+
+exit 0

package/scripts/validate-board.sh

@@ -25,6 +25,11 @@ STATUS_VALUES = {
     "Blocked",
     "Backlog",
     "Done",
+    "Merged",
+    "Publicized",
+    "Privatized",
+    "Deployed to Stage",
+    "Deployed to Prod",
 }
 
 # E39 tiered item-level caution/escalation. crucial_level is OPTIONAL — absence means no