yadflow 3.8.1 → 3.9.0

package/CHANGELOG.md

@@ -1,9 +1,14 @@
-## [3.8.1](https://github.com/abdelrahmannasr/yadflow/compare/v3.8.0...v3.8.1) (2026-07-05)
+# [3.9.0](https://github.com/abdelrahmannasr/yadflow/compare/v3.8.1...v3.9.0) (2026-07-05)
 
 
 ### Bug Fixes
 
-* **hub-bridge:** filter glab api output with jq in gate-sync ([352c681](https://github.com/abdelrahmannasr/yadflow/commit/352c681f9e5c6d43688410cfc5092c2382ec881e)), closes [#108](https://github.com/abdelrahmannasr/yadflow/issues/108)
+* **cli:** retry the publish push when the index is unchanged; note the registry in docs ([55209c0](https://github.com/abdelrahmannasr/yadflow/commit/55209c01e50e3a635e7311acd1ad10e8c61c5534))
+
+
+### Features
+
+* **cli:** add `yad repo refresh --push` to publish code-map refresh to the hub ([0e3697d](https://github.com/abdelrahmannasr/yadflow/commit/0e3697d0be4ec5d11c300be9b02e04468f07ba8c))
 
 # [2.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.1.0...v2.2.0) (2026-06-14)
 

package/bin/yad.mjs

@@ -103,7 +103,9 @@ ${c.bold('Build helpers')}
   yad review nudge --repo <r> --pr <n>                    Friendly @-mention on a bare code-PR approve
   yad review reconcile --epic <id> --repo <r> --pr <n>    Bridge: stamp engagement onto the build-log ship
   yad repo list                        Show connected repos (fresh / stale)
-  yad repo refresh [name]              Re-pack a stale repo (a human decision)
+  yad repo refresh [name] [--push]     Re-pack a stale repo (a human decision). --push commits the
+                       refreshed code-maps + registry as a chore(hub): sync code-context … [skip ci]
+                       audit commit and pushes it to the hub default branch (--allow-branch to override)
 
 ${c.bold('Feature threads (post-lock change management)')}
   yad thread                           List every feature thread (genesis → changes → defects)
@@ -136,7 +138,7 @@ ${c.bold('Options')}
   --merged              gate ci: merge phase — advance the step on the default branch
   --no-push             gate ci: commit the ledger but do not push
   --push                check --fix / update: commit + push applied changes to the default branch
-  --allow-branch        check --fix --push / update --push: allow committing on a non-default branch
+  --allow-branch        check --fix --push / update --push / repo refresh --push: allow committing on a non-default branch
   -h, --help            Show this help
   -v, --version         Print version`;
 
@@ -289,7 +291,7 @@ async function main() {
     }
     case 'repo': {
       const [, action, name] = o._;
-      await runRepo(o.dir, { action: action || 'list', name, today });
+      await runRepo(o.dir, { action: action || 'list', name, today, push: o.push, allowBranch: o.allowBranch });
       break;
     }
     case 'roster': {

package/cli/hubcommit.mjs

@@ -2,10 +2,32 @@
 // `yad checkpoint` (sync new state) and `yad tidy up` (fold finished shards). Both must commit ONLY on
 // the default branch, so their `[skip ci]` commit never enters a PR's base..HEAD range (where it would
 // strand required checks and fail verified-commits). This module is the single home of that guard.
+import fs from 'node:fs';
+import path from 'node:path';
 import { warn, fail, hand, run } from './lib.mjs';
 
 export const hubGit = (root) => (...args) => run('git', args, { cwd: root });
 
+const readFileSafe = (p) => { try { return fs.readFileSync(p, 'utf8'); } catch { return ''; } };
+
+// A direct-to-default push (`yad update --push`, `yad repo refresh --push`) will be rejected by the
+// yad-update-guard unless the commits are signed AND their author email is allowlisted. Warn up front
+// (never block) so the operator isn't surprised by a reddened default branch. Best-effort, hub-identity
+// based.
+export function preflightGuardReadiness(root) {
+  const gitcfg = (k) => run('git', ['config', '--get', k], { cwd: root }).stdout;
+  // Only commit.gpgsign actually enables signing — user.signingkey merely picks WHICH key once
+  // signing is on, so it must not count (it would hide the warning while commits stay unsigned).
+  const signing = run('git', ['config', '--bool', '--get', 'commit.gpgsign'], { cwd: root }).stdout === 'true';
+  if (!signing) warn('commit signing is not enabled (git config commit.gpgsign true) — the yad-update-guard requires a platform-Verified signature; unsigned pushes will fail the gate.');
+  const email = gitcfg('user.email').toLowerCase();
+  const allow = readFileSafe(path.join(root, '.sdlc', 'verified-authors'));
+  const known = allow.split('\n').map((l) => l.trim().toLowerCase()).filter((l) => l && !l.startsWith('#'));
+  if (known.length && email && !known.includes(email)) {
+    warn(`your git email <${email}> is not in .sdlc/verified-authors — the yad-update-guard will reject these commits (add it to the hub roster and re-run \`yad check --fix\`).`);
+  }
+}
+
 // The default branch: hub config, else the remote's published default (origin/HEAD), else 'main'.
 // NEVER the current branch — falling back to it (as gate.mjs does, safe there because CI checks out the
 // default branch) would make the guard below a no-op on a WIP branch and let an unsigned commit land in

package/cli/reconcile.mjs

@@ -4,27 +4,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import {
-  c, log, ok, info, warn, hand, readJSON, writeJSON, exists, run,
+  c, log, ok, info, warn, hand, readJSON, writeJSON, exists,
 } from './lib.mjs';
 
 const readFileSafe = (p) => { try { return fs.readFileSync(p, 'utf8'); } catch { return ''; } };
 
-// The yad-update-guard will reject the very commits `--push` is about to create unless they are
-// signed AND their author email is allowlisted. Warn up front (never block) so the operator isn't
-// surprised by a reddened default branch across every repo. Best-effort, hub-identity based.
-function preflightGuardReadiness(root) {
-  const gitcfg = (k) => run('git', ['config', '--get', k], { cwd: root }).stdout;
-  // Only commit.gpgsign actually enables signing — user.signingkey merely picks WHICH key once
-  // signing is on, so it must not count (it would hide the warning while commits stay unsigned).
-  const signing = run('git', ['config', '--bool', '--get', 'commit.gpgsign'], { cwd: root }).stdout === 'true';
-  if (!signing) warn('commit signing is not enabled (git config commit.gpgsign true) — the yad-update-guard requires a platform-Verified signature; unsigned pushes will fail the gate.');
-  const email = gitcfg('user.email').toLowerCase();
-  const allow = readFileSafe(path.join(root, '.sdlc', 'verified-authors'));
-  const known = allow.split('\n').map((l) => l.trim().toLowerCase()).filter((l) => l && !l.startsWith('#'));
-  if (known.length && email && !known.includes(email)) {
-    warn(`your git email <${email}> is not in .sdlc/verified-authors — the yad-update-guard will reject these commits (add it to the hub roster and re-run \`yad check --fix\`).`);
-  }
-}
+import { preflightGuardReadiness } from './hubcommit.mjs';
 import { VERSION, PROJECT_FILES } from './manifest.mjs';
 import {
   moduleActions, repoActions, hubActions, authorsActions,

package/cli/repo-publish.mjs

@@ -0,0 +1,145 @@
+// `yad repo refresh --push` — after a repack + registry stamp, commit the connected-repo code-context
+// (the tracked `code-map.md` per repo + the registry `.sdlc/repos.json`) and push it straight to the
+// hub's default branch, so a code-map refresh "just lands" for teammates / CI / `yad status` on other
+// machines instead of leaving a dirty tree for someone to hand-commit. This is the code-context
+// analogue of `yad checkpoint` (cli/checkpoint.mjs) and reuses its default-branch commit machinery.
+//
+// Invariants (shared with checkpoint):
+//   1. Stage an EXPLICIT allowlist — exactly the tracked code-maps + the registry (never `git add -A`,
+//      which would sweep unrelated work in the hub). The gitignored repomix pack.md is never staged.
+//   2. Commit ONLY on the hub's default branch (unless --allow-branch), so the `[skip ci]` audit
+//      commit never enters a PR's base..HEAD range where it would strand required checks.
+import fs from 'node:fs';
+import path from 'node:path';
+import { c, ok, info, fail, hand, exists, pushWithRebase } from './lib.mjs';
+import { PROJECT_FILES } from './manifest.mjs';
+import { loadHub } from './gate.mjs';
+import { resolveCommitterLogin } from './platform.mjs';
+import { hubGit, resolveDefaultBranch, guardDefaultBranch, preflightGuardReadiness } from './hubcommit.mjs';
+import { checkpointAuthor } from './checkpoint.mjs';
+
+// Collapse any whitespace/newline runs to a single space — keeps a hostile `git user.name` or a stray
+// path from breaking the one-line subject or injecting a fake trailer line.
+const oneLine = (s = '') => String(s).replace(/\s+/g, ' ').trim();
+
+// The tracked code-map for a repo: the registered path, else the conventional location.
+const codeMapOf = (repo) => repo.codeMap || path.posix.join('.sdlc/code-context', repo.name, 'code-map.md');
+
+// PURE — the repo-relative pathspecs to stage: the registry plus each registered repo's code-map that
+// exists on disk. When `name` is given (a scoped `yad repo refresh <name> --push`), only that repo's
+// code-map is staged, so an unrelated repo's uncommitted code-map never rides along in a named refresh's
+// audit commit. Explicit allowlist by design (invariant 1); the gitignored pack.md is never included.
+export function codeMapPathspecs(root, registry = { repos: [] }, name = null) {
+  const out = [];
+  for (const repo of registry.repos || []) {
+    if (name && repo.name !== name) continue;
+    const rel = codeMapOf(repo);
+    if (fs.existsSync(path.join(root, rel))) out.push(rel);
+  }
+  // The registry always rides along — `yad repo refresh` stamps syncedHead/lastSyncedAt into it.
+  if (fs.existsSync(path.join(root, PROJECT_FILES.reposRegistry))) out.push(PROJECT_FILES.reposRegistry);
+  return out;
+}
+
+// PURE — turn the staged pathspecs into the subject `label` + the body's file list. A `<name>` is
+// pulled from any `.sdlc/code-context/<name>/code-map.md` path; a commit that only touched the
+// registry is labelled `registry`.
+export function summarizeCodeContext(files = []) {
+  const repos = new Set();
+  const basenames = [];
+  for (const f of files) {
+    basenames.push(f);
+    const m = f.match(/\.sdlc\/code-context\/([^/]+)\/code-map\.md$/);
+    if (m) repos.add(m[1]);
+  }
+  let label;
+  if (repos.size === 1) label = [...repos][0];
+  else if (repos.size > 1) label = `${repos.size} repos`;
+  else label = 'registry';
+  return { label, basenames };
+}
+
+// PURE — the audit-trail commit message. Subject passes the hub commit-message gate (valid type
+// `chore`, scope `hub`, non-empty description, no trailing period). No Task trailer and no
+// Co-Authored-By: this is human-owned machine state, not an authored code change. `[skip ci]` mirrors
+// `yad checkpoint` — it lands on the default branch and needs no PR gate suite. `label`/`author` are
+// collapsed to one line so nothing can split the subject or forge a trailer.
+export function buildCodeMapMessage({ label, author, basenames = [] }) {
+  const subject = `chore(hub): sync code-context — ${oneLine(label)} by ${oneLine(author)} [skip ci]`;
+  const body = basenames.length ? `Updated: ${basenames.join(', ')}` : '';
+  return body ? `${subject}\n\n${body}` : subject;
+}
+
+// Commit the tracked code-context (and, with push, push it) on the hub's default branch. Mirrors
+// `runCheckpoint`. Never throws; sets process.exitCode on a hard error so the CLI reports failure.
+export async function publishCodeContext(root, { push = false, allowBranch = false, name = null } = {}) {
+  if (!exists(path.join(root, '.git'))) { fail('not a git repo'); process.exitCode = 1; return; }
+  if (!exists(path.join(root, PROJECT_FILES.hubConfig))) {
+    fail('no .sdlc/hub.json — --push publishes the hub code-context; run it from the product hub');
+    process.exitCode = 1;
+    return;
+  }
+
+  const { hub, repos } = loadHub(root);
+  const registry = { repos: repos || [] };
+  const git = hubGit(root);
+
+  const branch = git('rev-parse', '--abbrev-ref', 'HEAD').stdout;
+  const defaultBranch = resolveDefaultBranch(git, hub);
+  if (!guardDefaultBranch(branch, defaultBranch, { allowBranch, cmd: 'yad repo refresh --push' })) return;
+
+  const pathspecs = codeMapPathspecs(root, registry, name);
+  if (!pathspecs.length) { info('no code-context to publish — nothing to commit'); return; }
+
+  const add = git('add', '--', ...pathspecs);
+  if (!add.ok) { fail(`git add failed — ${add.stderr.split('\n')[0] || add.code}`); process.exitCode = 1; return; }
+
+  // Push HEAD to its OWN branch — on the default branch this is the same; with --allow-branch it keeps a
+  // WIP branch from being force-published onto the default branch. Shared by the fresh-commit path and
+  // the retry-after-failed-push path below.
+  const pushHead = () => {
+    if (pushWithRebase(root, branch).ok) { ok(`pushed to origin/${branch}`); return true; }
+    fail(`could not push to origin/${branch} — a protected branch, or an unresolvable rebase conflict`);
+    hand(`run \`git pull --rebase\` and re-run \`yad repo refresh --push\``);
+    process.exitCode = 1;
+    return false;
+  };
+
+  if (git('diff', '--cached', '--quiet', '--', ...pathspecs).ok) {
+    // Nothing new to commit. A non-push run is simply done. But on a push run a PRIOR run may have
+    // committed and then FAILED to push (the commit sits ahead of origin) — a plain re-run must land
+    // that commit, not silently no-op and exit 0 while it stays stranded. Push any unpushed commit(s).
+    if (!push) { info('code-context unchanged — nothing to commit'); return; }
+    const rev = git('rev-list', '--count', `origin/${branch}..HEAD`);
+    const ahead = rev.ok ? (Number(rev.stdout) || 0) : 1; // no upstream ref yet -> attempt the push
+    if (!ahead) { info('code-context unchanged and already published — nothing to do'); return; }
+    info(`code-context unchanged — pushing ${ahead} already-committed change(s) not yet on origin/${branch}`);
+    pushHead();
+    return;
+  }
+  // The exact files staged from the allowlist — scopes the commit to ONLY the allowlist, so any
+  // unrelated pre-staged file never rides along.
+  const staged = git('diff', '--cached', '--name-only', '--', ...pathspecs).stdout.split('\n').filter(Boolean);
+
+  // Only relevant when we are about to push a commit straight to the default branch: warn (never block)
+  // if signing/allowlisting would make the yad-update-guard reject it. Gated on `push` and deferred to
+  // here so it isn't noise on a guard-refused branch or a nothing-to-commit run.
+  if (push) preflightGuardReadiness(root);
+
+  const { label, basenames } = summarizeCodeContext(staged);
+  const author = checkpointAuthor(resolveCommitterLogin(root, hub?.roster || []), git('config', 'user.name').stdout);
+  const message = buildCodeMapMessage({ label, author, basenames });
+
+  const cm = git('commit', '-m', message, '--', ...staged);
+  if (!cm.ok) {
+    git('reset', '-q', '--', ...pathspecs); // don't leave the allowlist staged for an unrelated commit to sweep up
+    fail(`git commit failed — ${cm.stderr.split('\n')[0] || cm.code}`);
+    process.exitCode = 1;
+    return { message };
+  }
+  ok(`published ${staged.length} file(s): ${c.dim(label)}`);
+
+  if (!push) return { message };
+  pushHead();
+  return { message };
+}

package/cli/repo.mjs

@@ -7,6 +7,7 @@ import path from 'node:path';
 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';
+import { publishCodeContext } from './repo-publish.mjs';
 
 function load(root) {
   const regPath = path.join(root, PROJECT_FILES.reposRegistry);
@@ -35,7 +36,7 @@ function defaultBranch(cwd, repo) {
   return r.ok && r.stdout ? r.stdout.replace(/^origin\//, '') : 'main';
 }
 
-export async function runRepo(root, { action = 'list', name, today } = {}) {
+export async function runRepo(root, { action = 'list', name, today, push = false, allowBranch = false } = {}) {
   const { regPath, registry } = load(root);
   if (!registry.repos.length) { warn('no repos registered (.sdlc/repos.json) — run `yad setup`'); return { repos: 0 }; }
 
@@ -69,7 +70,16 @@ export async function runRepo(root, { action = 'list', name, today } = {}) {
     }
     writeJSON(regPath, registry);
     refreshed ? ok(`refreshed ${refreshed} repo(s)`) : info('nothing refreshed');
-    hand('regenerate the code-map in Claude Code (yad-connect-repos) — the pack is cached, the map is the AI step');
+    if (push) {
+      // Publish whatever tracked code-context now differs (the AI-regenerated code-maps + the stamped
+      // registry) straight to the hub's default branch as one audit-trail commit. The pack itself is
+      // gitignored; the code-map is regenerated by the AI (yad-connect-repos) — run that first if a
+      // repo's map is stale, then `yad repo refresh --push` lands it.
+      await publishCodeContext(root, { push: true, allowBranch, name });
+    } else {
+      hand('regenerate the code-map in Claude Code (yad-connect-repos) — the pack is cached, the map is the AI step');
+      hand('then publish it to the hub default branch with `yad repo refresh --push`');
+    }
     return { refreshed };
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "3.8.1",
+  "version": "3.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, thread, reconcile). A BMAD module + 38 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",

package/skills/sdlc/module-help.csv

@@ -9,7 +9,7 @@ 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-sync-repos,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. yad repo refresh --push publishes the refreshed code-maps + registry to the hub default branch as a chore(hub): sync code-context [skip ci] audit commit. 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

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

@@ -1,6 +1,6 @@
 ---
 name: yad-connect-repos
-description: 'Connects code repos to the product hub so the front/"brain" phases are code-aware. Registers N code repos (GitHub or GitLab, local-user auth, no stored tokens) into the project-wide .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. Run at one-time setup or any time a new repo is added. Reusable, idempotent, refreshable; staleness is tracked by HEAD sha. Use when the user says "connect a repo", "connect the code repos", "refresh the code context", or "list connected repos".'
+description: 'Connects code repos to the product hub so the front/"brain" phases are code-aware. Registers N code repos (GitHub or GitLab, local-user auth, no stored tokens) into the project-wide .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. Run at one-time setup or any time a new repo is added. Reusable, idempotent, refreshable; staleness is tracked by HEAD sha. `yad repo refresh --push` publishes the refreshed code-maps + registry to the hub default branch as a chore(hub): sync code-context [skip ci] audit commit. Use when the user says "connect a repo", "connect the code repos", "refresh the code context", "list connected repos", or "push the code-map refresh".'
 ---
 
 # SDLC — Connect Code Repos (make the brain code-aware)
@@ -109,7 +109,13 @@ the front phases will now load this repo's code-map. Nothing auto-advances; this
 ## Other actions
 
 - **`refresh`** — re-run Steps 2–4 for an already-connected repo (after its code moves). Updates
-  `syncedHead` + `lastSyncedAt`. Same machinery as `connect`.
+  `syncedHead` + `lastSyncedAt`. Same machinery as `connect`. Once the AI has regenerated the
+  `code-map.md` (Step 3), publish it to the product hub with **`yad repo refresh <repo> --push`**: it
+  commits the tracked code-maps + `.sdlc/repos.json` (never the gitignored `pack.md`) as one
+  audit-trail commit `chore(hub): sync code-context — <repos> by @<login> [skip ci]` and pushes it
+  straight to the hub's **default branch** (add `--allow-branch` to commit on a non-default branch).
+  This is the code-context analogue of `yad checkpoint` — human-owned machine state, no Task trailer,
+  no Co-Authored-By.
 - **`list`** — print every registry entry with a **fresh/stale** flag: compare each repo's current HEAD
   (`git -C <path> rev-parse HEAD`) to its `syncedHead`; differ ⇒ **stale** (suggest `refresh`).
 - **`disconnect`** — remove the repo from the registry and delete its cache dir. Leaves the **code repo

package/skills/yad-connect-repos/references/code-context.md

@@ -80,7 +80,9 @@ This is for a one-off look at a specific area. **Staleness is a human decision,
 side-effect:** when a repo is stale (HEAD ≠ `syncedHead`), the phase **flags it and stops** —
 "`<repo>` is stale; run `yad repo refresh <repo>` to re-pack the cache + `syncedHead`" — rather than
 silently re-packing the whole repo. A phase never refreshes the registry on its own; the human runs
-`yad repo refresh` (or `yad check --fix`).
+`yad repo refresh` (or `yad check --fix`). After the AI regenerates the code-map, `yad repo refresh
+--push` publishes the refreshed code-maps + registry to the hub's default branch as a `chore(hub): sync
+code-context … [skip ci]` audit commit (never `pack.md`; `--allow-branch` overrides the branch guard).
 
 ## Why this stays DRY with backfill
 

package/skills/yad-connect-repos/references/repos-registry.md

@@ -52,6 +52,8 @@ not under any `epics/EP-<slug>/.sdlc/`.
 
 Commit the **registry** (`repos.json`) and each repo's **`code-map.md`** — they are small, reviewable,
 and are what the front phases actually read (a diff on a code-map shows when a repo's surface moved).
+`yad repo refresh --push` commits and pushes exactly these (never `pack.md`) to the hub's default
+branch as one `chore(hub): sync code-context … [skip ci]` audit commit.
 **Ignore** the full Repomix `pack.md` — it is large and regenerable (`action: refresh`). The product
 hub's `.gitignore` carries `.sdlc/code-context/*/pack.md` for this. This mirrors how the per-epic
 `.sdlc/` state (state.json, approvals.json, build-log.json) is committed.

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

@@ -63,7 +63,9 @@ Never create a merge commit, rebase, or force.
 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).
+decision; this skill never repacks or writes the registry). After the repack + AI code-map
+regeneration, `yad repo refresh --push` publishes the refreshed code-maps + registry to the hub's
+default branch as a `chore(hub): sync code-context … [skip ci]` audit commit.
 
 ## Hard rules