yadflow 3.18.1 → 4.0.0-next.1

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

@@ -1,87 +1,96 @@
-# Hub config — schema, detection, and the reviewer roster
+# Product config — schema, detection, and who is recorded
 
-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
+The Product config is the Product's record of **its own** platform (so the Shape review/comment/
+approval cycle can run through a real PR/MR on the Product). It holds **no list of people** — no roster,
+no roles, no commit emails (E62). It is a single object for the Product 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 `yad-connect-repos action: detect-hub`.
+(`config.yaml` `product.config` (older projects: `hub.config`).) Created/updated by `yad-connect-repos action: detect-hub`.
 
 ## Schema
 
 ```json
 {
-  "platform": "github",                                       // github | gitlab (from the hub's own remote host); null when local-only
+  "schemaVersion": 10,                                        // the file's shape. Absent means 1 (rule 1). `yad migrate` moves it; see docs/migrations/shape-2.md
+  "platform": "github",                                       // github | gitlab (from the Product's own remote host); null when local-only
   "git_url": "https://github.com/abdelrahmannasr/yadflow.git", // REQUIRED when platform is non-null (scopes auth + opens PRs); yad doctor warns YAD-CFG-005 if absent
   "default_branch": "main",
-  "bridge_enabled": true,                                     // open review PRs/MRs on the hub for front-half reviews; travels WITH platform — bridge mode is both (isBridge), so never true beside platform: null (#186)
-  "gate_sync_version": "3.15.3",                              // OPTIONAL exact pin for the wired gate-sync job; an exact 3.x.y, prereleases included (3.16.0-rc.1) — anything else is skipped. Omitted => the .sdlc/cli-version.json stamp if that qualifies, else floating 3
+  "ledger": "verified",                                       // WHO WRITES THE LEDGER, and the one that decides: "verified" = CI only, signed; "local" = this machine. Travels WITH platform — verified is both (isVerifiedLedger), so never "verified" beside platform: null (#186)
+  "bridge_enabled": true,                                     // the older spelling of the same switch, kept so a check gate that predates `yad update` still reads it. Write it to MATCH `ledger`, never against it
+  "bridge": true,                                             // older still. Same rule
+  "gate_sync_version": "4.0.0",                              // OPTIONAL exact pin for the wired gate-sync job; an exact release of the wired fragment's major (4.x.y in this release), prereleases included (4.1.0-rc.1) — anything else, a 3.x pin included, is skipped. Omitted => the .sdlc/cli-version.json stamp if that qualifies, else floating on that major
   "review": { "requireEngagement": false },                   // Review Companion: false (soft) counts bare approves but nudges; true counts only verified-engagement approvals
-  "detectedAt": "2026-06-08",                                 // last detect-hub run (YYYY-MM-DD)
-  "roster": [
-    { "login": "abdelrahmannasr", "name": "alice", "email": "alice@example.com",
-      "roles": { "hub": ["owner", "reviewer"] } },
-    { "login": "carol-gh", "name": "carol", "email": "carol@example.com",
-      "roles": { "hub": ["reviewer"], "backend": ["domain-owner", "owner"], "payments": ["reviewer"] } }
-  ]
+  "solo": false,                                              // SOLO MODE, and the one that decides: true waives the approval requirement on every review gate (the merge + resolved threads still gate). Set by `yad setup --solo` / `--team <n>` or `yad mode`
+  "mode": "team",                                             // the roadmap's name for the same switch (E10): "solo" | "team", written beside `solo` by `yad mode` and `yad setup`. NOT read by the gates this major — `yad doctor` warns `mode:disagree` when it contradicts `solo`. Not the ledger switch: "verified mode" elsewhere means `ledger`
+  "mode_set": { "from": "solo", "to": "team", "by": "al", "date": "2026-09-15", "reason": null }, // the last change of mode (E10): who, when, why. `yad mode solo` requires the reason
+  "detectedAt": "2026-06-08"                                  // last detect-hub run (YYYY-MM-DD)
 }
 ```
 
