yadflow 1.0.1

package/cli/manifest.mjs

@@ -0,0 +1,119 @@
+// The single source of truth for what a set-up SDLC project should contain.
+// Drives setup (install from), update (re-sync), and check (diff against).
+// Keep the skill list here in sync with skills/sdlc/install.sh.
+import { readFileSync } from 'node:fs';
+
+// Read the version from package.json (the one source of truth) so it always
+// tracks the semantic-release-managed version — never a hardcoded constant
+// that would drift after a release. package.json ships in the npm tarball and
+// sits at the package root, one level up from this cli/ dir.
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+export const VERSION = version;
+
+// The 17 hand-authored sdlc-* skills (mirrors skills/sdlc/install.sh).
+export const SKILLS = [
+  'sdlc-author-analysis',
+  'sdlc-author-epic',
+  'sdlc-author-architecture',
+  'sdlc-author-ui',
+  'sdlc-author-stories',
+  'sdlc-connect-repos',
+  'sdlc-spec',
+  'sdlc-implement',
+  'sdlc-checks',
+  'sdlc-pr-template',
+  'sdlc-review-comments',
+  'sdlc-hub-bridge',
+  'sdlc-ship',
+  'sdlc-backfill',
+  'sdlc-run',
+  'sdlc-review-gate',
+  'sdlc-status',
+];
+
+// IDE install targets (relative to the target project root).
+export const IDE_FOLDER_TARGETS = ['.claude', '.agents', '.zencoder']; // <ide>/skills/<skill>/ (folder copy)
+export const IDE_OPENCODE_DIR = '.opencode/commands'; // <skill>.md (flat SKILL.md copy)
+
+// Module registration files copied from skills/sdlc/ into _bmad/sdlc/.
+export const MODULE_FILES = ['config.yaml', 'module-help.csv'];
+
+// Project-level files setup produces (used by `check` to spot missing setup).
+export const PROJECT_FILES = {
+  reposRegistry: '.sdlc/repos.json',
+  hubConfig: '.sdlc/hub.json',
+  version: '.sdlc/cli-version.json',
+};
+
+// ---- `sdlc commit` conventions (mirror skills/sdlc/config.yaml `build`) ----
+// Conventional-commit types (config.yaml commit_subject_style).
+export const COMMIT_TYPES = ['feat', 'fix', 'docs', 'refactor', 'test', 'perf', 'build', 'ci', 'chore', 'revert'];
+// Per-commit AI co-author choices (config.yaml build.ai_coauthor.allowed). The human git author OWNS
+// the commit; the AI is only a Co-Authored-By trailer. `none` => human-only (trailer omitted).
+export const AI_COAUTHORS = {
+  claude: { name: 'Claude', email: 'noreply@anthropic.com' },
+  copilot: { name: 'GitHub Copilot', email: 'copilot@users.noreply.github.com' },
+  cursor: { name: 'Cursor', email: 'noreply@cursor.com' },
+  coderabbit: { name: 'CodeRabbit', email: 'noreply@coderabbit.ai' },
+  none: null,
+};
+// Atomic-commit guard: warn/refuse above this many staged files (build plan: ≤3 where possible).
+export const ATOMIC_FILE_LIMIT = 3;
+// Trailer order is fixed: Task -> Contract-Change -> Co-Authored-By (config.yaml build comment).
+export const TASK_TRAILER = 'Task';
+export const CONTRACT_CHANGE_TRAILER = 'Contract-Change';
+export const COAUTHOR_TRAILER = 'Co-Authored-By';
+
+// Per-epic ledger files under epics/<epic>/.sdlc/ (the file source of truth the gate reads/writes).
+export const epicFiles = (epicRoot) => ({
+  state: `${epicRoot}/.sdlc/state.json`,
+  approvals: `${epicRoot}/.sdlc/approvals.json`,
+  comments: `${epicRoot}/.sdlc/comments.json`,
+  hubPrs: `${epicRoot}/.sdlc/hub-prs.json`,
+  contractLock: `${epicRoot}/.sdlc/contract-lock.json`,
+});
+
+// Per-repo wiring: src is relative to PKG_ROOT, dest relative to the repo root.
+// `common` always installs; the platform key installs by detected platform.
+export const REPO_WIRING = {
+  common: [
+    { src: 'skills/sdlc-checks/templates/checks/spec-link.sh', dest: 'checks/spec-link.sh', exec: true },
+    { src: 'skills/sdlc-checks/templates/checks/contract-check.sh', dest: 'checks/contract-check.sh', exec: true },
+    { src: 'skills/sdlc-checks/templates/checks/build-test-lint.sh', dest: 'checks/build-test-lint.sh', exec: true },
+    { src: 'skills/sdlc-checks/templates/checks/verified-commits.sh', dest: 'checks/verified-commits.sh', exec: true },
+    { src: 'skills/sdlc-pr-template/templates/checks/risk-route.sh', dest: 'checks/risk-route.sh', exec: true },
+  ],
+  github: [
+    { src: 'skills/sdlc-checks/templates/github/sdlc-checks.yml', dest: '.github/workflows/sdlc-checks.yml' },
+    { src: 'skills/sdlc-pr-template/templates/github/pull_request_template.md', dest: '.github/pull_request_template.md' },
+    { src: 'skills/sdlc-review-comments/templates/github/REVIEW_COMMENTS.md', dest: '.github/REVIEW_COMMENTS.md' },
+  ],
+  gitlab: [
+    { src: 'skills/sdlc-checks/templates/gitlab/sdlc-checks.gitlab-ci.yml', dest: '.gitlab/ci/sdlc-checks.yml' },
+    { src: 'skills/sdlc-pr-template/templates/gitlab/merge_request_templates/Default.md', dest: '.gitlab/merge_request_templates/Default.md' },
+    { src: 'skills/sdlc-review-comments/templates/gitlab/REVIEW_COMMENTS.md', dest: '.gitlab/REVIEW_COMMENTS.md' },
+  ],
+};
+
+export const wiringFor = (platform) => [
+  ...REPO_WIRING.common,
+  ...(REPO_WIRING[platform] || []),
+];
+
+// Hub wiring: CI installed on the PRODUCT HUB itself (dest is the project root — the hub IS the
+// root). Installed only when hub.json has a platform and the bridge is enabled. Carries the
+// event-driven gate sync (approvals/change requests/the merge trigger `sdlc gate ci`) and the
+// verified-commits gate (no unverified commits from unverified users reach merge on the hub).
+export const HUB_WIRING = {
+  common: [
+    { src: 'skills/sdlc-checks/templates/checks/verified-commits.sh', dest: 'checks/verified-commits.sh', exec: true },
+  ],
+  github: [
+    { src: 'skills/sdlc-hub-bridge/templates/github/sdlc-gate-sync.yml', dest: '.github/workflows/sdlc-gate-sync.yml' },
+    { src: 'skills/sdlc-checks/templates/github/sdlc-verified-commits.yml', dest: '.github/workflows/sdlc-verified-commits.yml' },
+  ],
+  gitlab: [
+    { src: 'skills/sdlc-hub-bridge/templates/gitlab/sdlc-gate-sync.gitlab-ci.yml', dest: '.gitlab/ci/sdlc-gate-sync.yml' },
+    { src: 'skills/sdlc-checks/templates/gitlab/sdlc-verified-commits.gitlab-ci.yml', dest: '.gitlab/ci/sdlc-verified-commits.yml' },
+  ],
+};

