@delorenj/pjangler 1.5.18 → 1.5.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delorenj/pjangler",
-  "version": "1.5.18",
+  "version": "1.5.21",
   "description": "Project subsystem bootstrapper CLI",
   "type": "module",
   "main": "dist/index.js",
@@ -26,7 +26,7 @@
     "node": ">=24"
   },
   "scripts": {
-    "build": "esbuild src/index.ts src/mcp-server.ts src/prompt.ts src/project-registry-service.ts src/notebook/journal-service-main.ts --bundle --packages=external --platform=node --format=esm --sourcemap --outbase=src --outdir=dist && node scripts/export-project-notebook-skill.mjs",
+    "build": "esbuild src/index.ts src/mcp-server.ts src/prompt.ts src/project-registry-service.ts src/notebook/journal-service-main.ts --bundle --packages=external --platform=node --format=esm --sourcemap --outbase=src --outdir=dist && esbuild src/crank/tui.tsx --bundle --packages=external --platform=node --format=esm --sourcemap --outbase=src --outdir=dist && node scripts/export-project-notebook-skill.mjs",
     "check:audit:prod": "npm audit --omit=dev",
     "check:lock": "node scripts/check-package-lock-parity.mjs",
     "check:submodules": "node scripts/check-submodule-contract.mjs",
@@ -35,6 +35,7 @@
     "mcp": "node dist/mcp-server.js",
     "typecheck": "tsc --noEmit",
     "test:bmad-installer-contract": "node tests/bmad-installer-contract-regressions.mjs",
+    "test:bmad-rollback-surface": "node tests/pjan-180-surface-oracle.mjs",
     "test:pjan-77": "node tests/pjan-77-notebook-domain-regressions.mjs && node tests/pjan-77-notebook-adapter-contract.mjs && node tests/pjan-77-notebook-lifecycle-regressions.mjs && node tests/pjan-77-notebook-cli-contract.mjs && node tests/pjan-77-notebook-hooks-capture.mjs && node tests/pjan-77-notebook-security-isolation.mjs && node tests/pjan-77-notebook-release-gates.mjs",
     "test": "node scripts/run-tests.mjs",
     "migrate:up": "node-pg-migrate --migrations-dir migrations up",
@@ -62,14 +63,17 @@
     "@delorenj/skillex": "0.3.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "commander": "^14.0.2",
+    "ink": "^8.0.0",
     "pg": "^8.16.0",
+    "react": "^19.3.1",
+    "smol-toml": "^1.8.0",
     "yaml": "^2.9.0",
-    "zod": "^4.4.3",
-    "smol-toml": "^1.8.0"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",
     "@types/pg": "^8.15.0",
+    "@types/react": "^19.3.0",
     "c8": "^10.1.3",
     "esbuild": "^0.25.0",
     "node-pg-migrate": "^8.0.0",

package/templates/commonproject/template/.github/scripts/check-gateway-routing.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# Regression guard: every workflow that runs Claude goes through the
+# AutomaticAI gateway (https://api.automaticai.io), never api.anthropic.com.
+# The code-review workflow runs it as its first step, so a regression fails the
+# job before any model call is made. Usage:
+#   bash .github/scripts/check-gateway-routing.sh [workflows-dir]
+#
+# A workflow fails when it:
+#   - uses the subscription OAuth token (claude_code_oauth_token /
+#     CLAUDE_CODE_OAUTH_TOKEN), which talks to api.anthropic.com directly;
+#   - names api.anthropic.com anywhere outside a comment;
+#   - runs claude-code-action without ANTHROPIC_BASE_URL set to the gateway,
+#     without anthropic_api_key from secrets.AUTOMATICAI_GATEWAY_TOKEN, or
+#     without github_token (the action's OIDC app-token exchange calls
+#     api.anthropic.com);
+#   - leaves classify_inline_comments on (its post-step POSTs the key to a
+#     hard-coded https://api.anthropic.com/v1/messages);
+#   - runs claude-code-action without `--model automaticai/...` in claude_args,
+#     with any other --model there, or with an OPUS/SONNET/HAIKU default model
+#     slot that is not an automaticai/ gateway route.
+# Comment lines are ignored so headers can explain what is forbidden.
+# Pattern: delorenj/heyma-obsidian 68a7810 + 1cd9f06 (AAI-59).
+set -uo pipefail
+
+GATEWAY="https://api.automaticai.io"
+dir="${1:-$(dirname "$0")/../workflows}"
+status=0
+count=0
+fail() { echo "  $1: $2" >&2; status=1; }
+
+# Values of `key:` lines, unquoted, one per line.
+values() {
+  grep -oE "$1:[[:space:]]*['\"]?[^[:space:]'\"]+" <<<"$2" |
+    sed -E "s/^$1:[[:space:]]*['\"]?//" || true
+}
+
+# claude_args values, inline or as a YAML block scalar (| or >).
+claude_args() {
+  awk '
+    block {
+      if ($0 ~ /^[[:space:]]*$/) next
+      match($0, /^[[:space:]]*/)
+      if (RLENGTH > indent) { print; next }
+      block = 0
+    }
+    /^[[:space:]]*claude_args:/ {
+      match($0, /^[[:space:]]*/); indent = RLENGTH
+      value = $0; sub(/^[[:space:]]*claude_args:[[:space:]]*/, "", value)
+      if (value ~ /^[|>][+-]?[[:space:]]*$/) block = 1; else print value
+    }
+  ' <<<"$1"
+}
+
+shopt -s nullglob
+for file in "$dir"/*.yml "$dir"/*.yaml; do
+  count=$((count + 1))
+  name=$(basename "$file")
+  code=$(grep -vE '^[[:space:]]*#' "$file" || true)
+
+  grep -qiE 'claude_code_oauth_token' <<<"$code" &&
+    fail "$name" "uses claude_code_oauth_token / CLAUDE_CODE_OAUTH_TOKEN (direct Anthropic subscription auth)"
+  grep -qE 'api\.anthropic\.com' <<<"$code" &&
+    fail "$name" "names api.anthropic.com; inference must go through $GATEWAY"
+  grep -qE 'anthropics/claude-code(-action)?@' <<<"$code" || continue
+
+  bases=$(values ANTHROPIC_BASE_URL "$code")
+  [ -n "$bases" ] || fail "$name" "claude-code-action needs ANTHROPIC_BASE_URL: $GATEWAY"
+  while read -r base; do
+    [ -z "$base" ] || [ "${base%/}" = "$GATEWAY" ] || fail "$name" "ANTHROPIC_BASE_URL $base is not $GATEWAY"
+  done <<<"$bases"
+  grep -qE 'anthropic_api_key:[[:space:]]*\$\{\{[[:space:]]*secrets\.AUTOMATICAI_GATEWAY_TOKEN[[:space:]]*\}\}' <<<"$code" ||
+    fail "$name" "claude-code-action must authenticate with secrets.AUTOMATICAI_GATEWAY_TOKEN"
+  grep -qE 'github_token:' <<<"$code" ||
+    fail "$name" "pass github_token (the action's OIDC app-token exchange calls api.anthropic.com)"
+  grep -qE "classify_inline_comments:[[:space:]]*['\"]?false['\"]?" <<<"$code" ||
+    fail "$name" "set classify_inline_comments: 'false' (its post-step calls api.anthropic.com directly)"
+
+  models=$(claude_args "$code" | grep -oE -- "--model(=|[[:space:]]+)['\"]?[^[:space:]'\"]+" |
+    sed -E "s/^--model(=|[[:space:]]+)['\"]?//" || true)
+  [ -n "$models" ] || fail "$name" "claude_args must pass --model automaticai/<account>/<model>"
+  while read -r model; do
+    [ -z "$model" ] || [[ "$model" == automaticai/* ]] ||
+      fail "$name" "claude_args --model $model must be an automaticai/ gateway route"
+  done <<<"$models"
+
+  for slot in OPUS SONNET HAIKU; do
+    slots=$(values "ANTHROPIC_DEFAULT_${slot}_MODEL" "$code")
+    [ -n "$slots" ] || fail "$name" "ANTHROPIC_DEFAULT_${slot}_MODEL must be an automaticai/ gateway route"
+    while read -r model; do
+      [ -z "$model" ] || [[ "$model" == automaticai/* ]] ||
+        fail "$name" "ANTHROPIC_DEFAULT_${slot}_MODEL $model must be an automaticai/ gateway route"
+    done <<<"$slots"
+  done
+done
+
+if [ "$status" -ne 0 ]; then
+  echo "Gateway routing check failed." >&2
+  exit 1
+fi
+echo "Gateway routing check passed ($count workflows)."

package/templates/commonproject/template/.github/workflows/code-review.yml.jinja

@@ -3,10 +3,35 @@
 # Rendered unconditionally by the CommonProject template: every project pjangler
 # creates gets code review on day one, with no opt-in question to forget.
 #
-# Auth: the `CLAUDE_CODE_OAUTH_TOKEN` repo secret (or an org-level secret this
-# repo inherits). It is a long-lived OAuth/session token, NOT a metered API key.
-# Until it is set the job runs and fails at the action step — see the "Code
-# Review" section of the CommonProject README.
+# Every model call this review makes goes through the AutomaticAI gateway,
+# https://api.automaticai.io, on the operator's personal Claude subscription.
+# Nothing here talks to api.anthropic.com for inference (AAI-59; the pattern is
+# delorenj/heyma-obsidian 68a7810 and 1cd9f06).
+#
+# Auth: the `AUTOMATICAI_GATEWAY_TOKEN` repo secret, a scoped gateway token for
+# consumer `<repo>-code-review` (routes personal claude-opus-5.5 and
+# claude-sonnet-5.5 only). Until it is set the job runs and fails at the action
+# step. Mint it, then set it, from ~/code/client-portal/gateway:
+#   python3 ops/gateway-tokens.py mint <repo>-code-review --days 90 \
+#     --models automaticai/personal/claude-opus-5.5 automaticai/personal/claude-sonnet-5.5
+#   op read 'op://DeLoSecrets/<item-id>/<repo>-code-review' \
+#     | gh secret set AUTOMATICAI_GATEWAY_TOKEN -R <owner>/<repo>
+# It expires after 90 days; `gateway-tokens.py rotate` and the same pipe renew
+# it. The action passes it as ANTHROPIC_API_KEY, so Claude Code sends it as
+# `x-api-key` to ANTHROPIC_BASE_URL; the gateway accepts that header.
+#
+# Every model slot is pinned to a personal-account gateway route: the main loop
+# and the plugin's Opus agents to claude-opus-5.5, its Sonnet and Haiku agents
+# (and Claude Code's background helper) to claude-sonnet-5.5. The personal
+# account has no Haiku route, and a helper must not leave the account.
+#
+# Two action defaults would still reach Anthropic directly, so both are off:
+#   - classify_inline_comments: its post-step POSTs ANTHROPIC_API_KEY to a
+#     hard-coded Anthropic Messages endpoint (Haiku).
+#   - the GitHub App token exchange (via OIDC). The job uses the workflow's own
+#     GITHUB_TOKEN and needs no `id-token: write`.
+# `.github/scripts/check-gateway-routing.sh` runs first and fails the job if any
+# of this regresses.
 #
 # Runner: self-hosted on big-chungus ONLY. GitHub-hosted minutes are billed and
 # the budget is $0, so a hosted label (`ubuntu-latest`, `macos-*`) just sits
@@ -16,6 +41,7 @@
 #
 # Trigger: `pull_request`, deliberately NOT `pull_request_target`. The latter
 # would hand repo secrets to code from forked PRs; nothing here needs it.
+# `workflow_dispatch` reviews an existing PR on demand (and proves the route).
 #
 # NOTE FOR TEMPLATE MAINTAINERS: this is a Copier `.jinja` file and GitHub
 # Actions expression syntax collides with Jinja's variable delimiters. Every
@@ -26,6 +52,11 @@ name: Code Review
 on:
   pull_request:
     types: [opened, synchronize, ready_for_review, reopened]
+  workflow_dispatch:
+    inputs:
+      pr:
+        description: 'Pull request number to review'
+        required: true
 
 jobs:
   claude-review:
@@ -34,7 +65,10 @@ jobs:
       contents: read
       pull-requests: read
       issues: read
-      id-token: write
+    env:
+      # Telemetry and error reporting are not inference, but they are the last
+      # direct Anthropic traffic a CI review would make.
+      CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1'
 
     steps:
       - name: Checkout repository
@@ -42,13 +76,25 @@ jobs:
         with:
           fetch-depth: 1
 
+      - name: Gateway routing guard
+        run: bash .github/scripts/check-gateway-routing.sh
+
       - name: Run Claude Code Review
         id: claude-review
         uses: anthropics/claude-code-action@v1
+        env:
+          ANTHROPIC_BASE_URL: https://api.automaticai.io
+          ANTHROPIC_DEFAULT_OPUS_MODEL: automaticai/personal/claude-opus-5.5
+          ANTHROPIC_DEFAULT_SONNET_MODEL: automaticai/personal/claude-sonnet-5.5
+          ANTHROPIC_DEFAULT_HAIKU_MODEL: automaticai/personal/claude-sonnet-5.5
         with:
-          claude_code_oauth_token: {% raw %}${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}{% endraw %}
+          anthropic_api_key: {% raw %}${{ secrets.AUTOMATICAI_GATEWAY_TOKEN }}{% endraw %}
+          github_token: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
+          classify_inline_comments: 'false'
+          claude_args: '--model automaticai/personal/claude-opus-5.5'
+          settings: '{"effortLevel": "xhigh"}'
           plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
           plugins: 'code-review@claude-code-plugins'
-          prompt: '/code-review:code-review {% raw %}${{ github.repository }}/pull/${{ github.event.pull_request.number }}{% endraw %}'
+          prompt: '/code-review:code-review {% raw %}${{ github.repository }}/pull/${{ github.event.pull_request.number || inputs.pr }}{% endraw %}'
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
           # or https://code.claude.com/docs/en/cli-reference for available options

package/templates/commonproject/template/.mise/scripts/docs-sync.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""Copy recent project Markdown into a dated Obsidian snapshot.
+
+The vault folder is Projects/<project_id>/<date>, where project_id comes from
+the repository's .project.json manifest (falling back to the repository
+directory name for bare repos). The index heading uses project_name (or the
+directory name) so the display name may differ from the vault folder.
+"""
+
+import argparse
+from datetime import datetime
+import json
+import math
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import time
+from urllib.parse import quote, urlencode
+
+
+# Sources are root files or under docs/ and _bmad-output/, so this cannot collide.
+INDEX = "_docs-sync/Index.md"
+
+
+def positive_hours(value):
+    hours = float(value)
+    if not math.isfinite(hours) or hours <= 0:
+        raise argparse.ArgumentTypeError("hours must be a finite number greater than zero")
+    return hours
+
+
+def vault_component(value, source):
+    """Reject anything that is not a safe single path component."""
+    if (
+        not value
+        or value in (".", "..")
+        or "/" in value
+        or "\\" in value
+        or "\x00" in value
+    ):
+        raise RuntimeError(f"Unsafe {source} for the vault path: {value!r}")
+    return value
+
+
+def project_identity(root):
+    """Return (vault folder, display name) for the repository.
+
+    Reads .project.json when present: project_id names the vault folder and
+    project_name titles the index. A bare repository without a manifest (or
+    with blank identity fields) falls back to the repository directory name
+    for both. A manifest that exists but is not valid JSON is an error rather
+    than a silent fallback, because it indicates a broken project.
+    """
+    identifier, name = None, None
+    manifest = root / ".project.json"
+    if manifest.is_file():
+        try:
+            data = json.loads(manifest.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as error:
+            raise RuntimeError(f"Cannot parse {manifest}: {error}")
+        if isinstance(data, dict):
+            identifier = data.get("project_id")
+            name = data.get("project_name")
+    if not isinstance(identifier, str) or not identifier.strip():
+        identifier = root.name
+    if not isinstance(name, str) or not name.strip():
+        name = root.name
+    # The display name goes into a Markdown heading; keep it one line.
+    display = " ".join(name.strip().splitlines())
+    return vault_component(identifier.strip(), "project_id"), display
+
+
+def recent_docs(root, hours):
+    result = subprocess.run(
+        ["git", "-C", str(root), "ls-files", "--cached", "--others",
+         "--exclude-standard", "-z"],
+        check=True, capture_output=True,
+    )
+    cutoff = time.time() - hours * 3600
+    for name in sorted(set(os.fsdecode(result.stdout).split("\0"))):
+        relative = Path(name)
+        if not name or relative.suffix.lower() != ".md":
+            continue
+        if any(part.startswith(".") for part in relative.parts):
+            continue
+        if len(relative.parts) > 1 and relative.parts[0] not in ("docs", "_bmad-output"):
+            continue
+        source = root / relative
+        if any(path.is_symlink() for path in (source, *source.parents)):
+            continue
+        if source.is_file() and source.stat().st_mtime >= cutoff:
+            yield relative
+
+
+def open_note(note):
+    uri = "obsidian://open?" + urlencode({"path": str(note)}, quote_via=quote)
+    if sys.platform == "win32":
+        os.startfile(uri)
+        return
+    launcher = "open" if sys.platform == "darwin" else "xdg-open"
+    executable = shutil.which(launcher)
+    if not executable:
+        raise RuntimeError(f"Cannot find {launcher}; use --no-open for a headless sync")
+    subprocess.run([executable, uri], check=True)
+
+
+def sync(root, vault, hours, no_open):
+    if not vault.is_dir():
+        raise RuntimeError(f"Obsidian vault does not exist: {vault}; set VAULT or pass --vault")
+    if vault == root or root in vault.parents:
+        raise RuntimeError("The vault must be outside the repository")
+    project_id, display = project_identity(root)
+    files = list(recent_docs(root, hours))
+    if not files:
+        print(f"No Markdown files modified in the last {hours:g} hours; nothing copied or opened.")
+        return
+
+    today = datetime.now().strftime("%Y-%m-%d")
+    destination = vault / "Projects" / project_id / today
+    destination.mkdir(parents=True, exist_ok=True)
+    for relative in files:
+        target = destination / relative
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(root / relative, target)
+
+    # Include earlier copies from today too; narrower reruns never delete notes.
+    links = []
+    for note in sorted(destination.rglob("*")):
+        if note.is_file() and note.suffix.lower() == ".md" and note != destination / INDEX:
+            relative = note.relative_to(destination).as_posix()
+            label = relative.replace("\\", "\\\\").replace("[", "\\[").replace("]", "\\]").replace("\n", " ")
+            links.append(f"- [{label}](<../{quote(relative, safe='/')}>)")
+    index = destination / INDEX
+    index.parent.mkdir(exist_ok=True)
+    index.write_text(
+        f"# {display} docs — {today}\n\n"
+        f"Copied from `{root}`. Relative repository paths are preserved.\n\n"
+        + "\n".join(links) + "\n",
+        encoding="utf-8",
+    )
+    print(f"Synced {len(files)} Markdown files to {destination}", flush=True)
+    print(f"Index: {index}", flush=True)
+    if not no_open:
+        open_note(index)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", type=Path, default=Path(__file__).resolve().parents[2],
+                        help=argparse.SUPPRESS)
+    parser.add_argument("--vault", type=Path,
+                        default=os.environ.get("VAULT") or os.environ.get("OBSIDIAN_VAULT")
+                        or str(Path.home() / "code/DeLoDocs"),
+                        help="existing Obsidian vault (default: VAULT, OBSIDIAN_VAULT, ~/code/DeLoDocs)")
+    parser.add_argument("--hours", type=positive_hours, default=24,
+                        help="copy Markdown modified within this many hours (default: 24)")
+    parser.add_argument("--no-open", action="store_true", help="copy without opening Obsidian")
+    args = parser.parse_args()
+    try:
+        sync(args.root.expanduser().resolve(), args.vault.expanduser().resolve(),
+             args.hours, args.no_open)
+    except (OSError, RuntimeError, subprocess.CalledProcessError) as error:
+        detail = ""
+        if isinstance(error, subprocess.CalledProcessError) and error.stderr:
+            detail = ": " + os.fsdecode(error.stderr).strip()
+        print(f"docs:sync: {error}{detail}", file=sys.stderr)
+        print("If copying succeeded but Obsidian could not open, retry with --no-open.", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/templates/commonproject/template/mise.toml.jinja

@@ -43,6 +43,10 @@ run = "'{% raw %}{{config_root}}{% endraw %}/.agents/hooks/sync.py' --uninstall
 [[watch_files]]
 patterns = ["AGENTS.md"]
 task = "link:agentfiles"
+
+[[watch_files]]
+patterns = [".env.op"]
+task = "env:materialize"
 {% if agent_hooks_layer %}
 # Re-fan-out the agent hooks whenever the single source of truth changes.
 [[watch_files]]
@@ -52,6 +56,10 @@ task = "hooks:sync"
 [tasks."link:agentfiles"]
 description = "Symlink all agent files to AGENTS.md"
 run = "'{% raw %}{{config_root}}{% endraw %}/.mise/scripts/link-agentfiles.sh' '{% raw %}{{config_root}}{% endraw %}'"
+
+[tasks."env:materialize"]
+description = "Inject .env.op into .env"
+run = "'{% raw %}{{config_root}}{% endraw %}/.mise/scripts/materialize-env.sh'"
 {% if agent_hooks_layer %}
 # --- Project-scoped agent hooks (see .agents/hooks/README.md) ---
 
@@ -70,3 +78,21 @@ run = "'{% raw %}{{config_root}}{% endraw %}/.agents/hooks/sync.py' --uninstall"
 [tasks."hindsight:setup"]
 description = "Provision this dev's shared project Hindsight key from 1Password into .env (op read; upserts those two keys, leaves the rest of .env intact)"
 run = "'{% raw %}{{config_root}}{% endraw %}/.mise/scripts/hindsight-setup.sh'"
+
+# Core task (unconditional): snapshot recent project Markdown into the
+# Obsidian vault under Projects/<project_id>/<date> and open its index.
+# {{config_root}} is raw-escaped like the hooks above so mise, not Jinja,
+# expands it at task runtime (and sh -c keeps the space-safe quoting).
+[tasks."docs:sync"]
+description = "Copy recent Markdown from docs/, _bmad-output/ and the repo root to the dated project vault folder and open its Obsidian index"
+usage = '''
+flag "--hours <hours>" default="24" help="Copy Markdown modified within this many hours"
+flag "--vault <vault>" default="" help="Existing Obsidian vault (defaults to VAULT, OBSIDIAN_VAULT, or ~/code/DeLoDocs)"
+flag "--no-open" help="Copy without opening Obsidian"
+'''
+run = '''
+set -- --hours "$usage_hours"
+if [ -n "$usage_vault" ]; then set -- "$@" --vault "$usage_vault"; fi
+if [ "$usage_no_open" = true ]; then set -- "$@" --no-open; fi
+python3 "{% raw %}{{config_root}}{% endraw %}/.mise/scripts/docs-sync.py" --root "{% raw %}{{config_root}}{% endraw %}" "$@"
+'''