-## The roster — login → name → per-scope roles
-
-The roster is how a platform identity (a GitHub/GitLab **login**) becomes an SDLC **name + role(s)** in
-the file ledger (`approvals.json` / `comments.json`). Roles are the same three the gate uses:
-`owner | reviewer | domain-owner`. Populate and edit it any time with the **`yad roster`** CLI command
-(`list` / `add` / `grant` / `revoke` / `remove`) — `add` walks the connected repos asking for each
-one's role, and a `domain-owner` grant keeps `repos.json` `domain_owners` in sync.
-
-- **`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.
-- **`email`** — the commit email; drives the **committer → login** reverse lookup that auto-assigns PRs.
-- **`roles`** — a **per-scope map**: scope (`hub`, or a connected repo name) → the roles held there. A
-  person can be **owner + reviewer + domain-owner at once** and across scopes; a repo gets **several**
-  people per role by appearing in several entries' maps. Validated against the hub during `yad setup` /
-  `yad doctor`; a login that does not resolve is flagged `unverified` (warn-only, never blocks).
-
-**Back-compat:** readers also accept a flat array `"roles": ["owner","reviewer"]` (treated as `hub`
-roles) and the legacy single `"role": "owner"` (a `hub` role).
-
-**`domain-owner` may also be DERIVED from `repos.json`.** A roster entry whose `name` equals a repo's
-`domain_owner`/`domain_owners` in `repos.json` is treated as that repo's domain-owner **when that repo is
-a touched domain for the step under review** — kept as a fallback so pre per-scope projects still resolve.
-New setups write the grant directly into the person's `roles[<repo>]` map.
-
-- **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.
+## People — no roster (E62)
+
+yadflow keeps **no stored list of people**. A list is a claim that goes stale; the platform already knows
+who is logged in and who has access.
+
+- **Who a record names.** A record's `by` is the platform login that `gh api user` / `glab api user`
+  reports, else git `user.name` (no platform, CLI missing or logged out, no network).
+  `YAD_PLATFORM_LOGIN=0` turns the lookup off.
+- **Approvals.** Each approval records the platform login that gave it as `approver`, with no `role` and
+  no `domain`. A team gate needs at least **1 approval from someone other than the author**, plus
+  resolved threads and a merged PR. The full count is `base 1 + risk step` (`contract` +2, `auth` /
+  `payments` +1, the largest and never the sum); the gate caps it at the active people less one and
+  reports that (E72); the risk step is advisory. Solo
+  mode still waives the approval.
+- **Reviewers.** Nothing requests reviewers on a PR/MR. Ask them on the PR/MR itself. `yad open-pr`
+  prints a suggestion for a code-repo PR (E68) from recent history and CODEOWNERS — a hint only.
+
+**Legacy data an older release wrote.** A `roster` array (with `login`/`name`/`email`/`roles`, or the
+older `role`) and a `verified_authors` list may still sit in this file. Nothing adds them, and nothing
+deletes them (`yad migrate`'s shape-3 step still adds a `product` role key beside `hub` in an old roster, so
+an older project upgrades the same way it always did). `verified_authors` decides nothing — only `yad doctor`
+reads it, to warn. The roster is read for one thing only: its `name` →
+`login` pairs let a gate write record the login on older approval and comment records
+(`../../yad-hub-bridge/references/login-roster.md` → "Recording the login on older records"). `yad doctor`
+warns `people:roster-unused` and `people:verified-authors-unused` so nobody edits them believing they decide
+something. Delete `verified_authors` when convenient; delete `roster` when `people:roster-unused` says it
+can go — no older record needs it any more, or only records it cannot place are left and their reviews are
+closed.
 
 ## 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 —
+run `git remote get-url origin` **on the Product 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.
 
 **`git_url` is required whenever `platform` is non-null.** `yad doctor` uses it to scope the auth
-probe to the hub's own host (an unscoped `glab auth status` fails on any unrelated broken instance),
-and the bridge/PR flow uses it to open PRs. Doctor flags its absence with a warn (`YAD-CFG-005`);
+probe to the Product's own host (an unscoped `glab auth status` fails on any unrelated broken instance),
+and the verified ledger/PR flow uses it to open PRs. Doctor flags its absence with a warn (`YAD-CFG-005`);
 re-running `yad setup` backfills it from the origin remote (idempotent, non-interactive).
 
-## Bridge enable / degradation
+## Who writes the ledger, and what happens when it degrades
 
-- `bridge_enabled: true` **and** a non-null `platform` **and** `gh`/`glab` authenticated → the front-half
-  review opens a PR/MR on the hub and `yad-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`.
+The switch is read in this order — `isVerifiedLedger` (`cli/manifest.mjs`) and the bash copy in
+`checks/ledger-guard.sh` both do exactly this, and a test asserts they agree on every shape:
+
+1. **`ledger`**, whenever the key is present. `"verified"` and nothing else means verified; any other
+   value, including an empty string, means local.
+2. **otherwise** the older booleans `bridge_enabled`, then `bridge`.
+3. and a non-null `platform` is required either way — without one there is no Verified badge to read.
+
+So on a migrated project `ledger` wins, and writing a boolean that contradicts it changes nothing.
+Keep all three in step.
+
+- `ledger: "verified"` **and** a non-null `platform` **and** `gh`/`glab` authenticated → the Shape
+  review opens a PR/MR on the Product and `yad-review-gate action: sync` pulls platform state into the ledger.
+- `ledger: "local"`, `platform: null`, or no/unauthenticated CLI → the gate falls back to the
+  existing **local** flow with no error. The file ledger is the source of truth in both modes.
+- The master switch `config.yaml` `product.bridge: false` (older projects: `hub.bridge`) disables the verified ledger globally regardless of `hub.json`.
 
 ## Review Companion engagement (`review.requireEngagement`)
 
@@ -90,15 +99,16 @@ engagement gate. Each approval records `engagement: verified | none`. **Soft (`f
 bare approve still passes but draws a friendly public nudge, so review *quality* is visible without
 blocking. **Strict (`true`):** the predicate counts only `verified` approvals. The signal is gameable by
 design ("visible, not impossible") — it raises the cost of a rubber-stamp, it does not prove a human