package/cli/openpr.mjs

@@ -0,0 +1,65 @@
+// `sdlc open-pr` — open a code-repo task PR/MR from the repo's platform template (build half).
+// Detects the platform, pushes the current branch, and creates the PR/MR with Summary / Story-task /
+// Impact & Risk prefilled. Distinct from `sdlc gate open`, which opens a front-half artifact-review PR
+// 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 { PROJECT_FILES } from './manifest.mjs';
+import { detectPlatform, createPr } from './platform.mjs';
+import { taskFromBranch } from './commit.mjs';
+
+// Resolve the target code repo: --repo <name> from the registry, else --dir, else cwd.
+function resolveRepo(root, { repo, dir }) {
+  if (repo) {
+    const reg = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
+    const found = reg.repos.find((r) => r.name === repo);
+    if (found) return { repoRoot: path.resolve(root, found.path), meta: found };
+  }
+  return { repoRoot: path.resolve(root, dir || '.'), meta: null };
+}
+
+function templateBody(repoRoot, platform, { task, risk, contract, domains }) {
+  const tplPath = platform === 'gitlab'
+    ? path.join(repoRoot, '.gitlab/merge_request_templates/Default.md')
+    : path.join(repoRoot, '.github/pull_request_template.md');
+  const base = exists(tplPath) ? fs.readFileSync(tplPath, 'utf8') : '## Summary\n\n## Impact & Risk\n';
+  // Fill the obvious fields; leave the rest of the committed template intact for the author.
+  return base
+    .replace(/EP-<slug>-S0N-T0N/g, task || 'EP-<slug>-S0N-T0N')
+    .replace(/(\*\*Risk level:\*\*)\s*\w+/i, `$1 ${risk}`)
+    .replace(/(\*\*Contract surface touched:\*\*)\s*\w+/i, `$1 ${contract ? 'yes' : 'no'}`)
+    .replace(/(\*\*Domains \/ repos touched:\*\*).*/i, `$1 ${domains || '<repo>'}`);
+}
+
+export async function runOpenPr(root, opts = {}) {
+  log(c.bold('\nsdlc open-pr'));
+  const { repoRoot, meta } = resolveRepo(root, opts);
+  if (!exists(path.join(repoRoot, '.git'))) { fail(`not a git repo: ${repoRoot}`); process.exitCode = 1; return; }
+
+  const remote = run('git', ['remote', 'get-url', 'origin'], { cwd: repoRoot }).stdout;
+  const platform = opts.platform || meta?.platform || detectPlatform(remote);
+  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; }
+
+  // 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} …`);
+  const push = run('git', ['push', '-u', 'origin', branch], { cwd: repoRoot });
+  if (!push.ok) { fail(`git push failed — ${push.stderr.split('\n')[0] || 'unknown'}`); process.exitCode = 1; return; }
+
+  const task = opts.task || taskFromBranch(branch);
+  const title = opts.title || run('git', ['log', '-1', '--format=%s'], { cwd: repoRoot }).stdout || `task ${task || branch}`;
+  const body = templateBody(repoRoot, platform, {
+    task, risk: opts.risk || 'low', contract: !!opts.contractChange, domains: meta?.name,
+  });
+
+  const r = createPr(platform, { title, body, base: baseBranch, head: branch, cwd: repoRoot });
+  if (!r.ok) { fail(`could not open PR/MR — ${r.reason || 'unknown'}`); process.exitCode = 1; return; }
+  ok(`opened ${r.url}`);
+  if (opts.risk === 'high' || opts.contractChange) hand('high risk / contract surface — run `bash checks/risk-route.sh "<pr body>"` for required reviewers');
+  return { url: r.url };
+}

