yadflow 3.16.2 → 3.16.3

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [3.16.3](https://github.com/abdelrahmannasr/yadflow/compare/v3.16.2...v3.16.3) (2026-08-12)
+
+
+### Bug Fixes
+
+* **open-pr:** base the task PR on the repo default branch, not main ([63da011](https://github.com/abdelrahmannasr/yadflow/commit/63da011fd2c4b6e81940c646879cc692b634a877)), closes [#168](https://github.com/abdelrahmannasr/yadflow/issues/168)
+
+
+### Performance Improvements
+
+* **review:** stop probing the platform for an already-configured base ([0fc3de3](https://github.com/abdelrahmannasr/yadflow/commit/0fc3de34c7a522ec3463953778787f247ab28071)), closes [#191](https://github.com/abdelrahmannasr/yadflow/issues/191)
+
 ## [3.16.2](https://github.com/abdelrahmannasr/yadflow/compare/v3.16.1...v3.16.2) (2026-08-12)
 
 

package/bin/yad.mjs

@@ -103,9 +103,11 @@ ${c.bold('Review gate (front half)')}
 
 ${c.bold('Build helpers')}
   yad commit --type <t> -m <subject>   Commit by convention (trailers, atomic guard)
-  yad open-pr [--repo <name>]          Open a task PR/MR — stage-aware on the hub: a review/EP-*
-                                       branch opens the front-half artifact-review PR (delegates to
-                                       gate open), any other hub branch uses the code-task template
+  yad open-pr [--repo <name>]          Open a task PR/MR against the repo's DEFAULT branch (never a
+                                       hardcoded main; --base overrides) — stage-aware on the hub: a
+                                       review/EP-* branch opens the front-half artifact-review PR
+                                       (delegates to gate open), any other hub branch uses the
+                                       code-task template
   yad ship --type <t> -m <subject>     Commit AND open the task PR/MR in one step (stage-aware)
   yad checkpoint [--push]              Commit the machine-written back-half hub state
                                        (trust-log/build-log/build-state) — plus any story
@@ -153,6 +155,10 @@ ${c.bold('Options')}
   --contract-change     commit/open-pr: mark the contract surface touched
   --risk <level>        open-pr: low|medium|high (default low)
   --repo <name>         open-pr: target a registered repo by name
+  --base <branch>       open-pr: override the PR/MR base — default is the repo's own default
+                        branch (repos.json default_branch, else hub.json default_branch for a PR
+                        on the hub itself, else the platform, else origin/HEAD, else main); a
+                        non-default base loses the AI first pass (warns, never blocks)
   --epic <id>           docs: target one epic's site (EP-<slug>)
   --overview            docs: target the project SDLC-overview site
   --check/--refresh/--wire   docs sync: report stale / rebuild / install Pages CI

package/cli/openpr.mjs

@@ -4,9 +4,11 @@
 // on the product hub.
 import path from 'node:path';
 import fs from 'node:fs';
-import { c, log, ok, info, hand, fail, run, exists, readJSON } from './lib.mjs';
+import { c, log, ok, info, warn, hand, fail, run, exists, readJSON } from './lib.mjs';
 import { PROJECT_FILES } from './manifest.mjs';
-import { detectPlatform, createPr, reviewersForScopes, resolveCommitterLogin } from './platform.mjs';
+import {
+  detectPlatform, createPr, reviewersForScopes, resolveCommitterLogin, resolveBaseBranch,
+} from './platform.mjs';
 import { taskFromBranch } from './commit.mjs';
 import { parseReviewBranch, artifactFromBase } from './epic-state.mjs';
 import { gateOpen } from './gate.mjs';
@@ -104,9 +106,6 @@ export async function runOpenPr(root, opts = {}) {
   if (!platform) { fail('could not detect platform (github/gitlab) — pass --platform'); process.exitCode = 1; return; }
 
   const branch = run('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: repoRoot }).stdout;
-  const baseBranch = opts.base || meta?.default_branch || 'main';
-  if (branch === baseBranch) { fail(`on ${baseBranch} — switch to your task branch first`); process.exitCode = 1; return; }
-
   const stage = detectStage(root, repoRoot, branch, meta);
 
   // hub-front: this is a front-half artifact-review PR (review/EP-*/<artifact> head on the hub). The
@@ -129,6 +128,34 @@ export async function runOpenPr(root, opts = {}) {
     return res;
   }
 
+  // The hub roster + its default_branch. The latter only applies when the PR targets the hub ITSELF
+  // (a hub-tooling branch) — for a connected code repo the hub's trunk belongs to a different repo and
+  // must never leak in. Resolved AFTER the hub-front hand-off above, which delegates its own base to
+  // `yad gate open`: resolving before it would spend a platform round-trip and print a base that the
+  // delegated path then ignores.
+  const hub = readJSON(path.join(root, PROJECT_FILES.hubConfig), { roster: [] });
+
+  // Resolve the base rather than assume it (#168). Hardcoding 'main' mis-based every PR on a repo
+  // whose trunk is something else — and CodeRabbit decides auto-review eligibility from the base at
+  // PR-OPEN time, so those PRs silently got no AI first pass at all.
+  const { base: baseBranch, source: baseSource, platformDefault } = resolveBaseBranch(platform, {
+    cwd: repoRoot, explicit: opts.base, meta, hub: stage === 'code-repo' ? null : hub, runner: opts.runner,
+  });
+  if (branch === baseBranch) { fail(`on ${baseBranch} — switch to your task branch first`); process.exitCode = 1; return; }
+  info(`base ${baseBranch} ${c.dim(`(from ${baseSource})`)}`);
+  // A base that is not the remote's default is legitimate (stacked PRs, release branches) but it costs
+  // the AI first pass, invisibly and irreversibly — so it is never silent. The REMEDY depends on where
+  // the base came from: telling someone to override a `default_branch` they deliberately configured
+  // would mean contradicting their own committed config on every PR, forever.
+  if (platformDefault && platformDefault !== baseBranch) {
+    warn(`base '${baseBranch}' is not the repo default '${platformDefault}' — CodeRabbit skips auto-review on a non-default base unless .coderabbit.yaml lists it under reviews.base_branches, and retargeting later does NOT undo the skip`);
+    if (baseSource === 'registry' || baseSource === 'hub') {
+      hand(`the configured default_branch (${baseSource === 'hub' ? '.sdlc/hub.json' : '.sdlc/repos.json'}) disagrees with the platform — reconcile them, or allow '${baseBranch}' in .coderabbit.yaml`);
+    } else {
+      hand(`open against '${platformDefault}' (or pass --base ${platformDefault}) unless you meant to stack this PR`);
+    }
+  }
+
   // Push the branch (sets upstream) using the user's own auth. Abort on failure — creating a PR for a
   // branch that is not on the remote just fails with a more confusing error.
   info(`pushing ${branch} …`);
@@ -155,7 +182,6 @@ export async function runOpenPr(root, opts = {}) {
   // Auto-assign from the hub roster, scoped to this repo: assignee = the committer (resolved from
   // local git identity), reviewers = the repo's reviewers + domain-owners, minus the committer.
   // Degrades cleanly when there is no roster / the committer is unmapped (gh self-assigns via @me).
-  const hub = readJSON(path.join(root, PROJECT_FILES.hubConfig), { roster: [] });
   const roster = hub.roster || [];
   const committer = resolveCommitterLogin(repoRoot, roster);
   const scope = meta?.name ? [meta.name] : [];
@@ -164,7 +190,10 @@ export async function runOpenPr(root, opts = {}) {
   const reviewers = reviewersForScopes(roster, scope, { excludeLogin: committer, repos: meta ? [meta] : [] });
   const assignees = committer ? [committer] : [];
 
-  const r = createPr(platform, { title, body, base: baseBranch, head: branch, reviewers, assignees, cwd: repoRoot });
+  // `creator` is injectable (mirrors gateOpen's) so a test can assert the base that reaches the
+  // platform CLI without shelling out to gh/glab.
+  const creator = opts.creator || createPr;
+  const r = creator(platform, { title, body, base: baseBranch, head: branch, reviewers, assignees, cwd: repoRoot });
   if (!r.ok) { fail(`could not open PR/MR — ${r.reason || 'unknown'}`); process.exitCode = 1; return; }
   ok(`opened ${r.url}`);
   if (r.mentioned?.length) info(`@-mentioned (GitLab single-reviewer field): ${r.mentioned.join(', ')}`);

package/cli/platform.mjs

@@ -378,6 +378,94 @@ export function branchExists(cwd, branch) {
   return remote.code === 2 ? false : null;
 }
 
+// ---- default branch -----------------------------------------------------------------------------
+// The REMOTE's own default branch, asked of the platform. This is the branch the platform (and the
+// tooling that keys off it — CodeRabbit's auto-review eligibility, branch protection, "compare"
+// defaults) considers the trunk, so it is the only authoritative answer to "what should a PR target?".
+// `runner` is injectable so the read is unit-testable without shelling out (mirrors searchIssues).
+// Returns { ok, branch, reason }; never throws — an absent/unauthenticated CLI is just `ok:false`.
+// It is a READ of the remote's own config, so it costs one API round-trip; callers that only need a
+// base branch get it folded into resolveBaseBranch below rather than calling this twice.
+export function platformDefaultBranch(platform, { cwd, runner = run } = {}) {
+  // No `platformReady` probe: an absent CLI already surfaces as a failed spawn, and skipping the probe
+  // keeps the read a pure function of `runner` (so a test never depends on gh/glab being installed).
+  if (!cliFor(platform)) return { ok: false, reason: 'no platform (github/gitlab) to ask' };
+  // This is a live network round-trip on a SYNCHRONOUS command path, so it carries the same ceiling
+  // branchExists documents for its own remote probe: "cannot ask" has to be fast, or a black-holed
+  // host / wedged credential helper turns `yad open-pr` into a hang. A timeout surfaces as ok:false,
+  // which the caller already treats as "the platform could not tell me".
+  const opts = { cwd, timeout: 10_000 };
+  if (platform === 'gitlab') {
+    // `:id` is glab's own placeholder for the project the cwd resolves to (same form as readPrGitLab).
+    const r = runner('glab', ['api', 'projects/:id'], opts);
+    if (!r.ok) return { ok: false, reason: r.stderr || 'glab api projects/:id failed' };
+    try {
+      const branch = JSON.parse(r.stdout)?.default_branch;
+      return branch ? { ok: true, branch } : { ok: false, reason: 'project has no default_branch' };
+    } catch { return { ok: false, reason: 'unreadable glab api response' }; }
+  }
+  const r = runner('gh', ['repo', 'view', '--json', 'defaultBranchRef', '-q', '.defaultBranchRef.name'], opts);
+  if (!r.ok) return { ok: false, reason: r.stderr || 'gh repo view failed' };
+  return r.stdout ? { ok: true, branch: r.stdout } : { ok: false, reason: 'gh returned no defaultBranchRef' };
+}
+
+// The branch a PR/MR should target, resolved rather than assumed (issue #168: open-pr hardcoded
+// 'main', so every task PR on a `staging`-trunk repo was mis-based — and CodeRabbit, which decides
+// auto-review eligibility at PR-OPEN time from the base, silently skipped every one of them).
+//
+// Order — most explicit first, and configuration outranks the remote: the same
+// configuration-outranks-the-remote order `yad repo sync` (repo.mjs) and the contract-check gate use,
+// though only this chain has a platform rung — they stop at the local `origin/HEAD`:
+//   1 flag        — an explicit --base; the human said so
+//   2 registry    — the repo's `default_branch` in .sdlc/repos.json
+//   3 hub         — hub.json's `default_branch`, for a PR against the product hub itself
+//   4 platform    — what the remote says (see platformDefaultBranch)
+//   5 origin-head — local `refs/remotes/origin/HEAD`, the same read repo.mjs/hubcommit.mjs use.
+//                   Deliberately NOT `ls-remote`: see branchExists above for why a network probe on
+//                   this path is a hang hazard.
+//   6 fallback    — 'main'
+//
+// `probe` decides WHEN the platform is asked, and exists because the two callers want different things:
+//   true  (default) — ask up front, so `platformDefault` rides along even when an earlier rung won.
+//                     `yad open-pr` needs that to warn about a base that is not the remote's trunk,
+//                     and it is about to shell out to gh/glab anyway.
+//   false           — ask only if the config rungs all miss. A caller that just wants a base (the
+//                     review companion) would otherwise pay a live round-trip — up to the full 10s
+//                     timeout on a slow/unreachable host — for a `platformDefault` it discards.
+// Either way the probe runs AT MOST once. Returns { base, source, platformDefault }; with `probe:false`
+// and an early rung winning, `platformDefault` is null because it was never asked, not because the
+// platform had no answer.
+export function resolveBaseBranch(platform, {
+  cwd, explicit = null, meta = null, hub = null, runner = run, probe = true,
+} = {}) {
+  let platformDefault = null;
+  let asked = false;
+  const askPlatform = () => {
+    if (asked) return platformDefault;
+    asked = true;
+    const remote = platformDefaultBranch(platform, { cwd, runner });
+    platformDefault = remote.ok ? remote.branch : null;
+    return platformDefault;
+  };
+  if (probe) askPlatform();
+  const originHead = () => {
+    const r = runner('git', ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], { cwd });
+    return r.ok && r.stdout ? r.stdout.replace(/^origin\//, '') : null;
+  };
+  const chain = [
+    ['flag', explicit],
+    ['registry', meta?.default_branch],
+    ['hub', hub?.default_branch],
+    ['platform', askPlatform],
+    ['origin-head', originHead],
+  ];
+  for (const [source, value] of chain) {
+    const branch = typeof value === 'function' ? value() : value;
+    if (branch) return { base: branch, source, platformDefault };
+  }
+  return { base: 'main', source: 'fallback', platformDefault };
+}
+
 // ---- create a PR/MR -----------------------------------------------------------------------------
 // `assignees` = the committer/PR-opener (always set, so the PR is owned by whoever pushed it);
 // `reviewers` = the scope's reviewers + domain-owners (computed by reviewersForScopes). On GitHub an

package/cli/review.mjs

@@ -12,6 +12,7 @@ import { updateShip } from './ledger.mjs';
 import { epicRoot } from './epic-state.mjs';
 import {
   detectPlatform, readPr, mapApprovers, getPrBody, editPrBody, postComment, prNumberFromUrl,
+  resolveBaseBranch,
 } from './platform.mjs';
 import { upsertTrailerBlock, nudgeMessage, parseEngagement } from './companion.mjs';
 import { sequenceDiff } from './walkthrough.mjs';
@@ -40,12 +41,16 @@ function platformOf(root, repoRoot, meta) {
 // Build (but don't print) the back-half grounding bundle. Shared by `context` and `walkthrough` so the
 // pair walkthrough adds an ordered stop-list on top of the exact same grounding the companion uses.
 // Returns { error } on a bad --repo, else { bundle, repoRoot, base }.
-function contextBundle(root, { repo, dir, pr } = {}) {
+function contextBundle(root, { repo, dir, pr, runner = run } = {}) {
   const rr = resolveRepo(root, { repo, dir });
   if (rr.error) return { error: rr.error };
   const { repoRoot, meta } = rr;
   const platform = platformOf(root, repoRoot, meta);
-  const base = meta?.default_branch || 'main';
+  // Same resolution as `yad open-pr` (#168): without it a repo whose trunk is not `main` grounded the
+  // companion on the wrong diff range — or on a branch that does not exist at all. `probe: false`
+  // because this caller only wants the base: a configured `default_branch` must answer locally and
+  // instantly, never behind a live gh/glab round-trip that could stall for the full timeout.
+  const { base } = resolveBaseBranch(platform, { cwd: repoRoot, meta, runner, probe: false });
   const bundle = {
     repo: meta?.name || null,
     repoRoot,
@@ -66,8 +71,8 @@ function contextBundle(root, { repo, dir, pr } = {}) {
 
 // `yad review context --repo <r> --pr <n>` — print the grounding bundle the companion uses to generate
 // the trailer / cards and run the chat over the CODE diff (grounded in the repo code-map + the PR).
-export async function reviewContext(root, { repo, dir, pr } = {}) {
-  const r = contextBundle(root, { repo, dir, pr });
+export async function reviewContext(root, { repo, dir, pr, runner = run } = {}) {
+  const r = contextBundle(root, { repo, dir, pr, runner });
   if (r.error) { fail(r.error); process.exitCode = 1; return; }
   log(JSON.stringify(r.bundle, null, 2));
   return r.bundle;
@@ -78,7 +83,7 @@ export async function reviewContext(root, { repo, dir, pr } = {}) {
 // first). The CLI sequences deterministically; the skill (yad-pair-review) walks the stops, generates
 // the per-stop briefing + Socratic question, and runs the two-way session. No LLM here, no ledger write.
 export async function reviewWalkthrough(root, { repo, dir, pr, runner = run } = {}) {
-  const r = contextBundle(root, { repo, dir, pr });
+  const r = contextBundle(root, { repo, dir, pr, runner });
   if (r.error) { fail(r.error); process.exitCode = 1; return; }
   const { bundle, repoRoot, base } = r;
   const diff = runner('git', ['-C', repoRoot, 'diff', `${base}...HEAD`]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "3.16.2",
+  "version": "3.16.3",
   "description": "Yadflow — the gated, team, multi-repo SDLC: author → review → build with a PR-driven review gate and a zero-dependency `yad` CLI (setup, gate, commit, open-pr, ship, repo, thread, reconcile). A BMAD module + 38 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",

package/skills/sdlc/module-help.csv

@@ -20,8 +20,8 @@ SDLC Workflow,yad-implement,Implement Task,IM,"Build-half Step B: with the dev l
 SDLC Workflow,yad-checks,Check Gates,CK,"Build-half Step C: wire and run the production-safety CI gates on a code repo (and product hub) — spec-link (every change links a real story/spec via its Task trailer), contract-check (a contract-surface change without Contract-Change + an updated re-locked contract FAILS and routes back to the architecture gate), build/test/lint, verified-commits (signed + roster-known authors), and the pattern gates commit-message / pr-title / pr-template (profile-aware code|hub). CI-agnostic bash invoked by GitHub Actions and GitLab CI. Blocking in CI; the human still owns the merge. Never auto-advances.",,{repo: <one of an epic's repos | hub>} {action: wire|run} {base: target branch},3-build,yad-implement,,false,demo-repos/<repo>/,checks/*.sh .github/workflows/yad-checks.yml .gitlab-ci.yml
 SDLC Workflow,yad-pr-template,PR/MR Template,PT,"Build-half Step D: detect a code repo's platform and commit the matching PR/MR template (.github/pull_request_template.md or .gitlab/merge_request_templates/Default.md) with an Impact & Risk block. A high risk level (or a touched contract/auth/payments surface) routes the review to domain owners — the same escalation yad-review-gate applies. Ships the routing helper risk-route.sh plus the pattern-gate scripts pr-title.sh and pr-template.sh (used by yad-checks). Never auto-advances.",,{repo: <one of an epic's repos | hub>} {action: wire|route} {body: PR description file},3-build,yad-checks,,false,demo-repos/<repo>/,.github/pull_request_template.md .gitlab/merge_request_templates/Default.md checks/risk-route.sh checks/pr-title.sh checks/pr-template.sh
 SDLC Workflow,yad-commit,Commit by Convention,CM,"Build-half helper: commit ONE staged atomic change by the conventions — a Conventional-Commits subject, the fixed trailer block (Task -> Contract-Change -> Co-Authored-By), and the <=3-file atomic guard. The human git author owns the commit; an assisting AI is recorded only as a Co-Authored-By footer chosen per-commit with --ai (claude|copilot|cursor|coderabbit|none, default none). Drives the yad commit CLI. Never auto-advances.",,{type: feat|fix|...} {message: subject} {ai: <tool|none>} {task: <id>} {contract-change: true|false},3-build,yad-implement,,false,<repo>/,one commit
-SDLC Workflow,yad-open-pr,Open PR/MR,OP,"Build-half helper: open a code-repo task PR/MR from the committed platform template — detect GitHub/GitLab, push the task branch, create the PR/MR with the body prefilled (Summary / Story-task / Impact & Risk) and the title defaulting to the commit subject. Auto-assigns from the hub roster (assignee = committer, reviewers = repo reviewers + domain-owners); high risk / contract surface routes to domain owners (risk-route.sh). Drives the yad open-pr CLI. Never merges; never auto-advances.",,{repo: <name>} {risk: low|medium|high} {contract-change: true|false},3-build,yad-commit,,false,<repo>/,one PR/MR
-SDLC Workflow,yad-ship,Commit + Open PR/MR,SP2,"Build-half helper: commit AND open the task PR/MR in one step — a thin orchestration over yad-commit then yad-open-pr. Commits the staged atomic change by the conventions, then pushes the branch and opens the PR/MR from the committed template with the roster auto-assigned. The PR step runs ONLY if the commit lands (a failed commit, tripped guard, or --dry-run stops before pushing). Drives the yad ship CLI. Never merges; never auto-advances.",,{type: feat|fix|...} {message: subject} {ai: <tool|none>} {repo: <name>} {risk: low|medium|high} {contract-change: true|false},3-build,yad-pr-template,,false,<repo>/,one commit + one PR/MR
+SDLC Workflow,yad-open-pr,Open PR/MR,OP,"Build-half helper: open a code-repo task PR/MR from the committed platform template — detect GitHub/GitLab, push the task branch, create the PR/MR with the body prefilled (Summary / Story-task / Impact & Risk) and the title defaulting to the commit subject. Auto-assigns from the hub roster (assignee = committer, reviewers = repo reviewers + domain-owners); high risk / contract surface routes to domain owners (risk-route.sh). Bases the PR on the repo's RESOLVED default branch (repos.json default_branch, else the platform's own default, else origin/HEAD, else main) instead of a hardcoded main, and warns when the base is not the platform default — that loses the AI first pass irreversibly. Drives the yad open-pr CLI. Never merges; never auto-advances.",,{repo: <name>} {risk: low|medium|high} {contract-change: true|false} {base: <branch>},3-build,yad-commit,,false,<repo>/,one PR/MR
+SDLC Workflow,yad-ship,Commit + Open PR/MR,SP2,"Build-half helper: commit AND open the task PR/MR in one step — a thin orchestration over yad-commit then yad-open-pr. Commits the staged atomic change by the conventions, then pushes the branch and opens the PR/MR from the committed template with the roster auto-assigned. The PR step runs ONLY if the commit lands (a failed commit, tripped guard, or --dry-run stops before pushing). Drives the yad ship CLI. Never merges; never auto-advances.",,{type: feat|fix|...} {message: subject} {ai: <tool|none>} {repo: <name>} {risk: low|medium|high} {contract-change: true|false} {base: <branch>},3-build,yad-pr-template,,false,<repo>/,one commit + one PR/MR
 SDLC Workflow,yad-hub-bridge,Hub Review Bridge,HB,"The templated PR/MR bridge for the front-half review gate: when the product hub has a platform (.sdlc/hub.json), open a review PR/MR on the hub for an authored artifact, set required reviewers/labels from the routing rule, and provide the read-only gh/glab recipes yad-review-gate's sync uses to pull platform comments + approvals into the file ledger. Local-user auth, no stored tokens; file ledger stays the source of truth; degrades to file-only when no platform/CLI. Never auto-advances.",,{epic: EP-<slug>} {artifact: epic.md|architecture.md|ui-design.md|stories/} {action: open|route},1-front,yad-review-gate,yad-review-gate,false,epics/EP-<slug>/.sdlc/,hub-prs.json
 SDLC Workflow,yad-engineer-review,Engineer Review & Merge,ER,"Build-half Step E: wire an advisory AI first-pass (CodeRabbit) on the PR, record the human engineer review with the same human_approve discipline as the front gates (owner + 1 reviewer, escalating to domain owners on high risk / contract / auth / payments), and on merge record the ship in epics/<epic>/.sdlc/build-log.json and update the story state. AI review is advisory, never the authority; the human owns the merge. Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {task: T0N} {repo: <repo>} {action: ai-review|approve|ship},3-build,yad-ship,,false,epics/EP-<slug>/.sdlc/,build-log.json story-status
 SDLC Workflow,yad-backfill,Backfill Specs,BF,"Build-half Step G: generate specs for already-built features in an existing repo. Confirm Repomix (npx repomix CLI), pack ONE feature (compress + git logs, secret-scan), feed to AI with a 'describe what exists, do not invent' prompt, write a DRAFT spec marked verified: false. Human approval (reuse yad-review-gate) makes it real. Boundary auto-proposed and human-confirmed. A change is blocked only until the features it touches have approved specs. The promote action flips a brownfield stub epic (yad-stub) to a real, verified feature epic once its backfill spec is approved. Never auto-advances.",,{repo: <repo>} {feature: <name + globs>} {action: pack|draft|approve|gate|promote} {epic: EP-<slug> (promote)},3-build,,,false,demo-repos/<repo>/specs/backfill/<feature>/,spec.md backfill-check.sh

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-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.