yadflow 3.16.2 → 3.17.0

package/skills/yad-checks/templates/hooks/ledger-guard.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# ledger-guard HARNESS HOOK — the local half of the CI gate of the same name (#171).
+#
+# The gate ledger is CI-owned in bridge mode: `checks/ledger-guard.sh` rejects any non-bot commit
+# that changes `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json` or `epics/*/reviews/*.md`.
+# This hook says so at the moment an agent tries the edit, instead of twenty minutes later in a
+# failed pipeline, and names the command that owns the transition (`yad gate open`).
+#
+# This file is only the ADAPTER. It locates `yad` and hands the tool-call payload to
+# `yad hook ledger-guard`, which holds the decision — so the wiring never hard-codes an install path
+# and the logic stays testable. The contract it passes through:
+#
+#   stdin   the harness's tool-call payload as JSON (optional)
+#   exit 0  allow
+#   exit 2  deny, reason on stderr
+#
+# Wired for Claude Code as a `PreToolUse` hook in `.claude/settings.json` (`yad check --fix` writes
+# that entry). Any harness that can run a command and read those two exit codes can use it.
+#
+# FAIL-OPEN: if no `yad` can be found, this ALLOWS and says why on stderr. A guardrail that blocked
+# every edit the moment an install went sideways would be worse than the problem. The CI gate fails
+# CLOSED and is what actually protects the ledger.
+set -uo pipefail
+
+# The hub root is this script's grandparent — hooks/ledger-guard.sh — so the resolution below does
+# not depend on the harness's working directory.
+HOOK_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+HUB_ROOT="$(dirname -- "$HOOK_DIR")"
+
+# Resolution order, cheapest and most specific first: an explicit override, then the copy installed
+# in this hub, then whatever is on PATH, then a network-free npx. `--no-install` matters — a hook
+# runs on every tool call and must never pause an agent to download a package.
+CMD=()
+_yad_bin="${YAD_BIN:-}"
+if [ -n "${_yad_bin//[[:space:]]/}" ]; then
+  # Split deliberately: YAD_BIN is commonly an interpreter + script ("node /path/to/yad.mjs").
+  # The whitespace-stripped test above matters: a YAD_BIN of only spaces would leave CMD empty, and
+  # macOS's bash 3.2 treats "${CMD[@]}" on an empty array as an unbound variable under `set -u` —
+  # aborting the script with a confusing 127 instead of taking one of the branches below.
+  read -r -a CMD <<< "$_yad_bin"
+elif [ -f "$HUB_ROOT/node_modules/yadflow/bin/yad.mjs" ] && command -v node >/dev/null 2>&1; then
+  CMD=(node "$HUB_ROOT/node_modules/yadflow/bin/yad.mjs")
+elif command -v yad >/dev/null 2>&1; then
+  CMD=(yad)
+elif command -v npx >/dev/null 2>&1; then
+  CMD=(npx --no-install yadflow)
+else
+  echo "  • yad hook: no \`yad\` on PATH and none installed in $HUB_ROOT — allowing (install yadflow to re-arm the ledger guard)" >&2
+  exit 0
+fi
+
+# Belt and braces for bash 3.2's empty-array-is-unbound rule: every branch above sets CMD, but an
+# unexpanded array under `set -u` would abort the script rather than allow, so check before using it.
+if [ "${#CMD[@]}" -eq 0 ]; then
+  echo "  • yad hook: could not resolve a \`yad\` to run — allowing" >&2
+  exit 0
+fi
+
+# Run it rather than `exec`, so the exit code can be mapped. ONLY an explicit deny (2) blocks: a
+# `yad` that is present but cannot run — an `npx --no-install` with no yadflow to find, a crash, a
+# broken install — must not read as a refusal. Fail-open is the whole stance of this hook; the CI
+# gate is what fails closed.
+"${CMD[@]}" hook ledger-guard "$@"
+rc=$?
+[ "$rc" -eq 2 ] && exit 2
+if [ "$rc" -ne 0 ]; then
+  echo "  • yad hook: \`${CMD[*]} hook ledger-guard\` exited $rc — allowing (run \`yad doctor\` to check the install)" >&2
+fi
+exit 0

package/skills/yad-hub-bridge/SKILL.md