package/cli/plan.mjs

@@ -0,0 +1,127 @@
+// Builds the deterministic action list (module install + per-repo wiring) for a
+// target project. Each action carries a current status and an apply() closure, so
+// setup (apply all), update (apply changed), and check (report; fix non-ok) share it.
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  asset, exists, copyDir, copyFile, dirMatches, sameContent, readJSON,
+} from './lib.mjs';
+import {
+  SKILLS, IDE_FOLDER_TARGETS, IDE_OPENCODE_DIR, MODULE_FILES, wiringFor, HUB_WIRING, PROJECT_FILES,
+} from './manifest.mjs';
+
+// status: 'ok' | 'missing' | 'outdated'
+const fileAction = (scope, item, src, dest, opts = {}) => ({
+  scope,
+  item,
+  status: !exists(dest) ? 'missing' : sameContent(src, dest) ? 'ok' : 'outdated',
+  apply: () => copyFile(src, dest, opts),
+});
+const dirAction = (scope, item, src, dest) => ({
+  scope,
+  item,
+  status: !exists(dest) ? 'missing' : dirMatches(src, dest) ? 'ok' : 'outdated',
+  apply: () => copyDir(src, dest),
+});
+
+// Which IDE targets this project wants. Recorded at setup time; falls back to
+// whichever IDE base dirs already exist, else .claude.
+export function ideTargetsFor(root) {
+  const rec = readJSON(path.join(root, PROJECT_FILES.version));
+  if (rec?.ideTargets?.length) return rec.ideTargets;
+  const present = [...IDE_FOLDER_TARGETS, '.opencode'].filter((d) => exists(path.join(root, d)));
+  return present.length ? present : ['.claude'];
+}
+
+// Module = skills installed into each IDE target + the _bmad/sdlc registration.
+export function moduleActions(root, ideTargets = ideTargetsFor(root)) {
+  const actions = [];
+  for (const ide of ideTargets) {
+    if (ide === '.opencode') {
+      for (const s of SKILLS) {
+        actions.push(fileAction(
+          ide, s,
+          asset('skills', s, 'SKILL.md'),
+          path.join(root, IDE_OPENCODE_DIR, `${s}.md`),
+        ));
+      }
+    } else {
+      for (const s of SKILLS) {
+        actions.push(dirAction(
+          ide, s,
+          asset('skills', s),
+          path.join(root, ide, 'skills', s),
+        ));
+      }
+    }
+  }
+  for (const f of MODULE_FILES) {
+    actions.push(fileAction(
+      '_bmad', f,
+      asset('skills', 'sdlc', f),
+      path.join(root, '_bmad', 'sdlc', f),
+    ));
+  }
+  return actions;
+}
+
+// Per-repo wiring (gate scripts, CI, PR template, comment scaffold).
+export function repoActions(root, repo) {
+  const repoRoot = path.resolve(root, repo.path);
+  return wiringFor(repo.platform).map((w) =>
+    fileAction(repo.name, w.dest, asset(w.src), path.join(repoRoot, w.dest), { exec: !!w.exec }),
+  );
+}
+
+// Hub wiring (gate-sync + verified-commits CI on the product hub itself). Only when the hub has a
+// platform and the bridge is explicitly enabled — a file-only hub stays file-only, with no error.
+export function hubActions(root) {
+  const hub = readJSON(path.join(root, PROJECT_FILES.hubConfig));
+  // `bridge_enabled` is the canonical flag (the documented hub-config schema); older setup versions
+  // wrote `bridge` — accept an explicit true in either spelling, wire nothing otherwise.
+  if (!hub?.platform || !(hub.bridge_enabled === true || hub.bridge === true)) return [];
+  return [...HUB_WIRING.common, ...(HUB_WIRING[hub.platform] || [])].map((w) =>
+    fileAction('hub', w.dest, asset(w.src), path.join(root, w.dest), { exec: !!w.exec }),
+  );
+}
+
+// Every email the verified-commits gate should accept as a known author: the hub roster's `email`
+// (or `emails`) fields plus hub.json's free-form `verified_authors` list. Lower-cased, deduped,
+// sorted — deterministic so the generated file is drift-checkable like any wired file.
+export function verifiedAuthorEmails(hub) {
+  const out = new Set();
+  for (const r of hub?.roster || []) {
+    for (const e of [r.email, ...(Array.isArray(r.emails) ? r.emails : [])]) {
+      if (e) out.add(String(e).toLowerCase());
+    }
+  }
+  for (const e of hub?.verified_authors || []) if (e) out.add(String(e).toLowerCase());
+  return [...out].sort();
+}
+
+// Generate .sdlc/verified-authors (one email per line) in the hub AND every registered repo, from
+// the hub config. No emails configured → no actions (the gate then warns instead of blocking —
+// never enforce an empty allowlist).
+export function authorsActions(root, repos = []) {
+  const hub = readJSON(path.join(root, PROJECT_FILES.hubConfig));
+  const emails = verifiedAuthorEmails(hub);
+  if (!emails.length) return [];
+  const desired = [
+    '# Generated by `sdlc check --fix` from .sdlc/hub.json (roster emails + verified_authors).',
+    '# The verified-commits gate accepts only these author emails. Edit hub.json, not this file.',
+    ...emails,
+  ].join('\n') + '\n';
+  const targets = [
+    { scope: 'hub', dest: path.join(root, '.sdlc', 'verified-authors') },
+    ...repos.map((r) => ({ scope: r.name, dest: path.join(path.resolve(root, r.path), '.sdlc', 'verified-authors') })),
+  ];
+  return targets.map(({ scope, dest }) => ({
+    scope,
+    item: '.sdlc/verified-authors',
+    status: !exists(dest) ? 'missing' : fs.readFileSync(dest, 'utf8') === desired ? 'ok' : 'outdated',
+    apply: () => {
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, desired);
+    },
+  }));
+}

