npm - yadflow - Versions diffs - 2.5.0 → 2.7.0 - Mend

yadflow 2.5.0 → 2.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (124) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -1,9 +1,15 @@
-# [2.5.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.4.2...v2.5.0) (2026-06-14)
+# [2.7.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.6.0...v2.7.0) (2026-06-14)
+### Bug Fixes
+* drop unused today param from runDocs (lint) ([1c255f1](https://github.com/abdelrahmannasr/yadflow/commit/1c255f1c848b9571502e29b142a07366612d638c))
+* publish per-epic docs sites in CI + check shell-version staleness ([9862646](https://github.com/abdelrahmannasr/yadflow/commit/9862646fbe910de8ad8248a5f1bb586a5604b18f))
 ### Features
-* per-scope roster roles + auto assignee/reviewer on PRs ([5ff066b](https://github.com/abdelrahmannasr/yadflow/commit/5ff066b2a83f63ddf25353ddaf0a088b91a6adb0))
+* add interactive documentation skills + yad docs CLI ([4bf7a25](https://github.com/abdelrahmannasr/yadflow/commit/4bf7a25c38e28ef47704a8e2f5acec2f724e4e29))
 # [2.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.1.0...v2.2.0) (2026-06-14)

package/README.md CHANGED Viewed

@@ -60,7 +60,10 @@ human**. Detailed walkthroughs for each phase follow below.
 | `skills/yad-pr-template/` | Build Step D: install the platform PR/MR template + risk routing (code repos **and** the hub). |
 | `skills/yad-review-comments/` | Install platform-matched PR/MR review-comment scaffolds (code repos and the hub). |
 | `skills/yad-hub-bridge/` | The templated PR/MR **review bridge**: open a review PR/MR on the hub and sync platform approvals/comments into the file ledger. |
-| `skills/yad-ship/` | Build Step E: AI review (advisory) → engineer review → ship + record in the build log. |
+| `skills/yad-commit/` | Build helper: commit ONE staged atomic change by the conventions (Conventional subject, trailers, `--ai` footer, ≤3-file guard). |
+| `skills/yad-open-pr/` | Build helper: open a code-repo task PR/MR from the committed template (push, prefill, roster auto-assign). |
+| `skills/yad-ship/` | Build helper: commit **and** open the task PR/MR in one step (`yad commit` then `yad open-pr`). |
+| `skills/yad-engineer-review/` | Build Step E: AI review (advisory) → engineer review → merge + record in the build log. |
 | `skills/yad-backfill/` | Generate a human-verified spec for already-built code (Repomix), gated per touched feature. |
 | `skills/yad-run/` | Phase 4 orchestrator: drive a story's back half on the `automation` dial; kill switch. |
 | `skills/yad-status/` | Read-only view: front chain, build-half dials, trust record, fleet roll-up. |
@@ -94,13 +97,15 @@ with `npx` from your **product hub** repo — no clone needed.
 | `yad gate ci [--branch <head>] [--pr <n>]` | The CI entry the hub workflow calls on review/merge events: derive the epic/artifact from the `review/EP-*` branch, run the same sync, and commit **only the ledger** to the hub default branch (sweep every open review PR when no `--branch`). |
 | `yad commit --type <t> -m <subject>` | Commit by the SDLC convention — Conventional subject, `Task`/`Contract-Change`/`Co-Authored-By` trailers, atomic-file guard. |
 | `yad open-pr [--repo <name>]` | Open a code-repo **task** PR/MR from the repo's platform template (build half). |
+| `yad ship --type <t> -m <subject>` | Commit **and** open the task PR/MR in one step (`yad commit` then `yad open-pr`). |
 | `yad repo list` / `yad repo refresh [name]` | List connected repos as **fresh / stale**, and re-pack a stale one — staleness is now an explicit human decision, never an automatic skill side-effect. |
 | `npx yadflow --version` | Print the installed CLI version. |
 Flags: `--dir <path>` targets a project other than the cwd; `--force` re-copies unchanged files (or
 bypasses the commit atomic guard). Commit flags: `--type`, `-m/--message`, `--task`, `--ai
 <claude\|copilot\|cursor\|coderabbit\|none>`, `--contract-change`, `--dry-run`. `open-pr` flags:
-`--repo`, `--risk <low\|medium\|high>`, `--contract-change`.
+`--repo`, `--risk <low\|medium\|high>`, `--contract-change`. `ship` takes the union of the `commit`
+and `open-pr` flags (it runs `open-pr` only if the commit lands).
 ### The PR-driven review gate
@@ -128,7 +133,7 @@ simultaneous advancements can be lost; the next event or scheduled sweep re-sync
 ### What `setup` walks you through (10 steps)
 1. **Preflight** — confirm the hub is a git repo (offers `git init`); check `git`/`node`/`npx`.
-2. **Install the module** — copy all 22 `yad-*` skills into the IDE skill dirs you pick
+2. **Install the module** — copy all 29 `yad-*` skills into the IDE skill dirs you pick
    (`.claude/`, `.agents/`, `.zencoder/`, `.opencode/`) and register `_bmad/sdlc/`.
 3. **Hub platform & roster** — detect GitHub/GitLab from the remote; record reviewers → `.sdlc/hub.json`.
 4. **Connect a design tool** — record the design tool (Figma / pencil / none) → `.sdlc/design.json` so
@@ -184,7 +189,7 @@ with a fix-it hint per finding. Failures carry stable, greppable codes, also pri
 Filing a bug? Attach `yad doctor --json` — it contains no secrets (names, paths, and check results only).
-## Agent skills (all 22)
+## Agent skills (all 29)
 The CLI **installs and wires** the module; the skills below are the **agents you invoke by name** in your
 AI IDE (e.g. *“run `yad-epic`”*) to actually do the work. State lives in files you can also edit
@@ -213,6 +218,27 @@ directly. Each skill stops at a gate and never auto-advances unless a step has *
   tokens), detecting the **DeepTutor CLI on PATH** (a subprocess like Repomix — DeepTutor ships no MCP)
   and degrading to **harness-native** tutoring when absent. Idempotent and refreshable; one connection
   per project.
+- **`yad-connect-docs`** — Connects a docs/Pages target (GitHub Pages / GitLab Pages, auto-detected from
+  `hub.json`) so the generated documentation sites can deploy. Records the target + scope + base path in
+  `.sdlc/docs.json` (local-user auth, no stored tokens), degrading to **build-only** when no Pages host /
+  CLI is present. Idempotent and refreshable; one connection per project.
+### Living documentation (generated, themed, auto-kept-fresh)
+- **`yad-docs`** — Generates an **interactive documentation site** for an epic (a React + Vite + Tailwind
+  SPA: an animated front-stage flow canvas + role-based stakeholder doc pages) from the authored
+  artifacts — `epic.md`, `architecture.md`, the locked `contract.md`, `ui-design.md`, the stories — into
+  `epics/EP-<slug>/docs-site/`, themed by the **connected design system** (`DESIGN.md` / `design.json`
+  tokens → the site's CSS). The content lives in generated `src/data/*.ts`; the shell is a vendored
+  template. An **output enrichment, never a gate** — it never touches epic state, approvals, or the
+  contract lock. `generate` / `refresh` / `deploy`.
+- **`yad-docs-overview`** — Generates the project **SDLC-overview site** (`docs/sdlc-site/`) — every
+  stage from setup → ship as flow paths / system components / stakeholder roles, reusing the same shell —
+  superseding the hand-maintained `docs/index.html`.
+- **`yad-docs-sync`** — Keeps the sites fresh: detects staleness (a content hash of the authored
+  artifacts + the connected repos' HEAD shas vs each site's build manifest), regenerates + redeploys, and
+  can wire a CI job that rebuilds on push. Generalizes the rule that feature work must hand-update the
+  docs — the overview now regenerates whenever the skill set / pipeline changes.
 ### The learning layer (cross-cutting — any member, any stage)
@@ -276,15 +302,25 @@ directly. Each skill stops at a gate and never auto-advances unless a step has *
   (≤3 files) on its own branch. The diff stays inside the files the task declared (flag and STOP if it
   would grow). Commit ends with the task ID; `Contract-Change: yes` only if it touches the locked
   contract surface.
-- **`yad-checks`** — Step C, the production-safety gates. Wire and run three CI gates: **spec-link**
+- **`yad-checks`** — Step C, the production-safety gates. Wire and run the CI gates: **spec-link**
   (every change links a real story/spec), **contract-check** (a contract-surface diff without a
-  re-locked contract FAILS), and **build/test/lint**. CI-agnostic bash for GitHub Actions and GitLab CI.
+  re-locked contract FAILS), **build/test/lint**, **verified-commits** (signed + roster-known authors),
+  and the **pattern gates** — **commit-message** (Conventional subject + trailer order), **pr-title**,
+  and **pr-template** (the PR/MR body uses the template). Profile-aware (`code`|`hub`), so they run on
+  both code repos and the product hub. CI-agnostic bash for GitHub Actions and GitLab CI.
 - **`yad-pr-template`** — Step D. Detect the repo's platform and commit the matching PR/MR template with
   an Impact & Risk block; high risk (or a contract/auth/payments surface) routes the review to domain
-  owners. Includes `risk-route.sh`.
-- **`yad-ship`** — Step E. AI review (CodeRabbit, advisory) → engineer review (the human gate, owner +
-  1 reviewer with the same escalation) → on merge, record the ship in the epic build-log and update the
-  story state so the epic → story → task → PR chain stays traceable.
+  owners. Includes `risk-route.sh` plus the `pr-title.sh` / `pr-template.sh` gate scripts.
+- **`yad-commit`** — build helper. Commit ONE staged atomic change by the conventions (Conventional
+  subject, `Task → Contract-Change → Co-Authored-By` trailers, the `--ai` co-author footer, the ≤3-file
+  atomic guard). Drives `yad commit`.
+- **`yad-open-pr`** — build helper. Open a code-repo task PR/MR from the committed template: push the
+  branch, prefill the body, auto-assign the repo-scoped roster. Drives `yad open-pr`.
+- **`yad-ship`** — build helper. Commit **and** open the task PR/MR in one step (`yad commit` then
+  `yad open-pr`; the PR step runs only if the commit lands). Drives `yad ship`.
+- **`yad-engineer-review`** — Step E. AI review (CodeRabbit, advisory) → engineer review (the human gate,
+  owner + 1 reviewer with the same escalation) → on merge, record the ship in the epic build-log and
+  update the story state so the epic → story → task → PR chain stays traceable.
 - **`yad-backfill`** — Step G. Generate specs for already-built features in an existing repo so new work
   doesn't break them: pack one feature at a time with Repomix, write a DRAFT spec, require human approval
   before it counts. A change is blocked only until the features it touches have approved specs.
@@ -382,12 +418,16 @@ build half by hand”** below.
 11. `yad-implement story:<id> repo:<repo> task:<T0N>` → one atomic task = one branch = one commit
     (repeat per task). Commit by convention with **`yad commit --type <t> -m <subject> [--ai <tool>]`**
     (Task/Contract-Change/Co-Authored-By trailers, atomic-file guard).
-12. `yad-checks repo:<repo> action: run` → spec-link, contract-check, build/test/lint, and
-    verified-commits (platform-Verified signature + roster-allowlisted author) must pass.
-13. Open the PR/MR from the wired template with **`yad open-pr --repo <repo> [--risk <level>]`**;
-    `yad-pr-template repo:<repo> action: route` prints the required reviewers from the Impact & Risk block.
-14. `yad-ship` → `ai-review` (advisory) → `approve` (the human engineer gate) → `ship` (merge, record
-    in `build-log.json`, update story status to `in-build`/`shipped`).
+12. `yad-checks repo:<repo> action: run` → spec-link, contract-check, build/test/lint, verified-commits
+    (platform-Verified signature + roster-allowlisted author), and commit-message must pass. (The
+    `pr-title` / `pr-template` gates need the PR title + body, so they run in CI once the PR exists —
+    step 13.)
+13. Open the PR/MR from the wired template with **`yad open-pr --repo <repo> [--risk <level>]`** (or do
+    12+13 in one step with **`yad ship --type <t> -m <subject> --repo <repo>`**). The PR's CI now also
+    runs the `pr-title` and `pr-template` gates; `yad-pr-template repo:<repo> action: route` prints the
+    required reviewers from the Impact & Risk block.
+14. `yad-engineer-review` → `ai-review` (advisory) → `approve` (the human engineer gate) → `ship` (merge,
+    record in `build-log.json`, update story status to `in-build`/`shipped`).
     - **Multi-repo:** repeat 10–14 in each repo, all from the **one** locked contract.
     - **Existing code:** `yad-backfill` first, to produce a human-verified spec for a built feature.
@@ -514,16 +554,19 @@ the product repo. Code repos are **separate git repos** under `demo-repos/<repo>
    (`feat/<story>-<task>-…`) = one PR. The diff stays inside the files the task declared. Commit with
    **`yad commit`** — it builds the conventional subject, derives the `Task:` trailer from the branch
    (add `--contract-change` only if the locked surface is touched), appends an optional `--ai` co-author,
-   and refuses a non-atomic stage. Open the PR with **`yad open-pr --repo <repo>`** (template prefilled).
-3. **Check gates** — `yad-checks` wires three CI gates (GitHub + GitLab) that must pass before merge:
+   and refuses a non-atomic stage. Open the PR with **`yad open-pr --repo <repo>`** (template prefilled),
+   or do both in one step with **`yad ship`** (commit then open-pr).
+3. **Check gates** — `yad-checks` wires the CI gates (GitHub + GitLab) that must pass before merge:
    **spec-link** (links a real story/spec), **contract-check** (a contract-surface change without
    `Contract-Change` + a re-locked contract FAILS, routing back to the architecture gate),
-   **build/test/lint**. They fail closed on a bad base ref.
+   **build/test/lint**, **verified-commits**, and the **pattern gates** **commit-message** / **pr-title**
+   / **pr-template** (profile-aware `code`|`hub`, so they also run on the product hub). They fail closed
+   on a bad base ref.
 4. **PR/MR template + risk routing** — `yad-pr-template` drops the platform-matched template with an
    Impact & Risk block; `high` risk (or a contract/auth/payments surface) routes the review to domain
    owners (`risk-route.sh`), the same escalation as the gate.
-5. **AI review → engineer review → ship** — `yad-ship`: CodeRabbit is an advisory first pass (never
-   the authority); a human engineer approves (owner + 1 reviewer, escalating to domain owners); on
+5. **AI review → engineer review → merge** — `yad-engineer-review`: CodeRabbit is an advisory first pass
+   (never the authority); a human engineer approves (owner + 1 reviewer, escalating to domain owners); on
    merge the ship is recorded in `.sdlc/build-log.json` and the story state becomes `in-build` →
    `shipped`. The epic → story → task → PR → mergeCommit chain is traceable both ways.
@@ -551,7 +594,7 @@ with their dials, per repo) and `trust-log.json` (every run's verdict). See
 - **Drive a story's back half:** `yad-run {story} {repo}` walks `spec → tasks → implement → checks`,
   reading each step's dial. On `machine_advance` it advances on its own; on `human_approve` it stops
   for a human; on any FAIL, scope overrun, or contract-surface touch it **halts and pulls in a human**.
-  It always stops at the engineer review (`yad-ship`), which is never automated.
+  It always stops at the engineer review (`yad-engineer-review`), which is never automated.
 - **Read the trust log:** `yad-status {epic}` shows each back step's dial, status, and trust record —
   runs, % `approved-unchanged`, and whether that clears the threshold (`automation.trust_threshold` in
   `config.yaml`, default ≥5 runs and ≥80% unchanged). The engineer review records each run's verdict

package/bin/yad.mjs CHANGED Viewed

@@ -8,7 +8,9 @@ import { gateOpen, gateSync, gateComments, gateStatus, gateCi } from '../cli/gat
 import { isValidEpicId } from '../cli/epic-state.mjs';
 import { runCommit } from '../cli/commit.mjs';
 import { runOpenPr } from '../cli/openpr.mjs';
+import { runShip } from '../cli/ship.mjs';
 import { runRepo } from '../cli/repo.mjs';
+import { runDocs } from '../cli/docs.mjs';
 import { runDoctor } from '../cli/doctor.mjs';
 const HELP = `${c.bold('yad')} — setup, review-gate & build helpers for the SDLC Workflow module  ${c.dim('v' + VERSION)}
@@ -34,9 +36,16 @@ ${c.bold('Review gate (front half)')}
 ${c.bold('Build helpers')}
   yad commit --type <t> -m <subject>   Commit by convention (trailers, atomic guard)
   yad open-pr [--repo <name>]          Open a code-repo task PR/MR from the template
+  yad ship --type <t> -m <subject>     Commit AND open the task PR/MR in one step
   yad repo list                        Show connected repos (fresh / stale)
   yad repo refresh [name]              Re-pack a stale repo (a human decision)
+${c.bold('Interactive docs (generated sites)')}
+  yad docs list                        Show the docs target + per-site freshness
+  yad docs build [--epic <id>|--overview]    npm-build a generated doc site
+  yad docs deploy [--epic <id>|--overview]   Build + report the Pages deploy
+  yad docs sync [--check|--refresh|--wire]   Staleness sweep; --wire installs the Pages CI
 ${c.bold('Options')}
   --dir <path>          Target project root (default: cwd)
   --type <t>            commit: feat|fix|docs|refactor|test|perf|build|ci|chore|revert
@@ -46,6 +55,9 @@ ${c.bold('Options')}
   --contract-change     commit/open-pr: mark the contract surface touched
   --risk <level>        open-pr: low|medium|high (default low)
   --repo <name>         open-pr: target a registered repo by name
+  --epic <id>           docs: target one epic's site (EP-<slug>)
+  --overview            docs: target the project SDLC-overview site
+  --check/--refresh/--wire   docs sync: report stale / rebuild / install Pages CI
   --dry-run             commit: print the message, do not commit
   --force               commit: bypass the atomic-file guard / re-copy unchanged files
   --branch <head>       gate ci: the review PR/MR head branch (review/EP-<slug>/<artifact>)
@@ -54,7 +66,7 @@ ${c.bold('Options')}
   -h, --help            Show this help
   -v, --version         Print version`;
-const VALUE_FLAGS = new Set(['--dir', '--type', '--message', '--task', '--ai', '--risk', '--repo', '--platform', '--base', '--title', '--scope', '--branch', '--pr']);
+const VALUE_FLAGS = new Set(['--dir', '--type', '--message', '--task', '--ai', '--risk', '--repo', '--platform', '--base', '--title', '--scope', '--branch', '--pr', '--epic']);
 function parseArgs(argv) {
   const o = { _: [], dir: process.cwd(), fix: false, force: false, scope: 'all' };
@@ -64,6 +76,10 @@ function parseArgs(argv) {
     else if (a === '--force') o.force = true;
     else if (a === '--contract-change') o.contractChange = true;
     else if (a === '--no-push') o.noPush = true;
+    else if (a === '--overview') o.overview = true;
+    else if (a === '--check') o.check = true;
+    else if (a === '--refresh') o.refresh = true;
+    else if (a === '--wire') o.wire = true;
     else if (a === '--dry-run') o.dryRun = true;
     else if (a === '--json') o.json = true;
     else if (a === '-h' || a === '--help') o.help = true;
@@ -123,11 +139,21 @@ async function main() {
     case 'open-pr':
       await runOpenPr(o.dir, { repo: o.repo, platform: o.platform, base: o.base, title: o.title || o.message, task: o.task, risk: o.risk, contractChange: o.contractChange });
       break;
+    case 'ship':
+      await runShip(o.dir, { type: o.type, message: o.message, task: o.task, ai: o.ai, contractChange: o.contractChange, dryRun: o.dryRun, force: o.force, repo: o.repo, platform: o.platform, base: o.base, title: o.title, risk: o.risk });
+      break;
     case 'repo': {
       const [, action, name] = o._;
       await runRepo(o.dir, { action: action || 'list', name, today });
       break;
     }
+    case 'docs': {
+      const [, action] = o._;
+      if (o.epic && !isValidEpicId(o.epic)) { log(c.red(`invalid epic id: ${o.epic} (expected EP-<slug>, [a-z0-9-] only)`)); process.exitCode = 1; break; }
+      const sync = o.wire ? 'wire' : o.refresh ? 'refresh' : 'check';
+      await runDocs(o.dir, { action: action || 'list', epic: o.epic, overview: o.overview, sync, today });
+      break;
+    }
     default:
       log(c.red(`unknown command: ${cmd}`));
       log(HELP);

package/cli/docs.mjs ADDED Viewed

@@ -0,0 +1,298 @@
+// `yad docs list|build|deploy|sync` — the build/deploy/staleness mechanics for the interactive
+// documentation sites generated by the yad-docs / yad-docs-overview skills. The CONTENT generation
+// (reading epic/architecture/contract/ui/stories → writing src/data/*.ts and theming index.css) is
+// the AI step inside those skills; this module only does the mechanical parts: npm build (a
+// subprocess, like yad-spec shelling npx repomix), the platform Pages wiring (reusing platform.mjs),
+// and the manifest-hash staleness check (reusing the head-sha idea from repo.mjs). It NEVER touches
+// epic state, approvals, or the contract lock — docs are an output enrichment, not a gate.
+//
+// Pure mapping fns (deployTargetFromHub / siteBasePath / docsArtifactHash / docsStale / pagesWorkflow)
+// are exported for unit tests; the side-effecting runDocs orchestrates them.
+import path from 'node:path';
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import { c, log, ok, info, warn, hand, fail, readJSON, run, has, exists } from './lib.mjs';
+import { PROJECT_FILES, VERSION } from './manifest.mjs';
+import { detectPlatform, platformReady } from './platform.mjs';
+import { gitHead } from './setup.mjs';
+import { contractSurfaceHash } from './epic-state.mjs';
+// ---- registry + site locations ------------------------------------------------------------------
+function loadDocs(root) {
+  const regPath = path.join(root, PROJECT_FILES.docsConfig);
+  return { regPath, docs: readJSON(regPath, null) };
+}
+// Per-epic site lives beside the epic artifacts; the overview is project-level under docs/.
+export function siteDir(root, { epic, overview } = {}) {
+  if (overview) return path.join(root, 'docs/sdlc-site');
+  return path.join(root, 'epics', epic, 'docs-site');
+}
+export function manifestPath(root, { epic, overview } = {}) {
+  if (overview) return path.join(siteDir(root, { overview }), '.docs-build.json');
+  return path.join(root, 'epics', epic, '.sdlc/docs-build.json');
+}
+// ---- pure: platform/target + base path ----------------------------------------------------------
+// hub.json platform -> the default Pages target (github-pages | gitlab-pages | none/build-only).
+export function deployTargetFromHub(hub = {}) {
+  const platform = hub?.platform || detectPlatform(hub?.git_url || '');
+  if (platform === 'github') return 'github-pages';
+  if (platform === 'gitlab') return 'gitlab-pages';
+  return 'none';
+}
+// The Vite `base` for one site: join the project base path (from docs.json) with the per-site
+// subpath. Per-epic sites nest under epics/<id>/; the overview is the Pages root. Always a
+// leading+trailing slash so it works as a Vite base and a router basename.
+export function siteBasePath(docs = {}, { epic, overview } = {}) {
+  const root = (docs.basePath || '/').replace(/\/+$/, '') || '';
+  const sub = overview ? '' : epic ? `/epics/${epic}` : '';
+  const joined = `${root}${sub}`.replace(/\/+/g, '/');
+  return joined ? `${joined.replace(/\/$/, '')}/` : '/';
+}
+// ---- pure: staleness ----------------------------------------------------------------------------
+// The artifacts whose content a per-epic site is generated from (any that exist contribute).
+// contract.md is deliberately EXCLUDED here: it is folded in via its CONTRACT-SURFACE block hash
+// (docsArtifactHash's `extra`), so docs-staleness tracks the same locked surface as the contract
+// lock — non-surface prose edits to contract.md don't needlessly mark the docs stale.
+export function docsArtifactFiles(root, epic) {
+  const epicRoot = path.join(root, 'epics', epic);
+  const flat = ['epic.md', 'architecture.md', 'ui-design.md', 'DESIGN.md', 'test-cases.md']
+    .map((f) => path.join(epicRoot, f));
+  const storiesDir = path.join(epicRoot, 'stories');
+  const stories = exists(storiesDir)
+    ? fs.readdirSync(storiesDir).filter((f) => f.endsWith('.md')).sort().map((f) => path.join(storiesDir, f))
+    : [];
+  return [...flat, ...stories].filter(exists).sort();
+}
+// sha256 over the (sorted) artifact files' bytes plus an optional `extra` string (the contract
+// surface hash) — the content baseline a site was built from. Deterministic: the file list is
+// sorted and each file is length-prefixed so concatenation is unambiguous (a + bc never collides
+// with ab + c).
+export function docsArtifactHash(files = [], extra = '') {
+  const h = createHash('sha256');
+  for (const f of [...files].sort()) {
+    const buf = fs.readFileSync(f);
+    h.update(`${path.basename(f)}:${buf.length}\n`);
+    h.update(buf);
+  }
+  if (extra) h.update(`\ncontract-surface:${extra}`);
+  return 'sha256:' + h.digest('hex');
+}
+// Current HEAD sha per repo the epic touches (mirrors repo.mjs head-sha staleness).
+export function repoHeadsFor(root, repos = [], registry = { repos: [] }) {
+  const out = {};
+  for (const name of repos) {
+    const entry = (registry.repos || []).find((r) => r.name === name);
+    if (!entry) continue;
+    out[name] = gitHead(path.resolve(root, entry.path)) || null;
+  }
+  return out;
+}
+// Compare a build manifest to the current world; list the concrete reasons it is stale.
+export function docsStale(manifest, { artifactHash, repoHeads = {}, templateVersion } = {}) {
+  const reasons = [];
+  if (!manifest) return { stale: true, reasons: ['never built'] };
+  if (artifactHash && manifest.artifactHash && artifactHash !== manifest.artifactHash) {
+    reasons.push('authored artifacts changed');
+  }
+  for (const [repo, head] of Object.entries(repoHeads)) {
+    const was = (manifest.repoHeads || {})[repo];
+    if (head && was && head !== was) reasons.push(`repo ${repo} HEAD advanced`);
+  }
+  if (templateVersion && manifest.templateVersion && templateVersion !== manifest.templateVersion) {
+    reasons.push(`doc shell upgraded (${manifest.templateVersion} → ${templateVersion})`);
+  }
+  return { stale: reasons.length > 0, reasons };
+}
+// ---- pure: the Pages CI workflow (committed by `yad docs sync --wire`) ---------------------------
+// GitHub Actions deploy-pages, or a GitLab `pages` job. Both assemble a single `public/` tree: the
+// overview at the root and every per-epic site under `epics/<id>/` — matching siteBasePath's nesting
+// (overview at `<base>/`, 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.
+const BUILD_PUBLIC = [
+  'mkdir -p public',
+  'if [ -d docs/sdlc-site ]; then (cd docs/sdlc-site && npm ci && npm run build) && cp -r docs/sdlc-site/dist/. public/; 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',
+];
+export function pagesWorkflow(platform) {
+  if (platform === 'gitlab') {
+    return `# yad-managed — built by \`yad docs sync --wire\`. include it from .gitlab-ci.yml:
+#   include: { local: .gitlab/ci/yad-docs.yml }
+# Edit the skill, not this file.
+pages:
+  stage: deploy
+  image: node:20
+  rules:
+    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
+  script:
+${BUILD_PUBLIC.map((l) => `    - '${l.replace(/'/g, "'\\''")}'`).join('\n')}
+  artifacts:
+    paths: [public]
+  resource_group: pages
+`;
+  }
+  return `# yad-managed — built by \`yad docs sync --wire\`. Edit the skill, not this file.
+name: yad-docs
+on:
+  push:
+    branches: [main, master]
+  workflow_dispatch:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: yad-docs-pages
+  cancel-in-progress: true
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: \${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Build the overview + per-epic sites into ./public
+        run: |
+${BUILD_PUBLIC.map((l) => `          ${l}`).join('\n')}
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: public
+      - id: deployment
+        uses: actions/deploy-pages@v4
+`;
+}
+export function pagesWorkflowPath(platform) {
+  return platform === 'gitlab' ? '.gitlab/ci/yad-docs.yml' : '.github/workflows/yad-docs.yml';
+}
+// ---- build (subprocess) -------------------------------------------------------------------------
+function buildSite(dir) {
+  if (!exists(dir)) { warn(`no generated site at ${path.relative(process.cwd(), dir)} — run the yad-docs skill first`); return { ok: false, missing: true }; }
+  if (!has('npm')) { warn('npm not on PATH — cannot build; the CI workflow will build on push'); return { ok: false, noNpm: true }; }
+  const install = exists(path.join(dir, 'package-lock.json')) ? ['ci'] : ['install'];
+  log(`  ${c.dim('$')} npm ${install[0]} ${c.dim(`(${path.relative(process.cwd(), dir)})`)}`);
+  const i = run('npm', install, { cwd: dir, stdio: 'inherit' });
+  if (!i.ok) { fail('npm install failed'); return { ok: false }; }
+  const b = run('npm', ['run', 'build'], { cwd: dir, stdio: 'inherit' });
+  if (!b.ok) { fail('npm run build failed'); return { ok: false }; }
+  return { ok: true, dist: path.join(dir, 'dist') };
+}
+// ---- orchestration ------------------------------------------------------------------------------
+export async function runDocs(root, { action = 'list', epic, overview, sync } = {}) {
+  const { docs } = loadDocs(root);
+  const targets = overview ? [{ overview: true }] : epic ? [{ epic }] : enumerateSites(root);
+  if (action === 'list') {
+    if (!docs) { warn('no docs target connected (.sdlc/docs.json) — run yad-connect-docs'); }
+    else {
+      log(c.bold('\ndocs target'));
+      info(`target ${c.cyan(docs.target)}  scope ${docs.scope}  base ${docs.basePath}  ${docs.source === 'unavailable' ? c.yellow('(build-only)') : ''}`);
+    }
+    log(c.bold('\ngenerated sites'));
+    if (!targets.length) { info('none generated yet'); return { sites: 0 }; }
+    for (const t of targets) reportFreshness(root, t);
+    return { sites: targets.length };
+  }
+  if (action === 'build' || action === 'deploy') {
+    let built = 0;
+    for (const t of targets) {
+      const r = buildSite(siteDir(root, t));
+      if (r.ok) { built++; ok(`built ${label(t)} ${c.dim('→ ' + path.relative(root, r.dist))}`); }
+    }
+    if (action === 'deploy') {
+      const platform = docs ? (docs.target === 'gitlab-pages' ? 'gitlab' : docs.target === 'github-pages' ? 'github' : null) : null;
+      if (!platform || !platformReady(platform)) {
+        hand('no Pages platform/CLI — built locally only; commit + push so the CI workflow can publish (yad docs sync --wire)');
+      } else {
+        ok(`deploy via the ${platform} Pages workflow on push (yad docs sync --wire installs it)`);
+        if (docs?.basePath) info(`will publish under ${docs.basePath}`);
+      }
+    }
+    return { built };
+  }
+  if (action === 'sync') {
+    if (sync === 'wire') return wirePages(root, docs);
+    // check (default) + refresh both compute staleness; refresh additionally rebuilds.
+    const registry = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
+    let stale = 0;
+    for (const t of targets) {
+      const s = freshness(root, t, registry);
+      if (s.stale) {
+        stale++;
+        warn(`${label(t)} — ${c.yellow('stale')}: ${s.reasons.join('; ')}`);
+        if (sync === 'refresh') buildSite(siteDir(root, t));
+      } else ok(`${label(t)} ${c.dim('— fresh')}`);
+    }
+    if (stale && sync !== 'refresh') hand('regenerate content with the yad-docs / yad-docs-overview skill (the AI step), then `yad docs deploy`');
+    return { stale };
+  }
+  fail(`unknown docs action: ${action} (list | build | deploy | sync)`);
+  process.exitCode = 1;
+  return {};
+}
+// ---- helpers ------------------------------------------------------------------------------------
+function enumerateSites(root) {
+  const out = [];
+  if (exists(siteDir(root, { overview: true }))) out.push({ overview: true });
+  const epicsDir = path.join(root, 'epics');
+  if (exists(epicsDir)) {
+    for (const e of fs.readdirSync(epicsDir).sort()) {
+      if (exists(path.join(epicsDir, e, 'docs-site'))) out.push({ epic: e });
+    }
+  }
+  return out;
+}
+function label(t) { return t.overview ? 'overview (docs/sdlc-site)' : `epic ${t.epic}`; }
+function freshness(root, t, registry) {
+  const manifest = readJSON(manifestPath(root, t), null);
+  if (t.overview) {
+    // The overview is generated from the project pipeline definition, not an epic's artifacts.
+    const files = ['skills/sdlc/config.yaml', 'skills/sdlc/module-help.csv', 'docs/diagrams/sdlc-overview.mmd']
+      .map((f) => path.join(root, f)).filter(exists);
+    return docsStale(manifest, { artifactHash: docsArtifactHash(files), templateVersion: VERSION });
+  }
+  const epicMeta = readJSON(path.join(root, 'epics', t.epic, '.sdlc/state.json'), {});
+  const repos = epicMeta.repos || [];
+  const surface = contractSurfaceHash(path.join(root, 'epics', t.epic)); // null when no locked surface
+  return docsStale(manifest, {
+    artifactHash: docsArtifactHash(docsArtifactFiles(root, t.epic), surface || ''),
+    repoHeads: repoHeadsFor(root, repos, registry),
+    templateVersion: VERSION,
+  });
+}
+function reportFreshness(root, t) {
+  const registry = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
+  const s = freshness(root, t, registry);
+  if (s.stale) warn(`${label(t)} — ${c.yellow('stale')}: ${s.reasons.join('; ')}`);
+  else ok(`${label(t)} ${c.dim('— fresh')}`);
+}
+function wirePages(root, docs) {
+  const platform = docs?.target === 'gitlab-pages' ? 'gitlab' : 'github';
+  const rel = pagesWorkflowPath(platform);
+  const dest = path.join(root, rel);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(dest, pagesWorkflow(platform));
+  ok(`wired ${rel} ${c.dim(`(${platform} Pages)`)}`);
+  if (platform === 'gitlab') hand(`include it from .gitlab-ci.yml:  include: { local: ${rel} }`);
+  else hand('commit it; set the repo Pages source to "GitHub Actions" so it publishes on push');
+  return { wired: rel };
+}

package/cli/doctor.mjs CHANGED Viewed

@@ -195,6 +195,7 @@ export function ciTagsChecks(checks, root, hub, registry) {
     fragments.push(
       { scope: 'hub', file: '.gitlab/ci/yad-gate-sync.yml', path: path.join(root, '.gitlab/ci/yad-gate-sync.yml') },
       { scope: 'hub', file: '.gitlab/ci/yad-verified-commits.yml', path: path.join(root, '.gitlab/ci/yad-verified-commits.yml') },
+      { scope: 'hub', file: '.gitlab/ci/yad-hub-checks.yml', path: path.join(root, '.gitlab/ci/yad-hub-checks.yml') },
     );
   }
   for (const repo of registry?.repos || []) {