@erclx/canon 4.31.0 → 4.31.1

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.31.0",
+  "version": "4.31.1",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.31.0",
+  "version": "4.31.1",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/core/check-capability-seeding.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+shopt -s nullglob
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+
+TOOLING_ROOT="$PROJECT_ROOT/tooling"
+MARKER="canon-no-seed:"
+
+# `find` writes to stderr and returns non-zero for a missing root, inside a
+# process substitution whose status nothing reads. Without this the walk covers
+# nothing and the check reports every capability seeded having never read one.
+if [ ! -d "$TOOLING_ROOT" ]; then
+  echo "No tooling root at ${TOOLING_ROOT#"$PROJECT_ROOT/"}, capability seeding unverifiable." >&2
+  exit 1
+fi
+
+failures=""
+
+# A comment naming the marker anywhere in the source file is the recorded
+# reason a capability withholds itself from every destination it was compared
+# against. The reason's own prose is free-form, so only the marker is tested.
+has_reason() {
+  grep -q "$MARKER" "$1"
+}
+
+# Compares one source directory's files against the basenames already
+# expanded from a set of destination paths. Presence on either side clears a
+# name; a source file reaching neither the destination nor a marked reason is
+# a capability answered on one side of the seed or config boundary and not
+# the other.
+check_capability() {
+  local label="$1" src_dir="$2"
+  shift 2
+
+  [ -d "$src_dir" ] || return 0
+
+  local dest_names=" "
+  local dest
+  for dest in "$@"; do
+    [ -f "$dest" ] || continue
+    dest_names="$dest_names$(basename "$dest") "
+  done
+
+  local src_file name
+  for src_file in "$src_dir"/*; do
+    [ -f "$src_file" ] || continue
+    name=$(basename "$src_file")
+    case "$dest_names" in
+    *" $name "*) continue ;;
+    esac
+    has_reason "$src_file" && continue
+    failures="$failures  $label: ${src_file#"$PROJECT_ROOT/"} reaches no seed or config and carries no $MARKER reason"$'\n'
+  done
+}
+
+check_capability "Hooks" "$PROJECT_ROOT/.claude/hooks" \
+  "$PROJECT_ROOT"/tooling/claude/seeds/.claude/hooks/*
+
+check_capability "Workflows" "$PROJECT_ROOT/.github/workflows" \
+  "$PROJECT_ROOT"/tooling/*/configs/.github/workflows/*
+
+check_capability "Husky" "$PROJECT_ROOT/.husky" \
+  "$PROJECT_ROOT"/tooling/base/configs/.husky/*
+
+# The reverse direction: a destination file whose source here is gone reaches
+# neither check_capability above nor the wiring pass below, both of which read
+# forward from the source, and it ships a target a hook, workflow, or husky
+# script this repository has already deleted. A destination carrying the same
+# marker clears just as a source does, which is the escape hatch a target-only
+# capability needs, such as a stack-specific workflow with no root counterpart
+# by design.
+check_orphans() {
+  local label="$1" src_dir="$2" dest_dir="$3"
+
+  [ -d "$dest_dir" ] || return 0
+
+  local dest_file name
+  for dest_file in "$dest_dir"/*; do
+    [ -f "$dest_file" ] || continue
+    name=$(basename "$dest_file")
+    [ -f "$src_dir/$name" ] && continue
+    has_reason "$dest_file" && continue
+    failures="$failures  $label: ${dest_file#"$PROJECT_ROOT/"} is seeded or configured with no source at ${src_dir#"$PROJECT_ROOT/"}/$name"$'\n'
+  done
+}
+
+check_orphans "Hooks" "$PROJECT_ROOT/.claude/hooks" \
+  "$PROJECT_ROOT/tooling/claude/seeds/.claude/hooks"
+
+for dir in "$PROJECT_ROOT"/tooling/*/configs/.github/workflows; do
+  check_orphans "Workflows" "$PROJECT_ROOT/.github/workflows" "$dir"
+done
+
+check_orphans "Husky" "$PROJECT_ROOT/.husky" \
+  "$PROJECT_ROOT/tooling/base/configs/.husky"
+
+# A hook that reached the seed tree with no wiring in the seeded settings.json
+# is installed dead, which fails the same way an unseeded hook does.
+SEED_HOOKS_DIR="$PROJECT_ROOT/tooling/claude/seeds/.claude/hooks"
+SEED_SETTINGS="$PROJECT_ROOT/tooling/claude/seeds/.claude/settings.json"
+
+if [ -d "$SEED_HOOKS_DIR" ]; then
+  if [ ! -f "$SEED_SETTINGS" ]; then
+    failures="$failures  Seed settings: no settings.json at ${SEED_SETTINGS#"$PROJECT_ROOT/"} to confirm a seeded hook is wired"$'\n'
+  elif ! command -v jq >/dev/null 2>&1; then
+    failures="$failures  Seed settings: jq is not installed, seeded-hook wiring unverifiable"$'\n'
+  else
+    # Every wired command as its own path segment set, rather than a substring
+    # search over the raw file, so a hook name that is a substring of another
+    # hook's filename (`log.sh` inside `pr-create-log.sh`) cannot pass on a
+    # neighbor's wiring.
+    wired=" $(jq -r '.. | .command? // empty' "$SEED_SETTINGS" | tr '/\n' '  ') "
+    for hook_file in "$SEED_HOOKS_DIR"/*.sh; do
+      [ -f "$hook_file" ] || continue
+      name=$(basename "$hook_file")
+      case "$wired" in
+      *" $name "*) continue ;;
+      esac
+      failures="$failures  Seed settings: $name is seeded and wired into no command in ${SEED_SETTINGS#"$PROJECT_ROOT/"}"$'\n'
+    done
+  fi
+fi
+
+if [ -n "$failures" ]; then
+  echo "A capability reaches one side of the seed or config boundary and not the other:" >&2
+  printf '%s' "$failures" >&2
+  echo "Seed or configure the capability, or mark the source line with # $MARKER <reason>." >&2
+  exit 1
+fi

package/scripts/lib/sandbox-git.sh

@@ -112,6 +112,14 @@ ensure_sandbox_anchor_repo() {
   log_info "Created ${GITHUB_ORG}/${repo_name} as a private repository."
 }
 
+# Mirrors the merge-base resolution the diff-baseline port already carries
+# across five skill bodies, so a checkout whose local main trails origin/main
+# does not pull in skill bodies other merged branches changed.
+resolve_sandbox_skill_diff_base() {
+  git -C "$PROJECT_ROOT" merge-base HEAD origin/main 2>/dev/null ||
+    git -C "$PROJECT_ROOT" merge-base HEAD main 2>/dev/null
+}
+
 # A remote is useless without an author, so the scenarios that reach one always
 # configure both. configure_sandbox_git_identity stays callable on its own for
 # the scenarios that never push. The probe runs first so an absent remote is

package/scripts/manage-sandbox.sh

@@ -283,8 +283,12 @@ tag_sandbox_baseline() {
 }
 
 inject_changed_skills() {
+  local base
+  base=$(resolve_sandbox_skill_diff_base)
+  base="${base:-main}"
+
   local changed untracked
-  changed=$(git -C "$PROJECT_ROOT" diff main --name-only -- 'claude/skills/**/SKILL.md' 2>/dev/null)
+  changed=$(git -C "$PROJECT_ROOT" diff "$base" --name-only -- 'claude/skills/**/SKILL.md' 2>/dev/null)
   untracked=$(git -C "$PROJECT_ROOT" ls-files --others --exclude-standard -- 'claude/skills/**/SKILL.md' 2>/dev/null)
 
   local combined
@@ -293,8 +297,8 @@ inject_changed_skills() {
   [ -z "$combined" ] && return
 
   while IFS= read -r skill_path; do
-    # The diff against main lists a deleted skill alongside a changed one, and
-    # there is nothing left to inject for a name this branch removed.
+    # The diff against the base lists a deleted skill alongside a changed one,
+    # and there is nothing left to inject for a name this branch removed.
     [ -f "$PROJECT_ROOT/$skill_path" ] || continue
 
     local skill_name
@@ -302,6 +306,9 @@ inject_changed_skills() {
     local target_dir="$SANDBOX/.claude/skills/$skill_name"
     mkdir -p "$target_dir"
     cp "$PROJECT_ROOT/$skill_path" "$target_dir/SKILL.md"
+    if [ -n "$SANDBOX_SKIP_AUTO_COMMIT" ]; then
+      echo ".claude/skills/$skill_name/SKILL.md" >>"$SANDBOX/.git/info/exclude"
+    fi
     log_info "Injected dev skill: $skill_name"
   done <<<"$combined"
 }

package/src/gate/stages.ts

@@ -296,6 +296,20 @@ export const STAGES: readonly Stage[] = [
     ],
     success: 'Seed prose cites no toolkit CLI',
   },
+  {
+    // A hook, a workflow, or a husky script reaching one side of the seed or
+    // config boundary and not the other is a capability withheld with no
+    // recorded reason, per the criterion in .claude/ARCHITECTURE.md.
+    id: 'capability-seeding',
+    label: 'Capability seeding',
+    checks: [
+      script(
+        'check-capability-seeding.sh',
+        'A capability reaches one side of the seed or config boundary and not the other.',
+      ),
+    ],
+    success: 'Capability seeding clean',
+  },
   {
     // A stack entry naming a rule folder takes every rule in it, which is what
     // stops a new rule from needing a second edit to reach a target. The

package/tooling/claude/seeds/.claude/hooks/pr-create-log.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+
+# Reminds a worker session of the pull-request announcement it owes and logs
+# the creation as a denominator for the miss rate `claude-worker` cannot
+# measure on its own. Follows path-form.sh's precedent: a PostToolUse hook
+# returning hookSpecificOutput.additionalContext is the shipped route back
+# into a session's own turn.
+#
+# The hook cannot know whether the announcement went out, only that a pull
+# request now exists to announce. It states the obligation and counts the
+# creation, and claims nothing about the send.
+
+# Claude Code sends a payload and closes stdin. A bare read with nothing
+# feeding it blocks forever and holds the session open, so the read is
+# bounded. `read` rather than `timeout cat`, which macOS does not ship.
+IFS= read -r -d '' -t 2 input
+[ -n "$input" ] || {
+  printf '%s reads a Claude Code hook payload on stdin and cannot be run by hand.\n' "${0##*/}" >&2
+  exit 1
+}
+
+command=$(printf '%s' "$input" | jq -r '.tool_input.command // empty')
+case "$command" in
+*"gh pr create"*) ;;
+*) exit 0 ;;
+esac
+
+# gh pr create prints the new pull request's URL to stdout on success, so
+# matching it is what tells a creation apart from a failed or refused call.
+stdout=$(printf '%s' "$input" | jq -r '.tool_response.stdout // empty')
+url=$(printf '%s' "$stdout" | grep -Eo 'https://github\.com/[^[:space:]]+/pull/[0-9]+' | tail -1)
+[ -n "$url" ] || exit 0
+
+# CLAUDE_PROJECT_DIR is the session's own worktree rather than the main root,
+# so a worker building in a linked worktree would log into a folder that dies
+# with the worktree. The log is a denominator across a wave rather than a
+# per-session record, so strip back to the main root the way tasks-index.sh
+# and memory-index.sh already derive theirs, off a path suffix.
+root="${CLAUDE_PROJECT_DIR:-.}"
+case "$root" in
+*/.claude/worktrees/*) root="${root%/.claude/worktrees/*}" ;;
+esac
+# The log is scratch, so it follows the scratch folder to whichever record root
+# the project carries rather than creating a second one beside it.
+if [ -d "$root/.canon" ]; then
+  log_dir="$root/.canon/tmp/pr-create-log"
+else
+  log_dir="$root/.claude/.tmp/pr-create-log"
+fi
+mkdir -p "$log_dir"
+session=$(printf '%s' "$input" | jq -r '.session_id // "unknown"')
+printf -- '- %s session=%s pr=%s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$session" "$url" >>"$log_dir/log.md"
+
+msg="Pull request $url just opened. If this session holds a worker's channel obligation, announce it to the controller now, per claude-worker."
+jq -nc --arg msg "$msg" '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'

package/tooling/claude/seeds/.claude/settings.json

@@ -41,6 +41,15 @@
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/path-form.sh"
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/pr-create-log.sh"
+          }
+        ]
       }
     ]
   }