package/cli/platform.mjs

@@ -0,0 +1,151 @@
+// Platform adapter — the ONLY place that shells out to gh/glab. Read recipes mirror
+// skills/sdlc-hub-bridge/references/bridge.md. Everything runs as the local user (gh/glab own auth);
+// no tokens are stored. Pure mapping fns (resolveLogin/mapApprovers) are exported for unit tests;
+// readPr is injectable so the gate can be tested with a fake.
+import { run, has } from './lib.mjs';
+
+// github | gitlab | null, from a repo/remote.
+export function detectPlatform(remoteUrl = '') {
+  if (/gitlab/i.test(remoteUrl)) return 'gitlab';
+  if (/github/i.test(remoteUrl)) return 'github';
+  return null;
+}
+
+export function cliFor(platform) {
+  if (platform === 'gitlab') return 'glab';
+  if (platform === 'github') return 'gh';
+  return null;
+}
+
+// Is the platform CLI present? (auth is the user's own; we don't probe it here.)
+export function platformReady(platform) {
+  const cli = cliFor(platform);
+  return !!cli && has(cli);
+}
+
+// ---- login -> sdlc identity (roster + derived domain-owner) -------------------------------------
+// Returns the records this login's APPROVED review contributes. A roster reviewer who owns a touched
+// repo's domain contributes BOTH a base record and a domain-owner record (bridge.md "Login -> role").
+export function resolveLogin(login, roster = [], repos = [], touchedDomains = []) {
+  const entry = roster.find((r) => r.login === login);
+  if (!entry) return [{ name: login, role: 'reviewer', unverified: true }];
+  const records = [{ name: entry.name, role: entry.role }];
+  for (const repo of repos) {
+    if (repo.domain_owner === entry.name && touchedDomains.includes(repo.name)) {
+      records.push({ name: entry.name, role: 'domain-owner', domain: repo.name });
+    }
+  }
+  return records;
+}
+
+// Normalized PR reviews -> approval records (only APPROVED states count). `submittedAt` rides along
+// so the gate can tell a fresh re-approval from a stale one (revoke-on-change).
+export function mapApprovers(reviews = [], { roster, repos, touchedDomains }) {
+  const out = [];
+  for (const r of reviews) {
+    if (r.state !== 'APPROVED') continue;
+    for (const rec of resolveLogin(r.login, roster, repos, touchedDomains)) {
+      out.push({ ...rec, submittedAt: r.submittedAt || null });
+    }
+  }
+  return out;
+}
+
+// ---- read PR state (github) ---------------------------------------------------------------------
+function readPrGitHub(n, { cwd } = {}) {
+  const view = run('gh', ['pr', 'view', String(n), '--json', 'state,mergedAt,headRefOid'], { cwd });
+  if (!view.ok) return { ok: false, reason: view.stderr || 'gh pr view failed' };
+  const meta = JSON.parse(view.stdout);
+  // latestReviews collapses a reviewer's superseded reviews to their current one.
+  const rev = run('gh', ['pr', 'view', String(n), '--json', 'latestReviews'], { cwd });
+  const reviews = rev.ok
+    ? (JSON.parse(rev.stdout).latestReviews || []).map((x) => ({ login: x.author?.login, state: x.state, submittedAt: x.submittedAt }))
+    : [];
+  // Review-thread resolution via GraphQL (REST does not expose isResolved). Paginate so a PR with
+  // >100 threads is not mistakenly read as "all resolved".
+  let threads = [];
+  const nwo = run('gh', ['repo', 'view', '--json', 'owner,name'], { cwd });
+  if (nwo.ok) {
+    const { owner, name } = JSON.parse(nwo.stdout);
+    const q = `query($o:String!,$r:String!,$n:Int!,$c:String){repository(owner:$o,name:$r){pullRequest(number:$n){reviewThreads(first:100,after:$c){pageInfo{hasNextPage endCursor} nodes{isResolved comments(first:1){nodes{author{login} body}}}}}}}`;
+    let cursor = null;
+    for (let guard = 0; guard < 50; guard++) {
+      const args = ['api', 'graphql', '-f', `query=${q}`, '-F', `o=${owner.login}`, '-F', `r=${name}`, '-F', `n=${n}`];
+      if (cursor) args.push('-F', `c=${cursor}`);
+      const g = run('gh', args, { cwd });
+      if (!g.ok) break;
+      const page = JSON.parse(g.stdout)?.data?.repository?.pullRequest?.reviewThreads;
+      for (const t of page?.nodes || []) {
+        threads.push({
+          id: `thread-${threads.length}`,
+          resolved: !!t.isResolved,
+          login: t.comments?.nodes?.[0]?.author?.login,
+          body: t.comments?.nodes?.[0]?.body,
+        });
+      }
+      if (!page?.pageInfo?.hasNextPage) break;
+      cursor = page.pageInfo.endCursor;
+    }
+  }
+  return {
+    ok: true,
+    state: meta.state,
+    merged: meta.state === 'MERGED' || !!meta.mergedAt,
+    headOid: meta.headRefOid,
+    reviews,
+    threads,
+  };
+}
+
+// ---- read PR state (gitlab) ---------------------------------------------------------------------
+function readPrGitLab(n, { cwd } = {}) {
+  const view = run('glab', ['mr', 'view', String(n), '-F', 'json'], { cwd });
+  if (!view.ok) return { ok: false, reason: view.stderr || 'glab mr view failed' };
+  const mr = JSON.parse(view.stdout);
+  const approvals = run('glab', ['api', `projects/:id/merge_requests/${mr.iid}/approvals`], { cwd });
+  const approvedBy = approvals.ok ? (JSON.parse(approvals.stdout).approved_by || []) : [];
+  const reviews = approvedBy.map((a) => ({ login: a.user?.username, state: 'APPROVED' }));
+  const disc = run('glab', ['api', `projects/:id/merge_requests/${mr.iid}/discussions`], { cwd });
+  let threads = [];
+  if (disc.ok) {
+    threads = (JSON.parse(disc.stdout) || [])
+      .filter((d) => d.notes?.some((nt) => nt.resolvable))
+      .map((d, i) => ({
+        id: d.id || `disc-${i}`,
+        resolved: !!d.notes.find((nt) => nt.resolvable)?.resolved,
+        login: d.notes[0]?.author?.username,
+        body: d.notes[0]?.body,
+      }));
+  }
+  return {
+    ok: true,
+    state: mr.state,
+    merged: mr.state === 'merged',
+    headOid: mr.diff_refs?.head_sha || mr.sha,
+    reviews,
+    threads,
+  };
+}
+
+// Injectable entry point. gate.mjs accepts a `reader` override; default dispatches to gh/glab.
+export function readPr(platform, n, opts = {}) {
+  if (!platformReady(platform)) return { ok: false, reason: `${cliFor(platform) || 'platform CLI'} not available` };
+  return platform === 'gitlab' ? readPrGitLab(n, opts) : readPrGitHub(n, opts);
+}
+
+// ---- create a PR/MR -----------------------------------------------------------------------------
+export function createPr(platform, { title, body, base, head, reviewers = [], labels = [], cwd } = {}) {
+  if (!platformReady(platform)) return { ok: false, reason: `${cliFor(platform) || 'platform CLI'} not available` };
+  if (platform === 'gitlab') {
+    const args = ['mr', 'create', '--title', title, '--description', body, '--target-branch', base, '--source-branch', head, '--yes'];
+    if (reviewers.length) args.push('--reviewer', reviewers.join(','));
+    if (labels.length) args.push('--label', labels.join(','));
+    const r = run('glab', args, { cwd });
+    return { ok: r.ok, url: r.stdout.split('\n').pop(), reason: r.stderr };
+  }
+  const args = ['pr', 'create', '--title', title, '--body', body, '--base', base, '--head', head];
+  if (reviewers.length) args.push('--reviewer', reviewers.join(','));
+  if (labels.length) args.push('--label', labels.join(','));
+  const r = run('gh', args, { cwd });
+  return { ok: r.ok, url: r.stdout.split('\n').pop(), reason: r.stderr };
+}

