crewly 1.20.376 → 1.20.379

package/config/hooks/destructive-git-guard/guard.mjs

@@ -22,11 +22,27 @@
 // The check asks GitHub through `gh` (CREWLY_GUARD_GH overrides the binary); when it cannot
 // ask, the merge is blocked. CREWLY_GUARD_MERGE_CHECK=0 turns it off.
 //
+// Local gate (private repos whose CI cannot run): a merge that CI would block (a check not green,
+// or none to show the merge works) is accepted when ALL of: the repo has an entry in
+// local-gates.json; every changed file (and every renamed-from path) matches that entry's
+// contentPaths; `record-local-gate` recorded exitCode 0 for exactly the PR head SHA; the record
+// was made against the current base head (or the PR is not behind); and no check really failed
+// (a job that never started because GitHub billing/spending limits stopped it counts as absent).
+// Anything else is blocked as before, and the message says what is missing. The record is a file
+// the agent could write by hand: a speed bump, not a boundary. A repo with "codePrs": true also
+// accepts a PR with non-content files, but only with a TL marker for the same head SHA written by
+// `record-tl-verification` (a team leader other than the session that ran the gate). A PR more than
+// CREWLY_GUARD_MERGE_MAX_BEHIND commits behind is still blocked.
+//
 // Coverage limits: an interpreter one-liner (python -c, node -e), a command built at
 // runtime ($VAR, base64, a script the agent writes then runs) and `$(...)` inside
 // double quotes are NOT seen. A speed bump, not a boundary (same as control-plane-guard).
 
 import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 const PREFIX = 'destructive-git-guard:';
 const PROTECTED_BRANCHES = new Set(['main', 'master']);
@@ -183,6 +199,135 @@ function checkState(c) {
 	return { name, green: done && GREEN.has(String(c.conclusion || '').toUpperCase()), at: c.completedAt || c.startedAt };
 }
 