-read the artifact. Applies to both the front gate and the back-half engineer review.
+read the artifact. Applies to both the Shape gate and the Build engineer review.
 
 ## Git tracking
 
-Commit `hub.json` — it is small, reviewable, and carries no secrets (logins and names only, never tokens).
+Commit `hub.json` — it is small, reviewable, and carries no secrets or tokens. The only people data in it is the login or git name in `mode_set.by`, plus
+whatever an older `roster` still lists.
 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.
+A brand-new Product has no `hub.json`. That is valid — the Shape gate runs local until `detect-hub`
+records a platform. The verified ledger is purely additive; nothing about authoring or the gate predicate changes.
 ```

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

@@ -1,6 +1,6 @@
 # Repos registry — schema + freshness rule
 
-The registry is the product hub's record of which code repos are connected and where their cached
+The registry is the Product'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/`.
 
@@ -21,8 +21,6 @@ not under any `epics/EP-<slug>/.sdlc/`.
       "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_owners": ["carol", "dave"],         // engineers who own this repo's domain (review routing); a repo may have several
-      "domain_owner": "carol",                    // legacy single-owner mirror = domain_owners[0] (kept for back-compat readers)
       "default_branch": "main",
       "connectedAt": "2026-06-08",                // first connect (YYYY-MM-DD)
       "lastSyncedAt": "2026-06-08",               // last connect/refresh
@@ -37,7 +35,10 @@ not under any `epics/EP-<slug>/.sdlc/`.
 
 ## Rules
 
-- **`name`** is the join key. It MUST match the names used in epic/story `repos:` tags so the front
+- **No owners.** An entry names no people (E62). `connect` writes no `domain_owner`/`domain_owners`. An
+  entry an older release wrote with them keeps them; nothing reads them, nothing deletes them, and
+  `yad doctor` warns `people:domain-owners-unused`.
+- **`name`** is the join key. It MUST match the names used in epic/story `repos:` tags so the Shape
   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).
@@ -51,15 +52,15 @@ not under any `epics/EP-<slug>/.sdlc/`.
 ## 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).