package/cli/reconcile.mjs

@@ -0,0 +1,83 @@
+// `sdlc check` (report) and `sdlc check --fix` (reconcile) — and `sdlc update`
+// as a thin alias (--scope=changed). Inspects actual project state against the
+// manifest: missing setup, drifted files, stale code-context.
+import path from 'node:path';
+import {
+  c, log, ok, info, warn, hand, fail, readJSON, writeJSON, exists,
+} from './lib.mjs';
+import { VERSION, PROJECT_FILES } from './manifest.mjs';
+import { moduleActions, repoActions, hubActions, authorsActions } from './plan.mjs';
+import { gitHead, packRepo } from './setup.mjs';
+
+const MARK = { missing: c.red('missing'), outdated: c.yellow('outdated'), stale: c.yellow('stale'), ok: c.green('ok') };
+
+export async function reconcile(root, { fix = false, scope = 'all', force = false } = {}) {
+  log(c.bold(`\nSDLC reconcile  ${c.dim('v' + VERSION)}`));
+  log(c.dim(`target: ${root}\n`));
+
+  // --- missing one-time setup (needs the interactive wizard) ---
+  const gaps = [];
+  if (!exists(path.join(root, PROJECT_FILES.version))) gaps.push('module not installed (.sdlc/cli-version.json absent)');
+  if (!exists(path.join(root, PROJECT_FILES.hubConfig))) gaps.push('hub not configured (.sdlc/hub.json absent)');
+  const registry = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
+  if (!exists(path.join(root, PROJECT_FILES.reposRegistry))) gaps.push('no repos registered (.sdlc/repos.json absent)');
+
+  // --- deterministic file actions (module + hub CI + author allowlists + every registered repo) ---
+  const actions = [...moduleActions(root), ...hubActions(root), ...authorsActions(root, registry.repos)];
+  for (const repo of registry.repos) actions.push(...repoActions(root, repo));
+
+  // --- stale code-context (HEAD moved since last pack) ---
+  const staleRepos = [];
+  for (const repo of registry.repos) {
+    const head = gitHead(path.resolve(root, repo.path));
+    if (head && repo.syncedHead && head !== repo.syncedHead) {
+      staleRepos.push(repo);
+      actions.push({ scope: repo.name, item: 'code-context', status: 'stale', apply: () => packRepo(root, repo) });
+    }
+  }
+
+  // --- report, grouped by scope ---
+  const byScope = new Map();
+  for (const a of actions) {
+    if (!byScope.has(a.scope)) byScope.set(a.scope, []);
+    byScope.get(a.scope).push(a);
+  }
+  const counts = { missing: 0, outdated: 0, stale: 0, ok: 0 };
+  for (const [scopeName, items] of byScope) {
+    const notOk = items.filter((i) => i.status !== 'ok');
+    items.forEach((i) => counts[i.status]++);
+    if (notOk.length === 0) { ok(`${scopeName} ${c.dim('— up to date')}`); continue; }
+    log(`  ${c.bold(scopeName)}`);
+    for (const i of notOk) log(`    ${MARK[i.status]}  ${i.item}`);
+  }
+  for (const g of gaps) warn(g);
+
+  const fixable = actions.filter((a) =>
+    a.status !== 'ok' && (scope === 'all' ? true : a.status !== 'missing'),
+  );
+  log('');
+  log(c.dim(`summary: ${counts.missing} missing, ${counts.outdated} outdated, ${counts.stale} stale, ${counts.ok} ok`));
+
+  if (!fix) {
+    if (fixable.length || gaps.length) hand('run `sdlc check --fix` to reconcile (or `sdlc setup` for missing one-time setup).');
+    return { counts, gaps, applied: 0 };
+  }
+
+  // --- apply ---
+  log('');
+  let applied = 0;
+  for (const a of fixable) {
+    a.apply();
+    applied++;
+    info(`${a.status} → fixed: ${a.scope}/${a.item}`);
+  }
+  if (force) {
+    for (const a of actions.filter((a) => a.status === 'ok')) a.apply();
+  }
+  // refresh the version stamp (preserve recorded ideTargets)
+  const rec = readJSON(path.join(root, PROJECT_FILES.version), {});
+  writeJSON(path.join(root, PROJECT_FILES.version), { ...rec, version: VERSION });
+  applied ? ok(`reconciled ${applied} item(s)`) : info('nothing to fix');
+  if (gaps.length) hand('one-time setup still missing — run `sdlc setup`.');
+  return { counts, gaps, applied };
+}

