yadflow 2.9.0 → 2.11.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-# [2.9.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.8.0...v2.9.0) (2026-06-15)
+# [2.11.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.10.0...v2.11.0) (2026-06-15)
 
 
 ### Features
 
-* **docs:** enhance interactive docs — clearer diagram, brand icon, dimmed stubs ([#65](https://github.com/abdelrahmannasr/yadflow/issues/65)) ([969a20d](https://github.com/abdelrahmannasr/yadflow/commit/969a20dc1e9778e1ffd0962e557f3e2c28dfd6ef))
+* add yad-sync-repos — switch every connected repo to its default branch + ff pull ([#67](https://github.com/abdelrahmannasr/yadflow/issues/67)) ([0abdcdf](https://github.com/abdelrahmannasr/yadflow/commit/0abdcdf80c8a0a6bfd8c94129fde90f1d35ec365)), closes [#30](https://github.com/abdelrahmannasr/yadflow/issues/30)
 
 # [2.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.1.0...v2.2.0) (2026-06-14)
 

package/README.md

@@ -100,6 +100,7 @@ with `npx` from your **product hub** repo — no clone needed.
 | `yad open-pr [--repo <name>]` | Open a code-repo **task** PR/MR from the repo's platform template (build half). |
 | `yad ship --type <t> -m <subject>` | Commit **and** open the task PR/MR in one step (`yad commit` then `yad open-pr`). |
 | `yad repo list` / `yad repo refresh [name]` | List connected repos as **fresh / stale**, and re-pack a stale one — staleness is now an explicit human decision, never an automatic skill side-effect. |
+| `yad repo sync [name]` | Switch every connected repo to its **default branch** and fast-forward it from origin (one or all). Dirty repos are skipped, never overwritten; fast-forward only. |
 | `npx yadflow --version` | Print the installed CLI version. |
 
 Flags: `--dir <path>` targets a project other than the cwd; `--force` re-copies unchanged files (or
@@ -134,7 +135,7 @@ simultaneous advancements can be lost; the next event or scheduled sweep re-sync
 ### What `setup` walks you through (10 steps)
 
 1. **Preflight** — confirm the hub is a git repo (offers `git init`); check `git`/`node`/`npx`.
-2. **Install the module** — copy all 29 `yad-*` skills into the IDE skill dirs you pick
+2. **Install the module** — copy all 30 `yad-*` skills into the IDE skill dirs you pick
    (`.claude/`, `.agents/`, `.zencoder/`, `.opencode/`) and register `_bmad/sdlc/`.
 3. **Hub platform & roster** — detect GitHub/GitLab from the remote; record reviewers → `.sdlc/hub.json`.
    Edit the roster any time afterwards with `yad roster` (no need to re-run the whole wizard).
@@ -191,7 +192,7 @@ with a fix-it hint per finding. Failures carry stable, greppable codes, also pri
 
 Filing a bug? Attach `yad doctor --json` — it contains no secrets (names, paths, and check results only).
 
-## Agent skills (all 29)
+## Agent skills (all 30)
 
 The CLI **installs and wires** the module; the skills below are the **agents you invoke by name** in your
 AI IDE (e.g. *“run `yad-epic`”*) to actually do the work. State lives in files you can also edit
@@ -204,6 +205,11 @@ directly. Each skill stops at a gate and never auto-advances unless a step has *
   `.sdlc/repos.json`, then caches an AI-readable picture of each — a compressed Repomix pack and a
   lightweight code-map (existing endpoints/events/data-models/modules), secret-scanned. Idempotent and
   refreshable; staleness tracked by HEAD sha.
+- **`yad-sync-repos`** — Brings every connected repo up to date in one shot: switches each repo in
+  `.sdlc/repos.json` to its `default_branch` and fast-forwards it from origin (local-user git, no stored
+  tokens). A working-tree-only maintenance op — never a gate, never writes the registry. A dirty repo is
+  skipped and reported (never overwritten); a diverged branch is left for manual resolution. Drives
+  `yad repo sync [name]`.
 - **`yad-connect-design`** — Connects a design tool (Figma-first, pluggable) so the UI step can
   materialize the actual feature design (mobile screens / web pages) inside it, alongside the Markdown.
   Records the tool + project/file references in `.sdlc/design.json` (local-user / MCP-session auth, no

package/cli/manifest.mjs

@@ -10,7 +10,7 @@ import { readFileSync } from 'node:fs';
 const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 export const VERSION = version;
 
-// The 29 hand-authored yad-* skills (mirrors skills/sdlc/install.sh).
+// The 30 hand-authored yad-* skills (mirrors skills/sdlc/install.sh).
 export const SKILLS = [
   'yad-analysis',
   'yad-epic',
@@ -19,6 +19,7 @@ export const SKILLS = [
   'yad-stories',
   'yad-test-cases',
   'yad-connect-repos',
+  'yad-sync-repos',
   'yad-connect-design',
   'yad-connect-testing',
   'yad-connect-learning',

package/cli/repo.mjs

@@ -1,8 +1,10 @@
-// `yad repo list|refresh` — connected-repo staleness as an explicit HUMAN decision.
-// Skill steps no longer silently repack a stale repo; they flag it and point here. (`yad check --fix`
-// still refreshes too — it is also human-invoked.)
+// `yad repo list|refresh|sync` — connected-repo maintenance as explicit HUMAN decisions.
+// list/refresh: staleness of the cached code-context pack (HEAD != syncedHead). Skill steps no longer
+// silently repack a stale repo; they flag it and point here. (`yad check --fix` refreshes too — also
+// human-invoked.) sync: switch every connected repo to its registry default_branch and fast-forward
+// it to origin — a working-tree-only op (it never writes the registry; a dirty tree is skipped).
 import path from 'node:path';
-import { c, log, ok, info, warn, hand, fail, readJSON, writeJSON } from './lib.mjs';
+import { c, log, ok, info, warn, hand, fail, readJSON, writeJSON, run } from './lib.mjs';
 import { PROJECT_FILES } from './manifest.mjs';
 import { gitHead, packRepo } from './setup.mjs';
 
@@ -18,6 +20,18 @@ function staleness(root, repo) {
   return { head, stale: !!stale, unknown: !head };
 }
 
+// ---- git helpers for `sync` (local-user auth only — never embed credentials) ----
+const git = (cwd, ...args) => run('git', args, { cwd });
+const hasRemote = (cwd, remote = 'origin') => git(cwd, 'remote', 'get-url', remote).ok;
+const isDirty = (cwd) => { const r = git(cwd, 'status', '--porcelain'); return r.ok && r.stdout.length > 0; };
+const currentBranch = (cwd) => { const r = git(cwd, 'rev-parse', '--abbrev-ref', 'HEAD'); return r.ok ? r.stdout : null; };
+// Registry default_branch wins; else origin/HEAD; else 'main'.
+function defaultBranch(cwd, repo) {
+  if (repo.default_branch) return repo.default_branch;
+  const r = git(cwd, 'symbolic-ref', '--short', 'refs/remotes/origin/HEAD');
+  return r.ok && r.stdout ? r.stdout.replace(/^origin\//, '') : 'main';
+}
+
 export async function runRepo(root, { action = 'list', name, today } = {}) {
   const { regPath, registry } = load(root);
   if (!registry.repos.length) { warn('no repos registered (.sdlc/repos.json) — run `yad setup`'); return { repos: 0 }; }
@@ -55,7 +69,44 @@ export async function runRepo(root, { action = 'list', name, today } = {}) {
     return { refreshed };
   }
 
-  fail(`unknown repo action: ${action} (list | refresh)`);
+  if (action === 'sync') {
+    const targets = name ? registry.repos.filter((r) => r.name === name) : registry.repos;
+    if (name && !targets.length) { fail(`unknown repo: ${name}`); process.exitCode = 1; return { synced: 0 }; }
+    log(c.bold('\nsync connected repos'));
+    let synced = 0, skipped = 0;
+    for (const repo of targets) {
+      const repoRoot = path.resolve(root, repo.path);
+      const tag = `${repo.name} ${c.dim(`(${repo.path})`)}`;
+      if (!gitHead(repoRoot)) { warn(`${tag} — not a git repo / HEAD unreadable — skipped`); skipped++; continue; }
+      if (isDirty(repoRoot)) { warn(`${repo.name} — ${c.yellow('dirty')} → SKIPPED (commit/stash first)`); skipped++; continue; }
+      const branch = defaultBranch(repoRoot, repo);
+      const remote = hasRemote(repoRoot);
+      if (remote) {
+        const f = git(repoRoot, 'fetch', 'origin', branch, '--prune');
+        if (!f.ok) { warn(`${repo.name} — fetch failed (${(f.stderr.split('\n')[0]) || 'auth?'}) — skipped`); skipped++; continue; }
+      }
+      if (currentBranch(repoRoot) !== branch) {
+        const co = git(repoRoot, 'checkout', branch);
+        if (!co.ok) { warn(`${repo.name} — cannot switch to ${branch} (${co.stderr.split('\n')[0] || 'no such branch'}) — skipped`); skipped++; continue; }
+      }
+      if (remote) {
+        const before = gitHead(repoRoot);
+        const m = git(repoRoot, 'merge', '--ff-only', `origin/${branch}`);
+        if (!m.ok) { warn(`${repo.name} — ${c.yellow('diverged')} on ${branch} → not fast-forwarded (resolve manually)`); skipped++; continue; }
+        ok(`${repo.name} ${c.dim('—')} ${before === gitHead(repoRoot) ? `already current on ${branch}` : `switched to ${branch}, pulled (ff)`}`);
+      } else {
+        ok(`${repo.name} ${c.dim('—')} on ${branch} (local-only, no remote)`);
+      }
+      synced++;
+    }
+    // A pulled repo's HEAD moves, so its cached code-context pack goes stale — point the human at refresh.
+    const staleCount = registry.repos.filter((r) => staleness(root, r).stale).length;
+    info(`synced ${synced}, skipped ${skipped}`);
+    if (staleCount) hand(`${staleCount} repo(s) now have a stale code-context pack — \`yad repo refresh\` to repack`);
+    return { synced, skipped, stale: staleCount };
+  }
+
+  fail(`unknown repo action: ${action} (list | refresh | sync)`);
   process.exitCode = 1;
   return {};
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "yadflow",
-  "version": "2.9.0",
-  "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). A BMAD module + 29 yad-* skills.",
+  "version": "2.11.0",
+  "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). A BMAD module + 30 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",
   "license": "MIT",

package/skills/sdlc/config.yaml

@@ -118,6 +118,9 @@ code_context:
                                                       # `yad repo refresh <repo>`) — they never silently
                                                       # re-pack. `yad repo list` shows fresh/stale;
                                                       # `yad repo refresh` and `yad check --fix` re-pack.
+  # `yad repo sync [<repo>]` (yad-sync-repos) switches every connected repo to its default_branch and
+  # fast-forwards it from origin before work starts — working-tree only (never writes the registry);
+  # a dirty repo is skipped, a diverged branch is left for manual resolution (fast-forward only).
   load_in_front_phases: true                          # epic, architecture, ui-design, stories read the maps
   # Auth: `yad-connect-repos` clones/fetches as the LOCAL user (SSH key or git credential helper),
   # works for both github and gitlab (and self-hosted), and stores NO tokens in the registry.

package/skills/sdlc/install.sh

@@ -11,7 +11,7 @@ set -euo pipefail
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 cd "$ROOT"
 
-SKILLS=(yad-analysis yad-epic yad-architecture yad-ui yad-stories yad-test-cases yad-connect-repos yad-connect-design yad-connect-testing yad-connect-learning yad-connect-docs yad-docs yad-docs-overview yad-docs-sync yad-learn yad-spec yad-implement yad-checks yad-pr-template yad-review-comments yad-hub-bridge yad-commit yad-open-pr yad-ship yad-engineer-review yad-backfill yad-run yad-review-gate yad-status)
+SKILLS=(yad-analysis yad-epic yad-architecture yad-ui yad-stories yad-test-cases yad-connect-repos yad-sync-repos yad-connect-design yad-connect-testing yad-connect-learning yad-connect-docs yad-docs yad-docs-overview yad-docs-sync yad-learn yad-spec yad-implement yad-checks yad-pr-template yad-review-comments yad-hub-bridge yad-commit yad-open-pr yad-ship yad-engineer-review yad-backfill yad-run yad-review-gate yad-status)
 
 echo "Installing sdlc module from $ROOT/skills ..."
 

package/skills/sdlc/module-help.csv

@@ -6,7 +6,8 @@ SDLC Workflow,yad-architecture,Author Architecture,AA,"Front state 3: with the a
 SDLC Workflow,yad-ui,Author UI Design,AU,"Front state 5: with the ux-designer author ui-design.md and DESIGN.md, driving Impeccable slash-commands when installed. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/,ui-design.md DESIGN.md state.json
 SDLC Workflow,yad-stories,Author Stories,AS,"Front state 7: with the pm break the epic into repo-tagged stories with stable EP-<slug>-S0N IDs, one file each under stories/. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/stories/,stories/EP-<slug>-S0N.md state.json
 SDLC Workflow,yad-test-cases,Author Test Cases,TC,"Front state 9 (PARALLEL, non-blocking): opens when the stories gate passes — the epic is already ready-for-build, so the build half can start at the same time the tester works here. With the test architect (Murat) author test-cases.md covering the approved stories, and — when a testing tool is connected (.sdlc/testing.json) — generate/link the actual automation tests in it, recording test-links.json; otherwise produce the test-case artifact only. Its review never moves currentStep off ready-for-build. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/,test-cases.md test-links.json state.json
-SDLC Workflow,yad-connect-repos,Connect Code Repos,CR,"Setup/maintenance: connect code repos to the product hub so the front/brain phases are code-aware. Registers each repo (GitHub or GitLab, local-user auth, no stored tokens) in .sdlc/repos.json and caches a Repomix pack + a lightweight code-map (existing endpoints/events/data-models/modules, secret-scanned). Idempotent and refreshable; staleness tracked by HEAD sha. Run at setup or any time a new repo is added. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {repo: <name>} {path: <path-or-absolute>} {git_url: <ssh-or-https>} {domain_owner: <who>},0-setup,,yad-epic,false,.sdlc/,repos.json code-context/<repo>/pack.md code-context/<repo>/code-map.md
+SDLC Workflow,yad-connect-repos,Connect Code Repos,CR,"Setup/maintenance: connect code repos to the product hub so the front/brain phases are code-aware. Registers each repo (GitHub or GitLab, local-user auth, no stored tokens) in .sdlc/repos.json and caches a Repomix pack + a lightweight code-map (existing endpoints/events/data-models/modules, secret-scanned). Idempotent and refreshable; staleness tracked by HEAD sha. Run at setup or any time a new repo is added. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {repo: <name>} {path: <path-or-absolute>} {git_url: <ssh-or-https>} {domain_owner: <who>},0-setup,,yad-sync-repos,false,.sdlc/,repos.json code-context/<repo>/pack.md code-context/<repo>/code-map.md
+SDLC Workflow,yad-sync-repos,Sync Connected Repos,SR,"Setup/maintenance: bring every connected repo up to date in one shot — switch each repo in .sdlc/repos.json to its default_branch and fast-forward it from origin (local-user git, no stored tokens). Working-tree only; never a gate and never writes the registry. A dirty repo is skipped and reported (never overwritten); a diverged branch is left for manual resolution (fast-forward only). After pulling, a repo's cached pack goes stale — points the human at yad repo refresh.",,{action: sync} {repo: <name>},0-setup,yad-connect-repos,yad-connect-design,false,,(none — working-tree only)
 SDLC Workflow,yad-connect-design,Connect Design Tool,CD,"Setup/maintenance: connect a design tool (Figma-first, pluggable) to the product hub so the UI design step can materialize the actual feature design (mobile screens / web pages) inside it, alongside ui-design.md + DESIGN.md. Records the tool + project/file references in .sdlc/design.json (local-user / MCP-session auth, no stored tokens), detecting whether a design-tool MCP is available and degrading to markdown-only when absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {tool: figma|pencil|none} {project_url: <team/project/file url>} {files: {web,mobile}},0-setup,,yad-ui,false,.sdlc/,design.json
 SDLC Workflow,yad-connect-testing,Connect Testing Tool,CT,"Setup/maintenance: connect a testing tool (Playwright-first, pluggable) to the product hub so the test-cases step can implement the actual automation tests in it, alongside test-cases.md. Records the tool + project/suite references in .sdlc/testing.json (local-user / MCP-session auth, no stored tokens), detecting whether a testing-tool MCP is available and degrading to artifacts-only when absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {tool: playwright|cypress|pytest|none} {project_url: <project/config reference>} {suites: {<repo>}},0-setup,,yad-test-cases,false,.sdlc/,testing.json
 SDLC Workflow,yad-connect-learning,Connect Learning Tool,CL,"Setup/maintenance: connect a learning/tutoring tool (DeepTutor-first, pluggable) so the cross-cutting learning layer can tutor any team member, at any SDLC stage, in the context of what is being built. Records the tool + an optional grounded knowledge base in .sdlc/learning.json (local-user auth, no stored tokens), detecting whether the DeepTutor CLI is on PATH (a subprocess like Repomix, not an MCP) and degrading to harness-native tutoring when absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {tool: deeptutor|none} {kb: <name>} {ground: true|false},0-setup,,yad-learn,false,.sdlc/,learning.json

package/skills/yad-checks/SKILL.md

@@ -16,6 +16,8 @@ in CI on every PR/MR and must pass before merge (build plan §C). Each is a smal
    contract upstream, it **FAILS and routes back to the architecture gate**. The shared surface is
    never widened from inside a code repo (Phase 2 contract representation: delimited block + SHA-256 lock).
 3. **build/test/lint** — standard quality stage; tests must actually exercise new behavior, not just pass.
+   The CI job sets `YAD_TEST_MAX_WORKERS` (default `2`); the gate caps jest/vitest test concurrency at
+   that and is a no-op for other runners (see `references/check-gates.md`).
 4. **verified-commits** — no unverified commits from unverified users: every commit in the range must
    carry a signature the platform marks **Verified** AND be authored by a known identity
    (`.sdlc/verified-authors`, generated from the hub roster's `email` fields). Enforced on the

package/skills/yad-checks/references/check-gates.md

@@ -46,6 +46,11 @@ repo uses. Each reads conventions established by earlier steps — it invents no
 - Runs `npm run lint`, `npm run build`, `npm test` in order; any non-zero exit fails the gate.
 - Tests must actually exercise behavior (build plan §C) — an empty or trivially-passing suite does not
   satisfy the gate's intent.
+- **Test worker cap.** When the CI job sets `YAD_TEST_MAX_WORKERS` (the templates default it to `2`)
+  and the repo's `test` script is jest/vitest, the gate forwards `--maxWorkers=<n>` to bound CI
+  concurrency. For any other runner (`node --test`, mocha, …) it is a no-op — the flag is never
+  passed, so the gate cannot break on an unknown option. Override it per repo via the
+  `YAD_TEST_MAX_WORKERS` CI variable, or unset it to remove the cap.
 
 ### Canonical `package.json` scripts (Node demo)
 

package/skills/yad-checks/templates/checks/build-test-lint.sh

@@ -8,7 +8,19 @@ echo "[build/test/lint] lint…"
 npm run --silent lint
 echo "[build/test/lint] build…"
 npm run --silent build
+
+# Worker cap: when YAD_TEST_MAX_WORKERS is set AND the repo's test script is jest/vitest (the
+# runners that accept --maxWorkers), forward it to bound CI test concurrency. For any other runner
+# (node --test, mocha, …) it is a deliberate no-op so the gate never breaks on an unknown flag.
+extra=""
+if [ -n "${YAD_TEST_MAX_WORKERS:-}" ]; then
+  case "$(npm pkg get scripts.test 2>/dev/null || true)" in
+    *jest*|*vitest*) extra="-- --maxWorkers=${YAD_TEST_MAX_WORKERS}" ;;
+  esac
+fi
 echo "[build/test/lint] test…"
-npm run --silent test
+# Intentional word-splitting: $extra is either empty or `-- --maxWorkers=N`.
+# shellcheck disable=SC2086
+npm run --silent test $extra
 
 echo "PASS [build/test/lint]: lint, build, and tests all green."

package/skills/yad-checks/templates/github/yad-checks.yml

@@ -25,6 +25,8 @@ jobs:
 
   build-test-lint:
     runs-on: ubuntu-latest
+    env:
+      YAD_TEST_MAX_WORKERS: "2" # cap jest/vitest test workers in CI; ignored by other runners
     steps:
       - uses: actions/checkout@v4
         with: { fetch-depth: 0 }

package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml

@@ -42,6 +42,8 @@ yad-contract-check:
 yad-build-test-lint:
   extends: .sdlc_mr_only
   needs: []
+  variables:
+    YAD_TEST_MAX_WORKERS: "2" # cap jest/vitest test workers in CI; ignored by other runners
   script:
     - bash checks/build-test-lint.sh
 

package/skills/yad-commit/SKILL.md

@@ -1,14 +1,15 @@
 ---
 name: yad-commit
-description: 'Build-half helper of the gated SDLC. Commit ONE staged atomic change by the conventions — a Conventional-Commits subject, the fixed trailer block (Task → Contract-Change → Co-Authored-By), and an atomic-file guard (≤3 files). 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, human-only). Drives the zero-dependency `yad commit` CLI; never auto-advances. Use when the user says "commit this", "commit by convention", or "make an atomic commit".'
+description: 'Build-half helper of the gated SDLC. Commit ONE staged atomic change by the conventions — a Conventional-Commits subject, the fixed trailer order (Task → Contract-Change, plus an OPTIONAL Co-Authored-By), and an atomic-file guard (≤3 files). By default the commit carries NO AI footer: the human git author owns it, and a Co-Authored-By trailer is added ONLY when --ai <id> is explicitly passed (claude|copilot|cursor|coderabbit; default none = human-only). The flag is the sole switch — never add the footer on the AI''s own initiative. Drives the zero-dependency `yad commit` CLI; never auto-advances. Use when the user says "commit this", "commit by convention", or "make an atomic commit".'
 ---
 
 # SDLC — Commit by Convention (build-half helper)
 
 **Goal:** Turn ONE staged atomic change into a single commit that satisfies the project conventions
 (`CONTRIBUTING.md` / `config.yaml` `build`): a Conventional-Commits subject, the fixed trailer order
-`Task → Contract-Change → Co-Authored-By`, and the atomic-file guard. This is the standalone commit
-step — the same engine `yad-implement` and `yad-ship` use. It **never auto-advances**; it just commits.
+`Task → Contract-Change → Co-Authored-By` (the footer **off by default** — added only via an explicit
+`--ai`), and the atomic-file guard. This is the standalone commit step — the same engine `yad-implement`
+and `yad-ship` use. It **never auto-advances**; it just commits.
 
 ## Conventions
 
@@ -23,14 +24,17 @@ step — the same engine `yad-implement` and `yad-ship` use. It **never auto-adv
   task-scoped, so the trailer is optional there.
 - **Contract-Change trailer** — `--contract-change` only when the diff touches the locked contract
   surface; it routes the change back to the architecture gate.
-- **AI co-author footer** — `--ai <id>` records the assisting tool as a `Co-Authored-By` trailer. The
-  human is always the author; `--ai none` (the default) is an explicit human-only commit.
+- **AI co-author footer — OFF by default.** No `Co-Authored-By` trailer is written unless `--ai <id>`
+  explicitly names a tool. `--ai none` (the default) produces a clean human-only commit. The flag is the
+  **only** switch that adds the footer — never add it on the AI's own initiative just because a tool
+  helped author the diff. The human is always the author.
 
 ## Inputs
 
 - `type`    — Conventional-Commits type (required).
 - `message` — the subject text (required), `-m "<subject>"`.
-- `ai`      — co-author footer: `claude|copilot|cursor|coderabbit|none` (default `none`).
+- `ai`      — co-author footer: `claude|copilot|cursor|coderabbit|none` (default `none` = **no 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; mark the contract surface touched.
 
@@ -55,8 +59,10 @@ the architecture gate. To also open the PR/MR in the same step, use `yad-ship`.
 ## Hard rules
 
 - **One staged atomic change = one commit.** Never bundle; never exceed the file boundary silently.
-- **The human author owns the commit.** The AI is only a `Co-Authored-By` footer, chosen per-commit.
-- **Trailer order is fixed:** `Task → Contract-Change → Co-Authored-By`.
+- **No AI footer by default.** A `Co-Authored-By` trailer is written ONLY when `--ai <id>` is explicitly
+  passed; the default is a clean human-only commit. Never add it on your own initiative.
+- **The human author owns the commit.** The AI is at most a `Co-Authored-By` footer, never the author.
+- **Trailer order is fixed:** `Task → Contract-Change → Co-Authored-By` (the footer only when `--ai` is given).
 - **Never widen the contract here.** A contract touch is flagged (`--contract-change`), not hidden.
 
 ## Reference

package/skills/yad-implement/SKILL.md

@@ -96,9 +96,9 @@ A contract change means the diff alters the agreed cross-repo shape itself.
 ### Step 6 — Commit on the task branch
 Stage only the declared files. Commit with the convention: a conventional subject, a short body, and a
 `Task: <story>-<task>` trailer (plus `Contract-Change: yes` if Step 5 applies). The human author owns the
-commit; if an AI tool helped author this diff, add its `Co-Authored-By:` line from
-`config.yaml` `build.ai_coauthor.allowed` (the `.gitmessage` template scaffolds the choices). Keep all
-trailers in one contiguous block. Do not commit sibling tasks' work.
+commit; **no `Co-Authored-By:` footer by default** — add one only when the human explicitly asks
+(`yad commit --ai <id>` / the `.gitmessage` choices from `config.yaml` `build.ai_coauthor.allowed`),
+never on the AI's own initiative. Keep all trailers in one contiguous block. Do not commit sibling tasks' work.
 
 ### Step 7 — Report; the advance decision belongs to the dial (Phase 4)
 Report: the branch name, the files changed, how the change satisfies the task's acceptance criterion,

package/skills/yad-ship/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-ship
-description: 'Build-half helper of the gated SDLC — commit AND open the task PR/MR in one step. A thin orchestration over yad-commit then yad-open-pr: commit the staged atomic change by the conventions (Conventional-Commits subject, Task → Contract-Change → Co-Authored-By trailers, --ai footer, ≤3-file atomic guard), then push the branch and open 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. Use when the user says "ship this task", "commit and open the PR", or "commit and raise the MR". (For the engineer review + merge, use yad-engineer-review.)'
+description: 'Build-half helper of the gated SDLC — commit AND open the task PR/MR in one step. A thin orchestration over yad-commit then yad-open-pr: commit the staged atomic change by the conventions (Conventional-Commits subject, Task → Contract-Change trailers, an OPTIONAL Co-Authored-By footer that is OFF by default and added only when --ai <id> is explicitly passed, ≤3-file atomic guard), then push the branch and open 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. Use when the user says "ship this task", "commit and open the PR", or "commit and raise the MR". (For the engineer review + merge, use yad-engineer-review.)'
 ---
 
 # SDLC — Commit + Open PR/MR (build-half helper)
@@ -16,8 +16,8 @@ its own and **never merges**. The engineer review + merge are Step E (`yad-engin
   task branch with the atomic change **already staged** (`git add`).
 - Inherits every convention of the two steps it wraps:
   - Commit: subject `<type>: <lowercase imperative, no trailing period>`, fixed trailer order
-    `Task → Contract-Change → Co-Authored-By`, the `--ai` co-author footer, the ≤3-file atomic guard
-    (`../yad-commit/SKILL.md`).
+    `Task → Contract-Change → Co-Authored-By` (the footer **off by default** — added only via an explicit
+    `--ai`), the ≤3-file atomic guard (`../yad-commit/SKILL.md`).
   - PR/MR: pushed branch, the committed template prefilled, title defaulting to the commit subject,
     roster auto-assign, risk routing (`../yad-open-pr/SKILL.md`).
 - **Order matters:** the PR/MR is opened **only if the commit lands**. A failed commit, a tripped
@@ -26,7 +26,8 @@ its own and **never merges**. The engineer review + merge are Step E (`yad-engin
 ## Inputs
 
 - `type` / `message` — the commit type + subject (required), `--type <t> -m "<subject>"`.
-- `ai`              — co-author footer: `claude|copilot|cursor|coderabbit|none` (default `none`).
+- `ai`              — co-author footer: `claude|copilot|cursor|coderabbit|none` (default `none` = **no
+  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`).
@@ -54,6 +55,8 @@ 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.
+- **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.
 - **High risk routes to domain owners** — the same escalation as the gate.
 - **Shipping here never merges.** The human owns the merge in `yad-engineer-review`.

package/skills/yad-sync-repos/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: yad-sync-repos
+description: 'Brings every connected code repo up to date in one shot: switches each repo in .sdlc/repos.json to its registry default_branch and fast-forwards it to the latest from origin (local-user git, no stored tokens). A working-tree-only maintenance op — never a gate; it reads the registry but never writes it. A repo with uncommitted local changes is skipped and reported, never overwritten; a diverged branch is left for manual resolution (fast-forward only). After pulling, a repo''s cached code-context pack goes stale, so it points the human at `yad repo refresh`. Use when the user says "sync the repos", "switch all repos to the default branch", "pull latest on every repo", or "get the latest from the default branch".'
+---
+
+# SDLC — Sync Connected Repos (one command, every repo on its default branch)
+
+**Goal:** Before front/build work starts, get every connected code repo onto its default branch at the
+latest commit, so nobody implements on a stale or wrong branch. This is the deterministic counterpart to
+the `sync-before-implementation` discipline: one command instead of N manual `git checkout && git pull`.
+
+This is **setup/maintenance, not a gated state** — it never touches `.sdlc/state.json`, any epic's
+approvals, or the contract lock. It reads the project-wide registry and only mutates each repo's working
+tree (branch + fast-forward). It writes **nothing** back to the registry.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory (the **product hub**).
+- Registry: `{project-root}/.sdlc/repos.json` (project-wide; the same file `yad-connect-repos` writes).
+  Each repo entry supplies `path` (local path, relative to `{project-root}` or absolute) and
+  `default_branch` (the branch to land on).
+- **Local-user auth only.** Fetch as the user running the command — their SSH key or git credential
+  helper. Store no tokens. Works for GitHub and GitLab alike. If a fetch fails on auth, the repo is
+  skipped (STOP and tell the user to authenticate); never embed a credential.
+- The deterministic half is the **`yad repo sync` CLI command** — `yad repo sync` (all repos) or
+  `yad repo sync <name>` (one). This skill drives that command and explains the result.
+
+## Inputs
+
+- `action` — `sync` (this skill's only action).
+- `repo` — optional short name (the registry `name`, e.g. `backend`) to sync a single repo; omit for all.
+
+## On Activation
+
+Run `yad repo sync [<repo>]`. For each target repo it performs, in order:
+
+### Step 1 — Locate and validate the repo
+Resolve the local path from the registry. If the path is not a git repo (no readable `HEAD`), warn and
+skip — there is nothing to switch.
+
+### Step 2 — Skip a dirty working tree (never overwrite local work)
+If `git status --porcelain` is non-empty, the repo has uncommitted changes: **skip it and warn**
+(`<name> dirty → SKIPPED (commit/stash first)`). The skill never stashes, resets, or force-checks-out —
+preserving local work is a hard rule.
+
+### Step 3 — Determine the default branch
+Use the registry `default_branch`. If absent, fall back to the remote's `origin/HEAD`, else `main`.
+
+### Step 4 — Fetch the latest
+If the repo has an `origin` remote: `git fetch origin <default_branch> --prune`. A local-only repo
+(no remote) skips the fetch and just switches branch.
+
+### Step 5 — Switch to the default branch
+If not already on it, `git checkout <default_branch>` (git creates the tracking branch from `origin/`
+when needed).
+
+### Step 6 — Fast-forward only
+`git merge --ff-only origin/<default_branch>`. If the branch has diverged (a real merge would be
+required), **do not pull** — warn (`<name> diverged → not fast-forwarded`) and leave it for the human.
+Never create a merge commit, rebase, or force.
+
+### Step 7 — Report
+Per repo: `switched to <branch>, pulled (ff)` / `already current` / `SKIPPED (...)`. Pulling moves HEAD,
+so any repo whose `HEAD` now differs from its registry `syncedHead` has a **stale code-context pack** —
+the command ends by pointing the human at `yad repo refresh` to repack (that is a separate human
+decision; this skill never repacks or writes the registry).
+
+## Hard rules
+
+- **Dirty = skip.** Never stash, reset, or discard uncommitted changes.
+- **Fast-forward only.** A diverged branch is reported and left alone — no merge/rebase/force.
+- **Local-user auth; store no tokens.** Fetch as the user; an auth failure skips that repo.
+- **Working-tree only; not a gate.** Never write `.sdlc/repos.json`, `.sdlc/state.json`, approvals, or
+  the contract lock. Refreshing the cached pack is the separate, human-invoked `yad repo refresh`.
+
+## Reference
+- Registry schema + the HEAD-sha freshness rule this reports against: `../yad-connect-repos/references/repos-registry.md`.
+- Connecting / refreshing repos and the code-context cache: `../yad-connect-repos/SKILL.md`.