-`yad repo refresh --push` commits and pushes exactly these (never `pack.md`) to the hub's default
+and are what the Shape phases actually read (a diff on a code-map shows when a repo's surface moved).
+`yad repo refresh --push` commits and pushes exactly these (never `pack.md`) to the Product's default
 branch as one `chore(hub): sync code-context … [skip ci]` audit commit.
-**Ignore** the full Repomix `pack.md` — it is large and regenerable (`action: refresh`). The product
-hub's `.gitignore` carries `.sdlc/code-context/*/pack.md` for this. This mirrors how the per-epic
+**Ignore** the full Repomix `pack.md` — it is large and regenerable (`action: refresh`). The Product
+'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
+A brand-new Product has no `repos.json` (or an empty `{ "repos": [] }`). That is valid — the Shape
 phases treat "no repos connected" as "nothing to consider yet" and proceed unchanged. The registry
 appears the first time `connect` runs.

package/skills/yad-connect-repos/references/risk-map.md

@@ -0,0 +1,81 @@
+# Risk map — format, the classification rubric, and the rules for the agent
+
+A code repo's **risk map** is one file, `.sdlc/risk-map`, **in the code repo** (not the Product). It
+gives each directory a risk level. It holds **no names** — no people, no roles, no teams, no `@login`.
+It is the team's file: `yad update` never installs, owns or overwrites it, and it changes only through
+that repo's PRs (E65).
+
+**What the levels do (E66).** A change touching a `high` directory asks for one more approver. The count
+reads the map on the **base branch**, so a PR cannot lower its own count, and a `guessed` level counts
+exactly as a `confirmed` one. That is why a guess matters: a `high` guess adds a reviewer to every change
+under that directory until a person confirms or changes it. `medium` and `low` add nothing. The count is
+reported, not enforced: branch protection holds the merge, and `yad open-pr` shows the count capped by the
+active people (E72). A `high` directory also asks for an approval from someone who has committed there in the last 30 days
+(E67), named live from the base branch's history — so a guess here decides who can review, too.
+
+## Format
+
+```
+# yad-risk-map v1
+src/payments/   high    confirmed  # charge.js calls the card processor
+src/catalog/    low     guessed    # read-only product listing
+docs/           unset
+./              low     confirmed  # the files at the repo root
+```
+
+| Rule | Meaning |
+|---|---|
+| Header | The first line is `# yad-risk-map v1`. |
+| One line per directory | `<dir>/ <level> <guessed\|confirmed>`, fields split on spaces or tabs, so a path holds none. |
+| Directory | Written from the repo root, ending in `/`. No leading `/` or `#`, no `.` or `..` segment, no space, tab, `*`, `?`, `[` or `\`. A directory whose name holds one of those (`app/[slug]/`) cannot have a line of its own: its parent's line covers it. At the top level (`my docs/`) nothing can, and the check says to rename it. |
+| `./` | The files **at** the repo root only — not everything below it. |
+| Which line decides | The deepest listed directory above a file. |
+| Levels | `high`, `medium`, `low`, or `unset` (listed, not classified; its state may be left out). |
+| States | `guessed` (an AI agent filled it in) or `confirmed` (a person checked it). |
+| Comment | Everything from the first `#` that follows a space or tab. |
+| Names | A word starting `@` (`@alice`, `@org/team`) is a name and is warned about. A word ending in `/` (`@types/`) is a directory. |
+| No `contract` | The contract surface keeps its own lock, `contract-check` and `Contract-Change` trailer. |
+
+The rules are code: `cli/riskmap.mjs`, with a bash twin in `checks/risk-map-check.sh`.
+
+## Rubric — read the CODE, not the folder name (one exception, below)
+
+Decide from what the code in the directory **does**: the calls it makes, the data it writes, the
+libraries it imports. A folder called `utils/` can move money; a folder called `payments/` can hold only
+display text. Use the pack and the code-map first, and open the files themselves when they do not say.
+
+| Level | The code in the directory… |
+|---|---|
+| `high` | moves money or bills anyone; handles login, sessions, tokens, permissions, secrets or keys; deletes stored data or changes its shape (migrations); reads or writes personal data (identity, contact, health, payment details); builds, deploys or releases (CI workflows, deploy scripts, infrastructure); and `.sdlc/` — see the exception below the table |
+| `medium` | writes to a database, a queue or an outside service in ordinary ways; serves a public API or event others depend on; is a shared library most of the code imports; sets build or dependency configuration |
+| `low` | only reads and shows data; styling and UI text; documentation; tests, fixtures and examples; developer tooling that never ships |
+
+- **When unsure between two levels, choose the higher one** and say what you could not tell in the reason.
+- **Split a directory when its parts differ.** If `src/` holds `payments/` (`high`) and `catalog/` (`low`),
+  write a line for each part, and keep a line for `src/` itself for the files directly in it.
+- **The one exception: `.sdlc/` is `high`**, judged by what it HOLDS — this map, which decides how much
+  review every later change needs — not by what its code does (the user's decision, 2026-09-17). A
+  `yad update` PR touches that folder too, so those PRs ask for the extra approver as well; accepted,
+  because they rewrite the gate scripts the repo runs.
+- **The reason is one line, taken from the code**: a file and what it does (`charge.js calls the card
+  processor`). Never a name, a secret, a customer value or an address.
+
+## What the agent may and may not change
+
+| Line | The agent may… | The agent may not… |
+|---|---|---|
+| `unset` | give it a level, a reason and `guessed` | mark it `confirmed` |
+| `guessed` | change its level or reason, keeping `guessed` | mark it `confirmed` |
+| `confirmed` | nothing — print a **suggestion** when the code now says otherwise | edit, re-level or delete it |
+| any | add a deeper line when a directory's parts differ | delete a line, or add a name |
+
+Only a person turns `guessed` into `confirmed`, in a PR in the code repo. The commit records who.
+
+## Staying true
+
+| Where | What it says |
+|---|---|
+| `checks/risk-map-check.sh` on every PR (both CI templates) | a file this change adds or edits that no line covers (names the directory to add); a line whose directory holds no file; a touched line still `unset` or `guessed`; a line it cannot read or that names a person; a change that edits the map itself. **Warnings only** — it never fails the build |
+| `yad risk-map check [repo]` | the same, for the whole repo |
+| `yad doctor`, section `risk-map` | one line per connected repo on disk |
+| `yad repo refresh` + this skill | a new directory is drafted `unset` and classified; a `confirmed` line the code now contradicts is printed as a suggestion |

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

@@ -1,16 +1,16 @@
 ---
 name: yad-connect-testing
-description: 'Connects a testing tool (Playwright, or another tool — pluggable) to the product hub so the test-cases step can implement the actual automation tests, not just Markdown test cases. Registers the tool into the project-wide .sdlc/testing.json (local-user / MCP-session auth, no stored tokens), detecting whether a testing-tool MCP is available and degrading to artifacts-only when it is not. Run at setup or any time the testing tool changes. Reusable, idempotent, refreshable. Use when the user says "connect Playwright", "connect a testing tool", "refresh the testing connection", or "list the testing connection".'
+description: 'Connects a testing tool (Playwright, or another tool — pluggable) to the Product so the test-cases step can implement the actual automation tests, not just Markdown test cases. Registers the tool into the project-wide .sdlc/testing.json (local-user / MCP-session auth, no stored tokens), detecting whether a testing-tool MCP is available and degrading to artifacts-only when it is not. Run at setup or any time the testing tool changes. Reusable, idempotent, refreshable. Use when the user says "connect Playwright", "connect a testing tool", "refresh the testing connection", or "list the testing connection".'
 ---
 
 # SDLC — Connect a Testing Tool (make the test-cases step automation-aware)
 
 **Goal:** Let the test-cases step (`yad-test-cases`) produce the **actual automation tests** — the
 runnable specs in a connected code repo — alongside the Markdown artifact (`test-cases.md`). This skill
-**connects** a testing tool such as **Playwright** to the product hub and records *how* to reach it (the
+**connects** a testing tool such as **Playwright** to the Product and records *how* to reach it (the
 tool, the suite references, which MCP runs it) — never a credential.
 
-This is **setup/maintenance**, not a gated front state — it never touches `.sdlc/state.json` or any
+This is **setup/maintenance**, not a gated Shape step — it never touches `.sdlc/state.json` or any
 epic's approvals. It only writes the project-wide testing registry. `yad-test-cases` consumes it: when a
 tool is connected and its MCP is available, the `test architect` lens **generates** automation tests
 into the connected repo(s) (or **links** an existing suite and reads it back); when nothing is
@@ -18,7 +18,7 @@ connected, `yad-test-cases` runs artifacts-only exactly as before.
 
 ## Conventions
 
-- `{project-root}` resolves from the project working directory (the **product hub**).
+- `{project-root}` resolves from the project working directory (the **Product**).
 - The integration is **Playwright-first but pluggable** (`config.yaml` `testing.tools`): a testing-tool
   *adapter*, like the GitHub/GitLab platform adapter or the design-tool adapter. Playwright is the
   primary provider; `cypress`, `pytest` and `maestro` are second providers; `none` → artifacts-only.
@@ -29,7 +29,7 @@ connected, `yad-test-cases` runs artifacts-only exactly as before.
   the sibling of `.sdlc/repos.json`, `.sdlc/hub.json`, and `.sdlc/design.json`.
 - Per-epic test→suite links are written later by `yad-test-cases`
   (`epics/EP-<slug>/.sdlc/test-links.json`), not here.
-- Speak in the configured `communication_language`; write documents in `document_output_language`.
+- Speak in the `communication_language` set in `{project-root}/.sdlc/config.yaml`; write documents in `document_output_language`.
 
 ## Inputs
 
@@ -101,7 +101,7 @@ automation tests here**. Nothing auto-advances; this is setup.
   **available/unavailable** flag for the MCP (best-effort, the user's own session). No testing tool
   connected ⇒ "artifacts-only".
 - **`disconnect`** — remove the registry file (or set `tool: "none"`). The testing tool's own
-  project/suites are **never touched** — only the hub's record of them.
+  project/suites are **never touched** — only the Product's record of them.
 
 ## Hard rules
 

package/skills/yad-connect-testing/references/testing-context.md

@@ -27,8 +27,7 @@ produce.
 
 ## Generate (write automation tests into the repo)
 
-When the connected provider is write-capable, the `test architect` lens (Murat, `bmad-tea` +
-`bmad-testarch-automate`) produces the epic's automation tests in the connected code repo(s), covering
+When the connected provider is write-capable, the `test architect` lens produces the epic's automation tests in the connected code repo(s), covering
 the cases `test-cases.md` enumerates and the acceptance criteria the stories define:
 
 - **Playwright** — the lens authors `*.spec.ts` E2E/API specs (reusing the repo's existing fixtures and
@@ -43,7 +42,7 @@ the cases `test-cases.md` enumerates and the acceptance criteria the stories def
 
 Reuse what already exists: load the connected code repos' code-maps (`yad-test-cases` Step 2b) so
 generated tests target real endpoints/components, not invented ones, and prefer the lowest useful test
-level (unit > integration > E2E) per Murat's principles.
+level (unit > integration > E2E).
 
 ## Link (reference an existing suite)
 
@@ -55,7 +54,7 @@ path/name + URL, and map it to the story it covers.
 
 Either direction ends by writing `epics/EP-<slug>/.sdlc/test-links.json` — the machine-readable
 case→test map — and a `## Automation (<tool>)` section in `test-cases.md` linking each case to its test.
-The tests themselves live in the code repo; the hub keeps the *links* and the Markdown spec beside the
+The tests themselves live in the code repo; the Product keeps the *links* and the Markdown spec beside the
 other epic artifacts.
 
 ## Degrade path (no MCP / no tool)

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

@@ -1,6 +1,6 @@
 # Testing registry — schema + freshness rule
 
-The registry is the product hub's record of which testing tool is connected and how to reach it. It is
+The registry is the Product's record of which testing tool is connected and how to reach it. It is
 **project-wide** (one testing tool per project, shared across every epic), so it lives at the product
 root, not under any `epics/EP-<slug>/.sdlc/`.
 
@@ -50,6 +50,6 @@ only). This mirrors how `repos.json`, `hub.json`, and `design.json` are committe
 
 ## Greenfield
 
-A brand-new product hub has no `testing.json`. That is valid — `yad-test-cases` treats "no testing tool
+A brand-new Product has no `testing.json`. That is valid — `yad-test-cases` treats "no testing tool
 connected" the same as `tool: "none"` and produces the Markdown test-case artifact only. The registry
 appears the first time `connect` runs.

package/skills/yad-defects/SKILL.md

@@ -1,21 +1,21 @@
 ---
 name: yad-defects
-description: 'Phase 6 output enrichment (never a gate) — the quality-gap report. Generates a per-epic AND per-thread defect/bug report (the vendored React/Vite/Tailwind shell HTML + a DEFECTS.md) that aggregates every kind:defect change-epic + each change.json defect block + shipped regressions in the build ledger (the folded build-log.json unioned with every build-log/ shard) BY escape_stage (the SDLC gate that should have caught the defect) and root_cause, and visualizes WHERE quality gaps systematically come from — e.g. "% of this feature''s defects that escaped at the test-cases gate" — so the team hardens the originating stage instead of just fixing symptoms. Degrades to markdown-only when no docs target is connected. Use when the user says "show the defect report", "where are our quality gaps", "generate the bug report for this epic", or "which gate is leaking defects".'
+description: 'Phase 6 output enrichment (never a gate) — the quality-gap report. Generates a per-epic AND per-thread defect/bug report (the vendored React/Vite/Tailwind shell HTML + a DEFECTS.md) that aggregates every defect-type change-epic + each change.json defect block + shipped regressions in the build ledger (the folded build-log.json unioned with every build-log/ shard) BY escape_stage (the SDLC gate that should have caught the defect) and root_cause, and visualizes WHERE quality gaps systematically come from — e.g. "% of this feature''s defects that escaped at the test-cases gate" — so the team hardens the originating stage instead of just fixing symptoms. Degrades to markdown-only when no docs target is connected. Use when the user says "show the defect report", "where are our quality gaps", "generate the bug report for this epic", or "which gate is leaking defects".'
 ---
 
 # SDLC — Quality-Gap Report (Phase 6, output enrichment)
 
 **Goal:** Turn the thread's defects into a **systemic quality signal**. Because every defect is a
-first-class `kind: defect` change-epic carrying an `escape_stage` (the gate that *should* have caught it)
+first-class `defect`-type change-epic carrying an `escape_stage` (the gate that *should* have caught it)
 and a `root_cause`, this report can show not just *what* broke but *where the SDLC let it through* — so
 the team fixes the originating stage (weak test design, an under-specified story, a missed architecture
 risk), not just the symptom. It is an **output enrichment**, exactly like `yad-docs` — **never a gate**.
 
 ## Conventions
 
-- `{project-root}` resolves from the product hub.
+- `{project-root}` resolves from the Product.
 - Reuses the **`yad-docs` shell** verbatim (`../yad-docs/templates/app/`) — generated `src/data/*.ts`,
-  themed, deployed via `yad docs deploy`; build-only / markdown-only when no docs target.
+  themed; build-only / markdown-only (`yad docs deploy` does not build `defects-site/` yet).
 - Per **epic** (one epic's defects) and per **thread** (the whole feature; the thread report lives under
   the genesis epic, since `thread == genesis id`). The thread is derived from `parent:` frontmatter.
 - Deterministic generation, like `yad-docs` (stable sort, fixed key order, no timestamps in data).
@@ -30,11 +30,11 @@ risk), not just the symptom. It is an **output enrichment**, exactly like `yad-d
 
 ### Step 1 — Collect the defects
 Resolve the scope (`yad thread <id> --json` for a thread). Collect, across the scoped epic(s):
-- every `kind: defect` (and `kind: hotfix`) change-epic + its `.sdlc/change.json` `defect` block
+- every `defect` (and `hotfix`) type change-epic + its `.sdlc/change.json` `defect` block
   (`origin`, `severity`, `escape_stage`, `root_cause`);
 - the shipped regression fixes from each epic's build ledger (the fix that closed the defect, linking
   the change-epic → its regression story/test);
-- open reconcile debt (a hotfix whose front truth is not yet restored).
+- open reconcile debt (a hotfix whose Shape truth is not yet restored).
 
 The build ledger is **shard-then-fold**: read it as the **union** of the folded `.sdlc/build-log.json`
 `ships` PLUS every loose `.sdlc/build-log/` shard, deduped by `(story, task, repo)` — a shard WINS over a
@@ -66,8 +66,8 @@ Generate the site into `epics/<scope>/defects-site/` with sections:
 5. **Severity & age.**
 6. **Recommendations** — which originating stage to harden, derived from the top escape-stages.
 
-Also write a plain `epics/<scope>/DEFECTS.md` mirror. On `action: deploy`, `yad docs deploy` the site
-(build-only when no target).
+Also write a plain `epics/<scope>/DEFECTS.md` mirror. On `action: deploy`, note that
+`yad docs deploy` does not build this folder yet (it builds only the epic `docs-site/` and the overview) — build it with `npm ci` (or `npm install` when it has no lockfile) and `npm run build` inside the folder, and report it as build-only; a failed npm build is reported as a failure, never as a deploy.
 
 ## Hard rules