@@ -87,7 +87,9 @@ Install the hub CI that turns the human **merge** into a `yad gate ci` run, with
 writer** of the ledger. There is no pre-merge CI write — during review the platform PR/MR is the
 source of truth (native approvals + threads). On merge, CI re-reads approvals from the platform,
 advances the step, and flips the artifact `status:` on the **default branch** (the only place CI ever
-commits). Also install the `ledger-guard` check (yad-checks) so humans cannot commit gate-state files.
+commits). Also install the `ledger-guard` check (yad-checks) so humans cannot commit gate-state files,
+and its local counterpart `hooks/ledger-guard.sh` — the harness hook that refuses an **agent** the
+same write at the moment it tries it, instead of letting it surface as a CI failure later (#171).
 Revoke-on-change is enforced at merge: on **GitHub** in code (an approval whose commit ≠ the merged
 head is dropped — no setting needed); on **GitLab** it has no per-approval commit SHA, so enabling the
 platform's **"remove all approvals when commits are added to the source branch"** is **required** for

package/skills/yad-open-pr/SKILL.md

@@ -30,6 +30,17 @@ the product hub.
     (`## Summary` / `Risk level:` / `## Checklist`) instead of the hub's artifact-review
     `pull_request_template.md`, so the hub `pr-template` gate passes.
   In a code repo nothing changes — it reads the repo's own committed code-task template.
+- **Base branch** — **resolved, never assumed.** In order: `--base` → the repo's `default_branch` in
+  `.sdlc/repos.json` → (for a PR against the hub itself) `hub.json`'s `default_branch` → what the
+  platform reports (`gh repo view --json defaultBranchRef` / `glab api projects/:id`) → local
+  `origin/HEAD` → `main`. The same **configuration-outranks-the-remote** order `yad repo sync` and the
+  contract-check gate already use (they stop at `origin/HEAD`; only this chain also asks the platform).
+  The CLI prints which rung answered.
+  **If the resolved base is not the platform's default branch it warns and still opens** — that is a
+  legitimate stacked-PR / release-branch move, but it costs the AI first pass: CodeRabbit decides
+  auto-review eligibility from the base at PR-**open** time, and retargeting afterwards does not undo
+  the skip. Hardcoding `main` here is the same bug the check gates already refuse to make (see
+  `../yad-checks/references/check-gates.md`).
 - **Auto-assign** — from the hub roster scoped to this repo: assignee = the committer (resolved from
   the local git identity), reviewers = the repo's `reviewer`/`domain-owner` logins minus the committer.
   Degrades cleanly when there is no roster.
@@ -42,7 +53,9 @@ the product hub.
 - `repo`           — target a registered repo by name (optional; else the current dir).
 - `risk`           — `low|medium|high` (default `low`); prefilled into the body.
 - `contractChange` — flag; marks the contract surface touched and triggers escalation.
-- `base` / `platform` / `title` — optional overrides.
+- `base`           — override the PR/MR base (optional; defaults to the repo's own default branch —
+  see **Base branch** above). Only pass it deliberately: a non-default base loses the AI first pass.
+- `platform` / `title` — optional overrides.
 
 ## On Activation
 
@@ -56,7 +69,14 @@ Run from the repo root:
 yad open-pr [--repo <name>] [--risk <level>] [--contract-change] [--title "<subject>"]
 ```
 The CLI pushes the branch (sets upstream, the user's own auth), fills the template, and creates the
-PR/MR with the auto-assigned assignee + reviewers.
+PR/MR with the auto-assigned assignee + reviewers. It prints the base it resolved and where that came
+from.
+
+The non-default-base warning is **advisory — it does not block, and the PR/MR is already open by the
+time you read it.** If the base was intended (a stacked PR, a release branch), carry on. If it was
+not, do **not** just retarget the open PR — that leaves the AI first pass skipped. Close it, fix the
+cause (the repo's `default_branch`, or drop the wrong `--base`), and re-run `yad open-pr` so the PR
+is *created* against the right base.
 
 ### Step 3 — Route the review (if escalated)
 On `high` risk or a contract touch, run `bash checks/risk-route.sh <pr-body>` to print the required
@@ -79,6 +99,8 @@ engineer review and merge happen in `yad-engineer-review` (Step E).
 ## Hard rules
 
 - **One task = one branch = one PR/MR.** Never open a PR from the default branch.
+- **The base is the repo's default branch** unless you deliberately chose otherwise with `--base`.
+  Never hardcode `main`, and never ignore the non-default-base warning silently.
 - **Title follows the commit subject** — Conventional-Commits style, so the `pr-title` gate passes.
 - **High risk routes to domain owners** — the same escalation as the gate; never a separate rule.
 - **Opening a PR never merges.** The human owns the merge in Step E.

package/skills/yad-review-gate/SKILL.md

@@ -188,7 +188,9 @@ PR only — against the `review/<epic>/<artifact>` branch, which must already ex
 records this skill describes. The skill's
 job is the human half: presenting the artifact, helping the owner address comments, and narrating the
 gate. Local `yad gate sync` is advisory in bridge mode (reads the platform, prints status, writes
-nothing); a human must never commit gate-state files (the `ledger-guard` check rejects it). The single
+nothing); a human must never commit gate-state files (the `ledger-guard` check rejects it, and the
+`hooks/ledger-guard.sh` harness hook refuses an agent the edit up front, naming `yad gate open`
+instead — see `yad-checks`). The single
 exception is an epic's **seed** — no CI path can create a ledger, so a brand-new epic's `.sdlc/` rides
 its **first** review PR/MR, cut from the authoring branch (creation, not mutation, #162).
 

package/skills/yad-ship/SKILL.md

@@ -34,7 +34,11 @@ its own and **never merges**. The engineer review + merge are Step E (`yad-engin
   footer**; the `Co-Authored-By` trailer appears only when this flag names a tool).
 - `task`           — Task trailer (optional; derived from the branch when omitted).
 - `contractChange` — flag; marks the contract surface touched (commit trailer + PR escalation).
-- `repo` / `risk` / `base` / `platform` / `title` — PR/MR options (see `yad-open-pr`).
+- `repo` / `risk` / `platform` / `title` — PR/MR options (see `yad-open-pr`).
+- `base`           — override the PR/MR base. The default is the repo's own default branch, resolved
+  by the full chain in **Base branch** (`yad-open-pr`) — the canonical description, including the
+  hub rung — never a hardcoded `main`. A non-default base loses the AI first pass; `ship` warns and
+  still opens.
 
 ## On Activation
 
@@ -59,6 +63,7 @@ the engineer review and merge are Step E (`yad-engineer-review`).
 ## Hard rules
 
 - **One staged atomic task = one commit = one PR/MR.** Never bundle; never open from the default branch.
+- **The PR targets the repo's default branch** unless `--base` says otherwise; never assume `main`.
 - **No AI footer by default.** The wrapped commit writes a `Co-Authored-By` trailer ONLY when `--ai <id>`
   is explicitly passed; never add it on the AI's own initiative.
 - **No PR without a landed commit.** A failed/`--dry-run` commit stops the step before pushing.