package/cli/repo.mjs

@@ -0,0 +1,61 @@
+// `sdlc 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. (`sdlc check --fix`
+// still refreshes too — it is also human-invoked.)
+import path from 'node:path';
+import { c, log, ok, info, warn, hand, fail, readJSON, writeJSON } from './lib.mjs';
+import { PROJECT_FILES } from './manifest.mjs';
+import { gitHead, packRepo } from './setup.mjs';
+
+function load(root) {
+  const regPath = path.join(root, PROJECT_FILES.reposRegistry);
+  return { regPath, registry: readJSON(regPath, { repos: [] }) };
+}
+
+// HEAD != syncedHead => stale (config.yaml code_context.staleness: head-sha).
+function staleness(root, repo) {
+  const head = gitHead(path.resolve(root, repo.path));
+  const stale = head && repo.syncedHead && head !== repo.syncedHead;
+  return { head, stale: !!stale, unknown: !head };
+}
+
+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 `sdlc setup`'); return { repos: 0 }; }
+
+  if (action === 'list') {
+    log(c.bold('\nconnected repos'));
+    let staleCount = 0;
+    for (const repo of registry.repos) {
+      const { stale, unknown } = staleness(root, repo);
+      if (unknown) { warn(`${repo.name} ${c.dim(`(${repo.path})`)} — HEAD unreadable`); continue; }
+      if (stale) { staleCount++; warn(`${repo.name} ${c.dim(`(${repo.path})`)} — ${c.yellow('stale')} (HEAD moved since last pack)`); }
+      else ok(`${repo.name} ${c.dim('— fresh')}`);
+    }
+    if (staleCount) hand(`refresh with \`sdlc repo refresh${registry.repos.length > 1 ? ' <name>' : ''}\` (or \`sdlc repo refresh\` for all)`);
+    return { repos: registry.repos.length, stale: staleCount };
+  }
+
+  if (action === 'refresh') {
+    const targets = name ? registry.repos.filter((r) => r.name === name) : registry.repos;
+    if (name && !targets.length) { fail(`unknown repo: ${name}`); process.exitCode = 1; return { refreshed: 0 }; }
+    let refreshed = 0;
+    for (const repo of targets) {
+      const { head, unknown } = staleness(root, repo);
+      if (unknown) { warn(`${repo.name}: HEAD unreadable — skipped`); continue; }
+      log(`  ${c.bold(repo.name)}`);
+      if (packRepo(root, repo)) {
+        repo.syncedHead = head;
+        if (today) repo.lastSyncedAt = today;   // always stamp when a date is supplied (the CLI passes today)
+        refreshed++;
+      }
+    }
+    writeJSON(regPath, registry);
+    refreshed ? ok(`refreshed ${refreshed} repo(s)`) : info('nothing refreshed');
+    hand('regenerate the code-map in Claude Code (sdlc-connect-repos) — the pack is cached, the map is the AI step');
+    return { refreshed };
+  }
+
+  fail(`unknown repo action: ${action} (list | refresh)`);
+  process.exitCode = 1;
+  return {};
+}