yadflow 1.0.1

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

@@ -0,0 +1,159 @@
+---
+name: sdlc-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".'
+---
+
+# SDLC — Connect Code Repos (make the brain code-aware)
+
+**Goal:** Give the front/"brain" phases (`sdlc-author-epic` → `-architecture` → `-ui` → `-stories`)
+full context about what **already exists** in the code, so the AI does not author a contract, UI, or
+stories that contradict or duplicate what is built. This skill **connects** code repos to the product
+hub and caches an AI-readable picture of each. It is the product → code half of the 2-way link (the
+code → product half is the existing `link.md` back-pointer each spec carries).
+
+This is **setup/maintenance**, not a gated front state — it never touches `.sdlc/state.json` or any
+epic's approvals. It only writes the project-wide registry and the per-repo context cache.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory (the **product hub**).
+- The **product repo is the front-phase toolchain hub** (`config.yaml` `code_context`): Repomix (and
+  Impeccable, later) are installed/run **here** and target the connected code repos **by path**. The
+  code repos themselves need no install for this. (The build-half CI gates are the exception — they
+  live inside each code repo; see `sdlc-checks`.)
+- **Repomix is a true CLI subprocess** (Phase 0 / RESEARCH-NOTES §3): `npx repomix@latest [flags]` —
+  NOT a slash-command. It secret-scans by default (Secretlint).
+- Registry: `{project-root}/.sdlc/repos.json` (project-wide, shared across all epics — NOT per-epic).
+- Per-repo cache: `{project-root}/.sdlc/code-context/<repo>/` holds `pack.md` + `code-map.md`.
+
+## Inputs
+
+- `action` — `connect` | `refresh` | `list` | `disconnect` | `detect-hub` | `roster` (default `connect`).
+- `repo` — the repo's short name (the key used in stories' `repos:` tag, e.g. `backend`).
+- `login`, `name`, `role` — for `roster` (set the hub's reviewer-roster mapping login → name → role).
+- `path` — local path to the code repo (relative to `{project-root}` or absolute). For local repos.
+- `git_url` — optional remote (SSH or HTTPS; GitHub or GitLab). Used when the repo is not yet on disk.
+- `domain_owner` — the engineer who owns this repo's domain (drives per-repo review routing later).
+
+## On Activation
+
+### Step 1 — Resolve the repo and its auth (GitHub + GitLab, local user)
+Determine where the code is:
+- If `path` is given and is a git repo (`.git` present) → use it in place.
+- Else if `git_url` is given → **clone it as the local user** into a working location
+  (`{code_repos_root}/<repo>/` by `config.yaml` `build.code_repos_root`, or a path the user names):
+  ```
+  git clone <git_url> <dest>
+  ```
+  Authentication is **the local user's own** — SSH keys or the git credential helper already on this
+  device. This works identically for **GitHub and GitLab** (and self-hosted instances); the skill
+  **stores no tokens**. If `gh`/`glab` are installed and authenticated they may be used, but plain
+  `git` over the user's credentials is the baseline. If the clone/fetch fails on auth, STOP and tell
+  the user to authenticate (`gh auth login` / `glab auth login` / add an SSH key) — never embed a token.
+- Detect the platform from the URL host: `github.com` → `github`, `gitlab.com`/self-hosted GitLab →
+  `gitlab`; record it as `platform`. A local-only repo with no remote records `platform: null`.
+
+### Step 2 — Pack the repo (Repomix, the full cached context layer)
+From the code repo, run (flags from `config.yaml` `code_context.pack_flags`):
+```
+npx repomix@latest --compress --include-logs --style markdown -o {project-root}/.sdlc/code-context/<repo>/pack.md
+```
+`--compress` (Tree-sitter structural compression) keeps it small and signal-dense; `--include-logs`
+adds recent git history; Secretlint secret-scans by default. **If a secret is reported, STOP and have
+it redacted before any AI reads the pack.** Pack the whole repo, or the source boundary from the
+project's constitution if one is defined. (If `npx repomix` is unavailable, degrade: hand-assemble the
+same context — the repo's source tree + recent git log — and record `source: repomix-unavailable`.)
+
+### Step 3 — Build the code-map (the lightweight index layer)
+Feed the pack to the AI with the **"describe what exists, do not invent"** instruction
+(`references/code-context.md`) and write `{project-root}/.sdlc/code-context/<repo>/code-map.md`: a small
+index of **stack/conventions, entry points, public endpoints/APIs, events, data models/entities, and
+module layout**. Mark anything unclear `<!-- unverified: ... -->`; never fill gaps with invented
+behaviour. This is the cheap artifact every front phase loads by default (the full pack is read only
+when a phase needs depth).
+
+### Step 4 — Record the repo in the registry
+Upsert the repo into `{project-root}/.sdlc/repos.json` (create the file if absent). Record the current
+HEAD sha as `syncedHead` (this drives staleness):
+```json
+{
+  "repos": [
+    {
+      "name": "<repo>",
+      "path": "<path rel. to project-root>",
+      "git_url": "<url or null>",
+      "platform": "github|gitlab|null",
+      "domain_owner": "<owner or null>",
+      "default_branch": "<branch>",
+      "connectedAt": "<YYYY-MM-DD>",
+      "lastSyncedAt": "<YYYY-MM-DD>",
+      "syncedHead": "<git HEAD sha at pack time>",
+      "contextPack": ".sdlc/code-context/<repo>/pack.md",
+      "codeMap": ".sdlc/code-context/<repo>/code-map.md",
+      "source": "repomix"
+    }
+  ]
+}
+```
+`connect` is **idempotent** — re-running it for an existing repo refreshes its entry in place. Adding a
+new repo later is the same `connect` action.
+
+### Step 5 — Report
+Report the connected repo, its `platform`, the pack + code-map paths, the secret-scan result, and that
+the front phases will now load this repo's code-map. Nothing auto-advances; this is setup.
+
+## Other actions
+
+- **`refresh`** — re-run Steps 2–4 for an already-connected repo (after its code moves). Updates
+  `syncedHead` + `lastSyncedAt`. Same machinery as `connect`.
+- **`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
+  itself untouched**.
+
+## Hub detection + reviewer roster (the front-half review bridge)
+
+The hub is itself a git repo on a platform. These actions record that so the front-half review/comment/
+approval cycle can run through a real PR/MR on the hub (`sdlc-review-gate` + `sdlc-hub-bridge`). They
+write only `{project-root}/.sdlc/hub.json` (`config.yaml` `hub.config`) — never an epic's state/approvals.
+
+- **`detect-hub`** — detect the hub's own platform and upsert `.sdlc/hub.json`. Run
+  `git remote get-url origin` **on the hub** and read the host with the SAME logic Step 1 uses for code
+  repos: `github.com` → `github`, GitLab host → `gitlab`, no remote → `platform: null`. Record
+  `git_url`, `default_branch`, `detectedAt`, and `bridge_enabled: true` (preserve an existing roster).
+  Auth is the local user's own `gh`/`glab`/git; **store no tokens**. Idempotent — safe to re-run.
+- **`roster`** — set one roster entry mapping a platform `login` → SDLC `name` + `role`
+  (`owner` | `reviewer`). Upsert by `login`. `domain-owner` is **not** set here — it is derived when a
+  roster `name` equals a repo's `domain_owner` in `repos.json` (see `references/hub-config.md`). An
+  unmapped login degrades to a plain `reviewer`, never auto-promoted to owner/domain-owner.
+
+If the hub has no remote (`platform: null`) or the bridge is disabled, the front-half gate runs
+file-only with no error — the bridge is purely additive.
+
+## Live on-demand (the third context layer)
+The cached pack + map are the default. When a front phase needs an **area** not in the map, it may
+re-run Repomix **live**, scoped to that area:
+```bash
+npx repomix@latest --compress --include "<area globs>" --style markdown -o -
+```
+Same CLI, invoked ad hoc — no registry write. A **stale repo** (HEAD ≠ `syncedHead`) is different: the
+phase **flags it and stops**, pointing the human at `sdlc repo refresh <repo>` (or `sdlc check --fix`) —
+it does not silently re-pack. Refreshing the cache is a human decision. Documented in
+`references/code-context.md`.
+
+## Hard rules
+
+- **Local-user auth only; store no tokens.** Clone/fetch as the user running the command; never embed
+  credentials in the registry. Works for GitHub and GitLab alike.
+- **Secret-scan before any AI sees the code.** Secretlint runs by default; a hit STOPS the pack.
+- **Describe what exists; never invent.** The code-map records built behaviour, not a design.
+- **Setup, not a gate.** Never touch `.sdlc/state.json`, approvals, or the contract lock from here.
+- **Idempotent + refreshable.** `connect`/`refresh` are safe to re-run; staleness is HEAD-sha based.
+
+## Reference
+- Registry schema + freshness rule: `references/repos-registry.md`.
+- Hub config + reviewer roster (the review bridge): `references/hub-config.md`.
+- Repomix command, secret-scan, degrade path, the code-map prompt, and live on-demand:
+  `references/code-context.md`.
+- The repomix discipline this reuses (one-feature-at-a-time variant): `../sdlc-backfill/references/backfill.md`.
+- Repos convention + per-repo review routing: `../sdlc-author-stories/references/story-schema.md`.

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

@@ -0,0 +1,92 @@
+# Code context — Repomix pack, the code-map prompt, and live on-demand
+
+How `sdlc-connect-repos` turns a connected code repo into an AI-readable picture the front/"brain"
+phases can read. Three layers, same Repomix machinery as `sdlc-backfill` (this is the repo-wide
+variant; backfill is the one-feature-at-a-time variant).
+
+## Layer 1 — the cached pack (full context)
+
+Run from the product hub, targeting the connected repo (flags from `config.yaml`
+`code_context.pack_flags`):
+
+```
+npx repomix@latest --compress --include-logs --style markdown \
+  -o {project-root}/.sdlc/code-context/<repo>/pack.md
+```
+
+- `--compress` — Tree-sitter structural compression (keeps the pack small and signal-dense).
+- `--include-logs` — recent git history (default 50; `--include-logs-count N` to change).
+- `--style markdown` — human/AI-readable; the default output is `repomix-output.xml`.
+- **Secretlint runs by default** — if a secret is reported, **STOP and redact** before any AI reads the
+  pack. Never let a secret reach the model or the cache.
+
+Pack the whole repo, or the source boundary defined in the project's constitution. If `npx repomix` is
+unavailable, degrade: hand-assemble the same context (the repo's source tree + recent git log) and
+record `source: repomix-unavailable` in the registry entry.
+
+## Layer 2 — the code-map (lightweight index, the default the brain reads)
+
+Feed the pack to the AI with the **"describe what exists, do not invent"** instruction (the same
+discipline as backfill) and write `{project-root}/.sdlc/code-context/<repo>/code-map.md`:
+
+> You are indexing an ALREADY-BUILT repo from its packed source + git history. Describe ONLY what the
+> code actually provides. Do NOT invent capabilities, do NOT propose changes, do NOT fill gaps with
+> assumptions. Where something is unclear from the code, mark it `<!-- unverified: ... -->` rather than
+> guessing. Produce a SHORT index a brain phase can scan, not a full spec.
+
+Index these sections (omit a section if the repo has none):
+
+```markdown
+---
+repo: <repo>
+artifact: code-map
+syncedHead: <sha>
+generated: <YYYY-MM-DD>
+source: repomix
+---
+
+## Stack & conventions
+<!-- language(s), framework(s), notable conventions a new feature must follow -->
+
+## Entry points
+<!-- how the app starts / is invoked; top-level modules -->
+
+## Public endpoints / APIs
+<!-- method + path (or RPC/handler) + one-line purpose — the surface a new contract must not collide with -->
+
+## Events
+<!-- event names + producer/consumer, if any -->
+
+## Data models / entities
+<!-- the entities + key fields already persisted -->
+
+## Module layout
+<!-- the main directories/modules and what each owns -->
+```
+
+The code-map is deliberately small so every front phase can load it cheaply. The full `pack.md` is read
+only when a phase needs depth (the architecture phase, primarily).
+
+## Layer 3 — live on-demand (a specific area, not a stale repo)
+
+When a front phase needs an area not captured in the code-map, it may re-pack that **slice** live,
+scoped to the area, without writing the cache:
+
+```bash
+npx repomix@latest --compress --include "<area globs>" --style markdown -o -
+```
+
+This is for a one-off look at a specific area. **Staleness is a human decision, not an automatic
+side-effect:** when a repo is stale (HEAD ≠ `syncedHead`), the phase **flags it and stops** —
+"`<repo>` is stale; run `sdlc 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
+`sdlc repo refresh` (or `sdlc check --fix`).
+
+## Why this stays DRY with backfill
+
+`sdlc-backfill` already documents the exact Repomix command, the Secretlint discipline, the
+`repomix: unavailable` degrade, and the "describe what exists, do not invent" prompt
+(`../sdlc-backfill/references/backfill.md`). This skill reuses all of it; the only differences are
+**scope** (repo-wide index vs one feature) and **output** (a lightweight code-map for the brain vs a
+human-approved feature spec). Backfill produces a *verified* spec that gates changes; connect produces a
+*context* artifact that informs design — they are complementary.

package/skills/sdlc-connect-repos/references/hub-config.md

@@ -0,0 +1,77 @@
+# Hub config — schema, detection, and the reviewer roster
+
+The hub config is the product hub's record of **its own** platform (so the front-half review/comment/
+approval cycle can run through a real PR/MR on the hub) and the **reviewer roster** that maps a platform
+login to an SDLC name + role. It is a single object for the hub itself — the sibling of the per-repo
+`repos.json` registry (see `repos-registry.md`), kept separate so it never pollutes that array.
+
+## Location
+
+`{project-root}/.sdlc/hub.json`
+
+(`config.yaml` `hub.config`.) Created/updated by `sdlc-connect-repos action: detect-hub`.
+
+## Schema
+
+```json
+{
+  "platform": "github",                                       // github | gitlab (from the hub's own remote host); null when local-only
+  "git_url": "https://github.com/abdelrahmannasr/sdlc-workflow.git",
+  "default_branch": "main",
+  "bridge_enabled": true,                                     // open review PRs/MRs on the hub for front-half reviews
+  "detectedAt": "2026-06-08",                                 // last detect-hub run (YYYY-MM-DD)
+  "roster": [
+    { "login": "abdelrahmannasr", "name": "alice", "role": "owner" },
+    { "login": "bob-gh",          "name": "bob",   "role": "reviewer" }
+  ]
+}
+```
+
+## The roster — login → name → role
+
+The roster is how a platform identity (a GitHub/GitLab **login**) becomes an SDLC **name + role** in the
+file ledger (`approvals.json` / `comments.json`). Roles are the same three the gate already uses:
+`owner | reviewer | domain-owner`.
+
+- **`login`** — the platform username whose PR review / approval is being mapped.
+- **`name`** — the SDLC name written into the ledger (the same names used across `approvals.json`,
+  `comments.json`, and `epic.md` `owner`). Keep it stable.
+- **`role`** — the person's default role: `owner` or `reviewer`.
+
+**`domain-owner` is DERIVED, never duplicated here.** A roster entry whose `name` equals a repo's
+`domain_owner` in `repos.json` is treated as that repo's domain-owner **when that repo is a touched
+domain for the step under review**. `repos.json` stays the single source of domain ownership; the roster
+only resolves the login → name link so the derivation can run.
+
+- **Unmapped login fallback.** A login absent from the roster maps to `name: <login>`, `role: reviewer`,
+  and is flagged `<!-- unverified login: <login> -->` in the review record (mirrors the code-map
+  `unverified` convention). An unmapped login is **never** auto-promoted to `owner` or `domain-owner` —
+  it stays a plain reviewer until a human adds it to the roster, so a stranger cannot satisfy the
+  owner/domain-owner requirement.
+
+## Detection
+
+`detect-hub` reuses the same host-detection logic this skill already applies to code repos:
+run `git remote get-url origin` **on the hub itself** and read the host —
+`github.com` → `github`, `gitlab.com`/self-hosted GitLab → `gitlab`, no remote → `platform: null`.
+Auth is the **local user's own** `gh`/`glab`/git credentials; **no tokens are ever stored** (same rule
+as the registry). `detect-hub` upserts `hub.json` in place — it is idempotent and safe to re-run.
+
+## Bridge enable / degradation
+
+- `bridge_enabled: true` **and** a non-null `platform` **and** `gh`/`glab` authenticated → the front-half
+  review opens a PR/MR on the hub and `sdlc-review-gate action: sync` pulls platform state into the ledger.
+- `bridge_enabled: false`, `platform: null`, or no/unauthenticated CLI → the gate falls back to the
+  existing **file-only** flow with no error. The file ledger is the source of truth in both modes.
+- The master switch `config.yaml` `hub.bridge: false` disables the bridge globally regardless of `hub.json`.
+
+## Git tracking
+
+Commit `hub.json` — it is small, reviewable, and carries no secrets (logins and names only, never tokens).
+This mirrors how `repos.json` and the per-epic `.sdlc/` state are committed.
+
+## Greenfield
+
+A brand-new hub has no `hub.json`. That is valid — the front-half gate runs file-only until `detect-hub`
+records a platform. The bridge is purely additive; nothing about authoring or the gate predicate changes.
+```

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

@@ -0,0 +1,62 @@
+# Repos registry — schema + freshness rule
+
+The registry is the product hub's record of which code repos are connected and where their cached
+code-context lives. It is **project-wide** (shared across every epic), so it lives at the product root,
+not under any `epics/EP-<slug>/.sdlc/`.
+
+## Location
+
+`{project-root}/.sdlc/repos.json`
+
+(`config.yaml` `code_context.registry`.) Create the file and its parent `.sdlc/` on the first
+`connect`.
+
+## Schema
+
+```json
+{
+  "repos": [
+    {
+      "name": "backend",                         // short name = the key used in stories' `repos:` tag
+      "path": "demo-repos/backend",              // path to the code repo, rel. to {project-root} (or absolute)
+      "git_url": "git@github.com:org/backend.git", // optional remote; SSH or HTTPS; GitHub or GitLab; null if local-only
+      "platform": "github",                       // github | gitlab (from the URL host); null when local-only
+      "domain_owner": "carol",                    // engineer who owns this repo's domain (review routing)
+      "default_branch": "main",
+      "connectedAt": "2026-06-08",                // first connect (YYYY-MM-DD)
+      "lastSyncedAt": "2026-06-08",               // last connect/refresh
+      "syncedHead": "5bd7e8d…",                   // code repo HEAD sha at last pack — drives staleness
+      "contextPack": ".sdlc/code-context/backend/pack.md",
+      "codeMap": ".sdlc/code-context/backend/code-map.md",
+      "source": "repomix"                         // repomix | repomix-unavailable (degraded pack)
+    }
+  ]
+}
+```
+
+## Rules
+
+- **`name`** is the join key. It MUST match the names used in epic/story `repos:` tags so the front
+  phases can map `epic.repos` → registry entries → code-maps. Keep it stable.
+- **Auth is never stored.** No tokens, passwords, or PATs in the registry. `git_url` is a plain remote;
+  `connect` clones/fetches as the local user (SSH key or git credential helper).
+- **`connect` upserts by `name`** — re-connecting an existing repo refreshes its entry in place; it
+  never creates a duplicate.
+- **`syncedHead`** is the authority for freshness. A repo is **stale** when
+  `git -C <path> rev-parse HEAD` ≠ `syncedHead`. `list` flags it; `refresh` clears it.
+- **`disconnect`** removes the entry and deletes `{project-root}/.sdlc/code-context/<name>/`. The code
+  repo on disk is never touched.
+
+## Git tracking
+
+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).
+**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.
+
+## Greenfield
+
+A brand-new product hub has no `repos.json` (or an empty `{ "repos": [] }`). That is valid — the front
+phases treat "no repos connected" as "nothing to consider yet" and proceed unchanged. The registry
+appears the first time `connect` runs.

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

@@ -0,0 +1,119 @@
+---
+name: sdlc-hub-bridge
+description: 'The templated PR/MR bridge for the front-half review gate. When the product hub has a platform (.sdlc/hub.json), it opens a review PR/MR on the hub for an authored artifact (the optional analysis / epic / architecture+contract / ui-design / stories), sets the required reviewers/labels from the routing rule, and provides the read-only gh/glab recipes that sdlc-review-gate uses to pull platform comments + approvals back into the file ledger. Can also wire event-driven sync on the hub: a CI workflow that runs `sdlc gate ci` whenever a reviewer approves / requests changes / a human merges, committing the ledger to the default branch. Local-user auth only — no stored tokens. The file ledger stays the source of truth; degrades to the file-only gate when there is no platform / no CLI. Use when the user says "open the review PR", "route the review", "wire the gate sync", or it is invoked by sdlc-review-gate open/sync.'
+---
+
+# SDLC — Hub Review Bridge (the templated PR/MR bridge)
+
+**Goal:** Run the front-half review/comment/approval cycle through a **real PR/MR on the product hub**,
+without changing the gate's predicate or making the file ledger optional. The bridge is an **alternate
+input path** into `sdlc-review-gate`: it opens a review PR for an artifact, reviewers approve/comment on
+the platform with **their own** `gh`/`glab` auth, and the gate's `sync` action (which calls this skill's
+read recipes) maps that platform state into `approvals.json` / `comments.json` / `reviews/*.md`, then
+runs the **unchanged** predicate. The file ledger remains the source of truth.
+
+This skill owns the **branch/PR mechanics + the gh/glab recipes** (mirroring how `sdlc-pr-template`
+keeps platform mechanics out of the gate). `sdlc-review-gate` *calls* it; it never advances a step.
+
+## Conventions
+
+- `{project-root}` is the **product hub**. Hub platform + reviewer roster live in `.sdlc/hub.json`
+  (`config.yaml` `hub.config`; schema in `../sdlc-connect-repos/references/hub-config.md`).
+- Per-step review-PR record: `epics/EP-<slug>/.sdlc/hub-prs.json` (`config.yaml` `hub.pr_ledger`) — a
+  sibling ledger to `approvals.json`, so `state.json`'s locked step shape is untouched.
+- The review-PR body is the hub template from `sdlc-pr-template` (`templates/hub/<platform>/…`).
+- Branch per artifact: `review/EP-<slug>/<artifact-base>` (`config.yaml` `hub.artifact_branch`).
+- **Local-user auth only; store no tokens.** Use the user's own `gh`/`glab`. If neither is installed/
+  authenticated, STOP this path and tell the gate to fall back to file-only — never embed a credential.
+
+## Inputs
+
+- `epic`     — the `EP-<slug>` under review.
+- `artifact` — the artifact file (`analysis.md` | `epic.md` | `architecture.md` | `ui-design.md` | `stories/`).
+- `action`   — `open` | `route` | `wire` (default `route`). (`sync`'s ledger writes live in
+  `sdlc-review-gate`; this skill provides the read recipes `sync` calls — see `references/bridge.md`.)
+
+## Preconditions (the bridge runs only when all hold)
+
+`.sdlc/hub.json` exists with a non-null `platform`, `bridge_enabled: true`, `config.yaml` `hub.bridge:
+true`, and `gh` (GitHub) / `glab` (GitLab) installed **and authenticated**. If any fails, report that the
+gate proceeds **file-only** (no error) and stop.
+
+## On Activation
+
+### Step 1 — Resolve platform + routing
+Read `.sdlc/hub.json` for the platform and roster, `epics/<epic>/epic.md` for `repos` + `owner`, and the
+matching `review+approve` step's `risk_tags` from `.sdlc/state.json`. Compute the **required reviewers**
+with `route` (below) — the same rule `sdlc-review-gate` enforces: base (owner + 1 reviewer); escalated
+(`risk_tags` ∩ {contract,auth,payments}, or the stories step) adds a domain-owner per touched repo. Map
+each required domain-owner to a platform `login` via the roster (a roster `name` equal to a repo's
+`domain_owner` in `repos.json` is that repo's domain-owner).
+
+### Step 2 — `open` (create the review PR/MR)
+1. From the hub default branch, create `review/EP-<slug>/<artifact-base>` and ensure the artifact file
+   (and, for architecture, `contract.md` + `.sdlc/contract-lock.json`) is committed on it. Push as the
+   local user.
+2. Open the PR/MR with `gh`/`glab` using the hub body template (`sdlc-pr-template` `templates/hub/…`),
+   filled with the epic, artifact, gate step, owner, `epic.repos`, and the step's risk tags.
+3. **Request the required reviewers** (their logins) and add a `domain:<repo>` label per touched repo so
+   per-repo routing is legible on the PR.
+4. Upsert a record into `epics/<epic>/.sdlc/hub-prs.json`:
+   ```json
+   { "step": "<review step id>", "artifact": "<artifact>", "platform": "github|gitlab",
+     "number": <n>, "url": "<pr/mr url>", "branch": "review/EP-<slug>/<artifact-base>", "lastSyncedAt": null }
+   ```
+5. Report the PR/MR URL and the required reviewers. **Do not** record approvals or advance — reviewers
+   act on the platform; `sdlc-review-gate action: sync` pulls it back.
+
+### Step 3 — `route` (print required reviewers)
+Compute and print the required reviewers as above. Use `templates/checks/hub-route.sh <body>` to parse a
+PR/MR body's Impact & Risk block when given one; otherwise derive from `epic.repos` + the step's
+`risk_tags`. Advisory only — it routes the human review, it does not approve.
+
+### Step 4 — `wire` (event-driven sync on the hub)
+Install the hub CI that turns platform actions — a review **approval**, a **change request**, a review
+dismissal, or the human **merge** — into an automatic `sdlc gate ci` run that syncs the ledger and
+commits it to the hub's default branch. No more waiting on a manual `sdlc gate sync`; the manual command
+remains valid and is the fallback whenever CI cannot push.
+
+1. Run `sdlc check --fix` (the wiring is manifest-driven, like `sdlc-checks`): with a platform +
+   enabled bridge in `.sdlc/hub.json` it installs
+   - GitHub → `.github/workflows/sdlc-gate-sync.yml` (from `templates/github/sdlc-gate-sync.yml`)
+   - GitLab → `.gitlab/ci/sdlc-gate-sync.yml` (from `templates/gitlab/sdlc-gate-sync.gitlab-ci.yml`)
+   - plus the hub-side **verified-commits** gate (`checks/verified-commits.sh` + its workflow/fragment,
+     owned by `sdlc-checks`) so review PRs accept only signed commits from roster-known authors
+2. **GitLab only — two one-time steps** (see the fragment's header for the exact recipes):
+   - add `include: - local: '.gitlab/ci/sdlc-gate-sync.yml'` to the root `.gitlab-ci.yml`, or write
+     `templates/gitlab/gitlab-ci.include-root.yml` as the root when none exists;
+   - create the 15-minute pipeline **schedule** (variable `SDLC_GATE_SYNC=true`) and the masked
+     `SDLC_GATE_TOKEN` project-access-token variable (`read_api` + `write_repository`). GitLab fires no
+     pipeline on an approval alone, so the schedule is the path that picks approvals up (≤ ~15 min
+     latency); MR events and the merge are near-immediate.
+3. Commit the workflow to the hub. GitHub needs nothing else — the ephemeral `github.token` reads the
+   PR and pushes the ledger. If the default branch is protected, see the workflow header for the
+   bypass / PAT options; until then the run fails visibly and manual `sdlc gate sync` still works.
+
+## Hard rules
+
+- **Local-user auth only; store no tokens.** Reviewers use their own `gh`/`glab`.
+- **The bridge is an input path, never the authority.** It opens PRs and reads state; the **file ledger
+  is the source of truth** and the gate predicate (in `sdlc-review-gate`) is unchanged.
+- **The bridge never approves on a reviewer's behalf.** Reviewers approve/merge with their own auth. The
+  step advances when a human **merges** the approved, fully-resolved review PR (the merge is that human
+  act) — `sdlc gate sync` records the approvals + resolution + merged state and advances; unresolved
+  comments or a changed artifact hold it `in_review`. The mechanical sync is the `sdlc gate` CLI.
+- **CI never approves and never merges.** The wired workflow only runs `gate ci` — the same sync +
+  unchanged predicate — and commits the **ledger files only** to the default branch; the artifact lands
+  on the default branch exclusively via the human merge. Front gates stay permanently human.
+- **The CI tokens are the one documented bend of "no stored tokens".** GitHub uses the platform's own
+  ephemeral `github.token` (nothing stored). GitLab requires a stored masked `SDLC_GATE_TOKEN`
+  project access token because `CI_JOB_TOKEN` can neither read the approvals API nor push — say so
+  when wiring, and scope it to `read_api` + `write_repository` only.
+- **Degrade gracefully.** No platform / disabled bridge / no CLI → the gate runs file-only with no error.
+
+## Reference
+- PR-body→ledger mapping, the read-only gh/glab recipes, idempotent re-sync, contract re-lock handling:
+  `references/bridge.md`.
+- Roster schema, login→role resolution, unverified-login fallback, per-repo routing: `references/login-roster.md`.
+- The gate this feeds (open hook + sync action + unchanged predicate): `../sdlc-review-gate/SKILL.md`, `../sdlc-review-gate/references/gating.md`.
+- The hub PR/MR body template + the code-repo routing analogue: `../sdlc-pr-template/`.

package/skills/sdlc-hub-bridge/references/bridge.md

@@ -0,0 +1,136 @@
+# The bridge — PR/MR ↔ ledger mapping, read recipes, idempotency
+
+The bridge maps platform review state onto the **same file records** the manual gate writes, so the gate
+predicate (`../sdlc-review-gate/references/gating.md`) runs unchanged. The bridge only changes the
+*input path*; it never changes what passing the gate means.
+
+## State mapping (platform → ledger)
+
+| Platform review state | Ledger effect |
+|---|---|
+| GitHub review `APPROVED` / GitLab MR approval (`approved_by`) | an `approved` record in `approvals.json`, role resolved from the roster (owner/reviewer) or derived domain-owner, tagged `"source": "bridge"` |
+| GitHub `COMMENTED` / `CHANGES_REQUESTED`; GitLab discussions/notes | a line under `## <name> (<role>)` in `reviews/<artifact>--<date>--comments.md` + a `comments.json` record; **never** an approval. `CHANGES_REQUESTED` is also flagged as blocking in the comments file |
+| GitHub review dismissed / GitLab approval revoked | the prior bridge `approved` record for that approver is removed on re-sync (see idempotency) |
+
+`approvals.json` records from the bridge carry `"source": "bridge"`; **manual** approvals have no such
+tag and are **never** touched by `sync` — the two coexist.
+
+## Read recipes (read-only, local-user auth — no tokens)
+
+**GitHub** (`gh`, the reviewer/runner's own auth):
+```
+gh pr view <n> --json reviews,comments,reviewDecision,latestReviews
+gh api repos/{owner}/{repo}/pulls/{n}/comments        # inline review comments
+```
+- `reviews[].state` ∈ {APPROVED, CHANGES_REQUESTED, COMMENTED, DISMISSED}; `reviews[].author.login` is
+  the login to resolve. Use `latestReviews` so a superseded earlier review doesn't double-count.
+
+**GitLab** (`glab` / `glab api`):
+```
+glab mr view <n>
+glab api projects/:id/merge_requests/:iid/approvals     # approved_by[].user.username
+glab api projects/:id/merge_requests/:iid/notes          # discussion notes (comments)
+```
+
+All commands run as the **local user**; the bridge stores no tokens. If the CLI is missing/unauthenticated
+or the remote is unreachable, the bridge stops and the gate falls back to file-only (no error).
+
+## Login → role resolution (order)
+
+1. Roster (`.sdlc/hub.json`) maps `login` → `name` + base `role` (owner/reviewer).
+2. If that `name` equals a repo's `domain_owner` in `repos.json` **and** that repo is a touched domain
+   for this step → also emit a `domain-owner` record with `domain: <repo>`.
+3. Login not in the roster → `name: <login>`, `role: reviewer`, flagged
+   `<!-- unverified login: <login> -->`. **Never** auto-promoted to owner/domain-owner.
+
+(Full detail + per-repo routing: `login-roster.md`.)
+
+## Idempotent re-sync
+
+- Key bridge approvals on `(step, approver, role, domain)`. On re-sync, **upsert** — do not append a
+  duplicate. Remove any bridge approval whose platform review was dismissed/revoked.
+- Key synced comments on the platform comment id so the same comment is not appended twice.
+- Update the step's `hub-prs.json` `lastSyncedAt` after a successful sync.
+- Running `sync` twice with no platform change is a no-op on the ledger.
+
+## Contract re-lock invalidates prior platform approvals too
+
+For the **architecture+contract** review, the gate already drops approvals when the contract-surface hash
+no longer matches `.sdlc/contract-lock.json`. The bridge extends this to platform-sourced approvals:
+`sync` discards bridge `approved` records for the architecture step dated **before** the new lock, and
+posts a comment on the review PR noting "contract re-locked — re-approval required". The escalation
+(`risk_tags: ["contract"]` → a domain-owner per repo) is unchanged.
+
+## CHANGES_REQUESTED & unresolved threads hold the gate
+
+`CHANGES_REQUESTED` and any **unresolved review thread** are recorded as comments and surfaced as
+**blocking**. Under the PR-driven gate they actively hold the step `in_review`: the predicate does not
+pass while any thread is unresolved, even if the approval counts are met. The owner addresses the
+comments, replies, the reviewer **resolves** their thread, then `sync` runs again.
+
+## Merge advances; an artifact change revokes approvals
+
+- **Merge → advance.** When the reviewer rule is satisfied, every thread is resolved, **and the review
+  PR/MR is merged**, `sync` marks the step `done` and unblocks the next step. The merge is the human
+  approval act — there is no separate machine advance. (`sdlc gate sync` performs this deterministically.)
+- **Revoke on artifact change.** Each bridge approval is stamped with the content hash it was given
+  against (the file bytes; the locked contract surface for architecture). On re-sync, an approval whose
+  stamped hash ≠ the current hash is **dropped** — the reviewer must re-approve the changed artifact. A
+  genuinely newer review (later `submittedAt`) re-stamps against the new hash. This is "revoke only when
+  the artifact changed", not "revoke on any PR commit".
+
+## Event-driven sync (hub CI)
+
+The `wire` action (SKILL.md Step 4) installs a CI workflow on the hub so the platform events drive
+`sdlc gate ci` instead of waiting on a manual `sdlc gate sync`. The CLI entry is self-sufficient: it
+derives the epic + artifact from the `review/EP-<slug>/<artifact-base>` head branch and takes the PR/MR
+number from the event payload — it even upserts the `hub-prs.json` entry when the author never committed
+it, so the first CI commit converges the views. `sdlc gate ci` with no `--branch` sweeps every open
+review PR (the scheduled path).
+
+| Platform event | CI action |
+|---|---|
+| review submitted (approve / changes requested) or dismissed | `gate ci --branch <head> --pr <n>` → sync the ledger; the predicate may hold or pass |
+| PR/MR `synchronize` (new commits on the review branch) | same — promptly re-stamps/revokes approvals on artifact change |
+| PR/MR closed **and merged** (the human act) | same — predicate sees `merged: true` and advances the step |
+| GitLab schedule (`*/15 * * * *`, `SDLC_GATE_SYNC=true`) | `gate ci` sweep — the **only** GitLab path that sees a bare approval (≤ ~15 min latency) |
+
+**The overlay.** Pre-merge, the artifact under review exists only on the review branch, while the
+ledger lives on the default branch. `gate ci` checks out the default branch, fetches the head ref and
+overlays just the artifact paths (for architecture: `architecture.md` + `contract.md` +
+`.sdlc/contract-lock.json`; for stories: `stories/`) so `artifactHash` binds each approval to **what the
+reviewers actually approved** — then drops the overlay before committing. Only
+`epics/<epic>/.sdlc/*.json` + `reviews/*.md` are committed (message `chore(gate): … [skip ci]`); the
+artifact reaches the default branch exclusively via the human merge.
+
+**Loop prevention & races.** The GitHub triggers (`pull_request_review`, `pull_request`) cannot fire on
+a push to the default branch, `[skip ci]` guards every other workflow on both platforms, and a
+repo-wide concurrency group serializes runs; the ledger push retries with a rebase (ledger-only commits
+across epics touch disjoint files).
+
+**Tokens.**
+- GitHub: the ephemeral `github.token` with `contents: write` + `pull-requests: read` — nothing stored.
+- GitLab: a masked `SDLC_GATE_TOKEN` project access token (`read_api` + `write_repository`) — the one
+  documented bend of the no-stored-tokens rule; `CI_JOB_TOKEN` can neither read the approvals API nor
+  push.
+- Protected default branch (GitHub): prefer a ruleset bypass for Actions; else a fine-grained PAT as
+  `SDLC_GATE_TOKEN` passed to `actions/checkout`; else leave it — the run fails **visibly** and manual
+  `sdlc gate sync` remains the fallback. Never wire branch protection that couples the merge itself to
+  the gate.
+
+**Manual sync stays first-class.** `sdlc gate sync <epic> [artifact]` is unchanged and always valid —
+the CI is the same sync on a trigger, and the file ledger is still the source of truth.
+
+### Manual end-to-end verification (GitHub)
+
+1. On a scratch hub: `sdlc setup` (platform github, roster with a second account) → `sdlc check --fix`
+   installs `.github/workflows/sdlc-gate-sync.yml`; commit + push it.
+2. Author an epic → `sdlc gate open EP-x epic.md` → the review PR opens.
+3. Second account **approves** → the Actions run commits `approvals.json` to the default branch.
+4. Second account **requests changes** → the run records the blocking comment; `sdlc gate status EP-x`
+   (after `git pull`) shows the gate held.
+5. Resolve the thread, approve again, a human **merges** → the closed-event run advances `state.json`
+   (`epic-review: done`, `currentStep: architecture`).
+6. `git pull` locally — `sdlc gate status EP-x` matches the platform history.
+
+GitLab variant: same flow on an MR; a bare approval appears after the next schedule tick.