+
+/** Repos with a local-gate path (config next to this file; CREWLY_GUARD_LOCAL_GATES overrides). */
+const LOCAL_GATES_FILE = process.env.CREWLY_GUARD_LOCAL_GATES || join(dirname(fileURLToPath(import.meta.url)), 'local-gates.json');
+/** Where `record-local-gate` writes its records. */
+const LOCAL_GATES_DIR = join(process.env.CREWLY_HOME || join(homedir(), '.crewly'), 'local-gates');
+/** GitHub's own wording for a job that never started because of billing or the spending limit. */
+const NOT_STARTED_RE = /was not started because/i;
+/** The files endpoint stops at 3000 files; a PR that large is not a content PR. */
+const FILES_CAP = 3000;
+
+/** Glob (`**` crosses directories, `*` does not) to an anchored RegExp. */
+function globToRegExp(glob) {
+	let re = '';
+	for (let i = 0; i < glob.length; i += 1) {
+		const c = glob[i];
+		if (c === '*' && glob[i + 1] === '*') {
+			if (glob[i + 2] === '/') {
+				re += '(?:.*/)?';
+				i += 2;
+			} else {
+				re += '.*';
+				i += 1;
+			}
+		} else if (c === '*') re += '[^/]*';
+		else re += c.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+	}
+	return new RegExp(`^${re}$`);
+}
+
+/** The local-gates entry for `slug` (owner/name), or null (no file, bad file, no entry). */
+function localGateEntry(slug) {
+	try {
+		const entry = JSON.parse(readFileSync(LOCAL_GATES_FILE, 'utf8'))?.[slug];
+		if (!entry || !Array.isArray(entry.contentPaths) || entry.contentPaths.length === 0) return null;
+		return entry;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * True when a CI check did not run at all: a finished job with no steps whose annotation says GitHub
+ * never started it (billing / spending limit). Anything else non-green, including a check we cannot
+ * inspect, is a real failure (fail closed). Two cheap `gh api` calls, only for non-green checks.
+ */
+function checkNeverRan(c, api, dir) {
+	try {
+		const m = /\/actions\/runs\/\d+\/job\/(\d+)/.exec(String(c.detailsUrl || ''));
+		if (!m || c.__typename === 'StatusContext' || String(c.status || '').toUpperCase() !== 'COMPLETED') return false;
+		if (Number(gh(['api', `${api}/actions/jobs/${m[1]}`, '--jq', '.steps | length'], dir)) !== 0) return false;
+		return NOT_STARTED_RE.test(gh(['api', `${api}/check-runs/${m[1]}/annotations`, '--jq', '[.[].message] | join("\n")'], dir));
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * May this merge go ahead on a recorded local green run instead of CI?
+ * @returns {{ok: true, note: string} | {ok: false, why: string}}
+ */
+function judgeLocalGate(pr, slug, api, base, behind, realFailures, dir) {
+	const entry = localGateEntry(slug);
+	if (!entry) return { ok: false, why: `no local-gates entry for ${slug}` };
+	if (realFailures.length > 0) return { ok: false, why: `a check really failed (${realFailures.slice(0, 5).join(', ')}); a local run does not override it` };
+	const matchers = entry.contentPaths.map(globToRegExp);
+	let files;
+	try {
+		files = gh(['api', '--paginate', `${api}/pulls/${pr.number}/files`, '--jq', '.[] | [.filename, (.previous_filename // "")] | @tsv'], dir)
+			.split('\n')
+			.filter(Boolean)
+			.map((l) => l.split('\t'));
+	} catch {
+		return { ok: false, why: 'could not list the PR files to check it is content-only' };
+	}
+	if (files.length === 0 || files.length >= FILES_CAP) return { ok: false, why: `the PR file list is empty or too long to check (${files.length})` };
+	const outside = [...new Set(files.flatMap(([f, prev]) => [f, prev]).filter(Boolean).filter((f) => !matchers.some((re) => re.test(f))))];
+	// A code PR (a file outside contentPaths) needs the repo's opt-in `codePrs` plus a TL marker below.
+	const codePr = outside.length > 0;
+	if (codePr && entry.codePrs !== true) {
+		return { ok: false, why: `not content-only, non-content files: ${outside.slice(0, 5).join(', ')}${outside.length > 5 ? `, +${outside.length - 5} more` : ''}` };
+	}
+	const file = join(LOCAL_GATES_DIR, slug.replace('/', '__'), `pr-${pr.number}-${pr.headRefOid}.json`);
+	const fix = `run record-local-gate --repo ${slug} --pr ${pr.number}`;
+	if (!existsSync(file)) return { ok: false, why: `no local-gate record at ${String(pr.headRefOid).slice(0, 10)} (${fix})` };
+	let rec;
+	try {
+		rec = JSON.parse(readFileSync(file, 'utf8'));
+	} catch {
+		return { ok: false, why: `the local-gate record ${file} is unreadable (${fix})` };
+	}
+	if (rec?.sha !== pr.headRefOid) return { ok: false, why: `the local-gate record is for another commit (${fix})` };
+	if (rec.exitCode !== 0) return { ok: false, why: `the local gate at ${String(pr.headRefOid).slice(0, 10)} failed (exit ${rec.exitCode})` };
+	if (behind > 0) {
+		let baseHead;
+		try {
+			baseHead = gh(['api', `${api}/commits/${encodeURIComponent(base)}`, '--jq', '.sha'], dir);
+		} catch {
+			return { ok: false, why: `could not read the head of ${base} to check the record is not stale` };
+		}
+		if (rec.baseSha !== baseHead) return { ok: false, why: `stale: the record was made against ${String(rec.baseSha).slice(0, 10)} but ${base} is now at ${baseHead.slice(0, 10)} (re-run record-local-gate)` };
+	}
+	let tl = '';
+	if (codePr) {
+		const dir2 = join(LOCAL_GATES_DIR, slug.replace('/', '__'));
+		const markerFix = `a team leader runs record-tl-verification --repo ${slug} --pr ${pr.number} --summary "<what you checked>"`;
+		const markerFile = join(dir2, `pr-${pr.number}-${pr.headRefOid}.tl.json`);
+		if (!existsSync(markerFile)) {
+			let other = [];
+			try {
+				other = readdirSync(dir2).filter((f) => f.startsWith(`pr-${pr.number}-`) && f.endsWith('.tl.json'));
+			} catch {
+				other = [];
+			}
+			return { ok: false, why: other.length > 0 ? `the TL verification marker is for another commit, not ${String(pr.headRefOid).slice(0, 10)} (${markerFix})` : `code PR (${outside.slice(0, 3).join(', ')}${outside.length > 3 ? ', ...' : ''}): no TL verification marker at ${String(pr.headRefOid).slice(0, 10)} (${markerFix})` };
+		}
+		let marker;
+		try {
+			marker = JSON.parse(readFileSync(markerFile, 'utf8'));
+		} catch {
+			return { ok: false, why: `the TL verification marker ${markerFile} is unreadable (${markerFix})` };
+		}
+		if (marker?.sha !== pr.headRefOid) return { ok: false, why: `the TL verification marker is for another commit (${markerFix})` };
+		if (typeof marker.verifier !== 'string' || marker.verifier === '') return { ok: false, why: 'the TL verification marker names no verifier' };
+		if (marker.verifier === rec.recordedBy) return { ok: false, why: `the TL verification marker was written by the session that ran the gate (${marker.verifier}); another team leader must verify` };
+		tl = `; TL verified by ${marker.verifier} (gate run by ${rec.recordedBy ?? '?'}): ${String(marker.summary ?? '').slice(0, 120)}`;
+	}
+	return { ok: true, note: `local gate accepted for PR #${pr.number} in place of CI: record ${file} (head ${String(pr.headRefOid).slice(0, 10)}, exit 0, finished ${rec.finishedAt ?? '?'}, ${files.length} ${codePr ? 'file(s), code PR' : 'content file(s)'})${tl}` };
+}
+
 /** @returns {string|null} why `gh pr merge <rest>` is not a verified merge, or null. */
 function judgePrMerge(rest, dir) {
 	if (!MERGE_CHECK_ON || rest.includes('--disable-auto')) return null;
@@ -217,17 +362,31 @@ function judgePrMerge(rest, dir) {
 	if (!Number.isFinite(behind)) return `could not compare PR #${pr.number} with ${base} on GitHub`;
 	const n = pr.number;
 	if (behind > MERGE_MAX_BEHIND) return `PR #${n} is ${behind} commits behind ${base} (more than ${MERGE_MAX_BEHIND}); its CI did not run on what the merge would produce`;
-	const checks = (Array.isArray(pr.statusCheckRollup) ? pr.statusCheckRollup : []).map(checkState);
-	const notGreen = checks.filter((c) => !c.green).map((c) => c.name);
-	if (notGreen.length > 0) return `CI is not green on PR #${n} (${notGreen.slice(0, 5).join(', ')})`;
-	if (behind > 0) {
-		if (checks.length === 0) return `PR #${n} is ${behind} commit(s) behind ${base} and has no CI run to show the merge result works`;
-		const latest = Math.max(...checks.map((c) => Date.parse(c.at || '')).filter((t) => Number.isFinite(t)));
-		if (!Number.isFinite(latest) || (Number.isFinite(baseAt) && latest < baseAt)) {
-			return `PR #${n}'s latest CI run predates the head of ${base} (the PR is ${behind} commit(s) behind)`;
+	const rollup = Array.isArray(pr.statusCheckRollup) ? pr.statusCheckRollup : [];
+	const checks = rollup.map((c) => ({ ...checkState(c), raw: c }));
+	const notGreen = checks.filter((c) => !c.green);
+	// A CI-state problem (not the behind-limit above): the local gate may stand in for CI.
+	let ciReason = null;
+	let realFailures = [];
+	if (notGreen.length > 0) {
+		ciReason = `CI is not green on PR #${n} (${notGreen.slice(0, 5).map((c) => c.name).join(', ')})`;
+		realFailures = notGreen.filter((c) => !checkNeverRan(c.raw, api, dir)).map((c) => c.name);
+	} else if (behind > 0) {
+		if (checks.length === 0) ciReason = `PR #${n} is ${behind} commit(s) behind ${base} and has no CI run to show the merge result works`;
+		else {
+			const latest = Math.max(...checks.map((c) => Date.parse(c.at || '')).filter((t) => Number.isFinite(t)));
+			if (!Number.isFinite(latest) || (Number.isFinite(baseAt) && latest < baseAt)) {
+				ciReason = `PR #${n}'s latest CI run predates the head of ${base} (the PR is ${behind} commit(s) behind)`;
+			}
 		}
 	}
-	return null;
+	if (ciReason === null) return null;
+	const local = judgeLocalGate({ number: n, headRefOid: pr.headRefOid }, `${m[1]}/${m[2]}`, api, base, behind, realFailures, dir);
+	if (local.ok) {
+		process.stdout.write(`${PREFIX} ${local.note}\n`);
+		return null;
+	}
+	return `${ciReason}; local gate: ${local.why}`;
 }
 
 let checked = 0;

package/config/hooks/destructive-git-guard/local-gates.json

@@ -0,0 +1,13 @@
+{
+	"_comment": "Repos whose CI cannot run (private repos, GitHub Actions billing off). For these, `gh pr merge` of a CONTENT-ONLY PR is accepted when `record-local-gate` recorded a green local run at the PR head. A repo without an entry here gets no such path. gate = commands run in order in a fresh clone of the PR head; contentPaths = the files a content PR may touch (glob: ** crosses directories, * stays inside one); codePrs: true = a PR with other files may also merge, but only with a TL verification marker for its head.",
+	"stevehuang0115/crewly-web": {
+		"gate": [
+			"npm ci --ignore-scripts --no-audit --no-fund",
+			"npx tsc --noEmit",
+			"npx vitest run --maxWorkers=2 --retry=1",
+			"npm run build"
+		],
+		"contentPaths": ["content/blog/**/*.md"],
+		"codePrs": true
+	}
+}

package/config/skills/agent/core/record-local-gate/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: Record Local Gate
+description: Run a private repo's gate on a PR's exact head in a fresh clone and record the result, so a content-only PR can merge when GitHub Actions cannot run.
+version: 1.0.0
+category: development
+skillType: claude-skill
+assignableRoles:
+  - developer
+  - fullstack-dev
+  - backend-developer
+  - frontend-developer
+  - generalist
+triggers:
+  - record local gate
+  - local green build
+  - ci cannot run
+  - merge content pr without ci
+tags:
+  - merge
+  - ci
+  - guard
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 1800000
+---
+
+# Record Local Gate
+
+Some private repos cannot run GitHub Actions (billing is off). `destructive-git-guard` blocks `gh pr merge` unless CI is green, so their PRs could never merge. For a repo listed in `config/hooks/destructive-git-guard/local-gates.json`, the guard accepts a recorded local run instead, for **content-only** PRs.
+
+## Use
+
+```bash
+bash config/skills/agent/core/record-local-gate/execute.sh --repo stevehuang0115/crewly-web --pr 285
+```
+
+It reads the PR head SHA with `gh`, checks that exact SHA out in a fresh temporary clone (never your working tree), runs the repo's gate commands with a scrubbed environment, and writes `$CREWLY_HOME/local-gates/<owner>__<repo>/pr-<N>-<sha>.json` (sha, baseRef, baseSha, command, exitCode, start and finish times, last 40 log lines, recordedBy). It prints what it ran and the exit code, and exits non-zero when the gate fails (the failing record is still written). There is no `--exit-code` flag: a record is never handed in.
+
+Then `gh pr merge` goes through the guard. The guard accepts only when ALL hold: the repo has an entry; every changed file (and renamed-from path) matches the entry's `contentPaths`; a record exists for exactly the PR head with exit 0; the record's base head is still the base head (or the PR is not behind); no check actually ran and failed. Push a new commit and the record no longer matches: run this again.
+
+## Limits
+
+The record is a file on disk. It is a speed bump, like the guard itself, not a boundary: someone who can write files can forge it. It does not replace review, and code PRs get no such path.

package/config/skills/agent/core/record-local-gate/execute.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+# record-local-gate — run a repo's gate on a PR's exact head commit in a FRESH clone and
+# record the result for destructive-git-guard (gh pr merge of a content-only PR whose CI
+# cannot run). There is no way to pass an exit code in: the record is only ever the real
+# result of the commands in local-gates.json. See config/hooks/destructive-git-guard/guard.mjs.
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+GH="${CREWLY_GUARD_GH:-gh}"
+GATES="${CREWLY_GUARD_LOCAL_GATES:-${SCRIPT_DIR}/../../../../hooks/destructive-git-guard/local-gates.json}"
+RECORDS_ROOT="${CREWLY_HOME:-$HOME/.crewly}/local-gates"
+LOG_TAIL_LINES=40
+
+usage() {
+  cat <<'EOF_USAGE'
+Usage: bash execute.sh --repo owner/name --pr N
+Runs the repo's gate (config/hooks/destructive-git-guard/local-gates.json) on the PR head in a
+fresh temporary clone and writes $CREWLY_HOME/local-gates/<owner>__<repo>/pr-<N>-<sha>.json.
+Exits non-zero when the gate fails (the record is still written, with the failing exit code).
+EOF_USAGE
+}
+
+fail() { printf '{"error":%s}\n' "$(jq -Rn --arg e "$1" '$e')" >&2; exit "${2:-1}"; }
+
+REPO=""; PR=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --repo) REPO="${2:-}"; shift 2 ;;
+    --pr) PR="${2:-}"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) usage >&2; fail "unknown argument: $1 (this skill takes only --repo and --pr; a record cannot be hand-made)" 2 ;;
+  esac
+done
+[[ "$REPO" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || fail "--repo owner/name is required" 2
+[[ "$PR" =~ ^[0-9]+$ ]] || fail "--pr <number> is required" 2
+command -v jq >/dev/null || fail "jq is required"
+
+ENTRY="$(jq -c --arg r "$REPO" '.[$r] // empty' "$GATES" 2>/dev/null)"
+[ -n "$ENTRY" ] || fail "no local-gates entry for $REPO in $GATES; this repo has no local-gate path (its CI is the only way)"
+N_CMDS="$(printf '%s' "$ENTRY" | jq '.gate | length')"
+[ "${N_CMDS:-0}" -gt 0 ] || fail "the local-gates entry for $REPO has no gate commands"
+
+VIEW="$("$GH" pr view "$PR" -R "$REPO" --json headRefOid,baseRefName 2>&1)" || fail "could not read PR #$PR with gh: $VIEW"
+SHA="$(printf '%s' "$VIEW" | jq -r .headRefOid)"
+BASE_REF="$(printf '%s' "$VIEW" | jq -r .baseRefName)"
+[[ "$SHA" =~ ^[0-9a-f]{7,64}$ ]] || fail "gh returned no head commit for PR #$PR"
+BASE_SHA="$("$GH" api "repos/$REPO/commits/$BASE_REF" --jq .sha 2>&1)" || fail "could not read the head of $BASE_REF: $BASE_SHA"
+
+WORK="$(mktemp -d "${TMPDIR:-/tmp}/local-gate.XXXXXX")" || fail "could not make a temp dir"
+trap 'rm -rf "$WORK"' EXIT
+CLONE="$WORK/clone"; LOG="$WORK/gate.log"; : > "$LOG"
+URL="${CREWLY_LOCAL_GATE_CLONE_URL:-https://github.com/$REPO.git}"
+
+git init -q "$CLONE" || fail "git init failed"
+(
+  cd "$CLONE" || exit 1
+  git remote add origin "$URL"
+  git -c credential.helper= -c "credential.helper=!$GH auth git-credential" fetch -q --depth 1 origin "pull/$PR/head" \
+    && [ "$(git rev-parse FETCH_HEAD)" = "$SHA" ] \
+    && git checkout -q --detach FETCH_HEAD
+) >"$WORK/fetch.log" 2>&1 || fail "could not check out PR #$PR at $SHA in a fresh clone (the PR may have moved): $(tail -3 "$WORK/fetch.log" | tr '\n' ' ')"
+
+echo "record-local-gate: $REPO PR #$PR at $SHA (base $BASE_REF $BASE_SHA), $N_CMDS gate command(s), fresh clone $CLONE"
+STARTED="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+EXIT_CODE=0; RAN=""
+while IFS= read -r CMD; do
+  [ -n "$CMD" ] || continue
+  RAN="${RAN:+$RAN && }$CMD"
+  echo "record-local-gate: running: $CMD"
+  # A scrubbed environment: no tokens or session secrets reach the repo's scripts.
+  (cd "$CLONE" && env -i PATH="$PATH" HOME="$HOME" TMPDIR="${TMPDIR:-/tmp}" LANG="${LANG:-en_US.UTF-8}" CI=true bash -c "set -o pipefail; $CMD") 2>&1 | tee -a "$LOG"
+  RC="${PIPESTATUS[0]}"
+  if [ "$RC" -ne 0 ]; then EXIT_CODE="$RC"; echo "record-local-gate: FAILED (exit $RC): $CMD"; break; fi
+done < <(printf '%s' "$ENTRY" | jq -r '.gate[]')
+FINISHED="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+DIR="$RECORDS_ROOT/${REPO/\//__}"
+mkdir -p "$DIR" || fail "could not create $DIR"
+OUT="$DIR/pr-$PR-$SHA.json"
+tail -n "$LOG_TAIL_LINES" "$LOG" | jq -Rs --arg sha "$SHA" --arg baseRef "$BASE_REF" --arg baseSha "$BASE_SHA" --arg command "$RAN" \
+  --argjson exitCode "$EXIT_CODE" --arg startedAt "$STARTED" --arg finishedAt "$FINISHED" --arg by "${CREWLY_SESSION_NAME:-unknown}" \
+  '{sha:$sha, baseRef:$baseRef, baseSha:$baseSha, command:$command, exitCode:$exitCode, startedAt:$startedAt, finishedAt:$finishedAt, logTail:(split("\n")|map(select(length>0))), recordedBy:$by}' \
+  > "$OUT.tmp" && mv "$OUT.tmp" "$OUT" || fail "could not write the record $OUT"
+
+echo "record-local-gate: ran $RAN"
+echo "record-local-gate: exit code $EXIT_CODE; record: $OUT"
+exit "$EXIT_CODE"

package/config/skills/agent/core/record-local-gate/execute.test.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+# Tests for record-local-gate. Offline: `gh` is a stub, the "remote" is a local repo with
+# refs/pull/7/head, and the gate commands are `true` / `false`.
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PASS=0; FAIL=0
+check() {
+  if [ "$2" = "$3" ]; then PASS=$((PASS + 1)); echo "  ✓ $1"
+  else FAIL=$((FAIL + 1)); echo "  ✗ $1"; echo "    expected: $2"; echo "    actual:   $3"; fi
+}
+
+T="$(mktemp -d)"; trap 'rm -rf "$T"' EXIT
+REMOTE="$T/remote"
+git init -q -b main "$REMOTE"
+git -C "$REMOTE" -c user.name=t -c user.email=t@t commit -q --allow-empty -m base
+git -C "$REMOTE" -c user.name=t -c user.email=t@t commit -q --allow-empty -m pr
+SHA="$(git -C "$REMOTE" rev-parse HEAD)"
+git -C "$REMOTE" update-ref refs/pull/7/head "$SHA"
+
+# gh stub: pr view -> head sha + base; api commits/main --jq .sha -> base sha
+cat > "$T/gh" <<EOF
+#!/bin/bash
+if [ "\$1" = pr ] && [ "\$2" = view ]; then echo '{"headRefOid":"'"\${PR_SHA:-$SHA}"'","baseRefName":"main"}'; exit 0; fi
+if [ "\$1" = api ]; then echo basesha0001; exit 0; fi
+exit 3
+EOF
+chmod +x "$T/gh"
+
+gates() { printf '{"o/r":{"gate":%s,"contentPaths":["content/**/*.md"]}}' "$1" > "$T/gates.json"; }
+export CREWLY_GUARD_GH="$T/gh" CREWLY_GUARD_LOCAL_GATES="$T/gates.json" CREWLY_HOME="$T/home" \
+  CREWLY_LOCAL_GATE_CLONE_URL="$REMOTE" CREWLY_SESSION_NAME=tester TMPDIR="$T"
+REC="$T/home/local-gates/o__r/pr-7-$SHA.json"
+run() { bash "$SCRIPT_DIR/execute.sh" "$@" >"$T/out" 2>"$T/err"; echo $?; }
+
+echo "record-local-gate"
+gates '["true","echo second"]'
+check "passing gate exits 0" 0 "$(run --repo o/r --pr 7)"
+check "record exists for the head sha" yes "$([ -f "$REC" ] && echo yes || echo no)"
+check "record sha is the PR head" "$SHA" "$(jq -r .sha "$REC")"
+check "record exitCode 0" 0 "$(jq .exitCode "$REC")"
+check "record keeps the base sha at run time" basesha0001 "$(jq -r .baseSha "$REC")"
+check "record names who recorded it" tester "$(jq -r .recordedBy "$REC")"
+check "record lists the commands run" "true && echo second" "$(jq -r .command "$REC")"
+check "output says what ran and the exit code" 1 "$(grep -c 'exit code 0; record:' "$T/out")"
+
+rm -f "$REC"
+gates '["true","false","echo never"]'
+check "failing gate exits non-zero" 1 "$(run --repo o/r --pr 7)"
+check "failing gate still writes a record" yes "$([ -f "$REC" ] && echo yes || echo no)"
+check "failing record has exitCode != 0" 1 "$(jq .exitCode "$REC")"
+check "gate stops at the first failure" 0 "$(grep -c '^never' "$T/out")"
+
+rm -f "$REC"
+gates '["true"]'
+check "--exit-code is refused" 2 "$(run --repo o/r --pr 7 --exit-code 0)"
+check "no record after a refused flag" no "$([ -f "$REC" ] && echo yes || echo no)"
+check "a repo with no entry is refused" 1 "$(run --repo x/y --pr 7)"
+check "a missing --pr is refused" 2 "$(run --repo o/r)"
+
+check "a PR that moved since gh looked is refused" 1 "$(PR_SHA=deadbeefdeadbeef run --repo o/r --pr 7)"
+check "no record for the moved head" 0 "$(find "$T/home" -name 'pr-7-deadbeef*' 2>/dev/null | wc -l | tr -d ' ')"
+
+echo "Passed: $PASS  Failed: $FAIL"
+[ "$FAIL" -eq 0 ] && [ "$PASS" -gt 0 ]

package/config/skills/agent/core/record-tl-verification/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: Record TL Verification
+description: A team leader's marker that a code PR in a CI-less private repo was verified at its exact head; the merge guard needs it next to a green local gate record.
+version: 1.0.0
+category: development
+skillType: claude-skill
+assignableRoles:
+  - team-leader
+triggers:
+  - record tl verification
+  - verify code pr without ci
+  - tl marker for merge
+tags:
+  - merge
+  - guard
+  - review
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 60000
+---
+
+# Record TL Verification
+
+For a repo with `"codePrs": true` in `config/hooks/destructive-git-guard/local-gates.json` (today: crewly-web), a PR with non-content files merges without CI only when (1) `record-local-gate` recorded a passing run at the PR head and (2) a team leader verified that same head. This skill is (2).
+
+```bash
+bash config/skills/agent/core/record-tl-verification/execute.sh --repo stevehuang0115/crewly-web --pr 266 --summary "read the diff, gate green at head, behaviour checked"
+```
+
+It refuses unless: the repo is enabled for code PRs; your session has role `team-leader` in a team config; a passing gate record exists at the PR's current head; and you are not the session that ran that gate (GitHub cannot tell agents apart, so the gate runner stands in for the author). It writes `pr-<N>-<sha>.tl.json` with the SHA, your session, the gate runner and your one-line summary; the guard prints both sessions when it accepts.
+
+A new commit changes the head: gate and marker must both be redone. Verify by reading the diff and the gate result, not by trusting the author's report.
+
+## Limits
+
+The marker is a file, so like the guard it is a speed bump, not a boundary: the role check reads team configs and `CREWLY_SESSION_NAME`, which a determined session could fake.

package/config/skills/agent/core/record-tl-verification/execute.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+# record-tl-verification — a team leader's verification marker for a CODE PR in a repo whose CI
+# cannot run. destructive-git-guard needs it, next to a green record-local-gate record, before it
+# lets `gh pr merge` through (local-gates.json "codePrs": true). The caller must be a team leader
+# (role "team-leader" in a team config under ~/.crewly/teams) and must not be the session that ran
+# the gate. A marker is for one head SHA: a new commit needs a new verification.
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+GH="${CREWLY_GUARD_GH:-gh}"
+GATES="${CREWLY_GUARD_LOCAL_GATES:-${SCRIPT_DIR}/../../../../hooks/destructive-git-guard/local-gates.json}"
+RECORDS_ROOT="${CREWLY_HOME:-$HOME/.crewly}/local-gates"
+TEAMS_DIR="${CREWLY_TEAMS_DIR:-$HOME/.crewly/teams}"
+
+usage() {
+  cat <<'EOF_USAGE'
+Usage: bash execute.sh --repo owner/name --pr N --summary "one line: what you verified"
+Team leaders only. Needs a passing record-local-gate record at the PR's current head, made by
+another session. Writes $CREWLY_HOME/local-gates/<owner>__<repo>/pr-<N>-<sha>.tl.json.
+EOF_USAGE
+}
+
+fail() { printf '{"error":%s}\n' "$(jq -Rn --arg e "$1" '$e')" >&2; exit "${2:-1}"; }
+
+REPO=""; PR=""; SUMMARY=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --repo) REPO="${2:-}"; shift 2 ;;
+    --pr) PR="${2:-}"; shift 2 ;;
+    --summary) SUMMARY="${2:-}"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) usage >&2; fail "unknown argument: $1" 2 ;;
+  esac
+done
+[[ "$REPO" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || fail "--repo owner/name is required" 2
+[[ "$PR" =~ ^[0-9]+$ ]] || fail "--pr <number> is required" 2
+[ -n "$SUMMARY" ] || fail "--summary \"what you verified\" is required (one line)" 2
+command -v jq >/dev/null || fail "jq is required"
+
+jq -e --arg r "$REPO" '.[$r].codePrs == true' "$GATES" >/dev/null 2>&1 \
+  || fail "$REPO is not enabled for code PRs (no \"codePrs\": true in $GATES); a TL marker would be ignored"
+
+SESSION="${CREWLY_SESSION_NAME:-}"
+[ -n "$SESSION" ] || fail "CREWLY_SESSION_NAME is not set; the verifier cannot be identified"
+ROLE=""; CONFIGS=0
+for c in "$TEAMS_DIR"/*/config.json; do
+  [ -f "$c" ] || continue
+  CONFIGS=$((CONFIGS + 1))
+  r="$(jq -r --arg s "$SESSION" '[.members[]? | select(.sessionName == $s) | .role] | first // empty' "$c" 2>/dev/null)"
+  [ -n "$r" ] && { ROLE="$r"; break; }
+done
+[ "$CONFIGS" -gt 0 ] || fail "no team configs found under $TEAMS_DIR (0 checked); cannot confirm $SESSION is a team leader"
+[ "$ROLE" = "team-leader" ] || fail "only a team leader may record a TL verification ($SESSION has role '${ROLE:-unknown}')"
+
+SHA="$("$GH" pr view "$PR" -R "$REPO" --json headRefOid --jq .headRefOid 2>&1)" || fail "could not read PR #$PR with gh: $SHA"
+[[ "$SHA" =~ ^[0-9a-f]{7,64}$ ]] || fail "gh returned no head commit for PR #$PR"
+
+DIR="$RECORDS_ROOT/${REPO/\//__}"
+REC="$DIR/pr-$PR-$SHA.json"
+[ -f "$REC" ] || fail "no local-gate record at ${SHA:0:10}; run record-local-gate --repo $REPO --pr $PR first"
+[ "$(jq -r '.sha' "$REC")" = "$SHA" ] && [ "$(jq -r '.exitCode' "$REC")" = "0" ] || fail "the local-gate record at ${SHA:0:10} is not a passing run for this head"
+RECORDER="$(jq -r '.recordedBy // empty' "$REC")"
+[ "$RECORDER" != "$SESSION" ] || fail "$SESSION ran the gate for this PR; another team leader must verify it"
+
+OUT="$DIR/pr-$PR-$SHA.tl.json"
+jq -n --arg sha "$SHA" --arg verifier "$SESSION" --arg role "$ROLE" --arg recorder "$RECORDER" --arg summary "$SUMMARY" \
+  --arg at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+  '{sha:$sha, verifier:$verifier, role:$role, gateRecordedBy:$recorder, summary:$summary, recordedAt:$at}' > "$OUT.tmp" \
+  && mv "$OUT.tmp" "$OUT" || fail "could not write $OUT"
+
+echo "record-tl-verification: $SESSION (team-leader) verified $REPO PR #$PR at $SHA; gate run by ${RECORDER:-unknown}; marker: $OUT"

package/config/skills/agent/core/record-tl-verification/execute.test.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# Tests for record-tl-verification. Offline: `gh` is a stub, team configs and records are temp files.
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PASS=0; FAIL=0
+check() {
+  if [ "$2" = "$3" ]; then PASS=$((PASS + 1)); echo "  ✓ $1"
+  else FAIL=$((FAIL + 1)); echo "  ✗ $1"; echo "    expected: $2"; echo "    actual:   $3"; fi
+}
+
+T="$(mktemp -d)"; trap 'rm -rf "$T"' EXIT
+SHA=0123456789abcdef0123456789abcdef01234567
+cat > "$T/gh" <<EOF
+#!/bin/bash
+echo "\${PR_SHA:-$SHA}"
+EOF
+chmod +x "$T/gh"
+mkdir -p "$T/teams/t1" "$T/home/local-gates/o__r"
+printf '{"members":[{"sessionName":"tl1","role":"team-leader"},{"sessionName":"tl2","role":"team-leader"},{"sessionName":"dev1","role":"developer"}]}' > "$T/teams/t1/config.json"
+printf '{"o/r":{"gate":["true"],"contentPaths":["c/**"],"codePrs":true},"o/nocode":{"gate":["true"],"contentPaths":["c/**"]}}' > "$T/gates.json"
+REC="$T/home/local-gates/o__r/pr-9-$SHA.json"
+MARK="$T/home/local-gates/o__r/pr-9-$SHA.tl.json"
+rec() { printf '{"sha":"%s","exitCode":%s,"recordedBy":"dev1"}' "${2:-$SHA}" "${1:-0}" > "$REC"; }
+export CREWLY_GUARD_GH="$T/gh" CREWLY_GUARD_LOCAL_GATES="$T/gates.json" CREWLY_HOME="$T/home" CREWLY_TEAMS_DIR="$T/teams"
+run() { local who="$1"; shift; CREWLY_SESSION_NAME="$who" bash "$SCRIPT_DIR/execute.sh" "$@" >"$T/out" 2>"$T/err"; echo $?; }
+has() { [ -f "$MARK" ] && echo yes || echo no; }
+
+echo "record-tl-verification"
+rec 0
+check "a team leader other than the gate runner verifies" 0 "$(run tl1 --repo o/r --pr 9 --summary 'read the diff')"
+check "marker written" yes "$(has)"
+check "marker sha is the head" "$SHA" "$(jq -r .sha "$MARK")"
+check "marker names the verifier" tl1 "$(jq -r .verifier "$MARK")"
+check "marker names the gate runner" dev1 "$(jq -r .gateRecordedBy "$MARK")"
+check "marker keeps the summary" "read the diff" "$(jq -r .summary "$MARK")"
+
+rm -f "$MARK"
+check "a developer is refused" 1 "$(run dev1 --repo o/r --pr 9 --summary x)"
+check "an unknown session is refused" 1 "$(run nobody --repo o/r --pr 9 --summary x)"
+check "no marker after refusals" no "$(has)"
+rec 0; printf '{"sha":"%s","exitCode":0,"recordedBy":"tl1"}' "$SHA" > "$REC"
+check "the session that ran the gate is refused" 1 "$(run tl1 --repo o/r --pr 9 --summary x)"
+check "another leader may still verify that gate" 0 "$(run tl2 --repo o/r --pr 9 --summary x)"
+rm -f "$MARK"
+rec 1
+check "a failed gate record is refused" 1 "$(run tl1 --repo o/r --pr 9 --summary x)"
+rm -f "$REC"
+check "no gate record is refused" 1 "$(run tl1 --repo o/r --pr 9 --summary x)"
+rec 0
+check "a repo without codePrs is refused" 1 "$(run tl1 --repo o/nocode --pr 9 --summary x)"
+check "a missing summary is refused" 2 "$(run tl1 --repo o/r --pr 9)"
+check "a PR whose head moved has no record to verify" 1 "$(PR_SHA=feedfacefeedface run tl1 --repo o/r --pr 9 --summary x)"
+check "no marker for the moved head" 0 "$(find "$T/home" -name '*feedface*' | wc -l | tr -d ' ')"
+
+echo "Passed: $PASS  Failed: $FAIL"
+[ "$FAIL" -eq 0 ] && [ "$PASS" -gt 0 ]