yadflow 4.5.0 → 4.5.1

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## [4.5.1](https://github.com/abdelrahmannasr/yadflow/compare/v4.5.0...v4.5.1) (2026-10-06)
+
+
+### Bug Fixes
+
+* **docs:** a failed site build fails the Pages deploy ([32dd88f](https://github.com/abdelrahmannasr/yadflow/commit/32dd88f69dc1140977e1a2c126f94078aaa5f2ea))
+* **docs:** doctor judges only the failure handling, on the wired platform (review 2) ([987a753](https://github.com/abdelrahmannasr/yadflow/commit/987a7532951f61aec530550e2a9cab9aa4e0795f))
+* **docs:** escape the apostrophe that broke the overview site build ([fe7dcc8](https://github.com/abdelrahmannasr/yadflow/commit/fe7dcc81b2772dc577659e4afd2b85bec2bff81a))
+* **docs:** name every failed site, quote GitLab lines as YAML, doctor warns on an old wired workflow (review 1) ([d525e87](https://github.com/abdelrahmannasr/yadflow/commit/d525e87961413a10ba16122dfc3811ac3d5361a7))
+* **gitlab:** check the git-lfs download against its SHA-256 ([#327](https://github.com/abdelrahmannasr/yadflow/issues/327) review 1) ([01763a2](https://github.com/abdelrahmannasr/yadflow/commit/01763a25fdc47eea298592f3ab453341c2c14196))
+* **gitlab:** install git-lfs in yad-gate-sync when the Product uses LFS ([#327](https://github.com/abdelrahmannasr/yadflow/issues/327)) ([fcb55fb](https://github.com/abdelrahmannasr/yadflow/commit/fcb55fb6a3c2d96be067cb7c027644424784181d))
+* **windows:** leave the npm launcher name unquoted so npx finds itself ([#326](https://github.com/abdelrahmannasr/yadflow/issues/326)) ([b042848](https://github.com/abdelrahmannasr/yadflow/commit/b0428484f371a03cc5e722158481faf51004b519))
+
 # [4.5.0](https://github.com/abdelrahmannasr/yadflow/compare/v4.4.0...v4.5.0) (2026-10-06)
 
 

package/cli/docs.mjs

@@ -144,12 +144,28 @@ export function docsStale(manifest, { artifactHash, repoHeads = {}, shellVersion
 // mounts under `app/`, and every per-epic site nests under `epics/<id>/` — matching siteBasePath
 // (overview at `<base>/app/`, epics at `<base>/epics/EP-<slug>/`). A concurrency group prevents the
 // deploy from retriggering. The shared shell script keeps the two platforms byte-for-byte aligned.
+// A site that fails to build fails the run: CI runs the script under `set -e`, which does not stop on a
+// failure inside an `&&` chain, so a failed site used to be silently left out while the deploy still went
+// green — yadflow's own site lost its root page that way for days. Each chain ends in `|| failed=…`, so
+// every site is still tried (as `yad docs build` does) and the last line fails the run, naming them all.
+// A red run uploads nothing, so the last good deployment stays live.
+// A YAML single-quoted scalar: a quote inside is written twice, and nothing else is escaped (a backslash
+// is literal). The shell's '\'' is not YAML — it would make GitLab reject the whole pipeline.
+export const yamlQuoted = (s) => `'${String(s).replace(/'/g, "''")}'`;
+const PAGES_FAIL_LINE = 'yad-docs: these sites did not build, so nothing is deployed:';
 const BUILD_PUBLIC = [
   'mkdir -p public',
-  'if [ -d docs/sdlc-site ]; then (cd docs/sdlc-site && npm ci && npm run build) && mkdir -p public/app && cp -r docs/sdlc-site/dist/. public/app/ && cp docs/sdlc-site/public/report.html public/index.html && cp docs/sdlc-site/public/report.html public/report.html; fi',
-  'if [ -d docs/tutorial-site ]; then (cd docs/tutorial-site && npm ci && npm run build) && mkdir -p public/tutorial && cp -r docs/tutorial-site/dist/. public/tutorial/; fi',
-  'for d in epics/*/docs-site; do [ -d "$d" ] || continue; id=$(basename "$(dirname "$d")"); (cd "$d" && npm ci && npm run build) && mkdir -p "public/epics/$id" && cp -r "$d/dist/." "public/epics/$id/"; done',
+  'failed=',
+  'if [ -d docs/sdlc-site ]; then (cd docs/sdlc-site && npm ci && npm run build) && mkdir -p public/app && cp -r docs/sdlc-site/dist/. public/app/ && cp docs/sdlc-site/public/report.html public/index.html && cp docs/sdlc-site/public/report.html public/report.html || failed="$failed docs/sdlc-site"; fi',
+  'if [ -d docs/tutorial-site ]; then (cd docs/tutorial-site && npm ci && npm run build) && mkdir -p public/tutorial && cp -r docs/tutorial-site/dist/. public/tutorial/ || failed="$failed docs/tutorial-site"; fi',
+  'for d in epics/*/docs-site; do [ -d "$d" ] || continue; id=$(basename "$(dirname "$d")"); (cd "$d" && npm ci && npm run build) && mkdir -p "public/epics/$id" && cp -r "$d/dist/." "public/epics/$id/" || failed="$failed $d"; done',
+  `if [ -n "$failed" ]; then echo "${PAGES_FAIL_LINE}$failed" >&2; exit 1; fi`,
 ];
+// The platform `--wire` writes for: the Product's docs target, GitHub unless it says GitLab.
+export const wiredPagesPlatform = (docs) => (docs?.target === 'gitlab-pages' ? 'gitlab' : 'github');
+// Does a wired Pages workflow fail its deploy when a site fails to build? Read by `yad doctor`. Only this
+// line is looked for — not the whole file — so a Dependabot pin bump or an edit elsewhere is not news.
+export const pagesWorkflowFailsOnBuild = (text) => text.includes(PAGES_FAIL_LINE);
 export function pagesWorkflow(platform) {
   if (platform === 'gitlab') {
     return `# yad-managed — built by \`yad docs sync --wire\`. include it from .gitlab-ci.yml:
@@ -161,7 +177,7 @@ pages:
   rules:
     - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
   script:
-${BUILD_PUBLIC.map((l) => `    - '${l.replace(/'/g, "'\\''")}'`).join('\n')}
+${BUILD_PUBLIC.map((l) => `    - ${yamlQuoted(l)}`).join('\n')}
   artifacts:
     paths: [public]
   resource_group: pages
@@ -347,7 +363,7 @@ function reportFreshness(root, t) {
 }
 
 function wirePages(root, docs) {
-  const platform = docs?.target === 'gitlab-pages' ? 'gitlab' : 'github';
+  const platform = wiredPagesPlatform(docs);
   const rel = pagesWorkflowPath(platform);
   const dest = path.join(root, rel);
   fs.mkdirSync(path.dirname(dest), { recursive: true });

package/cli/doctor.mjs

@@ -22,6 +22,7 @@ import { checkCodeowners, codeownersFindings } from './codeowners-command.mjs';
 import { RISK_MAP_FILE } from './riskmap.mjs';
 import { readProtection, protectionLine, protectionJSON, hideAddresses } from './protection.mjs';
 import { soloTeamHint, TEAM_CMD } from './people.mjs';
+import { pagesWorkflowPath, pagesWorkflowFailsOnBuild, wiredPagesPlatform } from './docs.mjs';
 import { indexFreshness, INDEX_FILE } from './product-index.mjs';
 import { productGit, resolveDefaultBranch } from './productcommit.mjs';
 import { readOwners } from './owners.mjs';
@@ -379,6 +380,7 @@ export function projectChecks(checks, root, { headCount = null } = {}) {
   // Background capture (E43), on any Product in either ledger mode: is the post-edit hook wired, and will
   // a push to the `yad/wip/*` branches start the team's own CI?
   if (exists(productPath)) captureChecks(root, checks, readJSON(productPath, null));
+  docsWorkflowChecks(root, checks);
   if (exists(productPath)) lineEndingChecks(root, checks);
 
   // design.json: parse + shape + tool + MCP confirmation (absent is the normal markdown-only default —
@@ -2697,6 +2699,21 @@ export function captureChecks(root, checks, cfg) {
   }
 }
 
+// The Pages workflow `yad docs sync --wire` wrote. Nothing else rewrites it, so a Product wired by yadflow
+// 4.5.0 or older keeps a script that deploys a site with a page missing when a site fails to build. Only
+// that one behaviour is judged — not the whole file, which Dependabot bumps and a team may edit — and only
+// in the file `--wire` writes for this Product's platform (it never touches the other one). A file
+// without our header is the team's own.
+export function docsWorkflowChecks(root, checks) {
+  const rel = pagesWorkflowPath(wiredPagesPlatform(readJSON(path.join(root, PROJECT_FILES.docsConfig), null)));
+  let text;
+  try { text = fs.readFileSync(path.join(root, rel), 'utf8'); } catch { return; }
+  if (!text.startsWith('# yad-managed — built by `yad docs sync --wire`')) return;
+  if (pagesWorkflowFailsOnBuild(text)) check(checks, 'docs-workflow', 'project', 'ok', `${rel} fails the deploy when a site fails to build`);
+  else check(checks, 'docs-workflow', 'project', 'warn', `${rel} still deploys when a site fails to build — the site then goes out with a page missing`,
+    'run `yad docs sync --wire` and commit the file; it rewrites the whole file, so re-apply any change your team made to it');
+}
+
 // The team's own GitHub workflow files that a push to a `yad/wip/*` branch would start. A line reader, not
 // a YAML parser, confined to the TOP-LEVEL `on:` block (a job named `push` is not a trigger). It reads the
 // usual spellings — `on: push`, `on: [push, …]`, and a `push:` key under `on:` — and decides the way

package/cli/lib.mjs

@@ -357,11 +357,14 @@ export function run(cmd, args = [], opts = {}) {
 export const has = (cmd) => run(process.platform === 'win32' ? 'where' : 'which', [cmd]).ok;
 
 // An npm launcher (`npm`, `npx`) is a `.cmd` file on Windows, which Node will not start without a shell
-// (since 18.20.2) — a plain spawn fails with EINVAL there. So on Windows it runs through one, each word in
+// (since 18.20.2) — a plain spawn fails with EINVAL there. So on Windows it runs through one, each argument in
 // double quotes (a Windows path cannot hold a `"`); everywhere else it is spawned directly (E113).
+// The launcher name itself stays bare: a `.cmd` found on PATH through a QUOTED name reads `%~dp0` as the
+// current folder, so `"npx"` looked for npx-cli.js inside the repo being packed (#326). Callers pass a
+// fixed name (`npm`, `npx`), never user input.
 export function launcherInvocation(cmd, args, platform = process.platform) {
   if (platform !== 'win32') return { cmd, args, shell: false };
-  return { cmd: [cmd, ...args].map((a) => `"${String(a).replace(/"/g, '')}"`).join(' '), args: [], shell: true };
+  return { cmd: [cmd, ...args.map((a) => `"${String(a).replace(/"/g, '')}"`)].join(' '), args: [], shell: true };
 }
 export function runLauncher(cmd, args = [], opts = {}) {
   const inv = launcherInvocation(cmd, args);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "4.5.0",
+  "version": "4.5.1",
   "description": "Shared project memory and workflows for teams building with AI: a versioned record of plans, decisions, contracts and reviews across repos, human-approved review gates, and a zero-dependency `yad` CLI plus 38 skills for your AI assistant.",
   "type": "module",
   "author": "AbdelRahman Nasr",

package/skills/sdlc/module-help.csv

@@ -31,9 +31,9 @@ SDLC Workflow,yad-report,Report Issue,RP,"Self issue reporter: when a yad flow b
 SDLC Workflow,yad-connect-docs,Connect Docs Target,DX,"Setup/maintenance: connect a docs/Pages publishing target so the interactive-docs steps can deploy the generated site (not just commit its source). Auto-detects the platform from .sdlc/product.json (github->github-pages, gitlab->gitlab-pages, null->build-only), resolves the Vite base path, and records the target in .sdlc/docs.json (local-user auth, no stored tokens). Degrades to build-only when gh/glab is absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {target: github-pages|gitlab-pages|none} {scope: product|<repo>|dedicated} {base_path: <override>},0-setup,,yad-docs,false,.sdlc/,docs.json
 SDLC Workflow,yad-docs,Author Docs Site,DS,"Generate the per-epic interactive documentation SPA (animated flow canvas + role-based stakeholder doc pages) from the epic's approved artifacts (epic, architecture, locked contract, ui-design, stories, code-context, test-cases), themed by the connected design system, into epics/EP-<slug>/docs-site/. Copies the vendored React/Vite/Tailwind shell verbatim and generates src/data/*.ts deterministically; drives the yad docs build/deploy CLI to publish to Pages (or build-only). An OUTPUT ENRICHMENT — never a gate; never mutates state.json, approvals, or the contract lock.",,{epic: EP-<slug>} {action: generate|refresh|deploy} {login_gate: true|false},4-automate,yad-review-gate,,false,epics/EP-<slug>/docs-site/,docs-site/ docs-build.json
 SDLC Workflow,yad-docs-overview,Docs Overview Site,DO,"Generate the project SDLC-overview interactive site (docs/sdlc-site/) — every stage from setup to ship modeled as flow paths, system components, and stakeholder roles — reusing the same vendored shell, themed with yadflow's brand palette. Reads config.yaml + module-help.csv + the overview diagram as the pipeline source. Folds the hand-maintained docs/index.html report into the site as report.html (linked from the nav). Not a gate — a project-level enrichment that regenerates whenever the skill set / pipeline changes.",,{action: generate|deploy},4-automate,,,false,docs/sdlc-site/,sdlc-site/ .docs-build.json
-SDLC Workflow,yad-docs-sync,Docs Sync,DY,"Maintenance/CI: keep the generated doc sites fresh. Detect staleness (a content hash of the approved artifacts + the connected repos' HEAD shas + for a per-epic site the doc-shell version, vs each site's build manifest), report which sites drifted and why, regenerate + redeploy the stale ones, and wire a CI job that rebuilds on push (carrying [skip ci] + a concurrency group to prevent deploy loops). Generalizes the rule that feature work must hand-update docs/index.html + diagrams + skill counts. Refresh is always a human/CI decision; never a gate.",,{action: check|refresh|wire} {epic: EP-<slug>},4-automate,,,false,epics/EP-<slug>/.sdlc/,docs-build.json yad-docs.yml
+SDLC Workflow,yad-docs-sync,Docs Sync,DY,"Maintenance/CI: keep the generated doc sites fresh. Detect staleness (a content hash of the approved artifacts + the connected repos' HEAD shas + for a per-epic site the doc-shell version, vs each site's build manifest), report which sites drifted and why, regenerate + redeploy the stale ones, and wire a CI job that builds and deploys every site on push (one deploy at a time; a site that fails to build fails the run). Generalizes the rule that feature work must hand-update docs/index.html + diagrams + skill counts. Refresh is always a human/CI decision; never a gate.",,{action: check|refresh|wire} {epic: EP-<slug>},4-automate,,,false,epics/EP-<slug>/.sdlc/,docs-build.json yad-docs.yml
 SDLC Workflow,yad-change,Change/Defect Intake,CH,"Phase 6 post-lock change management: the INTAKE + TRIAGE step of a feature thread. Classifies the change DEPTH (defect-fix / behavioral-no-surface / contract-surface / new-capability), seeds a NEW EP-<slug> change-epic threaded to its parent (lineage frontmatter kind+type/parent/thread/inherits/supersedes ; then `yad epic new --parent` writes the state.json whose inherited steps are carried by reference and only the changed steps run, plus a pointer-lock contract-lock.json when architecture is inherited), and records the intake in change.json (escape_stage + root_cause for defects). For hotfixes it records the ship-first exception and opens reconcile-debt.json. Never auto-advances — hands off to the normal authoring skills + yad-review-gate.",,{parent: EP-<slug>} {title: one-line} {type: change|defect|hotfix} {origin: production|staging|qa|review} {severity: sev1..sev4} {description: text} {affected: artifacts},6-change,,yad-review-gate,false,epics/EP-<slug>/,epic.md state.json change.json reconcile-debt.json contract-lock.json
 SDLC Workflow,yad-timeline,Feature Timeline,TL,"Render a feature THREAD (its linked epics, genesis->changes->defects) as an evolution view (the vendored React/Vite/Tailwind shell HTML + a TIMELINE.md summary) AND resolve the inheritance chain into the authoritative current artifact set (thread-resolved.md: the winning source per artifact + the resolved contract-lock hash) — the composed source-of-truth AI/humans read for the next change. Reads frontmatter lineage + each change.json + the build ledger (folded build-log.json UNIONed with every build-log/ shard). An OUTPUT ENRICHMENT — never a gate; never mutates state.",,{thread: EP-<genesis>} {action: generate|deploy},6-change,,,false,epics/EP-<genesis>/,timeline-site/ thread-resolved.md TIMELINE.md
 SDLC Workflow,yad-defects,Quality-Gap Report,DF,"Generate a per-epic AND per-thread defect/bug report (same vendored shell + DEFECTS.md). Walks the thread for every defect-type change-epic + each change.json defect block + shipped regressions in the build ledger (folded build-log.json UNIONed with every build-log/ shard), aggregates by escape_stage (the SDLC gate that should have caught it) and root_cause, and visualizes WHERE quality gaps systematically come from (e.g. % of thread defects that escaped at the test-cases gate) so the team can harden the originating stage. An OUTPUT ENRICHMENT — never a gate; never mutates state.",,{epic: EP-<slug> | thread: EP-<genesis>} {action: generate|deploy},6-change,,,false,epics/EP-<slug>/,defects-site/ DEFECTS.md
-SDLC Workflow,yad-reconcile,Change Reconciler,RE,"Maintenance/CI (mirrors yad-docs-sync — never a gate): detect post-lock DRIFT/ORPHANS — shipped code or a repo HEAD advance (the repos.json syncedHead-vs-current-HEAD rule) with NO owning change-epic in any thread — plus open hotfix reconcile debt, and report which thread drifted and why. refresh points at yad-change to open a reconcile change-epic (or yad-stub first, to anchor orphan brownfield code that has no epic at all) — never silent; wire commits advisory CI ([skip ci] + concurrency, like yad-docs-sync). The actual merge BLOCK is the lineage-check / reconcile-debt gates; this only discovers.",,{action: check|refresh|wire} {thread: EP-<genesis>},6-change,,,false,epics/EP-<genesis>/.sdlc/,(report) reconcile-debt.json yad-reconcile.yml
+SDLC Workflow,yad-reconcile,Change Reconciler,RE,"Maintenance/CI (mirrors yad-docs-sync — never a gate): detect post-lock DRIFT/ORPHANS — shipped code or a repo HEAD advance (the repos.json syncedHead-vs-current-HEAD rule) with NO owning change-epic in any thread — plus open hotfix reconcile debt, and report which thread drifted and why. refresh points at yad-change to open a reconcile change-epic (or yad-stub first, to anchor orphan brownfield code that has no epic at all) — never silent; wire commits advisory CI ([skip ci] + concurrency). The actual merge BLOCK is the lineage-check / reconcile-debt gates; this only discovers.",,{action: check|refresh|wire} {thread: EP-<genesis>},6-change,,,false,epics/EP-<genesis>/.sdlc/,(report) reconcile-debt.json yad-reconcile.yml
 SDLC Workflow,yad-stub,Stub Genesis Epic,SG,"Phase 6 brownfield helper: mint a STUB genesis epic for an already-built feature that has no epic in the Product, so a defect/change can thread off it TODAY (yad-change requires a real parent and dead-ends without one). Creates the smallest real thread anchor — a tiny epic.md (type feature, thread:self, verified:false, stub:backfill-pending) + a seeded state.json (kind:stub / currentStep:backfill-pending) + empty ledgers — never inventing behaviour. Defects thread off it immediately (gates pass; the bug list is derived by the thread rollup); yad-backfill + its promote step later flip it into a real feature epic. Never auto-advances.",,{feature: <name>} {repos: [<repo>]} {description: one-line},6-change,,yad-change,false,epics/EP-<slug>/,epic.md state.json approvals.json comments.json

package/skills/yad-docs-overview/SKILL.md

@@ -150,4 +150,4 @@ under `<base>/app/` and cross-linked. Never touches any epic state.
   `yad-*` skill in pipeline order + its phase + outputs: `references/pipeline-model.md`.
 - The per-epic counterpart (shell, determinism, theming): `../yad-docs/SKILL.md`.
 - The connected docs target + base-path resolution: `../yad-connect-docs/SKILL.md`.
-- The staleness/CI reconciler that enforces overview regeneration: `../yad-docs-sync/SKILL.md`.
+- The staleness reconciler (reports stale sites, refreshes on request, wires the Pages build): `../yad-docs-sync/SKILL.md`.

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

@@ -1,6 +1,6 @@
 ---
 name: yad-docs-sync
-description: 'The maintenance/CI reconciler for the generated docs sites — mirroring the `yad check` / `yad gate ci` drift pattern. Recomputes each site''s freshness hashes (per-epic: the artifact hash + repo HEADs; overview: config.yaml + module-help.csv + the overview diagram + skill count) and compares them to each docs-build.json baseline: a site is stale when any hash differs or its shell template is out of date. `--check` (default, read-only) reports which sites are stale and WHY; `--refresh` regenerates + redeploys each stale site; `--wire` commits the CI workflow that runs the check on push and rebuilds on staleness. Refresh is always a human/CI decision, never silent; docs are never a gate. Use when the user says "sync the docs", "check docs staleness", "refresh stale docs sites", or "wire the docs CI".'
+description: 'The maintenance/CI reconciler for the generated docs sites — mirroring the `yad check` / `yad gate ci` drift pattern. Recomputes each site''s freshness hashes (per-epic: the artifact hash + repo HEADs; overview: config.yaml + module-help.csv + the overview diagram + skill count) and compares them to each docs-build.json baseline: a site is stale when any hash differs or its shell template is out of date. `--check` (default, read-only) reports which sites are stale and WHY; `--refresh` regenerates + redeploys each stale site; `--wire` commits the CI workflow that builds and deploys every site on push. Refresh is always a human/CI decision, never silent; docs are never a gate. Use when the user says "sync the docs", "check docs staleness", "refresh stale docs sites", or "wire the docs CI".'
 ---
 
 # SDLC — Sync the Docs Sites (the staleness reconciler)
@@ -67,17 +67,17 @@ A missing `docs-build.json` (a site never generated) counts as **stale → needs
   rebuild failed: `yad docs sync --refresh` exits 1 when a stale site's npm install or build fails, and
   its `--json` `sites` rows say which (`built: false` with an `error`). **Never silent** — refresh
   is a deliberate human/CI act, surfaced exactly like `yad repo refresh`.
-- **`wire`** — commit the CI workflow (Step 4) that automates the check + rebuild.
+- **`wire`** — commit the CI workflow (Step 4) that builds and deploys every site on push.
 
 ### Step 4 — `wire`: the CI auto-rebuild workflow
 Commit the platform-matched workflow (GitHub `.github/workflows/yad-docs.yml`, or a GitLab `pages` job at
 `.gitlab/ci/yad-docs.yml` that must be `include:`d from the root `.gitlab-ci.yml` —
 `include: { local: .gitlab/ci/yad-docs.yml }`, the same fragment+include shape as the `yad-checks` gates):
-- on push, run **`yad docs sync --check`**; on detected staleness, **rebuild + deploy** the affected
-  site(s);
-- carry **`[skip ci]`** on any commit the workflow itself makes (the regenerated source / manifest) and
-  a **concurrency group** (one docs deploy at a time) — both to **prevent deploy loops** (a rebuild must
-  not retrigger the workflow). See `references/staleness.md`.
+- on a push to the default branch, **build every committed site and deploy them**; it commits nothing,
+  so it cannot retrigger itself, and a **concurrency group** keeps one docs deploy at a time;
+- a site that fails to build **fails the run** (every failed site is named) and nothing is deployed, so
+  the last good site stays live. `yad doctor` warns (`docs-workflow`) when the wired file still deploys after a failed site build (as yadflow 4.5.0 and older wrote it) — re-run
+  `yad docs sync --wire`. See `references/staleness.md`.
 
 ### Step 5 — Report
 Report per target: **fresh** or **stale (why)**; for `refresh`, what was regenerated + the deploy URL or
@@ -91,14 +91,15 @@ Report per target: **fresh** or **stale (why)**; for `refresh`, what was regener
   `contract-lock.json`. Staleness blocks nothing in the SDLC; it only flags out-of-date docs.
 - **HEAD-sha staleness, reused.** Repo drift uses the exact `repos.json` `syncedHead`-vs-current-HEAD
   rule. The overview uses config + manifest + diagram + skill-count.
-- **Loop-prevention is mandatory in CI.** The wired workflow must carry `[skip ci]` on its own commits
-  and a concurrency group so a deploy never retriggers a deploy.
+- **CI builds and deploys; it never commits.** The wired workflow builds every committed site on push
+  and deploys them, under one concurrency group; it makes no commit, so it cannot retrigger itself. A
+  site that fails to build fails the run, and nothing is deployed.
 - **Reconcile, don't re-author.** This skill detects drift and delegates regeneration to `yad-docs` /
   `yad-docs-overview`; it does not generate `src/data/*.ts` itself.
 
 ## Reference
 - The manifest schema (per-epic + overview), the exact hash inputs, the head-sha staleness rule, and the
-  CI loop-prevention note: `references/staleness.md`.
+  CI note: `references/staleness.md`.
 - The generators this delegates to: `../yad-docs/SKILL.md`, `../yad-docs-overview/SKILL.md`.
 - The docs target it deploys to: `../yad-connect-docs/SKILL.md`.
 - The drift / refresh discipline this mirrors: `../yad-connect-repos/SKILL.md` (HEAD-sha staleness).

package/skills/yad-docs-sync/references/staleness.md

@@ -65,18 +65,16 @@ A site is **stale** when ANY holds:
 `check` reports which of these tripped and why; `refresh` regenerates + redeploys; neither blocks any
 SDLC step (docs are never a gate).
 
-## CI loop-prevention note
+## CI note
 
 The `wire` workflow (`.github/workflows/yad-docs.yml`, or the GitLab `pages` job at
-`.gitlab/ci/yad-docs.yml` included from the root `.gitlab-ci.yml`) runs
-`yad docs sync --check` on push and rebuilds + deploys on staleness. Because the rebuild **commits** the
-regenerated `src/data/*.ts` + refreshed `docs-build.json`, that commit would re-trigger the same workflow
-— a deploy loop. Two guards, both mandatory:
-
-- **`[skip ci]`** in the message of any commit the workflow itself makes (the regenerated source +
-  manifest), so the workflow does not re-fire on its own output;
-- a **concurrency group** (e.g. `concurrency: { group: yad-docs-deploy, cancel-in-progress: true }`) so
-  at most one docs build/deploy runs at a time, and a queued one is superseded rather than stacking.
-
-Together these make the CI rebuild idempotent: a push that moves an artifact deploys exactly one fresh
-site, and the resulting bot commit does not start another round.
+`.gitlab/ci/yad-docs.yml` included from the root `.gitlab-ci.yml`) builds every committed site and
+deploys them on each push to the default branch. It does not check staleness and commits nothing:
+regenerating a site's `src/data/*.ts` stays a local `yad docs sync --refresh` that a person commits.
+So it cannot start itself again; a **concurrency group** (`yad-docs-pages`, cancel-in-progress) keeps
+it to one deploy at a time.
+
+A site that fails to build fails the run, and the run names every site that failed. A red run uploads
+nothing, so the last good deployment stays live. (Before this, a failed site was silently left out and
+the run went green — that is how a site could lose a page.) `yad doctor` warns (`docs-workflow`) when the wired file still deploys after a failed site build (as yadflow 4.5.0 and older wrote it); run
+`yad docs sync --wire` again and commit it.

package/skills/yad-product-bridge/SKILL.md

@@ -146,6 +146,10 @@ default branch. (local mode keeps `yad gate sync` as the local writer.)
      case set the variable to a real tag. The variable lives in project settings, so it survives
      every `yad` sync. Single value only — `tags: [$VAR]` is one tag equal to the whole variable,
      not a comma-split.
+   - **Git LFS needs nothing extra.** For a Product that uses Git LFS, the runner installs LFS git
+     hooks that fail without `git-lfs`, and the job's `node:20` image has none — so the job downloads a
+     pinned `git-lfs` itself before its checkout (#327; a Product without LFS skips it). A
+     `before_script` added by hand to install `git-lfs` can be removed after `yad update`.
 3. Commit the workflow to the Product. GitHub needs nothing else — the ephemeral `github.token` reads the
    PR and pushes the merge advance to the default branch, and the workflow's reconcile **schedule**
    runs automatically (no setup) as the safety net that recovers a merge whose run failed transiently.

package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml

@@ -81,6 +81,24 @@ yad-gate-sync:
     # jq streams glab's concatenated per-page --paginate arrays natively.
     - JQ_VERSION=1.7.1
     - curl -fsSL "https://github.com/jqlang/jq/releases/download/jq-${JQ_VERSION}/jq-linux-amd64" -o /usr/local/bin/jq && chmod +x /usr/local/bin/jq
+    # Pinned git-lfs, ONLY for a Product that uses Git LFS (issue #327). The runner clones an LFS repo
+    # with its own git-lfs and installs LFS git hooks (post-checkout, pre-push, …) that exit with an
+    # error when git-lfs is missing — and node:20 has none. So the `git checkout` below failed, and so
+    # would the push of the advance. A Product without LFS skips the download. Only the clone's own
+    # signs count (its hooks, its .git/config, its .gitattributes) — never a global git setting.
+    # The download is checked against the release's published SHA-256 (sha256sums.asc) before it is
+    # unpacked: this job holds a token that can push the default branch, and git-lfs then runs on every
+    # checkout and push. One command per line, not an `&&` chain — `set -e` does not stop on a failure
+    # inside a chain, so a bad checksum would fall through to the checkout.
+    - |
+      GIT_LFS_VERSION=3.8.0
+      GIT_LFS_SHA256=e455e00f15d9b95661b8d53498ffb0c3367962cf1ec73c31ab7369516cd6ab8d
+      if ! command -v git-lfs >/dev/null 2>&1 && { grep -qs git-lfs "$(git rev-parse --git-path hooks)"/* || git config --local --get-regexp '^filter\.lfs\.' >/dev/null 2>&1 || grep -qs 'filter=lfs' .gitattributes; }; then
+        curl -fsSL "https://github.com/git-lfs/git-lfs/releases/download/v${GIT_LFS_VERSION}/git-lfs-linux-amd64-v${GIT_LFS_VERSION}.tar.gz" -o /tmp/git-lfs.tar.gz
+        echo "${GIT_LFS_SHA256}  /tmp/git-lfs.tar.gz" | sha256sum -c -
+        tar -xzf /tmp/git-lfs.tar.gz -C /tmp "git-lfs-${GIT_LFS_VERSION}/git-lfs"
+        install -m 0755 "/tmp/git-lfs-${GIT_LFS_VERSION}/git-lfs" /usr/local/bin/git-lfs
+      fi
     - git config user.name "yad-gate-sync" && git config user.email "yad-gate-sync@noreply.${CI_SERVER_HOST}"
     - git remote set-url origin "https://oauth2:${SDLC_GATE_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git"
     - export GITLAB_TOKEN="$SDLC_GATE_TOKEN" GITLAB_HOST="$CI_SERVER_URL"

package/skills/yad-reconcile/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-reconcile
-description: 'Phase 6 maintenance/CI — the change reconciler (mirrors yad-docs-sync; NEVER a gate). Detects post-lock DRIFT and ORPHANS across feature threads: shipped code or a repo HEAD advance (the repos.json syncedHead-vs-current-HEAD rule) with NO owning change-epic in any thread, a broken lineage (cycle, missing parent, or a thread cache that disagrees with the computed root), and open hotfix reconcile debt — reporting which thread drifted and WHY. `check` (default, read-only) reports; `refresh` points the human at opening a reconcile change-epic with yad-change (never silent); `wire` commits an advisory CI job ([skip ci] + concurrency, like yad-docs-sync) that runs the check on push. The hard merge BLOCK is the lineage-check / epic-open / reconcile-debt CI gates — this only DISCOVERS. Use when the user says "reconcile the changes", "check for thread drift", "is anything shipped without an epic", or "find open hotfix debt".'
+description: 'Phase 6 maintenance/CI — the change reconciler (mirrors yad-docs-sync; NEVER a gate). Detects post-lock DRIFT and ORPHANS across feature threads: shipped code or a repo HEAD advance (the repos.json syncedHead-vs-current-HEAD rule) with NO owning change-epic in any thread, a broken lineage (cycle, missing parent, or a thread cache that disagrees with the computed root), and open hotfix reconcile debt — reporting which thread drifted and WHY. `check` (default, read-only) reports; `refresh` points the human at opening a reconcile change-epic with yad-change (never silent); `wire` commits an advisory CI job ([skip ci] + concurrency) that runs the check on push. The hard merge BLOCK is the lineage-check / epic-open / reconcile-debt CI gates — this only DISCOVERS. Use when the user says "reconcile the changes", "check for thread drift", "is anything shipped without an epic", or "find open hotfix debt".'
 ---
 
 # SDLC — Change Reconciler (Phase 6, the drift/orphan sweep)
@@ -65,7 +65,7 @@ that feature — then thread the reconcile change off that stub (and run `yad-ba
 
 ### Step 3 — `wire` (advisory CI, no block)
 Commit an advisory CI job that runs `yad reconcile --check` on push, carrying `[skip ci]` on any commit
-it makes and a concurrency group — the same loop-prevention `yad-docs-sync` uses. The job **reports**;
+it makes and a concurrency group, so it never retriggers itself. The job **reports**;
 it never blocks. The blocking enforcement is the `yad-checks` gates, not this.
 
 ### Step 4 — Report